vhdl-style-guide/README.rst

314 lines
11 KiB
ReStructuredText

VHDL Style Guide (VSG)
======================
**Coding style enforcement for VHDL.**
.. image:: https://img.shields.io/github/tag/jeremiah-c-leary/vhdl-style-guide.svg?style=flat-square
:target: https://github.com/jeremiah-c-leary/vhdl-style-guide
:alt: Github Release
.. image:: https://img.shields.io/pypi/v/vsg.svg?style=flat-square
:target: https://pypi.python.org/pypi/vsg
:alt: PyPI Version
.. image:: https://img.shields.io/codecov/c/github/jeremiah-c-leary/vhdl-style-guide/master.svg?style=flat-square
:target: https://codecov.io/github/jeremiah-c-leary/vhdl-style-guide
:alt: Test Coverage
.. image:: https://img.shields.io/readthedocs/vsg.svg?style=flat-square
:target: http://vhdl-style-guide.readthedocs.io/en/latest/index.html
:alt: Read The Docs
.. image:: https://api.codacy.com/project/badge/Grade/42744dca97544824b93cfc99e8030063
:target: https://www.codacy.com/app/jeremiah-c-leary/vhdl-style-guide?utm_source=github.com&utm_medium=referral&utm_content=jeremiah-c-leary/vhdl-style-guide&utm_campaign=Badge_Grade
:alt: Codacy
Announcements
-------------
Update 11/09/2025
Where has Jeremy been?
Just wanted to let everyone know that I have not abandoned this project.
There was a family emergency I had to handle and now work is taking a significant amount of my time.
I plan to start working on this again in December.
Regards,
--Jeremy
.. image:: https://github.com/jeremiah-c-leary/vhdl-style-guide/blob/master/docs/img/vim_macro.gif
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**.
.. code-block:: bash
pip install vsg
The latest development version can be cloned...
.. code-block:: bash
git clone https://github.com/jeremiah-c-leary/vhdl-style-guide.git
Install prerequisites.
.. code-block:: bash
pip install tox
Build locally, artifacts will appear in ``dist`` directory.
.. code-block:: bash
tox
Fork for ``vsg_bridge_ls``
~~~~~~~~~~~~~~~~~~~~~~~~~
This fork adds stream integration options so VSG can serve editor buffers.
``--diagnostics_json`` reads VHDL from ``--stdin`` and always writes one
versioned JSON diagnostic document to standard output. Failed analysis is a
valid document marked incomplete rather than missing or malformed JSON. Parser
failures include their best available one-based line and column so an editor can
replace stale style findings with a useful syntax error.
``--stdout`` writes fixed VHDL to standard output; if stdin cannot be parsed or
fixing otherwise fails, it returns the original input unchanged so callers get
a safe no-op rather than an empty replacement. Repeatable ``--fix_rule
RULE:LINE`` arguments restrict
``--fix`` to selected rules and one-based lines; they require ``--fix`` and
cannot be combined with ``--fix_only``. ``--no-failure`` permits diagnostic
findings without a nonzero process status. It is the VSG backend required for
`vsg_bridge_ls <https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls>`_.
The bridge README is the main user guide for installing both projects and
configuring an editor.
LLM disclosure and safety
^^^^^^^^^^^^^^^^^^^^^^^^^
* **Human foundation:** the original VSG parser, rules, fix engine, and command
line tool predate this fork and are the work of Jeremy C. Leary and upstream
contributors. The fork maintainer chooses its scope and accepts releases.
* **LLM-assisted work:** the fork-specific stream interface, machine-readable
diagnostics, scoped-fix adapter, packaging, tests, and related documentation
were developed or refined with an LLM coding assistant under maintainer
direction.
* **What is tested:** focused tests cover option validation, deterministic JSON,
Unicode, clean and invalid input, stdout/stderr separation, selected fixes,
and unchanged output for an unknown rule. CI also runs the upstream test and
style suites, builds the package, and smoke-tests installed wheels through
both pip and uv. Tests reduce risk; they do not prove the absence of defects.
* **Practical risk:** ``--diagnostics_json`` only serializes information
collected during normal parsing and rule analysis. It does not modify the
submitted VHDL, change formatting, write the source file, or use an LLM at
runtime. Existing VSG behavior is unchanged when the fork options are absent.
Explicit ``--fix``/``--stdout`` operations are different: they intentionally
return corrected VHDL, which a caller may then apply. Review generated edits
and use version control, especially for safety-critical HDL. See the
`full authorship, testing, and risk disclosure <DISCLOSURE.md>`_ for details.
The preferred installation uses uv and the prebuilt Gitea package:
.. code-block:: bash
uv venv .venv
uv pip install --python .venv/bin/python \
--index https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \
vsg
Installing from ``master`` also works with uv, and either source works with
standard pip. See the bridge's
`installation guide <https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls/src/branch/main/doc/installation.md>`_
for all supported commands and environment setup.
Fork maintainers can build locally with ``./build-package.sh`` and publish the
new artifacts with:
.. code-block:: bash
./build-package.sh ../gitea_token.txt --publish
On ``master``, Jenkins fetches the Git tags used by
``setuptools-git-versioning``, runs both installation smoke tests, archives the
generated distributions, and publishes those exact artifacts to Gitea. The
required Jenkins credential is documented in the bridge development guide.
Use ``./update-fork.sh`` to fetch upstream tags and rebase the small fork patch
series onto the latest upstream ``master``. The script requires a clean
worktree and automatically aborts a failed rebase.
Usage
-----
VSG is a both a command line tool and a python package.
The command line tool can be invoked with:
.. code-block:: bash
$ 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:
.. image:: https://github.com/jeremiah-c-leary/vhdl-style-guide/blob/master/docs/img/fixing_single_file.gif
pre-commit Integration
----------------------
Here is an example of ``.pre-commit-config.yaml`` file:
.. code-block:: yaml
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 <http://vhdl-style-guide.readthedocs.io/en/latest/index.html>`_.
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 <http://vhdl-style-guide.readthedocs.io/en/latest/index.html>`_ for more details on contributing.