In this section:
Prerequisites
Compiler
C/C++test must be configured for use with specific C and C++ compilers and versions before you can analyze code. The configuration should reflect the original compiler and version used for building the code under test. The original compiler executable must be available on $PATH (unless it is specified with a full path).
Use the -compiler
switch to specify the compiler configuration identifier:
cpptestcli -config "builtin://Recommended Rules" -compiler gcc_4_5 -input cpptest.bdf
Alternatively, you can configure the cpptest.compiler.family
property in a custom configuration file:
cpptest.compiler.family=gcc_4_5
If you are using a single compiler and version for all testing, the compiler identifier can be specified in the cpptestcli.properties
global configuration file in either the [INSTALL_DIR] or [USER_HOME] directory; see Configuration Overview.
Compiler Discovery
Perform one of the following actions to find the configuration for your compiler:
Use the
-detect-compiler
switch to the auto-detect configuration:cpptestcli -detect-compiler gcc
Use the
-list-compilers
switch to find the configuration in the list of all supported compilers:cpptestcli -list-compilers
See Configuring the Compiler and Supported Compilers for additional information.
About Usage Examples
The following instructions assume that:
- GNU GCC 4.5 compiler is being used (configuration identifier: gcc_4_5)
- The prerequisites discussed above have been met.
- Users are running commands in the [INSTALL_DIR]/examples/ATM directory.
Analyzing a Single File
Run an analysis and specify the original compiler command with the --
switch (separator).
All values after --
switch will be interpreted as a compiler command, so options specific to C/C++test must be specified before --
switch.
cpptestcli -config "builtin://Recommended Rules" -compiler gcc_4_5 -- gcc -I include Bank.cxx
C/C++test will analyze the Bank.cxx file using the original compiler executable and compiler options and report detected violations to the output console.
Only the specified source files will be analyzed. Header files included by the source files will be excluded from analysis. To broaden the scope of files tested, including header files, see Configuring the Test Scope.
You can also use the -fail
option to generate a non-zero exit code when the analysis reports static analysis findings (see Command Line Exit Codes).
Analyzing a Makefile-based Project
Run code analysis and specify the original build command with the -trace
switch.
All values after -trace
will be interpreted as a build command, so options specific to C/C++test must be specified before -trace
.
cpptestcli -config "builtin://Recommended Rules" -compiler gcc_4_5 -module . -trace make clean all
C/C++test will perform the following tasks:
- Run the original build (make clean all)
- Detect which files to test
- Run the analysis for these files
- Report results to the output console
- Store all build information in the cpptest.bdf file for future runs (see About Build Data Files for additional information about build data files).
C/C++test will detect a source file for testing only if that file was compiled when running the build command. Only source files from Makefile will be analyzed. Header files included by the source files will be excluded from analysis. To broaden the scope of files tested, including header files, see Configuring the Test Scope.
About Build Data Files
A build data file stores build information, such as such as the working directory, command line options for the compilation, and link processes of the original build. Specifying the path to a .bdf file allows you to analyze a project without having to rebuild it; see Re-analyzing a Project without Re-building.
You can use the -trace
switch to create a .bdf or use the standalone cpptestscan
or cpptesttrace
utility located in the [INSTALL_DIR]/bin directory
.; see Using cpptestscan
and cpptesttrace
Utilities.
The following example is a fragment from a build data file:
working_dir=/home/place/project/hypnos/pscom project_name=pscom arg=g++ arg=-c arg=src/io/Path.cc arg=-Iinclude arg=-I. arg=-o arg=/home/place/project/hypnos/product/pscom/shared/io/Path.o
Using cpptestscan
and cpptesttrace
Utilities
The cpptestscan
utility is used as a wrapper for the compiler and/or linker during the normal build. To use cpptestscan
with an existing build, prefix the compiler/linker executable with cpptestscan
when building the code base. This can be done in two ways:
- Modify the build command line to use
cpptestscan
as the wrapper for the compiler/linker executables - If you aren’t able to override the compiler variable on the command line, embed
cpptestscan
in the actual make file or build script.
To use cpptesttrace
with an existing build, prefix the entire build command with cpptesttrace
when building the code base. cpptesttrace
will trace the compiler and linker processes executed during the build and store them in the build data file.
In both cases, you must specify the full path to either utility in your PATH environment variable. Additional options for cpptestscan
and cpptesttrace
are summarized in the following table. Options can be set directly for the cpptestscan
command or via environment variables. Most options can be applied to cpptestscan
or cpptesttrace
by changing the prefix in the command line.
Basic cpptestscan
usage:
cpptestscan [options] [compile/link command] cpptestscan --cpptestscanHelp
Basic cpptesttrace
usage:
cpptesttrace [options] [build command] cpptesttrace --cpptesttraceHelp
Option | Environment Variable | Description | Default |
---|---|---|---|
| CPPTEST_SCAN_OUTPUT_FILE | Defines file to append build information to. | cpptestscan.bdf |
| CPPTEST_SCAN_PROJECT_NAME | Defines a suggested name of the C/C++test project. | name of the current working directory |
| CPPTEST_SCAN_RUN_ORIG_CMD | If set to "yes", the original command line will be executed. | yes |
| CPPTEST_SCAN_QUOTE_CMD_LINE_MODE | Determines the way C/C++test quotes parameters when preparing cmd line to run.
--cpptestscanQuoteCmdLineMode is not supported on Linux. | all |
| CPPTEST_SCAN_CMD_LINE_PREFIX | If non-empty and running original executable is turned on, the specified command will be prefixed to the original command line. | [empty] |
| CPPTEST_SCAN_ENV_IN_OUTPUT | Enabling dumps the selected environment variables and the command line arguments that outputs the file. For advanced settings use --cpptestscanEnvFile and --cpptestscanEnvars options. | no |
| CPPTEST_SCAN_ENV_FILE | If enabled, the specified file keeps common environment variables for all build commands; the main output file will only keep differences. Use this option to reduce the size of the main output file. Use this option with --cpptestscanEnvInOutput enabled. | [empty] |
| CPPTEST_SCAN_ENVARS | Selects the names of environment variables to be dumped or '*' to select them all. Use this option with --cpptestscanEnvInOutput enabled. | * |
| CPPTEST_SCAN_USE_VARIABLE | Replaces each occurrence of "VALUE" string in the scanned build information with the "${VAR_NAME}" variable usage. | [empty] |
--cpptesttraceTraceCommand=[<regexp>|<regexp>|...] | CPPTEST_SCAN_TRACE_COMMAND | Defines the command names that will be traced when collecting build process information. These names, specified as regular expressions, should match the original compiler/linker commands used in the build process. |
Re-analyzing a Project without Re-building
Run code analysis and specify the path to an existing build data file with the -input
switch. For example:
cpptestcli -config "builtin://Recommended Rules" -compiler gcc_4_5 -module . -input cpptest.bdf
C/C++test will perform the following tasks:
- Read the information about which files to test from the existing cpptest.bdf file.
- Run the analysis for these files
- Report results to the output console.
The original build command will not be executed.
You can specify multiple files using multiple -input
switches:
cpptestcli -config "builtin://Recommended Rules" -compiler gcc_4_5 -module . -input project1.bdf -input project2.bdf
Only the source files defined in the build data file will be analyzed. Header files included by the source files will be excluded from analysis. To broaden the scope of files tested, including header files, see Configuring the Test Scope.
Analyzing a CMake-based Project
To analyze a CMake-based project:
- Ensure that your CMake build can output a compile commands file in the JSON format (you can configure CMake to output the file using the
CMAKE_EXPORT_COMPILE_COMMANDS
variable.) Update the C/C++test command line to include
-input <PATH_TO_COMPILE_COMMANDS_JSON>
to pass the location of the compile commands file. Your command line may resemble the following:cpptestcli -config "builtin://Recommended Rules" -compiler gcc_4_5 -module . -input compile_commands.json
C/C++test will perform the following tasks:
- Read the information about the analysis scope and build options from the
compile_commands.json
file. - Run the analysis on the files in the scope.
- Report results.
C/C++test will only analyze the source files defined in the compile commands file. Header files included by the source files will be excluded from analysis. See Configuring the Test Scope for information how to extend the scope of analysis and include header files.
Analyzing an MSBuild-based Project
C/C++test ships with a script that allows you to quickly reconfigure your MSBuild project to generate .bdf files. This script supports both Visual Studio and CMake-generated MSBuild projects. The script creates a backup of the target .vcxproj file and then modifies it to enable the requested Parasoft features on all build targets.
C/C++test includes a Python script launcher to run the included tools, which can be found at:
<CPPTEST_INSTALL_DIR>/bin/engine/bin/cpptestpy.exe
The MSBuild integration script is in the following location:
<CPPTEST_INSTALL_DIR>/integration/msbuild/msbuild_cpptest.py
To analyze an MSBuild-based project:
- Setup the environmental variables.
Be sure to not use double quotes after =
which will cause incorrect string interpretation.
Setup the
CPPTEST_INSTALL_DIR
variable.set CPPTEST_HOME=<CPPTEST_INSTALL_DIR>
(CMake only) Generate your MSBuild files using CMake.
cd <PROJECT_DIR> mkdir build cd build cmake ..
Run the integration script.
<cpptestpy.exe> <msbuild_cpptest.py> -b -f project.vcxproj
Build the project using MSBuild.
msbuild -t:Rebuild project.sln
A .bdf file will be generated in your current working directory.
Launch static analysis on the .bdf file.
cpptestcli.exe \ -compiler <COMPILER> \ -config "builtin://Recommended Rules" \ -module . \ -input cpptestscan.bdf
For more information about running static analysis on the .bdf file, see About Build Data Files.
Analyzing a Microsoft Visual Studio Project or Solution
C/C++test can read Visual Studio project and solution files and analyze all source and included header files from the project or solution. Use the -input
switch to specify a Visual Studio project or solution file:
cpptestcli -config "builtin://Recommended Rules" -input MyProject.vcproj
You can specify the build configuration and the platform you want to use during analysis of your project or solution. Append the configuration and platform names to the solution or project file name. Your command may resemble the following:
cpptestcli -config "builtin://Recommended Rules" -input MyProject.vcproj@Debug|x64
Alternatively, you can use the following properties to specify the build configuration and the platform you want to use during analysis of all Visual Studio solutions and projects:
cpptest.input.msvc.config=Debug cpptest.input.msvc.platform=x64
For all Microsoft Visual Studio settings, see Visual Studio Settings.
Ensure that the correct version of Microsoft Visual C++ compiler is available on $PATH before running analysis. Microsoft Visual Studio 6 is not supported.
Specifying C/C++test Data Location
Exclusive access to the .cpptest
directory is required. The directory is created in the current working directory by default, which is where some of the run-specific data is stored. As a result, only one instance of C/C++test can run in a directory at a time. You can use the -workspace
switch to change the location of the .cpptest directory.
-workspace <WORKSPACE_LOCATION>