[Only in Sigasi Visual HDL Enterprise Edition]

Sigasi CLI is the Command Line Interface that brings the Sigasi technology to your CI/CD environment.

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.

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.
  -a, --absolute             Use absolute paths to refer to files instead of
                               Sigasi project paths.
      --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

Absolute paths

By default, the file paths of the files with issues will be given as Sigasi project paths. This makes it easy to find the relevant file in SVH and fix the problem, because these are path relative to the project root. When the output of the verify command is to be processed by a script, though, Sigasi project paths are usually not what you want, especially if your project contains a lot of linked resources. Much easier to work with are absolute paths, which you’ll get when you pass the --absolute flag.

Output formats

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:

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.

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