VHDL-Tool is configured through a single plaintext YAML file. The file needs to be at the root of your VHDL source code and must be named
To test your configuration file for common errors, run VHDL-Tool as below from the root of your source code (the same directory as the configuration file).
$ vhdl-tool check-config
#Define your project's libraries and source files here. #This section is compulsory. Libraries: #The name of the library. - name: hardware_lib #The paths where the source files for this library can be found. Use "**" to match arbitrarily nested directories. paths: - "hardware_lib/**/*.vhd" - "hardware_lib/**/*.vhdl"
- name: hardware_lib2 paths: - "hardware_lib2/**/*.vhd" - "hardware_lib2/**/*.vhdl"
#Point to the IEEE standard libraries - name: ieee paths: - "/home/awesome-vhdl-dev/ieee/*.vhd" - "/home/awesome-vhdl-dev/ieee/*.vhdl"
Preferences: #Enable/disable typechecking TypeCheck: True
#Display errors over multiple lines MultiLineErrors: True
#Enable/disable check-as-you-type CheckOnChange: True
#Enable/disable linting Lint: True
#Display the first sintax error only in a file FirstSyntaxErrorOnly: True
#Linter rule configuration. #Rules can be enabled or disabled. #Rules also have a severity. It may be one of Info, Warning, Critical or Error. Lint: #Threshold, below which messages are not displayed. Threshold: Warning
#Long form rule configuration. Both enabled/disabled status and severity can be configured this way. DeclaredNotAssigned: enabled: True severity: Warning #Default severity Warning
#Short form. Only enabled/disabled status can be specified. Severity is the default for the rule. DeclaredNotRead: True #Default severity Warning ReadNotAssigned: True #Default severity Critical SensitivityListCheck: True #Default severity Warning ExtraSensitivityListCheck: True #Default severity Warning DuplicateSensitivity: True #Default severity Warning LatchCheck: True #Default severity Critical VariableNotRead: True #Default severity Warning VariableNotWritten: True #Default severity Warning PortNotRead: True #Default severity Warning PortNotWritten: True #Default severity Critical NoPrimaryUnit: True #Default severity Warning DuplicateLibraryImport: True #Default severity Warning DuplicatePackageUsage: True #Default severity Warning DeprecatedPackages: True #Default severity Warning ImplicitLibraries: True #Default severity Warning DisconnectedPorts: True #Default severity Critical IntNoRange: True #Default severity Warning
Only the Libraries section is compulsory. The other sections assume sensible defaults.
This section defines the name and location of each library that can be imported in your source code. This section is compulsory because VHDL-Tool uses it to create an index of all types and identifiers so that it can type check and search your code.
It consists of a YAML list of records. Each record must contain "name" and "paths" fields. Name is straightforward — it specifies the name of the library that is being defined. Paths is a YAML list of locations where the source files for this library can be found. It may contain wildcards.
You may want to download the IEEE standard libraries from here and reference them from this section so that you can type check code that uses them and jump to identifiers defined in them. The example configuration file above does this.
PreferencesTypeCheck: Enable/disable typechecking.
MultiLineErrors: Display errors over multiple lines.
CheckOnChange: Enable/disable live check-as-you-type, instead of waiting for the file to be saved.
Lint: Enable/disable linting.
FirstSyntaxErrorOnly: Display the first syntax error only in a file.
This section enables/disables linting rules as well as optionally changing their severity from the default. A special "Threshold" key exists to set the threshold under which warnings will not be displayed. This section is only relevant for the premium version.
Lastly, the tags section tells VHDL-Tool which syntax elements to create tags for when invoked with the ctags argument. This is relevant, not just for generating tags, but for editor plugins which use the tags file to generate a file overview within the editor.