Module reference (user manual)

Per-module reference for the hdlpkg library and the hdlpkg CLI. Each page covers one module's purpose, public API, behavior, errors, and a worked example. New to the tool? Start with the User guide; for the design rationale and how the modules fit together, see architecture.md.

The library is layered, with a pure core (parsing/logic, no I/O) and I/O only at the edges (the CLI and registry/cache). The pages below follow that flow:

Foundation (pure value types)

Module	What it covers
Versioning	Version + VersionConstraint: SemVer parsing, ordering, constraint matching
Identity (VLNV)	PackageRef + Vlnv: how a core is named
Manifest (ip.toml)	The Manifest model + the ip.toml format, plus the init scaffolder
Errors	The HdlPackagerError exception hierarchy

Resolve & record

Module	What it covers
Resolver	resolve → selected version(s) per package (Cargo-style unification, on-conflict policy, scheme-aware)
Lockfile (ip.lock)	Serialize/verify a resolution with per-core source + SHA-256

Distribute

Module	What it covers
Content-addressed cache	SHA-256-keyed local blob store with verify-on-read
Registry	The Registry interface + local / HTTP / OCI backends and registry_from_location
Credentials	Per-host bearer tokens for private registries (hdlpkg login)
Packaging (.ipkg)	The deterministic .ipkg artifact: build, extract, read

Generate & interop

Module	What it covers
Tool-flow backends	EDAM intermediate → Verilator / Vivado / Icarus / GHDL / Yosys inputs
Name-mangling	SystemVerilog/VHDL package renaming so two versions coexist in one gen build
IP-XACT export	IEEE 1685-2014 component XML
SBOM (CycloneDX)	Deterministic CycloneDX 1.5 bill of materials

Interface

Module	What it covers
CLI (hdlpkg)	Full command reference for every hdlpkg subcommand

The public API is re-exported from the top-level package, so from hdlpkg import Manifest, resolve, pack_core, … works directly.