vsg-rs

A fast Rust-native VHDL formatter and style checker with VSG-compatible rules and configuration.

vsg-rs is an independent Rust implementation of a VHDL formatter and style checker that aims for compatibility with the rules and configuration of the VHDL Style Guide (VSG). It is not affiliated with, endorsed by, or maintained by the VHDL Style Guide project or its maintainers.

vsg-rs was inspired by the VHDL Style Guide (VSG) project by Jeremiah Leary and contributors. vsg-rs contains no VSG code; VSG is used only as a behavioural reference.

Status: beta. Formatting is tested against a corpus of more than 11,000 real-world files. 192 VSG rules are implemented as lint rules with fixes (structure, identifier case, naming, comments, length_001), and the other 779 layout rules are covered by the formatter's policy (blank lines, alignment, keyword case, indentation). Expect layout changes before 1.0.

Why

• A real formatter. Formatting is not "run the lint rules and apply their fixes". Source is parsed once into a lossless syntax tree and printed in one canonical layout, like rustfmt or Black. Running it twice changes nothing.
• Long lines are folded, not just reported. length_001 becomes a formatter capability: calls, maps, aggregates, expressions, conditions, declarations and assignments fold at structural boundaries (see docs/line-folding.md).
• Safe for format-on-save. Every result is re-parsed and checked to contain exactly the same tokens and comments before it is used. Files with syntax errors are left untouched. In pipe mode, stdout carries nothing but the formatted source.
• No fix phases. No --fix runs that must be repeated until they converge, and no rule-order dependencies. Fixes that could change behaviour are only applied on request (--unsafe-fixes).
• Fast. Formatting a typical file from stdin takes a few milliseconds; parsing, formatting and verifying real-world VHDL runs at about 3.4 MB/s on one core, and files are processed in parallel (performance).

Usage

pip install vsg-rs                     # Linux and Windows wheels, Python 3.10+ (or: uv tool install vsg-rs)
cargo install --path .                 # from source

vsg-rs fmt src/                        # format files in place
vsg-rs fmt --check src/                # CI: exit 1 if anything would change
vsg-rs fmt --diff src/foo.vhd          # show what would change
vsg-rs fmt --line-length 100 src/
cat foo.vhd | vsg-rs fmt --stdin-filename foo.vhd -   # editor integration
cat foo.vhd | vsg-rs fmt --range 10:24 -              # only lines 10 to 24

vsg-rs lint src/                       # report rule violations
vsg-rs check src/                      # CI: violations and unformatted files
vsg-rs check --output-format sarif src/ > vsg.sarif   # also json, junit, gitlab, syntastic, summary
vsg-rs fix src/                        # apply all safe fixes, then format
vsg-rs fix --unsafe-fixes --diff src/  # also fixes that may change behaviour (review them)
vsg-rs rules --all                     # every VSG rule and how vsg-rs handles it

Configuration uses the VSG format (YAML or JSON). It is read from --config FILE, or from the nearest vsg-rs.yaml / .vsg-rs.yaml (or .json):

rule:
  length_001:
    length: 100
  process_016:
    disable: true
  group:
    case::name:
      case: lower
file_rules:
  legacy/**/*.vhd:
    rule:
      length_001:
        disable: true

Formatting can be switched off for a region with -- vsg-rs: fmt off / -- vsg-rs: fmt on; VSG's -- vsg_off [rule ...] / -- vsg_on comments suppress rules.

Editor integration

Configure your editor to pipe the buffer through vsg-rs fmt --stdin-filename <path> - (add --range START:END to format selected lines). On success (exit code 0) the buffer is replaced with stdout. On failure (exit code 2) stdout is empty and stderr explains why; leave the buffer unchanged. See docs/editors.md for VS Code, Neovim, Helix and Emacs setups.

Documentation

• Architecture
• Editor integration (pipe mode)
• Formatting, line folding and its coverage matrix
• VHDL frontend (why vhdl_syntax)
• Compatibility with VSG and rule status
• Performance
• Releasing (Python package, platforms, release workflow)
• VSG configuration model, VSG rule catalog
• Known VSG bugs and limitations that vsg-rs is designed to avoid

Development

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo run --release --example corpus -- --width 80 path/to/vhdl   # stability and overflow report
UPDATE_EXPECT=1 cargo test --test golden                           # re-bless golden files (review the diff)

License

vsg-rs is licensed under either of Apache License, Version 2.0 or MIT license, at your option. Third-party dependencies are listed in THIRD_PARTY_LICENSES.md. The VHDL parser, vhdl_syntax from the rust_hdl project, is MPL-2.0 and is used as an unmodified dependency.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in vsg-rs, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.