sv2svg 0.8.1

SystemVerilog to SVG using Schemdraw (left-to-right logic diagrams)

sv2svg

Convert SystemVerilog modules into readable logic-diagram SVGs with a single CLI command. sv2svg parses structural HDL, places gates left-to-right, and outputs Schemdraw-based graphics that stay aligned and symmetric.

Highlights

• Deterministic left-to-right layout with minimal crossings
• Automatic input ordering (alphabetical, module ports, or auto)
• Optional grid snapping and symmetry controls
• CLI-first workflow with --help, --version, --style, and --orientation discovery
• Semantic-release driven SemVer tagging and automated PyPI publishing

Installation

Choose one of the following approaches:

• uvx (no install):

  uvx sv2svg --help
  

• uv run:

  uv run sv2svg --help
  

• Virtual environment:

  python3 -m venv .venv
  source .venv/bin/activate
  pip install --upgrade pip
  pip install sv2svg
  

• Editable checkout:

  python3 -m venv .venv
  source .venv/bin/activate
  pip install --upgrade pip
  pip install -e .
  

Quickstart

sv2svg --help
sv2svg --version
sv2svg examples/full_adder.sv --style blueprint --orientation vertical -o full_adder.svg

The last command renders examples/full_adder.sv into an SVG file in the working directory (falls back to full_adder_schemdraw.svg when -o is omitted) using the "blueprint" color preset and a vertical layout.

CLI reference

usage: sv2svg [-h] [-o OUTPUT] [--input-order {alpha,ports,auto}] [--grid-x GRID_X]
              [--grid-y GRID_Y] [--no-symmetry]
              [--style {classic,blueprint,midnight,mono}]
              [--orientation {horizontal,vertical}] [-V]
              input_file

• input_file — source SystemVerilog file with the module to visualize
• -o / --output — target SVG file path (- writes SVG to stdout)
• --input-order — sort inputs alphabetically, preserve declaration order, or auto-detect
• --grid-x, --grid-y — snap coordinates to half-grid (0 disables snapping)
• --no-symmetry — disable mirrored placement for sibling signals
• --style — select a color/line-weight preset for the output (classic, blueprint, midnight, mono)
• --orientation — choose horizontal (default left-to-right) or vertical (top-to-bottom) layout; vertical mode currently produces rotated SVG output only
• -V / --version — print the sv2svg version derived from git metadata

Tips for better diagrams

• Keep each module in its own file and ensure port declarations are explicit.
• The parser expects synthesizable structural constructs; unsupported statements raise errors during generation.
• Use the grid options to align gates when mixing manual annotations with generated drawings.

Supported SystemVerilog Constructs

sv2svg is designed for structural SystemVerilog where logic is described using explicit gate instantiations. It has limited support for behavioral assign statements:

✅ Fully Supported: Gate Instantiations

module example(a, b, y);
  input logic a, b;
  output logic y;
  
  logic ab;
  AND u1(a, b, ab);
  NOT u2(ab, y);
endmodule

⚠️ Limited Support: Simple Assign Statements

The tool recognizes basic two-input gate patterns in assign statements:

• assign y = a & b; → AND gate
• assign y = a | b; → OR gate
• assign y = a ^ b; → XOR gate
• assign y = ~(a & b); → NAND gate
• assign y = ~(a | b); → NOR gate
• assign y = ~(a ^ b); → XNOR gate
• assign y = ~a; → NOT gate

❌ Not Supported: Complex Expressions

The parser cannot handle:

• Mixed operators: assign y = a & b | c;
• Multi-input gates: assign y = a & b & c;
• Nested expressions: assign y = (a & b) | (c ^ d);
• Arbitrary Boolean expressions

For complex logic, decompose it into explicit gate instantiations for proper visualization.

Development workflow

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
python -m sv2svg.cli --version

Run the CLI against fixtures or your own modules; any Python exception surfaces with a clear message.

Testing

The CI workflow (.github/workflows/ci.yml) installs the package in editable mode and performs an import smoke test. Extend it with richer checks as the project grows.

Release automation

• Commits merged to main must follow Conventional Commits so semantic-release can infer version bumps.
• On qualifying commits, the Release workflow updates CHANGELOG.md, tags the release, publishes GitHub release notes, and uploads the built artifacts to PyPI using trusted publishing.
• Local builds without git metadata fall back to version 0.0.0; regular development builds look like 0.2.1.dev0+g8733005aa.d20250922 courtesy of hatch-vcs.

Contributing

Issues and pull requests are welcome. Please include reproduction snippets for parser bugs and respect the release automation by using Conventional Commit messages.

License

MIT