Veresta


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

Requirements

Java Runtime

You will need to have a Java Runtime (JRE) installed in order to run Sigasi Veresta.

  • The Java runtime must be 64-bit. Make sure to use at least JRE 11
  • You can check your Java version with java -version

License

In order to use Sigasi Veresta 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.

Installation

To install Sigasi Veresta, obtain a build ZIP and extract it. Then use either sigasi-cli (Linux / Mac) 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:
      --debug     Output debug information to the console.
  -v, --verbose   Output more to the console.
Commands:
  verify  Validate the project.

Logging

To turn on verbose output, use any of the following flags.

optiondescription
--verbose | -vbasic progress reporting
--debugdebug 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, JSON or XML.

$ sigasi-cli verify --help
Usage: sigasi-cli verify [-hV] [--include-suppressed] [-o=FILE] [-v | --debug]
                         [--json | --warnings-ng | --plain] [PROJECT...]
Validate the project.
      [PROJECT...]           One or more project folders.
  -h, --help                 Show this help message and exit.
      --include-suppressed   Include suppressed issues in output.
  -o, --out=FILE             File to write the output to.
  -V, --version              Print version information and exit.
Logging:
      --debug                Output debug information to the console.
  -v, --verbose              Output more to the console.
Output Formats:
      --json                 Output in JSON format.
      --plain                Output in plain format.
      --warnings-ng          Output in Warnings NG XML format.

Output formats

formatdescription
defaultcolored, suitable for terminal
--plaincolorless
--jsonJSON format, more detailed
--warnings-ngXML 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": "144",
      "codeDescription": "Array assignment validation",
      "category": "Range validation",
      "languageQualifier": "com.sigasi.hdt.vhdl.Vhdl"
    },

    ...

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 Veresta installation
final String SigasiVeresta = "/opt/sigasi-cli/sigasi-cli"
// ...

// Add the following somewhere in your build step
sh "${SigasiVeresta} 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')
)

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

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 --warnings-ng format.

Exit codes

Sigasi Veresta should always finish with a 0 exit code. If this is not the case, refer to the following table.

CodeDescription
0Successful execution.
1Unhandled exception occurred.
2Invalid command line arguments / options.
7License problem. Make sure a valid license is available.