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.
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.
$ 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
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 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:
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 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.
Code | Description |
---|---|
0 | Successful execution. |
1 | Unhandled exception occurred. |
2 | Invalid command line arguments / options. |
7 | License problem. Make sure a valid license is available. |
16 | Verification severity threshold reached. |