Usage

hdltbgen is used through the command line.

Basic command

The minimal invocation requires an input file and at least one output type:

hdltbgen --file my_design.vhd --type vhdl

Short-option form:

hdltbgen -f my_design.vhd -t vhdl

Common examples

Generate a VHDL testbench into the same folder as the input file:

hdltbgen -f rtl/my_design.vhd -t vhdl

Generate VHDL and CSV artifacts into a dedicated output directory:

hdltbgen -f rtl/my_design.vhd -t vhdl -t csv -o build/tb

Generate an Excel workbook (requires optional Excel dependencies):

hdltbgen -f rtl/my_design.vhd -t excel -o build/tb

Mark a specific clock and reset explicitly:

hdltbgen -f rtl/my_design.vhd -t vhdl -c clk_i -rn rst_n

Generate a VUnit-compatible testbench and a separate simulation wrapper:

hdltbgen -f rtl/my_design.vhd -t vhdl -v -s

Prompt for generic values interactively:

hdltbgen -f rtl/my_design.vhd -t vhdl -a

Argument overview

Required arguments:

  • --file or -f: path to the VHDL input file

  • --type or -t: output type, repeatable for multiple generators

Optional arguments:

  • --output or -o: target directory for generated files

  • --clock or -c: one or more clock signal names

  • --reset-negative or -rn: one or more active-low reset names

  • --reset-positive or -rp: one or more active-high reset names

  • --vunit or -v: enable VUnit-specific additions in generated VHDL

  • --simfile or -s: generate a separate simulation wrapper file

  • --ask or -a: prompt for generic values during parsing

The full autogenerated argument reference is available in Command-Line Interface.

Optional dependency note

The Excel generator (-t excel) depends on optional packages. Install them with:

pip install "hdltbgen[excel]"

What happens on invalid input

The CLI stops with an exception in these common situations:

  • the input file does not exist

  • the input file extension is not supported

  • a named clock or reset signal is not part of the parsed port list

  • an unknown generator type is requested

Practical recommendations

For predictable results:

  • pass --clock and reset options explicitly when the port naming does not follow common conventions

  • use --ask when your entity has generics and you want immediately compilable VHDL output

  • generate CSV or Excel together with VHDL when the testbench should be driven by editable vector files