Sigasi CLI is the Command Line Interface that brings the Sigasi technology to your CI/CD environment.
Table of Contents
Requirements
License
In order to use Sigasi CLI, you will need a license. The license can be configured by either:
- A license file in your home directory, named
.sigasi.lic
- Using an environment variable:
SIGASI_LM_LICENSE_FILE
LM_LICENSE_FILE
For more information about licenses, please refer to our manual.
If the license is not available, Sigasi CLI will start polling the license server at regular intervals until the license can be obtained.
Installation
To install Sigasi CLI, obtain a build ZIP for your operating system and extract it.
Then, use either sigasi-cli
(Linux) or sigasi-cli.bat
(Windows).
Usage
sigasi-cli [COMMAND] [ARGUMENTS]
Help
You can get usage information by adding the --help
or -h
flag.
You can also use this flag for each command to get usage information for those commands specifically.
$ sigasi-cli --help Usage: sigasi-cli [-hV] [-v | --debug] [COMMAND] -h, --help Show this help message and exit. -V, --version Print version information and exit. Logging Options: -v, --verbose Output more to the console. --debug Output debug information to the console. Commands: verify Validate the project. document Export project documentation. compilation-order Export project compilation order. extract Extract a library or all tool libraries to a library database.
Logging Options
To turn on verbose output, use any of the following flags.
Option | Description |
---|---|
--verbose | -v | basic progress reporting |
--debug | debug information |
Verify
The verify
command allows you to check an entire Sigasi project for issues.
Issues can be reported in different formats, such as plain text, JSON, or XML.
$ sigasi-cli verify --help Usage: sigasi-cli verify [OPTIONS] PROJECT Validate the project. PROJECT Path of a project root folder. -h, --help Show this help message and exit. -V, --version Print version information and exit. Logging Options: -v, --verbose Output more to the console. --debug Output debug information to the console. Project Options: -P, --path=<key=value> Adds a custom path variable. Can be used multiple times to add more variables. -D, --library-database=<database> Path of a library database folder (for projects that use extracted libraries). Output Options: -o, --out=FILE File to write the output to. --plain Output in plain format. --json Output in JSON format. --sonarqube Output in SonarQube format. --warnings-ng Output in Warnings NG XML format. Execution Options: --fail-on-error Fail on any error marker. --fail-on-warning Fail on any warning or error marker. --fail-on-info Fail on any info, warning or error marker. --include-suppressed Include suppressed issues in output.
Project Options
Environment Variables
Sigasi projects sometimes use environment variables to point at external files and folders, e.g. at the location of your VUnit installation. These variables are set in the IDE, but Sigasi CLI is not aware of these variables by default. Also, the environment in which you run CLI (e.g. your CI server) may be different from the environment in which you run SVH. For example, VUnit may be installed in a different location in each environment.
Using -P
or --path
, you can specify the value of the different
PATH variables in your .project
file. For example, if your
.project
file contains a linked folder like this:
<link>
<name>Common Libraries/vunit_include</name>
<type>2</type>
<locationURI>VUNIT/verilog/include</locationURI>
</link>
You can set the VUNIT
variable to the path of your VUnit installation:
$ sigasi-cli verify --path=VUNIT=/path/to/vunit/installation [FURTHER OPTIONS]
You can use -P
or --path
multiple times to specify the value of
multiple PATH variables.
Note that Sigasi CLI does not support resource filters in the .project
file.
Common Third-Party Libraries
Sigasi projects can also use third-party libraries from the Library Database. Refer to the extract command documentation and SVH libraries manual for more information about the Library Database.
With the -D
or --library-database
option, you can specify the path to a Library Database
that contains these libraries.
Output Options
Output to file
To save the output to a file, you can use one of the output options (--out
or -o
) or, on Linux, redirect the output using >
.
$ sigasi-cli verify -o markers.txt . $ sigasi-cli verify --out=markers.txt . $ sigasi-cli verify . > markers.txt
Output formats
Format | Description |
---|---|
default | colored, suitable for terminal |
--plain | colorless |
--json | JSON format, more detailed |
--sonarqube | JSON format for SonarQube |
--warnings-ng | XML format for Warnings NG |
Plain
By default, the verify
command will output a single line of information for each issue found.
This includes the path, line, and column where the issue is located, the severity, and a message.
If you want to use this format but without coloring, you can use the --plain
flag.
hdl/boards/vfc/rtl/IRQ_Generator_Top.vhd:147:17: WARNING: Incorrect array size in assignment: expected (<g_wb_data_width>) but was (<64>) hdl/boards/vfc/rtl/IRQ_Generator_Top.vhd:155:21: WARNING: Incorrect array size in assignment: expected (<32>) but was (<g_wb_data_width>) hdl/boards/vfc/rtl/IRQ_Generator_Top.vhd:156:17: WARNING: Incorrect array size in assignment: expected (<32>) but was (<g_wb_data_width>) hdl/boards/vfc/rtl/IRQ_Generator_Top.vhd:157:17: WARNING: Incorrect array size in assignment: expected (<g_wb_data_width>) but was (<32>) hdl/boards/vfc/rtl/IRQ_Generator_Top.vhd:158:17: WARNING: Incorrect array size in assignment: expected (<g_wb_data_width>) but was (<32>) hdl/boards/vfc/rtl/IRQ_Generator_Top.vhd:192:10: WARNING: The order of the associations is different from the declaration order hdl/boards/vfc/rtl/IRQ_Generator_Top.vhd:202:10: WARNING: The order of the associations is different from the declaration order hdl/boards/vfc/rtl/IRQ_generator.vhd:117:10: WARNING: The order of the associations is different from the declaration order hdl/boards/vfc/rtl/IRQ_generator.vhd:123:10: WARNING: The order of the associations is different from the declaration order ...
JSON
If you want more detailed information for each issue, you can use the JSON output format by using the --json
flag.
{
"project": "vme64x-core",
"issues": [
{
"resource": "hdl/boards/vfc/rtl/IRQ_Generator_Top.vhd",
"library": "work",
"description": "Incorrect array size in assignment: expected (<g_wb_data_width>) but was (<64>)",
"line": 147,
"lineEnd": 147,
"column": 17,
"columnEnd": 37,
"severity": "WARNING",
"code": "com.sigasi.hdt.vhdl.Vhdl.144",
"codeDescription": "Array assignment validation",
"category": "Range validation"
}
]
}
SonarQube
To import issues into SonarQube , use the --sonarqube
flag to output issues in a format that can be interpreted by SonarQube. First output the issues into a file, then pass them to SonarQube by adding the sonar.externalIssuesReportPaths
parameter. More info can be found here .
Warnings NG
Additionally, issues can be formatted in an XML format suitable for the Jenkins plugin Warnings NG by using the --warnings-ng
flag.
This allows for output to be fed to the plugin, which will visualize the issues for each Jenkins run.
To do this, add the following to your Jenkinsfile
:
// Specify the path of your Sigasi CLI installation
final String sigasi_cli = "/opt/sigasi-cli/sigasi-cli"
// ...
// Add the following somewhere in your build step
sh "${sigasi_cli} verify --warnings-ng --out sigasi-issues.xml ."
// ...
// Add this to your 'post' step
recordIssues(
enabledForFailure: true, aggregatingResults: true,
recordIssues tool: issues(pattern: 'sigasi-issues.xml', analysisModelId: 'sigasi')
)
Execution Options
Failure thresholds
To easily check if any issues of a certain severity were found in the project (without having to parse the output), you can use one of the following options:
Option | Threshold |
---|---|
--fail-on-error | Any error markers |
--fail-on-warning | Any error or warning markers |
--fail-on-info | Any error, warning or info markers |
If any issue was found that matches the threshold, an exit code of 16
will be returned once finished.
The project is still validated in its entirety, regardless of whether the threshold was reached.
Suppressed issues
Suppressed issues are filtered from the output by default, as we consider these issues ‘resolved’.
If you do want to include suppressed issues in the output, add the --include-suppressed
option:
$ sigasi-cli verify --include-suppressed .
Note that this option is ignored when using the --sonarqube
or --warnings-ng
format.
Document
The document
command allows you to create documentation for a Sigasi project.
The documentation can include problem information and generated diagrams and can be split into pages.
$ sigasi-cli document --help Usage: sigasi-cli document [OPTIONS] PROJECT Export project documentation. PROJECT Path of a project root folder. -h, --help Show this help message and exit. -V, --version Print version information and exit. Logging Options: -v, --verbose Output more to the console. --debug Output debug information to the console. Project Options: -P, --path=<key=value> Adds a custom path variable. Can be used multiple times to add more variables. -D, --library-database=<database> Path of a library database folder (for projects that use extracted libraries). Export Options: --top-level=<qualifiedName> Export documentation for the given qualified name. --diagrams=<diagramExports> Specify whether or how to include diagrams in output. Defaults to embedded diagrams. The following options are available: EMBEDDED: include diagrams and embed them in HTML files (default). LINKED: include diagrams and write them to separate file which is linked in HTML file. NONE: don't include diagrams. --include-problems Include problem information in output. --include-suppressed Include suppressed problems in output. --design-units-per-page=<unitsPerPage> Split into multiple pages with the given design units per page. --diagram-node-limit=<nodeLimit> Maximum number of nodes in diagrams. Modifying this limit might result in slow diagram generation. Defaults to 12000. -T, --threads=<threads> Number of parallel export threads. Defaults to maximum available. -d, --output-directory=<outputDirectory> Directory to write documentation files to. Defaults to PROJECT/sigasi-doc.
Project Options
These are the same as the project options for the verify command.
Export Options
Choosing a Top Level
You can export the documentation for a given top level qualified name using --top-level=qualified.name
. For example: --top-level=work.entity.architecture
.
Diagram Generation
By default, diagrams are included as embedded SVGs in the generated documentation.
This can be changed to generate separate files that are linked into the HTML using --diagrams=linked
.
It can also be disabled using --diagrams=none
.
If the project root contains a file named sigasi-doc.css
it will be copied to the target folder and
included in the HTML, embedded or linked according to the --diagrams
value.
Diagram generation is multi-threaded by default, this can be adjusted using -T
or --threads
.
Problem Information
Problem information is not included by default in the generated documentation. It can be added using --include-problems
.
Suppressed problems can also be added with the additional flag --include-supressed
.
Paged Documentation
The documentation can also be split into multiple pages with the option --design-units-per-page=unitsPerPage
.
The summarized project information is on the first page. Subsequent pages provide more detailed insights about a limited
amount of design units per page, as specified.
Node Limit
You can configure an upper limit to the number of nodes in a diagram. This limit prevents large diagrams from being rendered. By default, it is set to 12000.
Changing Output Directory
The folder where you want to export the documentation can be set with the option --output-directory
. By default, it is exported into the sigasi-doc
folder of the selected project.
Compilation Order
The compilation-order
command allows you to generate a CSV file of all HDL files in your project, sorted in the correct compilation order.
$ sigasi-cli compilation-order --help Usage: sigasi-cli compilation-order [OPTIONS] PROJECT Export project compilation order. PROJECT Path of a project root folder. -h, --help Show this help message and exit. -V, --version Print version information and exit. Logging Options: -v, --verbose Output more to the console. --debug Output debug information to the console. Project Options: -P, --path=<key=value> Adds a custom path variable. Can be used multiple times to add more variables. -D, --library-database=<database> Path of a library database folder (for projects that use extracted libraries). Export Options: -o, --out=<file> Output file. Defaults to PROJECT/compilation_order.csv or PROJECT/toplevel_order.csv --top-level=<qualifiedName> Export documentation with the given qualified name as top level.
Project Options
These are the same as the project options for the verify command.
Export Options
By default, the compilation order is written into compilation_order.csv
in the root folder of the selected project. You can export the documentation for a given top level qualified name using --top-level=qualified.name
(e.g. --top-level=work.entity.architecture
).
Adding this option will generate the compilation order list in a file named toplevel_order.csv
. To save the output to a specific file, you can use either -o
or --out
.
Extract
The extract
command allows you to extract tool libraries or standalone libraries into the Library Database.
These libraries can be then used in your projects. Refer to the SVH libraries manual
for more information about the Library Database.
$ sigasi-cli extract --help Usage: sigasi-cli extract [-hV] -k=<kind> -a=<alias> -p=<toolOrLibrary> -D=<database> Extract a library or all tool libraries to a library database. -k, --kind=<kind> Supported tool name (Quartus, Vivado), library name (UVVM, UVM), or a custom library name. -a, --alias=<alias> Alias for this tool or library instance. This alias can be used in a project configuration to switch between different versions of a tool or library. -p, --path=<toolOrLibrary> Path of a tool or library directory to extract from. -D, --library-database=<database> Path of a library database folder. -h, --help Show this help message and exit. -V, --version Print version information and exit. Examples: sigasi-cli extract --kind=Quartus --alias=24.1 \ --path=/opt/intelFPGA_pro/24.1/quartus \ --library-database=/opt/sigasi-libraries sigasi-cli extract --kind=UVM --alias=1800.2-2020-2.0 \ --path=/opt/uvm/1800.2-2020-2.0 \ --library-database=/opt/sigasi-libraries sigasi-cli extract --kind=mylib --alias=v0.1 \ --path=/opt/mylib_v0.1 \ --library-database=/opt/sigasi-libraries
Extract Options
The following information should be provided to extract libraries:
- What should be extracted: if it’s a tool, specify which kind of tool it is; if it’s a library, specify which kind of library it is.
- The alias that will be used in projects to identify exactly this version of a tool or a library.
- The path where this tool or library is located.
- The path to a Library Database where libraries should be extracted to.
Exit Codes
Sigasi CLI should always finish with a 0
exit code.
If this is not the case, refer to the following table.
Code | Description |
---|---|
0 | Successful execution. |
1 | Unhandled program exception occurred. |
2 | Invalid command line arguments / options. |
7 | Licensing error. Make sure a valid license is available. |
16 | Verification severity threshold reached. |
17 | Documentation export failed. |
18 | Compilation export failed. |
19 | Extraction of libraries failed. |
Sigasi CLI Usage in Continuous Integration (CI)
Check out the following articles with step-by-step examples of how to use Sigasi CLI in CI:
- Sigasi CLI Code Verification in GitLab CI
- Sigasi CLI Code Verification in Jenkins CI
- Monitoring HDL code quality with Sigasi CLI and SonarQube
- Sigasi CLI as a Git Commit Hook
- Sigasi CLI Documentation with Jenkins and GitLab CI