314 lines
11 KiB
ReStructuredText
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.
|