ohsh 0.4.0rc1

ohsh is a humble command-line tool that works out which HDL source files (SystemVerilog and VHDL) a design needs and in what order to compile them. Each module gets a manifest.json that lists its sources and the modules it depends on. ohsh reads the manifests and writes plain .src file lists, one per library and language.

ohsh works alongside build flows such as hog, Vivado, Quartus, Questa, cocotb and VUnit. It does not run simulators, manage tool projects or parse your HDL.

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.
• Checks that every listed source file exists.
• Creates, fixes and checks manifests by reading the HDL sources (best effort).
• Pure Python with no runtime dependencies.

Installation

pip install ohsh

Or from a clone, which needs Python 3.9 or newer:

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

Usage

The Getting started guide walks through a small project from install to compiled sources.

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

Manifest actions

These options work on the manifests under --top-dir instead of writing source lists. They read the sources to find which design units each file declares and uses. --fix and --check work on all modules, or on MODULE and its dependencies when one is given. See Create, fix and check manifests.

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

The full documentation is at ohsh.readthedocs.io:

• Getting started
• Manifest file format
• Integrations with simulators and build tools
• Create, fix and check manifests
• Exit codes
• Contributing and development

License

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

Author

Ola Groettvik - GitHub

AI assistance

ohsh started as a hand-written script. Most later development was done with AI assistance, with all changes reviewed and tested by the author.