In this section:

Overview

The input scope defines the C and C++ source files to test with C/C++test. The input scope also provides the full set of information about compiler options and environment, so C/C++test can re-create the original build environment to provide accurate test results. See Running Static Analysis for information about defining compilers.

Analyzing a Single File

See Running Static Analysis for instructions.

Analyzing a Makefile-based Project

See Running Static Analysis for instructions.

Analyzing Code Using Existing Build Data

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. See the following sections for additional information:

• Description of the concept of the .bdf and how to create it, see Running Static Analysis.
• Description of the steps for using the .bdf for analysis, see Running Static Analysis.
• Description of how to broaden the scope of files tested, including header files, see Defining Source File Structures (Modules).

Defining Source File Structures (Modules)

C/C++test treats the input scope as a set of unrelated source files. Defining modules allows you to introduce a well-defined source file structure and add additional files, such as header files, into the Input Scope. 

Modules are defined by specifying its name and the root directory. All tested files located in the root directory or its sub-directories will belong to the module. All header files located in the root directory or its sub-directories that are included by the tested source files will also belong to the module and be analyzed with the source files.

For all files from the module, a "module-relative path" will be available. A project-relative path is computed as a relative path from the module root to the actual file location. In most cases, module-relative paths are independent of machines, so the test results can be easily shared across different machines. 

Example of Module Structure

The first block of code describes a simple directory/file structure. In the second block of code, the relationships between the files and module root directory are described, as well as which files will be analyzed:

Assuming module MyApp is defined with /home/devel_1/project root location, the following files will be tested as part of the module: 

Defining a Basic Module Structure

Use the -[<MODULE_NAME>=]<MODULE_ROOT_LOCATION> switch to define a module. If the name is unspecified, the name of the root directory will be used:   

-module MyApp=/home/devel_1/project
-module /home/devel_1/project
-module MyModule=../projects/module1
-module .

Alternatively, module structures can be defined in a custom configuration file using the cpptest.scope.module.<MODULE_NAME>=<MODULE_ROOT_LOCATION>  property:

cpptest.scope.module.MyApp=/home/devel_1/project
cpptest.scope.module.MyModule=../projects/module1

Defining a Module with Multiple Root Locations

Add a logical path to the module name that points to the appropriate root location to define multiple, non-overlapping locations: 

-module MyApp/module1=/home/devel_1/project -module MyApp/module2=/home/external/module2/src

cpptest.scope.module.MyApp/module1=/home/devel_1/project
cpptest.scope.module.MyApp/module2=/home/external/module2/src

Fine-tuning the Input Scope

Use the  -resource switch to specify a file or set of files for testing. 

-resource /home/cpptest/examples/ATM/ATM.cxx
-resource /home/cpptest/examples/ATM
-resource ATM.cxx

You can specify the following resources in the path:

• File path (only selected file will be tested)
• Directory path (only files from selected directory will be tested)
• File name (only files with selected name will be tested)

Use the -include and -exclude switches to apply additional filters to the scope.

• -include instructs C/C++test to test only the files that match the file system path; all other files are skipped.
• -exclude instructs C/C++test to test all files except for those that match the file system path.

If both switches are specified, then all files that match -include, but not those that match -exclude patterns are tested.

-include pattern
-exclude pattern

The -include and -exclude switches accept an absolute path to a file, with asterisk (*) as an accepted wildcard. 

-include /home/project/src/ATM.cxx
-include /home/project/CustomIncludes.lst
-exclude /home/project/src/*.cxx
-exclude /home/project/CustomExcludes.lst 

You can specify a file system path to a list file (*.lst) to include or exclude files in bulk. Each item in the *.lst file is treated as a separate entry.

Defining File Filters Based on Source Control Data

You can restrict the scope of analysis to locally modified files or to files modified on the current working branch by setting up additional file filters. This allows you to focus on identifying and fixing bugs introduced by your recent code changes before the code is checked in your source control system or merged with the main development stream.

Prerequisites

• Connection to a supported source control system must be properly configured (see Connecting to Source Control and Source Control Settings).
• The scope.scontrol=true setting must be configured to enable computing authorship based on your source control system (see Scope and Authorship Settings).

Analyzing Locally Modified Files

To narrow down the scope of analysis to files that are locally modified, add the following option in your .properties configuration file:

scope.scontrol.files.filter.mode=local

Analyzing Files Modified on the Current Working Branch

To narrow down the scope of analysis to files on the current working branch that differ from the main integration stream, such as "master" or "trunk", add the following option in your .properties configuration file:

scope.scontrol.files.filter.mode=branch

If you want to compare your working branch with another branch or with a specific revision rather than the main integration stream, you need to provide the name or ID of the branch or revision you want to use as reference. The following configuration narrows down the scope of analysis to files on the current working branch that differ from a custom branch/revision:

scope.scontrol.files.filter.mode=branch
scope.scontrol.ref.branch=[name/ID of the custom reference branch/revision]

Including Header Files in the Test Scope

C/C++test does not analyze header files directly. This means that header files are only analyzed if they are included in a source file that is being tested. If an unmodified source file is excluded from analysis by applying file filters, all header files that are used by that source file are also excluded–even if they have been modified.

To ensure that modified header files are analyzed, even if the source files that include them remain unchanged, enable the cpptest.scope.adjuster.cu.enabled  option in your .properties file that includes advanced scope options. This will enable analyzing all files that belong to the same compilation unit as the file that has been modified. 

Examples

scope.scontrol.files.filter.mode=local
cpptest.scope.adjuster.cu.enabled=true

scope.scontrol.files.filter.mode=branch
scope.scontrol.ref.branch=[name/ID of the custom reference branch/revision]
cpptest.scope.adjuster.cu.enabled=true

See Scope and Authorship Settings.

Alternatively, you can define additional scope filters in the test configuration by creating a custom test configuration and specifying the filter you want to apply, see Creating Custom Test Configurations. The scope filter settings configured in the GUI only affect the given test configuration and are overridden by scope filter settings configured in .properties file.