ohsh - Ola's HDL Source Handler

ohsh is a small, deliberately humble command-line tool that figures out, in the right order, which HDL (Verilog / SystemVerilog / 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.

So simple it's an oh sh… that was easy moment. 🙂

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 Verilog 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 Verilog and VHDL source lists per library.
4. Write them as <lib>_verilog.src / <lib>_vhdl.src in the output directory.
5. Write the library compile order to libraries.src.

Options

Example

ohsh -t /path/to/hdl_project -w mylib -o ./src_lists top_module

Produces:

src_lists/
├── libraries.src
├── mylib_verilog.src
└── mylib_vhdl.src

Each <lib>_verilog.src / <lib>_vhdl.src file contains absolute paths to the source files, one per line, in compilation order.

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!