# Usage

## Installation

```bash
pip install svhier
```

Or, if you are working from source with [uv](https://docs.astral.sh/uv/):

```bash
uv sync
```

## Quick start

Parse a single file and print the hierarchy to stdout:

```bash
svhier top.sv --yaml
```

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

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

## Command-line reference

```{eval-rst}
.. argparse::
   :module: svhier.cli
   :func: _build_parser
   :prog: svhier
```

:::{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.

```yaml
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:

```yaml
- 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.

```text
// 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 |