Go to file
Jeremiah C Leary cd13dff27f Preparing for release 0.32 2019-03-02 15:28:49 -06:00
bin Move main logic into module 2018-08-31 11:24:22 +10:00
docs Preparing for release 0.32 2019-03-02 15:28:49 -06:00
vsg Updates to address codeclimate issues. 2019-03-02 09:29:53 -06:00
.coveragerc Disabling coverage on vsg/tests/utils.py 2017-12-07 19:30:03 -06:00
.gitignore Add egg metadata to .gitignore 2018-09-04 10:23:19 +10:00
.travis.yml Removing coverity configuration. 2017-12-30 17:17:05 -06:00
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md 2018-11-01 23:25:42 -05:00
LICENSE Initial commit 2017-07-03 13:24:44 -05:00
MANIFEST.in Updates for issue #189 2018-12-12 17:48:15 -06:00
README.md Updating README to match read the docs documentation. 2018-11-15 19:25:56 -06:00
setup.cfg Configuring PEP8 and pycodestyle maximum line length. 2017-12-02 17:57:03 -06:00
setup.py Preparing for release 0.32 2019-03-02 15:28:49 -06:00
sonar-project.properties Attempting to add sonarsource. 2017-11-22 11:13:43 -06:00

README.md

VHDL Style Guide (VSG)

Coding style enforcement for VHDL.

VHDL Style Guide (VSG) provides coding style guide enforcement for VHDL code.

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
  • Fixes and/or reports issues found
    • whitespace
      • horizontal
      • vertical
    • upper and lower case
    • keyword alignments
    • etc...
  • Fully configurable rules via JSON 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 ...]]
                              [--local_rules LOCAL_RULES]
                              [--configuration CONFIGURATION] [--fix]
                              [--fix_phase FIX_PHASE] [--junit JUNIT]
                              [--output_format {vsg,syntastic}] [--backup]

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
  --local_rules LOCAL_RULES
                        Path to local rules
  --configuration CONFIGURATION
                        JSON configuration file
  --fix                 Fix issues found
  --fix_phase FIX_PHASE
                        Fix issues up to and including this phase
  --junit JUNIT         Extract Junit file
  --output_format {vsg,syntastic}
                        Sets the output format.
  --backup              Creates copy of input file for comparison with fixed
                        version.

Here is an example output running against a test file:

$ vsg -f PIC.vhd 
File:  PIC.vhd
==============
Phase 1... Reporting
Phase 2... Reporting
Phase 3... Reporting
Phase 4... Reporting
Phase 5... Reporting
  comment_002               |         51 | Ensure proper alignment of comment with previous line.
  comment_002               |         52 | Ensure proper alignment of comment with previous line.
  comment_002               |         54 | Ensure proper alignment of comment with previous line.
  comment_002               |         55 | Ensure proper alignment of comment with previous line.
  comment_003               |     76-256 | Inconsistent alignment of comments within process.
  sequential_005            |      87-93 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    102-103 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    105-108 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    110-113 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    115-118 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    120-124 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    129-133 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    160-161 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    173-174 | Inconsistent alignment of "<=" in group of lines.
  comment_002               |        183 | Ensure proper alignment of comment with previous line.
  sequential_005            |    225-226 | Inconsistent alignment of "<=" in group of lines.
  sequential_005            |    238-239 | Inconsistent alignment of "<=" in group of lines.
Phase 6... Not executed
Phase 7... Not executed
==============
Total Rules Checked: 204
Total Failures:      523

Local rules

VSG supports customization by allowing localized rules. This is simply a directory with an init.py file and one or more python files. The files should follow the same structure and naming convention as the rules found in the vsg/rules directory.

The localized rules will be used when the --local_rules command line argument is given.

Documentation

All documentation for VSG is hosted at read-the-docs