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

Requirements

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.

If the license is not available, Veresta will start polling the license server at regular intervals until the license can be obtained.

Installation

To install Sigasi Veresta, obtain a build ZIP for your operating system and extract it. Then use either veresta (Linux) or veresta.bat (Windows).

Usage

veresta [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.

$ veresta --help
Usage: veresta [-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.

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.

$ veresta verify --help
Usage: veresta verify [OPTIONS] [PROJECT...]
Validate the project.
      [PROJECT...]           One or more project folders.
  -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>     Custom path variables.
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

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 Veresta is not aware of these variables by default. Also, the environment in which you run Veresta (e.g. your CI server) may be different from the environment in which you run Sigasi Studio. 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:

$ veresta 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.

Output Options

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

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

$ veresta verify -o markers.txt .
$ veresta verify --out=markers.txt .
$ veresta verify . > markers.txt

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 it’s entirety, regardless of wether 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:

$ veresta verify --include-suppressed .

Note that this option is ignored when using the --sonarqube or --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.