ohsh

ohsh is a small, deliberately humble command-line tool that figures out, in the right order, which HDL (SystemVerilog and VHDL) source files your design needs - by reading simple per-module manifest.json files and resolving their dependencies.

It is a companion to the big build flows (like hog, Vivado, Quartus, Questa, cocotb, VUnit, …), not a replacement for them. ohsh just answers one question well - "what files, in what order, for which libraries?" - and hands you plain .src lists you can feed anywhere.

Features

• Auto-discovers HDL module manifests anywhere under a project tree.
• Resolves module dependencies recursively, across libraries.
• Detects circular dependencies and exits with an error naming the cycle.
• Emits ordered, per-library source lists for SystemVerilog and VHDL.
• Writes the order to compile the libraries in.
• Validates that every referenced source file actually exists.
• Pure Python, zero runtime dependencies.

Installation

pip install ohsh

Or from a clone:

git clone https://github.com/logvik-org/ohsh.git
cd ohsh
pip install .

Usage

ohsh [OPTIONS] MODULE

ohsh will:

1. Search for all manifest*.json files starting from --top-dir.
2. Resolve dependencies for MODULE (the top-level).
3. Generate ordered SystemVerilog and VHDL source lists per library.
4. Write them as <lib>_systemverilog.src / <lib>_vhdl.src in the output directory.
5. Write the library compile order to libraries.src.

Options

Example

Give each module a manifest.json next to its sources:

project/
├── accumulator/
│   ├── accumulator.vhd
│   └── manifest.json
└── adder/
    ├── adder.vhd
    └── manifest.json

{
  "module": "accumulator",
  "sources": ["accumulator.vhd"],
  "dependencies": {
    "work": ["adder"]
  }
}

{
  "module": "adder",
  "sources": ["adder.vhd"]
}

Then run ohsh in the project directory with the top module's name:

cd project
ohsh accumulator

It writes work_vhdl.src with the sources in compile order:

/path/to/project/adder/adder.vhd
/path/to/project/accumulator/accumulator.vhd

and libraries.src with the libraries to compile (here only work). Modules with SystemVerilog sources go to <lib>_systemverilog.src in the same way. See the manifest file format for dependencies across libraries.

libraries.src lists the library names, one per line, in the order to compile them: each library comes after the libraries it uses. Compile the libraries in this order rather than hard-coding it. If libraries depend on each other in a loop (a module in libA uses libB and a module in libB uses libA), no such order exists. ohsh then logs a warning and writes a best-effort order, which works for tools that sort files themselves (such as Vivado or Quartus projects) but may fail with tools that compile one library at a time.

Documentation

• Manifest file format
• Exit codes
• Integrations with simulators and build tools
• Contributing and development

License

Licensed under the Apache License 2.0. See LICENSE and NOTICE.

Author

Ola Groettvik - GitHub

Contributions, issues, and suggestions are welcome!