Configuring

VSG can use a configuration file to alter it’s behavior or include a list of files to analyze. This is accomplished by passing JSON and/or YAML file(s) through the –configuration command line argument. This is the basic form of a configuration file in JSON:

{
    "file_list":[
      "fifo.vhd",
      "source/spi.vhd",
      "$PATH_TO_FILE/spi_master.vhd",
      "$OTHER_PATH/src/*.vhd"
    ],
    "local_rules":"$DIRECTORY_PATH",
    "rule":{
        "global":{
            "attributeName":"AttributeValue"
        },
        "ruleId_ruleNumber":{
            "attributeName":"AttributeValue"
        }
    }
}

This is the basic form of a configuration file in YAML:

---
file_list:[
  - fifo.vhd
  - source/spi.vhd
  - $PATH_TO_FILE/spi_master.vhd
  - $OTHER_PATH/src/*.vhd
local_rules: $DIRECTORY_PATH
rule:
  global:
    attributeName: AttributeValue
  ruleId_ruleNumber:
      attributeName: AttributeValue
...

It is not required to have file_list, local_rules, and rule defined in the configuration file. Any combination can be defined. The order does not matter either.

Note

All examples of configurations in this documentation use JSON. However, YAML can be used instead.

file_list

The file_list is a list of files that will be analyzed. Environment variables will expanded. File globbing is also supported. The Environment variables will be expanded before globbing occurs. This option can be useful when running VSG over multiple files.

local_rules

Local rules can be defined on the command line or in a configuration file. If they are defined in both locations, the configuration will take precedence.

rule

Any attribute of any rule can be configured. Using global will set the attribute for every rule. Each rule is addressable by using it’s unique ruleId and ruleNumber combination. For example, whitespace_006 or port_010.

Note

If global and unique attributes are set at the same time, the unique attribute will take precedence.

Here are a list of attributes that can be altered for each rule:

Attribute Values Description
indentSize Integer Sets the number of spaces for each indent level.
phase Integer Sets the phase the rule will run in.
disable Boolean If set to True, the rule will not run.
fixable Boolean If set to False, the violation will not be fixed

Note

Some rules have additional attributes. These will be noted in the rule description.

Example: Disabling a rule

Below is an example of a JSON file which disables the rule entity_004

{
    "rule":{
        "entity_004":{
            "disable":true
        }
    }
}

Use the configuration with the –configuration command line argument:

$ vsg -f RAM.vhd --configuration entity_004_disable.json

Example: Setting the indent increment size for a single rule

The indent increment size is the number of spaces an indent level takes. It can be configured on an per rule basis…

{
    "rule":{
        "entity_004":{
            "indentSize":4
        }
    }
}

Example: Setting the indent increment size for all rules

Configure the indent size for all rules by setting the global attribute.

{
    "rule":{
        "global":{
            "indentSize":4
        }
    }
}

Configuring Uppercase and Lowercase Rules

There are several rules that enforce either uppercase or lowercase. They are noted in the documentation for each rule what the default is. The example violation and fixes are in reference to the default setting.

The default value for each of these case rules can be overridden using a configuration.

Overriding Default Case Enforcement

The default setting can be changed using a configuration. For example the rule constant_002 defaults to lowercase. We can use the following configuration to change the case to upper:

---

rule :
  constant_002 :
     case : 'upper'

Conversley, rule entity_008 defaults to uppercase. We can use the following configuration to change the case to lower:

---

rule :
  entity_008 :
     case : 'lower'

Changing Multiple Case Rules

If there are a lot of case rules you want to change, you can use the global option to reduce the size of the configuration. For example, if we want to uppercase everything except the entity name, we could write the following configuration:

---

rule :
  global :
    case : 'upper'
  entity_008 :
    case : 'lower'

Configuring Prefix and Suffix Rules

There are several rules that enforce specific prefixes/suffixes in different name identifiers. It is noted, in the documentation, what are the default prefixes/suffixes for each such rule.

All prefix/suffix rules are disabled by default. The default prefixes/suffixes for each of these rules can be overridden using a configuration.

Overriding Default Prefixes/Suffixes Enforcement

The default setting can be changed using a configuration. For example, the rule port_025 defaults to following suffixes: [‘_I’, ‘_O’, ‘_IO’]. We can use the following configuration to change allowed suffixes:

---

 rule :
     port_025:
         # Each prefix/suffix rule needs to be enabled explicitly.
         disable: false
         suffixes: ['_i', '_o']

The rule variable_012 defaults to following prefix: [‘v_’]. We can use the following configuration to change allowed prefix:

---

 rule :
     variable_012:
         # Each prefix/suffix rule needs to be enabled explicitly.
         disable: false
         prefixes: ['var_']

Configuring Number of Signals in Signal Declaration

VHDL allows of any number of signals to be declared within a single signal declaration. While this may be allowed, in practice there are limits impossed by the designers. Limiting the number of signals declared improves the readability of VHDL code.

The default number of signals allowed, 2, can be set by configuring rule signal_015.

Overriding Number of Signals

The default setting can be changed using a configuration. We can use the following configuration to change the number of signals allowed to 1.

---

rule :
  signal_015 :
     consecutive : 1

Configuring the Maximum Line Length

Limiting the line length of the VHDL code can improve readability. Code that exceeds the editor window is more difficult to read.

The default line length is 120, and can be set by configuring rule length_001.

Overriding Line Length

The default setting can be changed using a configuration. We can use the following configuration to change the line length to 180.

---

rule :
  length_001 :
     length : 180