Setting up a VUnit project in VS Code

This article explains how to set up VUnit  with the new Sigasi Project format. This method uses a scripted target to integrate VUnit’s compilation flow into Sigasi Visual HDL.

Prerequisites

Before you begin, you must have a working VUnit project. Specifically, you should be able to successfully run your test suite from the command line using a command like python run.py. This setup ensures that Sigasi only needs to hook into your existing, functional VUnit process.

Configuring ‘project.sigasi’

To integrate VUnit, you’ll need to add a scripted target to your project.sigasi file. Scripted targets specify compilation scripts, allowing Sigasi to execute them, intercept compiler invocations, and derive the project structure accordingly. You then configure the scripted target to use the built-in TCL interpreter and invoke the import_vunit procedure which simplifies the import of VUnit projects.

The following sections show two common configuration examples: one using system Python, and one with a virtual environment.

Without a Virtual Environment

If your python and VUnit installations are available directly in your system’s PATH, you only need to specify the path to your run.py script:

{
    "name": "vunit_example",
    "targets": {
        "vunit": {
            "interpreter": "tcl",
            "command": "import_vunit run.py"
        }
    }
}

Explanation of target fields:

• "interpreter": Specifies that the TCL interpreter bundled with SVH will be used for the target command (by default, a system shell is used).
• "command": Uses the import_vunit TCL procedure from the built-in package and specifies the path to a VUnit script.

With a Python Virtual Environment (venv)

Why Use a Virtual Environment? Using a Python virtual environment (venv) is highly recommended. It creates an isolated space for your project, keeping its dependencies (like VUnit) separate from other projects. This avoids dependency conflicts and ensures your project’s environment is reproducible.

If you manage your Python dependencies and VUnit installation within a Python virtual environment , you also have to specify the path to the virtual environment with a -venv option. This works for standard environments created with venv and also for environments created with modern alternatives like uv .

{
    "name": "venv_vunit_example",
    "targets": {
        "vunit": {
            "interpreter": "tcl",
            "command": "import_vunit -venv .venv run.py"
        }
    }
}

Note: You can use environment variables in the command. SVH will substitute their values before passing the command to the TCL interpreter, e.g.: "command": "import_vunit -venv $MY_VENV run.py"

Automating Test Execution

Once Sigasi can inspect your VUnit project through the scripted target, you can go a step further and automate compilation and test runs from inside VS Code. The Designflow Automation guide shows how to create a sigasiVUnitIntegration task that reuses the simulator configuration already defined by VUnit. This lets you trigger runs manually, bind them to a key, or let them watch your project for continuous feedback.

Conclusion

Once you have added this target to your project.sigasi file, Sigasi will automatically execute your VUnit script to discover all source files, libraries, and their compilation order. Your VUnit project will be fully integrated, and any changes to your run.py or HDL source files will be automatically detected and reflected in Sigasi Visual HDL.

If you experience any issues with the project setup, refer to the documentation on Scripted Targets for more advanced troubleshooting.