Go to file
Jeremiah Leary 8482d7490e Adding solutions to comment_004 and whitespace_007 rules. 2020-11-23 17:23:34 -06:00
.github Add GitHub issue and pull request templates 2019-06-15 01:10:15 +02:00
bin Move main logic into module 2018-08-31 11:24:22 +10:00
docs Updates for issues #464 and #465: 2020-11-22 21:42:29 -06:00
vsg Adding solutions to comment_004 and whitespace_007 rules. 2020-11-23 17:23:34 -06:00
.coveragerc Updates for issue #226 2019-04-05 07:25:11 -05:00
.gitignore Adding dist to ignore list. 2019-11-25 21:45:41 -06:00
.prospector.yaml Minor formatting updates for Codacy issues. 2020-01-02 11:58:48 -06:00
.travis.yml Preparing for Release 1.0. 2019-11-25 20:40:49 -06:00
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md 2018-11-01 23:25:42 -05:00
LICENSE
…
MANIFEST.in Updates for issue #350: 2020-05-18 09:14:08 -05:00
README.rst Updating conversion status. 2020-11-22 19:36:28 -06:00
setup.cfg Switching README to restructured text. 2019-06-09 14:07:25 -05:00
setup.py Adding minimum PyYAML requirement. 2020-09-24 22:30:12 -05:00
sonar-project.properties Attempting to add sonarsource. 2017-11-22 11:13:43 -06:00

README.rst

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/travis/jeremiah-c-leary/vhdl-style-guide/master.svg?style=flat-square
   :target: https://travis-ci.org/jeremiah-c-leary/vhdl-style-guide
   :alt: Build Status
.. 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
.. image:: https://badges.gitter.im/vhdl-style-guide/repo.png
   :target: https://gitter.im/vhdl-style-guide/community
   :alt: Gitter

Announcements
-------------

**11/22/2020**

All rules have been converted to the new parser and all previous tests are now passing.
Additional hardening will continue to be performed.

**11/12/2020**

More progress has been made and I have started the hardening phase of the rewrite.

**11/01/2020**

Significant progress has been made.
I have converter 430 out of 445 rules for the new parser.
Rule and parser hardening will being shortly after converting the last 15 rules.

**09/26/2020**

In order to address some outstanding issues, I decided to implement a new parser.
An initial parser has been complete.
I am now in the process of convertering existing rules to use the new parser.
Unfortunetely, at some point the master branch broke.

I have decided to keep moving forward instead of keeping backwards compatibility.

Below is a roadmap showing when I expect master to be working again.

.. image:: https://github.com/jeremiah-c-leary/vhdl-style-guide/blob/master/docs/img/roadmap.png



.. 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`_
*   `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

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

...and then installed locally...

.. code-block:: bash

    python setup.py install

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] [-of {vsg,syntastic}] [-b] [-oc OUTPUT_CONFIGURATION]
                                 [-rc RULE_CONFIGURATION] [--style {indent_only,jcl}] [-v] [--debug]
   
   Analyzes VHDL files for style guide violations. Reference documentation is located at: http://vhdl-style-
   guide.readthedocs.io/en/latest/index.html
   
   optional arguments:
     -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
     -of {vsg,syntastic}, --output_format {vsg,syntastic}
                           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
     --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

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.