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 Project scripted targets, you can avoid duplicating the information already present in your build scripts: Sigasi will extract all relevant information from the build scripts themselves, and automatically remain in sync with them.
To capture and record the semantics of the build scripts specified in scripted targets, Sigasi executes them 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 Compilers
The list of tools that are natively supported and can be introspected by Sigasi on Linux and Windows can be found here.
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.
If your build scripts call executables that cause side-effects, take a long time, or aren’t present on your current machine, you can intercept their invocation. The intercept key can be added to a scripted target to replace any number of executables with a stub.
Predefined Environment Variables
Sigasi launches the build in a prepared environment, where the PATH variable is prefixed with a directory that contains the stub executables.
In addition, Sigasi sets additional environment variables. They allow Sigasi specific augmentation of the build scripts.
Caveats
Capturing the project structure works best if the build scripts respect the following rules:
- 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 Scripted target command or repeated runs of the build do not regenerate from scratch but keep the existing generated files untouched.
- When your build script is triggered from within Sigasi, ensure that your build script builds all your artifacts from scratch.
Avoid triggering an incremental build. An incremental build will not reveal to Sigasi all build operations and artifacts.
This will result in an incomplete Sigasi Project being captured.
For example,
make --always-makeshould be used to ensure that subsequent builds still run the entire pipeline.
Troubleshooting
If you encounter any problems with compilation scripts, you can check a few log files that can help you debug the issue.
In the project directory, Sigasi creates a .sigasi/targets/generated/<target name> directory for every scripted target. It contains the following files:
compilation.logcontains all intercepted compiler invocations with arguments, working directory, and environment variable values they were invoked with.- In
compilation.out, Sigasi writes the standard output stream (stdout) of compilation process. - In
compilation.err, Sigasi writes the standard error stream (stderr) of compilation process. - Finally,
compilation.plancontains structured information about files that are compiled as well as how they are compiled.
Code Lenses in the project.sigasi file allow you to quickly open some of these files.
Disabling automatic refresh
A scripted target command might still have accidental side effects.
Since Sigasi attempts to capture targets automatically if some meaningful change on disk is detected,
it might go into a build loop.
Although this situation will be detected by the tool,
the build script should be adjusted to avoid side effects to prevent unnecessary waiting for build loops to finish.
The automatic refresh of targets can be disabled by the
This is for example required when using scripted targets to import Vivado configurations, as the Vivado project updates timestamps and such in their project file on every run.
After disabling automatic refresh,
you can refresh targets manually by using the Refresh Target and Refresh All Targets Code Lenses in the project.sigasi file.