#####
Usage
#####

hdltbgen is used through the command line.

Basic command
=============

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

.. code-block:: bash

   hdltbgen --file my_design.vhd --type vhdl

Short-option form:

.. code-block:: bash

   hdltbgen -f my_design.vhd -t vhdl

Common examples
===============

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

.. code-block:: bash

   hdltbgen -f rtl/my_design.vhd -t vhdl

Generate VHDL and CSV artifacts into a dedicated output directory:

.. code-block:: bash

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

Generate an Excel workbook (requires optional Excel dependencies):

.. code-block:: bash

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

Mark a specific clock and reset explicitly:

.. code-block:: bash

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

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

.. code-block:: bash

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

Prompt for generic values interactively:

.. code-block:: bash

   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 :doc:`/code/cli`.

Optional dependency note
========================

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

.. code-block:: bash

   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