vsg 3.26.0

Description:

vsg 3.26.0

Coding style enforcement for VHDL.
















Announcements
Update 02/10/2024
For Release 3.22.0.
In an attempt to be more consistent in the configuration files, the following options are changing from camelCase to snake_case:


option
Changed To



indentSize
indent_size

indentStyle
indent_style



An Error message will be generated if the old style is encountered.
A reminder to change the option to snake_case will be given.
Regards,
–Jeremy



Table of Contents

Overview
Key Benefits
Key Features
Known Limitations
Installation
Usage
Documentation
Contributing



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





Known Limitations
VSG is a continual work in progress.
As such, this version has the following known limitations:

Parser will not process embedded PSL
Parser will not process VHDL 2019



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
Install prerequisites.
pip install tox
Build locally, artifacts will appear in dist directory.
tox


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] [--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
Here is an example output running against a test file:



pre-commit Integration
Here is an example of .pre-commit-config.yaml file:
repos:
- repo: https://github.com/jeremiah-c-leary/vhdl-style-guide
rev: v3.18.0
hooks:
- id: vsg


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.