Setting up a Sigasi Project

Sigasi Visual HDL (SVH) offers a new and sophisticated mechanism to construct a Sigasi project based on your own, existing build scripts.

The Basic Use Case

Many EDA projects have build scripts that start simulations. These build scripts already contain a detailed description of the designs your team is working on. Using Sigasi’s scripted project support, you can avoid duplicating the information already present in your build scripts: SVH will extract all relevant information from the build scripts itself.

Enable the Experimental Project Support

This new project support is hidden by a feature flag and can be enabled in the VS Code settings JSON file. Note that the flag is not exposed in the settings UI.

{
  ..
  "sigasi.project.enableSigasiProjectSupport": true
  ..
}

Creating or Importing a Sigasi Project

A directory is recognized as a Sigasi project if it contains a project.sigasi file. A wizard to create new projects is available from the command palette via Sigasi: New Project…. It offers the option to make a legacy project or a project backed by build scripts. The minimal script based project.sigasi will look similar to the following:

{
    // define targets
    "targets": {
        "rtl": "vcs -f file.list"
    }
}

A more elaborated version illustrates the concepts further:

{
    "name": "MyProject",
    // define targets
    "targets": {
        "rtl": {
            "environment": {
                "VARIABLE_A": "value",
                "VARIABLE_B": "${VARIABLE_A}"
            },
            "command": [
                "vcs -f ip/list.f",
                "vcs -f src/list.f"                
            ],
            "ignoreReturnCode": false
        },
        "tb" : "make --always-make -f tb/Makefile"
    }
}

From top to bottom, the following configuration is deduced from the JSON:

1. A Sigasi project has a name. If the name is not explicitly set, it is derived from the name of the enclosing directory. In the example, the project’s name is MyProject.
2. One or more targets are listed to assemble the contents of the project. A target comprises a self-contained set of files that are compiled together. For SVH 2025.1 it is encouraged to configure exactly one target per project.
   1. You can give a target a logical name. The first target in the example above is called rtl, the second one is called tb.
   2. The rtl target runs two simulator commands to compile the RTL code of the project. The argument files ip/list.f and src/list.f are maintained as part of the project’s build system and can be reused directly. This target also defines custom environment variables.
   3. The tb target is built by a Makefile. No further configuration is necessary for this target, since everything is derived from the build itself.

In the Sigasi Projects View, the structure of the captured project will be visualized in two different forms: as a file system centric Design perspective and as a logical Targets perspective.

The Design Perspective

The Design perspective allows navigating the structure of all directories that contribute to the project. The captured information from the build script might refer to files from various locations on disk, configure include paths, or rely on files that are located on shared drives. All the directories are accessible in the Design folder.

The Target Perspective

The Target perspective reveals the logical structure of the project. For each defined Target, a folder represents the libraries and their associated files. The files are rendered in the order of compilation wherever possible. This view will also reveal if some files are mentioned in the build scripts but are missing on disk.

How Does it Work?

A Sigasi project is backed by one or multiple build scripts. Yet, it is independent of the technology that is used to build the project.

To capture and record the semantics of the build scripts, the build is executed in a prepared shell environment. There, the simulators or compilers (the tools) are shadowed by so-called stub implementations. These stubs capture the command invocations and their execution context as a compilation log. Subsequently, the captured compilation log is interpreted and converted into a detailed compilation plan that contains all participating files and directories in the order of their appearance. The compilation plan is used to derive the underlying logical structure of the target.

The mechanism is generally agnostic to the chosen build technology, as long as it launches the supported tools as external processes from a regular shell environment by their simple executable name.

Supported Tools

The following tools are natively supported and can be introspected on Linux and Windows:

• Synopsis VCS
  • vcs
  • vhdlan
  • vlogan
• Siemens Questa
  • qrun
  • qverilog
  • vlog
  • vcom
  • vlib
  • vmap
  • vopt
  • vsim
• Cadence XCelium
  • xrun

TCL scripts are supported when passed to vsim via vsim -do.

It should be noted that the tool stubs do not call the original tool. They do not create any artifacts besides adding information to the compilation log. That is why the project structure can be captured on any machine, even if the simulators or compilers are unavailable. The utilities that are used to run the build scripts are required though, e.g., make, perl, python, or any other command line based build technology that is used. Some compiler options may need environment variables to be interpreted correctly.

Predefined Environment Variables

SVH launches the build in a prepared environment, where the PATH variable is prefixed with a directory that contains the stub executables. In addition, the following environment variables are used. They allow SVH specific augmentation of the build scripts.

Caveats and Troubleshooting

Capturing the project structure works best if the build scripts respect the following rules:

1. The configured commands should not cause side effects. If code generation is necessary for a project to work, it is best if the generation step is either not part of the build or repeated runs of the build do not regenerate from scratch but keep the existing generated files untouched.
2. The build must not be incremental in the way it is triggered from within SVH. For example, make --always-make should be used to ensure that subsequent builds still run the entire pipeline.
3. The build might still have accidental side effects. Since SVH attempts to capture targets automatically if some meaningful change on disk is detected, it might go into a build loop. This situation will be detected by the tool. Yet, the build script might need adjustments to not cause side effects. The automatic refresh of targets can be disabled in the settings JSON "sigasi.project.enableAutomaticTargetRefresh": false.