Usage¶

Installation¶

pip install svhier

Or, if you are working from source with uv:

uv sync

Quick start¶

Parse a single file and print the hierarchy to stdout:

svhier top.sv --yaml

Parse an entire directory recursively and write both outputs to files:

svhier -r rtl/ --yaml hierarchy.yaml --filelist compile.f

Command-line reference¶

Parse SystemVerilog files and emit a module hierarchy as YAML.

usage: svhier [-h] [-r] [--yaml [FILE]] [--filelist [FILE]] [--no-summary]
              PATH [PATH ...]

Positional Arguments¶

PATH: One or more .sv/.v files or directories containing .sv/.v files.

Named Arguments¶

-r, --recursive

Recurse into subdirectories when a directory is given.

Default: False

--yaml

Write YAML hierarchy to FILE, or to stdout when FILE is omitted.

--filelist

Write dependency-ordered filelist to FILE, or to stdout when FILE is omitted.

--no-summary

Suppress the summary table printed to stderr.

Default: False

Note

All diagnostic output (spinner, summary table, warnings, errors) goes to stderr so that --yaml and --filelist stdout output can be piped safely.

YAML output¶

The --yaml output describes the module/instance hierarchy of every parsed file. Each file entry lists the modules defined there together with their direct child instances and package imports.

files:
- file_name: rtl/alu.sv
  defs:
  - mod_name: alu
    insts:
    - mod_name: adder
      inst_name: u_add
    - mod_name: mux2
      inst_name: u_mux
- file_name: rtl/adder.sv
  defs:
  - mod_name: adder
- file_name: rtl/mux2.sv
  defs:
  - mod_name: mux2

Note

Modules that are defined but never instantiated still appear in defs with an empty insts list.

Package imports are shown when present:

- mod_name: alu
  pkg_imports:
  - alu_pkg
  insts: []

Filelist output¶

The --filelist output is a plain text file listing source files in dependency order (dependencies before dependants), ready to pass to a simulator or synthesis tool.

// Generated by svhier — files in compilation order
+incdir+rtl/include
rtl/adder.sv
rtl/mux2.sv
rtl/alu.sv

+incdir+ lines are emitted for any directory that contains .svh/.vh header files. The format is compatible with VCS, Questa, and Xcelium.

Tip

If a dependency cycle is detected, svhier falls back to the original input order and continues without error.

Exit codes¶

Code	Meaning
`0`	Elaboration completed with no errors
`1`	pyslang reported one or more error-level diagnostics