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] [-js JSON] [-of {vsg,syntastic,summary}] [-b] [-oc OUTPUT_CONFIGURATION]
                              [-rc RULE_CONFIGURATION] [--style {indent_only,jcl}] [-v] [-ap] [--fix_only FIX_ONLY] [-p JOBS]
                              [--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
  -js JSON, --json JSON
                        Extract JSON file
  -of {vsg,syntastic,summary}, --output_format {vsg,syntastic,summary}
                        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
  -ap, --all_phases     Do not stop when a violation is detected.
  --fix_only FIX_ONLY   Restrict fixing via JSON file.
  -p JOBS, --jobs JOBS  number of parallel jobs to use, default is the number of cpu cores
  --debug               Displays verbose debug information

Command Line Options

Option Description
-f FILENAME The VHDL file to be analyzed or fixed. Multiple files can be passed through this option.
–local_rules LOCAL_RULES Additional rules not in the base set.
–configuration CONFIGURATION JSON or YAML file(s) which alters the behavior of VSG. Configuration can also include a list files to analyze. Any combination of JSON and YAML files can be passed. Each will be processed in order from left to right.
–fix Update issues found. Replaces current file with updated one.
–fix_phase Applies for all phases up to and including this phase. Analysis will then be performed on all phases.
–junit Filename of JUnit XML file to generate.
–json Filename of JSON file to generate.
–output_format
Configures the sdout output format.
vsg – standard VSG output syntastic – format compatible with the syntastic VIM module summary – Minimal output useful when running on multiple files
–backup Creates a copy of the input file before applying any fixes. This can be used to compare the fixed file against the original.
–output_configuration Writes a JSON configuration file of the current run. It includes a file_list, local_rules (if used), and how every rule was configured. This configuration can be fed back into VSG.
–rule_configuration Displays the configuration of a rule.
–style Use a built in coding style.
–version Displays the version of VSG.
–all-phases Executes all phases without stopping if a violation is found.
–fix_only Restrict which rules are fixed based on JSON file.
–jobs Restrict the number of cores used to run. The default is the number of cores available.
–debug Print verbose debug information to assist with debuging errors with VSG.

Here is an example output running against a test file:

$ vsg -f example/architecture-empty.vhd
================================================================================
File:  example/architecture-empty.vhd
================================================================================
Phase 1 of 7... Reporting
Total Rules Checked: 83
Total Violations:     3
  Error   :     3
  Warning :     0
----------------------------+------------+------------+--------------------------------------
  Rule                      |  severity  |  line(s)   | Solution
----------------------------+------------+------------+--------------------------------------
  port_021                  | Error      |         45 | Move the ( to the same line as the "port" keyword.
  instantiation_034         | Error      |        169 | Change to component instantiation
  generic_map_003           | Error      |        170 | Move the ( to the same line as the "generic map" keyword.
----------------------------+------------+--------------------------------------
NOTE: Refer to online documentation at https://vhdl-style-guide.readthedocs.io/en/latest/index.html for more information.

VSG will report the rule which is violated and the line number or group of lines where the violation occured. It also gives a suggestion on how to fix the violation. The rules VSG uses are grouped together into Phases. These phases follow the order in which the user would take to address the violations. Each rule is detailed in the Rules section. The violation and the appropriate fix for each rule is shown.

The violations can be fixed manually, or use the –fix option to have VSG update the file.

$ vsg -f example/architecture-empty.vhd
================================================================================
File:  example/architecture-empty.vhd
================================================================================
Phase 7 of 7... Reporting
Total Rules Checked: 378
Total Violations:    0

If rule violations can not be fixed, they will be reported after fixing everything else:

$ vsg -f example/architecture-empty.vhd
================================================================================
File:  example/architecture-empty.vhd
================================================================================
Phase 1 of 7... Reporting
Total Rules Checked: 83
Total Violations:     1
  Error   :     1
  Warning :     0
----------------------------+------------+------------+--------------------------------------
  Rule                      |  severity  |  line(s)   | Solution
----------------------------+------------+------------+--------------------------------------
  instantiation_034         | Error      |        169 | Change to component instantiation
----------------------------+------------+--------------------------------------
NOTE: Refer to online documentation at https://vhdl-style-guide.readthedocs.io/en/latest/index.html for more information.