VHDL Style Guide (VSG) ====================== **Coding style enforcement for VHDL.**
Github Release PyPI Version Build Status Test Coverage Read The Docs Codacy
VHDL Style Guide (VSG) provides coding style guide enforcement for VHDL code. ![vim macro](https://github.com/jeremiah-c-leary/vhdl-style-guide/blob/master/docs/img/vim_macro.gif) VSG was created after participating in a code review. A real issue in the code was masked by a coding style issue. A finding was created for the style issue, while the real issue was missed. When the code was re-reviewed, the real issue was discovered. Depending on your process, style issues can take a lot of time to resolve. 1. Create finding/ticket/issue 2. Disposition finding/ticket/issue 3. Fix 4. Verify fix Spending less time on style issues leaves more time to analyze the substance of the code. This ultimately reduces the amount of time performing code reviews. It also allows reviewers to focus on the substance of the code. This will result in a higher quality code base. ## Key benefits * Define VHDL coding standards * Makes coding standards visible to everyone * Improve code reviews * Quickly bring code up to current standards VSG allows the style of the code to be defined and enforced over part or the entire code base. Configurations allow for multiple coding standards. ## Key Features * Command line tool - integrate into continuous integration flow * Reports and fixes issues found - whitespace - horizontal - vertical - upper and lower case - keyword alignments - etc... * Fully configurable rules via JSON or YAML configuration file - Disable rules - Alter behavior of existing rules - Change phase of execution * Localize rule sets - Create your own rules using python - Use existing rules as a template - Fully integrates into base rule set ## Installation You can get the latest released version of VSG via **pip**. ``` pip install vsg ``` The latest development version can be cloned... ``` git clone https://github.com/jeremiah-c-leary/vhdl-style-guide.git ``` ...and then installed locally... ``` python setup.py install ``` ## Usage VSG is a both a command line tool and a python package. The command line tool can be invoked with: ``` $ vsg usage: VHDL Style Guide (VSG) [-h] [-f FILENAME [FILENAME ...]] [-lr LOCAL_RULES] [-c CONFIGURATION [CONFIGURATION ...]] [--fix] [-fp FIX_PHASE] [-j JUNIT] [-of {vsg,syntastic}] [-b] Analyzes VHDL files for style guide violations. Reference documentation is located at: http://vhdl-style-guide.readthedocs.io/en/latest/index.html optional arguments: -h, --help show this help message and exit -f FILENAME [FILENAME ...], --filename FILENAME [FILENAME ...] File to analyze -lr LOCAL_RULES, --local_rules LOCAL_RULES Path to local rules -c CONFIGURATION [CONFIGURATION ...], --configuration CONFIGURATION [CONFIGURATION ...] JSON or YAML configuration file(s) --fix Fix issues found -fp FIX_PHASE, --fix_phase FIX_PHASE Fix issues up to and including this phase -j JUNIT, --junit JUNIT Extract Junit file -of {vsg,syntastic}, --output_format {vsg,syntastic} Sets the output format. -b, --backup Creates copy of input file for comparison with fixed version. ``` Here is an example output running against a test file: ![fixing](https://github.com/jeremiah-c-leary/vhdl-style-guide/blob/master/docs/img/fixing_single_file.gif) ## Documentation All documentation for VSG is hosted at [read-the-docs](http://vhdl-style-guide.readthedocs.io/en/latest/index.html)