qacli analyze

Perform static analysis on all or part of an existing Helix QAC or CMA project(s).

Usage

analyze [-P <directory>] [-K <config name>] [-C <solution-name>] [--cma-project <project-name>] [-j <n>] [-u] [--use_disk_storage] [-r] [--reuse_db] [-R] [-I] [--repeat <n>] [--retry <n>] [-o <output-path>] [-T] [-D] [-s] [--force-complete] [-g] [-c] [-f] [-l <cct-file>] [-F <filelist>] [-b <script>] [-a] [--] [-h] <source-file>

Extended Description

Analysis can be performed on one or more individual files, an entire Helix QAC project or a CMA project, i.e. a collection of Helix QAC projects.

By default, only files that have been changed, including any dependent files (or settings) will be re-analyzed. Files and projects may be ‘cleaned’ and this will remove their analysis results, this effectively will force analysis next time the command is run.

All the examples shown are for a default Helix QAC project with a single configuration. If you are using a project with multiple configurations (see Projects with Multiple Configurations) and want to specify a non-default config to use, then add the ‑‑config <Config Name> option.

Options

Name, shorthand	Default	Description
`‑‑assemble‑support‑analytics, ‑a`		This will create a compressed archive for each failed file containing its arc file, its pre-processed source file, and its options file. The archive is created in the source file's output directory.
`‑‑build‑command, ‑b`		Specify a path to a script that, when executed, will build your code. The build will be set in motion and source files and dependent information will be extracted, added to the specified Helix QAC project, and analyzed.
`‑‑clean, ‑c`		Cleans all analysis results from the specified project(s) before optionally performing analysis. In the case where the '`cma‑project`' option is specified, all Helix QAC projects involved in the analysis will be cleaned.
`‑‑cma‑solution, ‑C`		Specifies the name of a CMA project to conduct cross-module analysis. Using this option implies specifying that analysis will be conducted on all modules (Helix QAC projects) involved in the project before cross-module analysis is conducted. Use --qaf-project to specify the project to use for storing the results of the CMA (the first module of the CMA project is used by default).
`‑‑config, ‑K`		For projects with multiple configurations, specify which configuration to use. If none is specified, then the default configuration will be used.
`‑‑disable‑sync, ‑D`		For connected Validate projects, do not synchronize the RCF before analysis is started.
`‑‑file‑based‑analysis, ‑f`		Conduct analysis on the specified files(s) or project. This switch is implicitly turned on when conducting raw-source or cma-project analysis, but must be explicitly used otherwise. If you want to both clean and analyze a cma-project then this option needs to be explicitly specified.
`‑‑files, ‑F`		Specify a path to a file containing a list of files to be analyzed. If not supplied, all files in the project will be analyzed.
`‑‑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 `‑‑stop‑on‑fail`.
`‑‑generate‑preprocessed‑source, ‑g`		For each source file that is analysed, generate a pre-processed source file in the file's output directory.
`‑‑help, ‑h`		Displays usage information and exits.
`‑‑ignore‑rest, ‑‑`		Ignores the rest of the labeled arguments following this flag.
`‑‑inter‑tu‑dataflow, ‑I`		Perform Inter TU Dataflow analysis.
`‑‑jobs, ‑j`		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).
`‑‑language‑cct, ‑l`		Specify the path to the CCT to be used for raw-source analysis. If none is specified, then '`Helix_Generic_C++.cct`' will be used by default.
`‑‑output‑progress, ‑o`		Specify that analysis progress will be piped to the given file.
`‑‑qaf‑project, ‑P`		Specify a path to a valid Helix QAC project to act upon.
`‑‑raw‑source, ‑R`		Specify that the file(s) to be analyzed is not part of any Helix QAC project. This is useful for debugging configuration problems. The files must be '.i' files i.e. previously generated by analysing with the 'Generate Preprocessed Source' option enabled.
`‑‑retry`	3	If analysis fails due to a license failure or the parser returns an unexpected return code then wait a short period and retry upto '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 `‑‑force‑complete`.

Examples

Analysis of Helix QAC Projects

The following command can be issued to perform analysis on a Helix QAC project:

qacli analyze -P <directory> --file-based-analysis

This will analyze all files that have changed (either source file, dependent source files or configuration) since the last analysis run.

To remove all analysis results from the project it may be cleaned:

qacli analyze -P <directory> --clean

These options may be combined to effectively clean and re-analyze the whole project:

qacli analyze -P <directory> --file-based-analysis --clean

If you wish to kill the commands currently running in the command window, use Ctrl+C.

Analysis of Helix QAC Projects

The following command can be issued to perform analysis on a Helix QAC project:

qacli analyze -P <directory> --file-based-analysis

This will analyze all files that have changed (either source file, dependent source files or configuration) since the last analysis run.

Selectively Analyzing Files

A single file may be analyzed directly on the command line by specifying it after the double-dash (‑‑) option:

qacli analyze -cf -P . -- src/test_1.cxx

Absolute paths can be used or relative paths, these are relative to the source root (see qacli project roots --list).

To specify a set of files to be analyzed, the path to each source file must be placed in a filelist, which is a text file made up of one path per line. To analyze the files in the filelist:

qacli analyze -P <directory> -f --files <path-to-filelist>

The above option cannot be used with CMA projects.

Inter-TU Analysis

Dataflow analysis typically occurs at the TU (Translation Unit) level i.e. a single source file including all its dependent header files. To enable Dataflow analysis at the whole program level add the ‑‑inter‑tu‑dataflow option:

qacli analyze -P <directory> -f --inter-tu-dataflow

You should ensure that your configured value for df::inter is non-zero and df::query_timeout > 10. You can use one of the 'Depth' settings to do this which automatically populate these configuration options with appropriate values.

This option cannot be used with a CMA solution i.e. ‑‑cma‑solution <solution‑name>.

Further details on Inter-TU dataflow can be found in the Helix QAC Dataflow manual

Failure Action

The following command will keep processing subsequent files and reporting progress per file even if a license check failure has occurred:

qacli analyze -P <directory> -f --force-complete

The following switch can be used to stop scheduling more analysis jobs on the first analysis failure (jobs already started will be allowed to complete):

qacli analyze -P <directory> -f --stop-on-fail

Depending upon network stability and/or limits on your license it's possible for the analysis to fail with a licence failure or perhaps due to available machine resources a parser could fail. By default, analysis will be attempted up to three additional times. You can modify the number of times it will retry using the ‑‑retry option, for example:

qacli analyze -P <directory> -f --retry 5

This will try up to five additional times to analyze a file if a license or parser failure occurs, with a small wait before each retry. A value of zero will disable retries.

The ‑‑force‑complete and ‑‑stop‑on‑fail options are mutually exclusive.

Monitoring Progress

As files are analyzed progress is output to the console (refer to Progress Output). Progress from the analysis of source files can additionally be written to a file which can then be monitored to gauge the progress of the analysis, with one line output for each file processed. The last line will begin with "Progress(<label>)", followed by one dot (".") for every 3% of progress that the final component has taken. When complete, it will end the line with "done". For example:

qacli analyze -P <directory> -f --output-progress <output-path>

By default, the delta time for analysis is not displayed. If you wish to add this to the output (both console and file) then specify ‑‑show‑timings. The output will then be appended with the time taken to analyze each file. It will be in the format: ([nd] HH:MM:SS)

Where ’nd ’ is the number of days (only shown if greater than zero) and HH:MM:SS are the number of hours, minutes and seconds that the analysis took to complete. For example:

qacli analyze -P <directory> -f --show-timings
Progress(Cleaning): .................................... done
/home/cartman/sample_inspect_c/src/inspect.c:qac:0:1:0 (00:00:01)
Progress(File-based Analysis): ........................ done (00:00:02)

The time taken to analyze each file will be shown and additionally the total analysis time will also be shown at the end of the command.

All times are rounded to the nearest second, and the individual times are for analysis only and will not include any time taken by Helix QAC to process each file.

Because of this, it’s possible that summing all the individual times will not match the displayed total analysis time.

Simultaneous Synchronization and Analysis

It is possible to simultaneously synchronize (add files to a Helix QAC project) and analyze them:

qacli analyze -P <directory> --build-command <script>

The script, which is generally a build command will be executed and the build monitored. As files are detected they will be added to the project. At the end of the build any added files will then be analyzed, for example:

qacli analyze -b makecc -c -ohello\ world.o hello\ world.ccc -ohello\ world hello\
world.o/home/unicorn/sample_projects/Hello World-C/hello world.c - found
The command 'make' has completed with an exit code of 0
/home/unicorn/sample_projects/Hello World-C/hello world.c:qac:0:1:0
Progress(Sync Analysis): ................................... done

Analysis of CMA Projects

As outlined in CMA Project Management section, Helix QAC projects can be associated with CMA projects as "modules". This feature can be used to conduct analysis on several Helix QAC projects. To conduct CMA, specify the name of the CMA project and the name of the Helix QAC project against which the results are to be stored:

qacli analyze -P <directory> -C <cma-project-name>

If no Helix QAC project is specified, the default is to use the first in the list of Helix QAC projects in the CMA project.

Unless explicitly stated, all of the normal switches apply for CMA (except for --file-based-analysis, which is implicit). For example, the following command:

qacli analyze -P <directory> -C <cma-project-name> -csga

This will clean the associated modules first before performing file-based analysis on each, halting if an analysis failure is encountered, generating preprocessed source for each source file that is analyzed, and creating an archive containing support data for any file that fails analysis.

Raw Source Analysis

Sometimes it is beneficial to analyze a file that is not part of a Helix QAC project, for example, to analyze a preprocessed file in order to debug configuration issues. The following command can be used to do this:

qacli analyze -P <directory> --raw-source <file-path> --language-cct <cct-path>

If no CCT is supplied then ’Helix_Generic_C++.cct’ is used by default.

If the file is omitted, then you may also use ’-F’ to specify a filelist.

The files must be ’.i’ files, that is to say, files previously generated by analyzing with the ’Generate Preprocessed Source’ option enabled.

Debugging Analysis

For C and C++, preprocessed source is useful for debugging configurations and code in general. Helix QAC will generate preprocessed source files in the prqa/configs/<config_name>/output/SOURCE_ROOT directory structure of a project.

The following switch can be used to generate a preprocessed source file for each file that is analyzed:

qacli analyze -P <directory> -f --generate-preprocessed-source

When analysis configuration problems result in source files failing to analyze successfully, it is helpful to gather information and relay it to a Support Engineer. The following switch specifies that Helix QAC is to create an archive for each file that fails analysis, with each archive containing the .arc, .i and .via files (this is equivalent to the QA·GUI option Assemble Support Analytics for Failed Files. Refer to The Analyze Menu for more information):

qacli analyze -P <directory> -f --assemble-support-analytics