##########
Generators
##########

hdltbgen can emit three artifact types from the same parsed entity model.

VHDL generator
==============

The VHDL generator creates a testbench skeleton that includes:

* a generated header block
* standard IEEE library imports
* optional VUnit imports
* signal declarations for entity ports
* constants for generics
* DUT instantiation
* a generated clock process
* reset sequencing
* CSV-driven stimulus application and response checking logic

When ``--simfile`` is enabled, the generator creates an additional wrapper file that
instantiates both the DUT and the generated testbench entity.

The generated VHDL relies on a CSV test vector file named after the entity, so the
CSV artifact is part of the expected workflow even if it is created or maintained
later.

CSV generator
=============

The CSV generator creates a structured text file for test vectors.

Its content includes:

* a comment-like header section
* a port information summary
* separated input and output signal listings
* placeholder space for user-defined test steps

Clock ports are intentionally excluded from the editable vector section.

Excel generator
===============

The Excel generator creates a workbook intended for manual vector editing. It:

* builds a worksheet named after the entity
* writes the same header information used by the other generators
* groups stimulus columns and response columns
* freezes panes for easier editing
* inserts highlighted placeholder sections for reset and test steps
* attempts to embed VBA code for CSV export on save

The final target format is a macro-enabled workbook with the extension ``.xlsm``.

Excel-specific requirement
==========================

The Excel path depends on local Microsoft Excel automation through xlwings.

Python dependencies for the Excel generator are optional and can be installed with:

.. code-block:: bash

	pip install "hdltbgen[excel]"

If VBA insertion fails, hdltbgen prints guidance that Excel must allow access to
the VBA project object model. On systems without a working Excel installation,
the Excel generator is therefore the least portable option.