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.                                |
+------------+-------------------------------------------------+
