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.

Note: This guide describes a manual setup method. Sigasi is working on a more streamlined VUnit integration for the new project format, which will be available in a future release.

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. This target will execute your VUnit run script and allow Sigasi to analyze the compilation calls.

The key is to instruct VUnit to use Sigasi’s compiler stubs instead of an actual simulator. This is done by setting the VUNIT_MODELSIM_PATH (or equivalent for your simulator) to point to Sigasi’s internal SIGASI_COMPILER_STUBS_DIRECTORY. This makes VUnit run the compilation phase, which Sigasi intercepts, without actually invoking a simulator.

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

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 must first activate it in the command. This method works for standard environments created with venv and also for environments created with modern alternatives like uv . Because the activation command and directory structure are platform-specific (bin on Linux/macOS vs. Scripts on Windows), you will need separate configurations if you work across different operating systems. You can read more about it in the official venv documentation .

For Linux

{
    "targets": {
        "vunit": {
            "environment": {
                "VUNIT_SIMULATOR": "modelsim",
                "VUNIT_MODELSIM_PATH": "$SIGASI_COMPILER_STUBS_DIRECTORY"
            },
            "command": ". .venv/bin/activate && python run.py -o $SIGASI_COMPILATION_LOG/../vunit-out --clean --compile --keep-compiling"
        }
    }
}

For Windows

On Windows, the command must call the activate.bat script and use Windows-style path separators (\).

{
    "targets": {
        "vunit": {
            "environment": {
                "VUNIT_SIMULATOR": "modelsim",
                "VUNIT_MODELSIM_PATH": "$SIGASI_COMPILER_STUBS_DIRECTORY"
            },
            "command": ".venv\\Scripts\\activate.bat && python run.py -o $SIGASI_COMPILATION_LOG\\..\\vunit-out --clean --compile --keep-compiling"
        }
    }
}

Explanation of key settings:

• "VUNIT_SIMULATOR": "modelsim": Tells VUnit which simulator configuration to use.
• "VUNIT_MODELSIM_PATH": "$SIGASI_COMPILER_STUBS_DIRECTORY": This is the crucial step. It redirects VUnit’s compiler calls to Sigasi’s stubs, allowing Sigasi to see the design files and compilation order.
• "command": This activates the virtual environment (. on Linux, .bat on Windows) and then runs the VUnit script.
• --clean --compile: These flags tell VUnit to always perform a clean compilation.
• --keep-compiling: Ensures VUnit tries to compile as many files as possible, even if some fail.
• -o ...: Sets the output path for VUnit. Note that Sigasi variables like $SIGASI_COMPILATION_LOG are substituted on all platforms.

Without a Virtual Environment

If your python and VUnit installation are available directly in your system’s PATH, the configuration is simpler as you don’t need to activate an environment. However, you should still be mindful of platform-specific path separators.

For Linux

{
    "targets": {
        "vunit": {
            "environment": {
                "VUNIT_SIMULATOR": "modelsim",
                "VUNIT_MODELSIM_PATH": "$SIGASI_COMPILER_STUBS_DIRECTORY"
            },
            "command": "python run.py -o $SIGASI_COMPILATION_LOG/../vunit-out --clean --compile --keep-compiling"
        }
    }
}

For Windows

{
    "targets": {
        "vunit": {
            "environment": {
                "VUNIT_SIMULATOR": "modelsim",
                "VUNIT_MODELSIM_PATH": "$SIGASI_COMPILER_STUBS_DIRECTORY"
            },
            "command": "python run.py -o $SIGASI_COMPILATION_LOG\\..\\vunit-out --clean --compile --keep-compiling"
        }
    }
}

The environment variables and VUnit arguments serve the same purpose in both examples.

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.