Run an analysis and upload the results to Validate as part of a server CI build.
Usage
validate cibuild -P <directory> -b <build-name> [-j <n>] [-I] [--retry <n>] [-o <output-path>] [-T] [-s] [--force-complete] [-c] [--incremental] [--tags <tag[,tag...]>] [-m] [-i] [--] [-h]Extended Description
This command enables you to run an analysis of a connected project in a CI environment. It will perform an analysis and upload to Validate all the diagnostics that are not found in the last successful integration build of the project. All such diagnostics must have been introduced as part of the work being analyzed.
This enables DevOps to implement a quality gate as part of the CI build process that allows new diagnostics to be identified, triaged, and fixed or cited before being committed to the main development branch.
Prerequisites for using CI builds are:
- A valid CI build license
- The project must be a connected project
- At least one complete integration build must be available as a baseline. For more information, see qacli validate build.
Options
| Name, shorthand | Default | Description |
|---|---|---|
‑‑build‑name, ‑b <build-name>
|
(Required) Specify the unique build name to be used when uploading to Validate. It is recommended that the name ties in some way the build job it is run from. |
|
‑‑clean, ‑c
|
Cleans all analysis data from the specified qaf-project before performing analysis. | |
‑‑disable‑metrics, ‑m
|
Disable the upload of metrics. | |
‑‑force‑complete
|
Forces the analysis to process all of the files, even in the event of a process level error that would lead to premature termination (such as a license check failure).
Mutually exclusive with |
|
‑‑help, ‑h
|
Displays usage information and exits. | |
‑‑ignore‑rest, ‑‑ |
Ignores the rest of the labeled arguments following this flag. | |
‑‑ignore, ‑i
|
Ignore project and file checks, including dependency checking when uploading to Validate. The resultant upload may not be 100% complete and accurate. | |
‑‑incremental |
Disable whole program analysis and only analyze files that have changed. | |
‑‑inter‑tu‑dataflow, ‑I |
Perform Inter TU Dataflow analysis. | |
‑‑jobs, ‑j <n>
|
Specify the maximum number of jobs to run in parallel during analysis. This optional parameter temporarily overrides any previously set value
(qacli config cpu ‑‑set <jobs>) and the system default (usually the number of cores - 1).
|
|
‑‑output‑progress, ‑o
|
Specify that analysis progress will be piped to the given file. | |
‑‑qaf-project <directory>, ‑P <directory>
|
(Required) Specify a path to a valid Helix QAC project to act upon. |
|
‑‑retry <n>
|
3 | If analysis fails due to a license failure or the parser returns an unexpected return code then wait a short period and retry up to 'n' times. By default 3 retries are attempted. This feature can be disabled by specifying a retry value of 0. |
‑‑show‑timings, ‑T
|
Show analysis timing information, in the format ([nd ]HH:MM:SS). Where 'nd ' is the number of days - this is only shown if greater than zero. | |
‑‑stop‑on‑fail, ‑s
|
Halts analysis once the first analysis failure is encountered. Mutually exclusive with |
|
‑‑tags
|
Add comma separated tags to the project that is uploaded to the Validate portal. Individual tags can be a maximum of 128 characters and the maximum size of the total tags option is 256 characters. Tags can contain spaces, but not at the start or end of a tag. |
Examples
Performing a typical CI build
The following example shows the basic steps you need to perform with qacli to setup and execute a CI build.
It is assumed that you will have fetched your source code and successfully compiled it prior to performing static analysis. Therefore, your CI environment should already be configured with source projects in place. All that is needed is to setup the static analysis with qacli.
- First, authenticate with the Validate server if you have not already done so
- After this, fetch the project from Validate:
- Make sure that the Helix QAC project is up to date with any file additions, removals, or renames by synchronizing with the source.
Failure to synchronize the project with latest source could result in new or renamed files not being analyzed during the build.
For example:
This will quickly bring the Helix QAC project up to date based on the content of the JSON compilation database used to build the source.
Refer to the “Project Synchronization” section for details.
- Perform the CI build. This will analyze the project and compare the results with the baseline from the last successful build for the project:
New results will be uploaded to the Validate server under the CI build name “ci-build-001”. You should ensure that the name of the build is unique. It is recommended that it relates in some way to the build job it is run from (e.g. the Jenkins job ID).
Upon completion of the CI build, the result of the build will be displayed. If no new issues were discovered in the build, the CI build status will be shown as “Success” – (return code 0).
If new issues were uploaded to Validate, then the result of the build will be shown as “Unstable” (return code 4), and a URL pointing to the CI build results in Validate will be shown.
This can be copied into the output of your build job (for example on Jenkins) to make it easier for developers to find the results directly from the build environment.
Upload Diagnostics to Perforce Validate Including Tags
To upload Helix QAC diagnostics to Validate and add tags to the build:
Perform an Incremental CI Build
To perform incremental CI builds there should be at least one full build for the project that analyses all the source in the project. This gives the incremental build a baseline to compare with.
The incremental build will analyze files in the project that have been changed (directly or indirectly via a header) relative to the last successful full build for the project.
To keep the set of files analyzed to a minimum it is a recommended that you keep your branch source up to date with the main branch prior to running an incremental CI build.