VHDL‐LS Configuration

The vhdl_ls.toml file configures the VHDL Language Server (vhdl_ls). This file defines which VHDL libraries are available, their source files, linting rules, and code formatting preferences.

File Location and Configuration Resolution

The language server loads configuration files in the following order of priority (first to last):

1. .vhdl_ls.toml in the user's home directory (~/.vhdl_ls.toml)
2. File path specified in the VHDL_LS_CONFIG environment variable
3. vhdl_ls.toml in the workspace root (current project directory)

Settings in later files override those from previously loaded files. This allows for global defaults in your home directory and project-specific overrides in the workspace.

Example Resolution

If you have:

• ~/.vhdl_ls.toml (home) with standard = "2008"
• $VHDL_LS_CONFIG pointing to /path/to/shared/vhdl_ls.toml with standard = "2019"
• ./vhdl_ls.toml (workspace) with preferred_case = "upper_snake"

The final configuration will use standard = "2019" and preferred_case = "upper_snake" (combined from all three files).

Configuration Options

preferred_case

Controls the letter case used by the language server when providing code completions and generating suggestions.

• Type: string (enum)
• Required: no
• Default: (not set — the language server preserves original case without transformation)
• Valid values:
  • lower — lowercase (e.g., signal_name)
  • snake — snake_case (e.g., signal_name)
  • upper — UPPERCASE (e.g., SIGNAL_NAME)
  • upper_snake — UPPER_SNAKE_CASE (e.g., SIGNAL_NAME)
  • pascal — PascalCase (e.g., SignalName)
  • upper_camel — UpperCamelCase (e.g., SignalName)

Example:

preferred_case = "upper_snake"

---

standard

Specifies which VHDL standard the language server should use for linting and analysis.

• Type: string (enum)
• Required: no
• Default: "2008" (VHDL-2008 is used if not specified)
• Valid values:
  • 1993 or 93 — VHDL-1993
  • 2008 or 08 — VHDL-2008
  • 2019 or 19 — VHDL-2019

Note

As of April 2024, this is a relatively new feature. Currently, most improvements are for VHDL-2008. Other standards have limited semantic analysis enhancements.

Example:

standard = "2008"

---

libraries

Defines the VHDL libraries available in your project. Each library must have at least a files entry specifying source files.

• Type: object
• Required: yes (must have at least one library)
• Library naming rules:
  • Library names can be any string except work (which is reserved by VHDL).

Library Properties

Each library object can contain:

files

List of VHDL source files or glob patterns belonging to this library.

• Type: array of strings
• Required: yes
• Values: file paths (absolute or relative to vhdl_ls.toml)

Example:

[libraries.ieee2008]
files = [
  "lib/ieee_2008/std_logic_1164.vhd",
  "lib/ieee_2008/numeric_std.vhd"
]

exclude

List of file paths or glob patterns to exclude from analysis.

• Type: array of strings
• Required: no
• Values: file paths and glob patterns (e.g., legacy/*, test_*.vhd)

Example:

[libraries.my_project]
files = ["src/**/*.vhd"]
exclude = ["src/experimental/*", "src/*_old.vhd"]

is_third_party

Marks a library as third-party, which may affect how warnings and diagnostics are reported.

• Type: boolean
• Required: no
• Default: false

Example:

[libraries.unisim]
files = ['C:\Xilinx\Vivado\2023.1\data\vhdl\src\unisims\unisim_VCOMP.vhd']
is_third_party = true

---

lint

Configures linting rules and diagnostics. Each entry is a rule name mapped to a configuration value.

• Type: object (key-value pairs)
• Required: no
• Key naming: rule names are arbitrary strings (e.g., unused, unnecessary_work_library)
• Value type: string or boolean
  • true — enable the rule (use default severity)
  • false — disable the rule completely
  • String values — configure rule severity (e.g., "warn", "error")

Warning

You can configure any diagnostic error code, including syntax or analysis errors (e.g., syntax, mismatched_kinds). However, overwriting syntax or analysis errors can cause unwanted side effects. The intended use-case is for lints only.

Example:

[lint]
unused = "error"                    # Upgrade unused diagnostic to error
unnecessary_work_library = false    # Disable linting for 'library work;'
unused_signal = true                # Enable with default severity

---

Complete Example

# Preferred case for code completions
preferred_case = "upper_snake"

# VHDL standard to use for analysis (defaults to 2008)
standard = "2008"

# Define libraries
[libraries.ieee2008]
files = [
  "deps/ieee_2008/std_logic_1164.vhd",
  "deps/ieee_2008/numeric_std.vhd"
]
is_third_party = true

[libraries.my_project]
files = ["src/**/*.vhd"]
exclude = ["src/experimental/*", "src/*_old.vhd"]
is_third_party = false

# Configure linting rules
[lint]
unused = true
unnecessary_work_library = false

---

---

Path Resolution and Patterns

All file paths in vhdl_ls.toml are either absolute or relative to the directory containing the configuration file, not the current working directory. For example:

• If vhdl_ls.toml is at /project/vhdl_ls.toml and contains files = ["src/top.vhd"], the file is resolved as /project/src/top.vhd.

Glob Patterns

Glob patterns are supported in both files and exclude arrays:

• * — matches any sequence within a single directory level
• ** — matches across directory levels (e.g., src/**/*.vhd matches all .vhd files under src/ recursively)
• ? — matches a single character
• [abc] — matches any of the characters in the brackets

Example:

[libraries.my_lib]
files = ["src/**/*.vhd", "rtl/*.vhd"]
exclude = ["src/*_tb.vhd", "rtl/old/*"]

Environment Variables

On Unix machines (Linux, macOS), you can use environment variables in paths:

• $NAME or ${NAME} syntax expands environment variables
• Example: files = ["$PROJECT_ROOT/src/*.vhd"]

On Windows machines, use the %NAME% syntax instead:

• Example: files = ["%PROJECT_ROOT%/src/*.vhd"]

Schema validation

For IDE completion and correctness checking there is a JSON Schema that can be used by tools like taplo resp. Even Better TOML.