VHDL Style Guide
Project description
Coding style enforcement for VHDL.
Announcements
Version 2 has been released.
Please be aware that there are some rule incompatabilities with the 1.x releases:
The default for all case rules is now lowercase
Alignment rules have changed significantly
Some rules have been moved to group them with the correct rule sets
These changes will require another tunning of the rules against your code. Refer to the documentation on configuring case and alignment rules. There are many more options for the alignment rules than in the 1.x releases.
There are additional features added from version 1:
Alignment of identifiers has been added
Built in styles
Improved console output
Refer to the release notes for a full listing of features and bug fixes.
Table of Contents
Overview
VSG was created after participating in a code review where 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.
Create finding/ticket/issue
Disposition finding/ticket/issue
Fix
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 with JUnit output
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
Localize rule sets
Create your own rules using python
Use existing rules as a template
Fully integrates into base rule set
Built in styles
Use existing style or create your own
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] [-oc OUTPUT_CONFIGURATION]
[-rc RULE_CONFIGURATION] [--style {indent_only,jcl}] [-v] [--debug]
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 a copy of input file for comparison with fixed version.
-oc OUTPUT_CONFIGURATION, --output_configuration OUTPUT_CONFIGURATION
Write configuration to file name.
-rc RULE_CONFIGURATION, --rule_configuration RULE_CONFIGURATION
Display configuration of a rule
--style {indent_only,jcl}
Use predefined style
-v, --version Displays version information
--debug Displays verbose debug information
Here is an example output running against a test file:
Documentation
All documentation for VSG is hosted at read-the-docs.
Contributing
I welcome any contributions to this project. No matter how small or large.
There are several ways to contribute:
Bug reports
Code base improvements
Feature requests
Pull requests
Please refer to the documentation hosted at read-the-docs for more details on contributing.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.