vhdl-style-guide/docs/usage.rst

293 lines
15 KiB
ReStructuredText

Usage
=====
VSG is a both a command line tool and a python package.
The command line tool can be invoked with:
.. code-block:: text
$ 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] [--stdin]
[--quality_report QUALITY_REPORT] [-p JOBS]
[--debug]
[FILENAME ...]
Analyzes VHDL files for style guide violations. Reference documentation is
located at: http://vhdl-style-guide.readthedocs.io/en/latest/index.html
positional arguments:
FILENAME File to analyze
options:
-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.
--stdin Read VHDL input from stdin, disables all other file
selections, disables multiprocessing
--quality_report QUALITY_REPORT
Create code quality report for GitLab
-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. |
| | The path to each file can also be specified. |
| | File globbing is also supported. |
+-------------------------------+-------------------------------------------------+
| --stdin | Reads VHDL file input from standard in put |
| | instead of reading from a file or files. Can be |
| | useful for using with other tools such as |
| | editors that can interact through stdin/stdout |
| | for diagnostics |
+-------------------------------+-------------------------------------------------+
| --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. |
| | The path to the file can also be specified, but |
| | the destination directory must exist. |
+-------------------------------+-------------------------------------------------+
| --json | Filename of JSON file to generate. |
| | The path to the file can also be specified, but |
| | the destination directory must exist. |
+-------------------------------+-------------------------------------------------+
| --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. |
| | NOTE: This is only valid when using --fix. |
+-------------------------------+-------------------------------------------------+
| --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. |
| | The path to the file can also be specified, but |
| | the destination directory must exist. |
+-------------------------------+-------------------------------------------------+
| --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. |
| | NOTE: This is not valid with the --fix option. |
+-------------------------------+-------------------------------------------------+
| --fix_only | Restrict which rules are fixed based on JSON |
| | file. |
+-------------------------------+-------------------------------------------------+
| --quality_report | Write a quality report which can be used by |
| | GitLab |
+-------------------------------+-------------------------------------------------+
| --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 |
| | debugging errors with VSG. |
+-------------------------------+-------------------------------------------------+
Here is an example output running against a test file:
.. code-block:: text
$ 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 occurred.
It also gives a suggestion on how to fix the violation.
The rules VSG uses are grouped together into :doc:`phases`.
These phases follow the order in which the user would take to address the violations.
Each rule is detailed in the :doc:`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.
.. code-block:: text
$ 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 that can be mixed:
.. code-block:: text
$ 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.
Use Cases
#########
The following examples show how to perform certain tasks with VSG.
Checking a single file
----------------------
.. code-block:: text
$ vsg -f fifo.vhd
Checking a single file over standard input
------------------------------------------
.. code-block:: text
$ vsg --stdin
Checking multiple files using globbing
--------------------------------------
.. code-block:: text
$ vsg -f *.vhd
Checking multiple files in different directories
------------------------------------------------
.. code-block:: text
$ vsg -f fifos/src/*.vhd cpu_core/src/*.vhd usb_hub/src/*.vhd
Checking all files in a project
-------------------------------
.. code-block:: text
$ find . -name "*.vhd" -exec vsg -f {} \;
Integration with CI server
--------------------------
.. code-block:: text
$ vsg -f fifos/src/*.vhd --junit fifos/src/fifos_junit.xml
Fixing a single file
--------------------
.. code-block:: text
$ vsg -f fifo.vhd --fix
Fixing multiple files using globbing
------------------------------------
.. code-block:: text
$ vsg -f *.vhd --fix
Fixing all files in a project
-----------------------------
.. code-block:: text
$ find . -name "*.vhd" -exec vsg -f {} --fix \;
Error Codes
###########
One of the following error codes will be returned after running VSG:
+------------+-------------------------------------------------+
| Error Code | Description |
+------------+-------------------------------------------------+
| 0 | VSG ran without encountering any errors and no |
| | rule violations were detected. |
+------------+-------------------------------------------------+
| 1 | VSG ran and detected a rule violation. |
+------------+-------------------------------------------------+
| 2 | An attempt was made to configure a rule which |
| | was deprecated. |
+------------+-------------------------------------------------+