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.
  document  Export project documentation.
  compilation-order  Export project compilation order.

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

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.

$ veresta document --help
Usage: veresta 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.
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.
  -T, --threads=<threads>    Number of parallel export threads. Defaults to
                               maximum available.

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.

$ veresta compilation-order --help
Usage: veresta 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.
Export Options:
  --top-level=<qualifiedName>
                             Export documentation with the given qualified name
                               as top level.

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.

Note that Veresta does not support resource filters in the .project file.

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 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:

$ veresta verify --include-suppressed .

Note that this option is ignored when using the --sonarqube or --warnings-ng format.

Export Options

Documentation Options

You can export the documentation for a given top level qualified name using --top-level=qualified.name. For example: --top-level=work.entity.architecture.
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.

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.

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.

Compilation Order Options

You can export the compilation order for a given top level by using --top-level=qualified.name. For example: --top-level=work.entity.architecture.
Adding this option will generate the compilation order list in a file named toplevel_order.csv.

Exit Codes

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

Veresta Usage in Continuous Integration (CI)

Check out the following articles with step-by-step examples of how to use Veresta in CI:

• Veresta Code Verification in GitLab CI
• Veresta Code Verification in Jenkins CI
• Monitoring HDL code quality with Sigasi Veresta and SonarQube
• Veresta as a Git Commit Hook
• Veresta Documentation with Jenkins and GitLab CI