Part IV
CoverageScanner Reference

Chapter 8 Introduction

CoverageScanner is a C++ program that—in effect—replaces the usual compiler. It uses the native compiler’s preprocessor program to process the source code, then inserts instrumentation code into the preproecessed program, and at the end it compiles and links the project file, in the same way as in a normal build.

CoverageScanner’s instrumentation process consists of:

declaring a static table that contains the of instrumentation results.
generating a library which produces an execution report when the program terminates or receives a UNIX^® signal or a Microsoft^® Windows event.
adding the instrumentation code itself for each relevant statement or Boolean expression.

The compiler, linker and preprocessor that are used are from the native environment (gcc, Visual Studio, etc.). The Squish Coco tools are used transparently and the developer has only to prepend ’cs’ to the name of the compiler executable to activate the code coverage¹. For example, using ’csgcc’ instruments the source code and uses the ’gcc’ compiler to generate objects.

Another way to achieve coverage is to add a wrapper directory to the search path. It contains compiler wrappers with the same name as the native tools. They are disabled by default but can be switched on with help of the COVERAGESCANNER_ARGS environment variable.

8.1 Invoking CoverageScanner

CoverageScanner works like a pre-processor which calls after instrumenting a source file the native compiler (Microsoft^® cl.exe, GNU g++, …).

Several invocation method are possible:

Using the dedicated CoverageScanner executable for a specific compiler: CoverageScanner executable for a specific compiler is called to cs+’native compiler name’ or alternatively ’native compiler name’+-cs. (example: cl.exe is the Microsoft^® C++ compiler and the corresponding CoverageScanner executable is cscl.exe or cl-cs.exe).
CoverageScanner aims to work then as the native compiler with the difference that the code get instrumented.
Example:
csg++ source.cpp -o application.exe
Using CoverageScanner compiler wrapper and activating the instrumentation using --cs-on in the command line arguments:
Squish Coco provides also a replacement of the native compiler called wrapper which extends its command line argument to support the code coverage feature. To use it it is necessary to add at the first position in the PATH variable the path of CoverageScanner wrapper. The instrumentation get activated, when adding --cs-on to the command line argument.
Example:
export PATH=/opt/SquishCoco/wrapper/bin:$PATH
g++ --cs-on source.cpp -o application.exe
Or, without modifying globally the PATH variable:
PATH=/opt/SquishCoco/wrapper/bin:$PATH g++ --cs-on source.cpp -o application.exe
Using CoverageScanner compiler wrapper and activating the instrumentation through COVERAGESCANNER_ARGS environment variable:
It is also possible to set the command line arguments of the wrapper using the COVERAGESCANNER_ARGS environment variable (see Chapter 9.1). In this case it is no longer necessary to modify the command line arguments.
Example:
export PATH=/opt/SquishCoco/wrapper/bin:$PATH
export COVERAGESCANNER_ARGS='--cs-on'
g++ source.cpp -o application.exe
Or, to instrument a complete project built using GNU make:
COVERAGESCANNER_ARGS='--cs-on' PATH=/opt/SquishCoco/wrapper/bin:$PATH make all
Using --cs-compiler command line option of CoverageScanner:
--cs-compiler permits to select which native compiler should be used. All other command line arguments, except those specific to CoverageScanner, are passed through to the native compiler.
Example:
coveragescanner --cs-compiler=g++ source.cpp -o application.exe

The native compiler path needs to appear in the PATH variable, after the path to the compiler wrappers. This is necessary for finding the location of the native compiler after insertion of the instrumentation code.

Compiler support is done with the help of a profile. It contains declarations which make it possible to adapt CoverageScanner to C, C++ and C# preprocessors, compilers and linkers.

For a description of the compilers that are currently supported see Chapter 42. For a description of the profile syntax see Chapter 12

Chapter 9 Command Line Arguments

Syntax:

cs⟨compiler⟩ [⟨cs-options⟩] ⟨compiler arguments⟩
coveragescanner –cs-compiler=⟨STRING⟩ [⟨cs-options⟩] ⟨compiler arguments⟩
coveragescanner –cs-profile=⟨STRING⟩ [⟨cs-options⟩] ⟨compiler arguments⟩

where

⟨compiler⟩: One of the compilers supported by Squish Coco. Calling cs⟨compiler⟩ results in a call of CoverageScanner as a wrapper of ⟨compiler⟩.
⟨cs-options⟩: One or more of the options that are described in the following sections.
⟨compiler arguments⟩: All the other options. They are copied to the command line of the compiler when it is called by CoverageScanner.

For the use of --cs-compiler and --cs-profile see Chapter 9.2.9.

The command line arguments are prioritized by their order in the command line: the latest entered option has a higher priority than the first one.

Example: cscl --cs-include=foo.h --cs-exclude=foo.h will exclude the header file foo.h from the coverage analysis.

9.1 Environment variables

CoverageScanner also reads options from the environment variable COVERAGESCANNER_ARGS. The options must be separated by spaces or tab characters (‘ ’ or ‘\t’). If both command line arguments are present and the variable COVERAGESCANNER_ARGS is set, the command line options take precedence over the options in the environment variable.

This variable should only be set temporarily, e.g. in a script, because otherwise it would influence all builds.

The location of the temporary files that CoverageScanner generates can be changed by setting the environment variable SQUISHCOCO_TEMP_DIR to the path to another directory (see Chapter 41.3).

9.2 List of options

9.2.1 Coverage modes

For a description of the coverage modes, see Part III.

--cs-off: Disable all code coverage analysis. CoverageScanner then calls the compiler or linker unchanged.
--cs-on: Enable code coverage analysis.
This is the default if CoverageScanner is called directly or as a wrapper that starts with cs, like csgcc. If the wrapper has however the same name as the program (e.g. gcc), code coverage is by default switched off.
--cs-off=⟨pattern⟩: Disable all code coverage analysis when compiling a source with an absolute file name that matches the wildcard expression ⟨pattern⟩ or if the string ⟨pattern⟩ is identical to a command line argument. CoverageScanner then calls the compiler or linker unchanged.
--cs-on=⟨pattern⟩: Enable all code coverage analysis when compiling a source with an absolute file name that matches the wildcard expression ⟨pattern⟩ or if the string ⟨pattern⟩ is identical to a command line argument.
It is possible to have several --cs-on=⟨pattern⟩ and --cs-off=⟨pattern⟩ options. The last option that is matching decides whether code coverage analysis is enabled or disabled.
If several sources are compiled with the same compiler command (as it occurs with C#), disabling the coverage analysis for one source file with --cs-off=⟨pattern⟩ will disable the analysis for all others.
--cs-hit: Set the instrumentation mode to hit instrumentation. It then only matters whether an instrumentation point (a line, a condition or a block) was executed at least once, not how many times.
--cs-count: Set the instrumentation mode to count instrumentation. (Default)
With this mode, the number of times an instrumentation point is executed is counted.
--cs-statement-block: Enable statement block coverage.
--cs-decision: Enable statement block and decision coverage.
--cs-condition: Enable statement block, decision and condition coverage. (Default)
--cs-mcc: Enable Multiple condition coverage.
--cs-mcdc: Enable MC/DC coverage.
--cs-function: Enable function coverage. (Default)
--cs-no-function: Disable function coverage instrumentation.
--cs-line: Enable line coverage. (Default)
If this option is set, decision and condition coverage are automatically enabled too and full instrumentation mode (--cs-full-instrumentation) is switched on.
--cs-no-line: Disable line coverage. The other instrumentation modes that are automatically enabled by --cs-line are not disabled.

9.2.2 Fine-tuning of the instrumentation

--cs-no-exceptions

Do not instrument the catch block of a try…catch statement.

--cs-no-assignments

Do not instrument Boolean expressions in assignments.

--cs-no-execution-time

Disable the usage of performance measurements of the application to instrument. (By default, execution time measurement is enabled.)

--cs-execution-time

Enable the usage of performance measurements of the application to instrument.

--cs-no-returns

Do not instrument Boolean expressions in return statements.

--cs-combine-switch-cases

With this option, decision and condition coverage do not distinguish between case labels that lead to the same code. This means that in the following code, the cases i == 3 and i == 4 are not distinguished. If the option is not set, the two cases are counted separately.

switch (i) {
    case 3:
    case 4:
       i = 0;
       break;
    ...
}

The option is valid for C++ and C#.

--cs-partial-instrumentation

Suppression of redundant conditions. Setting this option also disables line coverage.

The option influences the instrumentation of if statements without an else part, like

if (cond) {
i += 1;
}

Without the option, an invisible else branch is created and its coverage is measured too. If the option is set, this is no longer done and the coverage of the case in which cond is false is no longer measured. The instrumented code then becomes slightly smaller, which may be necessary on small embedded systems.

--cs-full-instrumentation

No suppression of redundant conditions. (Enabled by default)

--cs-boost

Specific handling of Boost library constructs. Currently this only means that the code behind the macro BOOST_FOREACH is not instrumented. (Enabled by default.)

--cs-no-boost

No specific handling of Boost library constructs.

--cs-qt4

No instrumentation for class members generated by moc for the Qt4 and Qt5 libraries (Q_OBJECT, qt_metacall, qt_metacast, …) . The code behind the macro Q_FOREACH stays also uninstrumented. Qt signals remain instrumented. (Enabled by default.)

--cs-no-qt4

No specific handling of the Qt4 and Qt5 libraries.

--cs-qt3

No instrumentation for class members generated by moc for the Qt3 library (Q_OBJECT, className, tr, …). Qt signals remain instrumented. (Enabled by default.)

--cs-no-qt3

No specific handling of the Qt3 library.

--cs-no-annotations

No extraction of annotations (comments and manual validations) from the source files.

--cs-no-purecov-annotations

No extraction of purecov’s annotations from the source files.

--cs-vs2010-lambda

Instrument the expression in the return statement of a lambda function.

This brings a better support of lambda expression on Microsoft^® Visual Studio^® 2010. The option is only valid for C++11 compilers and Microsoft^® Visual Studio^® 2010. With a C compiler or an older C++ compiler, this option has no effect.

--cs-exit-function=⟨function⟩

Declare ⟨function⟩ as the name of an exit function.

An exit function is a command that ends the control flow in a function, like a return statement or the call of the exit() function, or a function that always throws an exception. Any code directly after such a statement is then unreachable. With this option, it is possible to inform Squish Coco that there are user-defined functions that have the same effect as exit().

The option can be repeated; then several exit functions are declared.

--cs-no-line-directive

Remove all #line directives from the code generated by the preprocessor for C++and C#.

The preprocessor is called by the CoverageScanner before instrumenting a file; afterwards the original compiler is called. On some systems, compiling a file this way causes problems that do not occur when the compiler is called directly. Removing the #line statements then sometimes helps.

--cs-counter-size=⟨int⟩

Size of the internal execution counters. Possible values are 1 (byte), 4 (32bit integer) or 8 (64bit integer). The counters are used inside the instrumented program to count the number of times an instrumentation point has been executed. Large internal counters prevent counter overflows, smaller counters may be necessary on small embedded systems to save space. The default value is 8.

--cs-mcc-max=⟨size⟩ | --cs-mcdc-max=⟨size⟩

Set the maximal size of the instrumentation tables that are used for Multiple Condition coverage or MC/DC. The default for ⟨size⟩ is 8000.

For each decision, a truth table is generated under Multiple Condition coverage and MC/DC. ⟨size⟩ is the maximal number of lines in the table. If a decision requires a truth table that is longer than ⟨size⟩, Squish Coco falls back to condition coverage for that decision.

9.2.3 File and path inclusion

The following options allow to specify which files are included in the code coverage. The options apply to files on the command line and to those that are specified on #include statements.

One can use wildcards and regular expressions. In contrast to the common usage, the ‘*’ in wildcard expressions matches also the path separation characters. The syntax of regular expressions is described in Section 9.4.

Options accumulate. If more than one of the file inclusion/exclusion option is present, the last one that matches a given file determines whether it is included or excluded.

In the next options, name of the file in question is first converted to an absolute path.

--cs-include-file-abs-wildcard=⟨pattern⟩: Include a file in the coverage analysis if its absolute path matches the wildcard expression ⟨pattern⟩.
--cs-exclude-file-abs-wildcard=⟨pattern⟩: Exclude a file from the coverage analysis if its absolute path matches the wildcard expression ⟨pattern⟩.
Example: --cs-exclude-file-abs-wildcard=*.h excludes all files with the extension .h.
--cs-include-file-abs-regex=⟨pattern⟩: Include a file in the coverage analysis if its absolute path matches the regular expression ⟨pattern⟩.
--cs-exclude-file-abs-regex=⟨pattern⟩: Exclude a file from the coverage analysis if its absolute path matches the regular expression ⟨pattern⟩.
Example: --cs-exclude-file-abs-regex=^.*\.h$ excludes all files with the extension .h.
--cs-include-path=⟨path⟩: Include all files in the directory ⟨path⟩ and its subdirectories in the coverage analysis. Wildcards or regular expressions cannot be used.
Example: --cs-include-path=c:\include includes all files located in c:\include.
--cs-exclude-path=⟨path⟩: Exclude all files in the directory ⟨path⟩ and its subdirectories from the coverage analysis. Wildcards or regular expressions cannot be used.
Example: --cs-exclude-path=c:\include excludes all files located in c:\include and its subdirectories.

Examples for complex inclusion patterns:

--cs-exclude-file-abs-wildcard=* --cs-include-file-abs-wildcard=*.cpp instruments only .cpp files.
--cs-exclude-file-abs-wildcard=* --cs-include-file-abs-wildcard=*.cpp --cs-include-file-abs-wildcard=*.cxx instruments only .cpp and .cxx files.
--cs-exclude-file-abs-wildcard=*/3rdparty/* does not instrument any files from the directory 3rdparty.
--cs-exclude-file-abs-wildcard=*/3rdparty/* --cs-include-file-abs-wildcard=* instruments all files: The first filter rule has no effect.

Relative paths

The following options refer to the name under which a file occurs in an #include statement or on the command line.

File paths and wildcard expression are converted to a canonical form which does not contain ‘.’, ‘..’, or a duplicated path separation character. (A ‘..’ at the beginning is however not removed.) On Microsoft^® Windows, characters are also converted to lower case and every slash (‘/’) is replaced with a backslash (‘\’).

Regular expressions are untouched. It is e.g. necessary to ensure that they do not contain duplicated path separators.

--cs-include-file-wildcard=⟨pattern⟩: Include a file in the coverage analysis if its normalized path matches the wildcard expression ⟨pattern⟩.
Example: --cs-include-file-wildcard=../include/*.h includes all files with the extension .h located in the directory ../include/ and its subdirectories.
--cs-exclude-file-wildcard=⟨pattern⟩: Exclude a file from the coverage analysis if its normalized path matches the wildcard expression ⟨pattern⟩.
--cs-include-file-regex=⟨pattern⟩: Include a file in the coverage analysis if its normalized path matches the regular expression ⟨pattern⟩.
Example: --cs-include-file-regex=^\.\./include/[^/]*\.h$ includes all files with the extension .h located in ../include/.
--cs-exclude-file-regex=⟨pattern⟩: Exclude a file from the coverage analysis if its normalized path matches the regular expression ⟨pattern⟩.

Relative file names are computed relatively to the current working directory. For example, depending on the working directory one has to use different parameters in order to inhibit the instrumentation of a file src/test.c: If one is outside the directory src, one may use

$ csgcc src/test.c --cs-exclude-file-wildcard=src/test.c

but when switching to src, the parameters must change:

$ cd src
$ csgcc test.c --cs-exclude-file-wildcard=test.c

Setting inclusion/exclusion expressions on absolute paths should be preferred on complex build systems, since modern build system often change the current working directory. Working with absolute paths make it easier to set global rules for a project.

9.2.4 Function inclusion

--cs-include-function-wildcard=⟨string⟩: This command line option enables the user to include a function in the coverage analysis. The function name is specified using a wildcard expression and must include for C++ code the class name and namespace.
Example: --cs-include-function-wildcard=C::* includes all members of the class C.
--cs-exclude-function-wildcard=⟨string⟩: This command line option enables the user to exclude a function from the coverage analysis. The function name is specified using a wildcard expression and must include for C++ code the class name and namespace.
Example: --cs-exclude-function-wildcard=*::Get* excludes all members of any classes which starts with Get.
--cs-include-function-regex=⟨string⟩: This command line option enables the user to include a function in the coverage analysis. The function name is specified using a regular expression and must include for C++ code the class name and namespace. (see chapter 9.4 for the syntax)
--cs-exclude-function-regex=⟨string⟩: This command line option enables the user to exclude a function from the coverage analysis. The function name is specified using a regular expression and must include for C++ code the class name and namespace. (see chapter 9.4 for the syntax)

If more than one of these inclusion/exclusion option is present, the last one that matches a given function determines whether it is included or excluded.

The following option works indepentent of the previous ones:

--cs-record-empty-functions: Enable instrumentation of functions with an empty body. (By default this is disabled.)

9.2.5 Debugging

--cs-verbose-source-lines=⟨int⟩

Maximum number of source code lines dumped in an error message.

--cs-verbose=⟨string⟩

Generate verbose debug messages. Possible options are:

cmd: During the build, CoverageScanner displays the command line arguments of the programs it executes. This includes especially the command line arguments of the compiler when it translates the instrumented source code.
build: During the build, the instrumentation by CoverageScanner is traced. This includes e.g. the information about which files are instrumented and which are excluded from instrumentation.
This option automatically implies --cs-verbose=cmd.
api: When the instrumented program is run, the calls to the CoverageScanner library are traced.

By default, the output is written to stderr.

--cs-verbose-file=⟨file⟩

Define the file used for generating a CoverageScanner log file. This option has no effect when --cs-verbose is not used.

--cs-keep-instrumentation-files

Do not delete temporary instrumentation files. They will be left under random names in the Squish Coco temporary directory (see Chapter 41.3).

--cs-warnings=⟨string⟩

Instrumentation warning behaviour:

none: Warnings will not be displayed.
display: Warnings will be displayed via stderr.
error: Warnings will trigger a compilation error.

--cs-compilation-warnings=⟨string⟩

Compilation warning behaviour:

none: Warnings will not be displayed.
display: Warnings will be displayed via stderr.
error: Warnings will trigger a compilation error.

--cs-annotation-warnings=⟨string⟩

Source code annotations warning behaviour:

none: Warnings will not be displayed.
display: Warnings will be displayed via stderr.
error: Warnings will trigger a compilation error.

9.2.6 Execution report

--cs-output=⟨string⟩

Set the file name for the execution report. The extension .csexe is added automatically.

By default, ⟨string⟩ has the value “%F” and CoverageScanner uses the application name without the path as name for the .csexe file.

The value of ⟨string⟩ may be an absolute path, like “/my/dir/%F”. The directories in this path must already be present when the instrumented program runs, since CoverageScanner does not create them by default.¹ Otherwise, ⟨string⟩ is interpreted as a path relative to the working directory at the time the program starts.

⟨string⟩ may contain several format specifiers. The values of the following specifiers are computed at compile time:

%T: Current local time as an integer. (Example: 163355 for 16h33 and 55s)
%D: Current local date as an integer. (Example: 20140130 for January 30, 2014)
%F: Application/library file name without path.
%A: Absolute application/library file name.
%B: Application/library file name without path and extension.
%P: Application/library file path.
%/: File path separator (on Unix a slash, ‘/’, and on Windows a backslash, ‘\’).

The values of the following format specifiers are computed at runtime:

%c: Current working directory. The value is is computed before the main() function is started. If the current working directory changes, this path remains identical.
%p: Process identifier. If for any reason it cannot be computed, “%p” will be replaced with an empty string.
%t: Current local time. If for any reason it cannot be computed, “%t” will be replaced with an empty string.
%d: Current local date. If for any reason it cannot be computed, “%d” will be replaced with an empty string.
<X>: Replace “<X>” with the content of the environment variable “X”.

--cs-file-name-format-specifier

Enable the file format specifiers support.

--cs-no-file-name-format-specifier

Disable the file format specifiers support.

--cs-lock-csexe

Create a lock file which lock the access of the .csexe file during its generation.

--cs-nolock-csexe

Inverse option to --cs-lock-csexe. The preprocessor output is transmitted to CoverageScanner through a temporary file.

--cs-dump-on-signal=⟨signal⟩

Generate an execution report when a specific signal was received. The signal can be specified by a number from 1 to 63, or by the conventional signal name, like SIGINT, SIGTERM, etc. (see Chapter 34.1).

--cs-dump-on-event=⟨string⟩

Generate an execution report when a specific Microsoft^® Windows event was received (see Chapter 34.2).

9.2.7 Command line modification

--cs-compiler-option=⟨option⟩: Add ⟨option⟩ to the end of the compiler command line when compiling the instrumented code. When code coverage is disabled, nothing happens. The option can be repeated if more than one option is needed.
--cs-libgen=⟨option⟩: Put an additional command line option to the compiler call which generates the code coverage library. The option can be repeated if more than one option is needed.
The options are appended and become the content of $LIBGEN$, a variable that may occur in the replacement text for the profile option COMPILER_CMD (see Chapter 12.4).
--cs-library-after=⟨option⟩: Put the linker argument for the CoverageScanner library after a specified option.
If used in the form “--cs-library-after=-lmylib”, the linker parameter for the CoverageScanner library will be inserted directly after the option -lmylib.
--cs-library-at-start: Add the linker argument for the CoverageScanner library before all other command line options.
--cs-library-at-end: Add the linker argument for the CoverageScanner library after all other command line options.

9.2.8 Generated code

--cs-no-csharp-dynamic

If set, the C# dynamic type is not used in the instrumentation code generated by Squish Coco.

With the dynamic type, Squish Coco can better handle Boolean expressions that contain non-Boolean objects with overloaded true and false functions. Dynamic types are however only available for Microsoft^® Visual Studio^® 2010 and later; for earlier C# versions, this option is needed.

--cs-csharp-dynamic

If set, the C# dynamic type is used in the instrumentation code generated by Squish Coco.

--cs-enable-coveragescanner-library-abs-wildcard=⟨string⟩

Enable the generation of the CoverageScanner library when the absolute file name of the generated binary matches the given wildcard expression.

--cs-disable-coveragescanner-library-abs-wildcard=⟨string⟩

Disable the generation of the CoverageScanner library when the absolute file name of the generated binary matches the given wildcard expression.

--cs-memory-pool=⟨int⟩

Generate a CoverageScanner library which uses a memory pool bytes instead of calling malloc()free(). The size of the pool is ⟨int⟩ bytes. This option is useful only for operating systems which do not support dynamic memory allocation.

--cs-memory-pool-code=⟨string⟩

Declaration code for the memory pool. This is optional and permits a custom declaration of the array containing the head used by the CoverageScanner library. The default implementation is a static array of character declared as followings: static char %S[%I]. The following placeholder are available:

%S: the symbol name for the custom heap.
%I: the heap size in bytes.

--cs-link-instrumentation-tables

Chain all instrumentation tables at link time and not at run time. (This is the default.)

The instrumentation tables are internal arrays generated by Squish Coco which contain the counter variables for code coverage.

--cs-register-instrumentation-tables

Chain all instrumentation tables at run time and not at link time. This option has an effect only on platforms for which the profile parameter INSTRUMENTATION_TABLES_LINKED_DURING_RUNTIME_SUPPORT (see Chapter 12.4) has the value “Yes”.

--cs-no-exit-handler-installation

Disable the automatic installation of the handler which saves the code coverage report. If this handler is not installed, no executions report will be generated when the application exits or when a custom signal or Windows event is received. Call __coveragescanner_install() to install the handler manually.

--cs-minimal-api

With this command line option, a CoverageScanner API is generated that has fewer dependencies to external libraries than the default API. This may be necessary for embedded systems or when compiling a C# application with the command line switch /noconfig.

9.2.9 Miscellaneous

--cs-compiler=⟨string⟩: This command option enables the user to select a profile. This option does not normally need to be specified, due to the fact that the profile name is usually extracted from the command line name. (cscl.exe implicitly selects the profile cl.cspro)
Example: --cs-compiler=cl selects the profile ’cl.cspro’.
--cs-profile=⟨string⟩: This option permits to set directly the path of CoverageScanner profile. Using this option if not compatible with --cs-compiler.
Example: --cs-profile=%SQUISHCOCO%\cl.cspro is equivalent to --cs-compiler=cl on Microsoft^® Windows.
--cs-architecture=⟨string⟩: Internal option to specify the target architecture. It sets the variable $ARCHITECTURE$ in the replacement text for the profile parameter PREPROCESSOR_CMD (see Chapter 12.3). The target architecture is also used to select alternate profile parameters (see Chapter 12).
--cs-parallel-build=⟨int⟩: Maximum number of concurrent code generation/compilation.
--cs-cpp-ext=⟨list⟩: List of file extensions corresponding to C++ files (ex: .cpp,.cxx)
--cs-c-ext=⟨list⟩: List of file extensions corresponding to C files (ex: .c)
--cs-native-toolchain=⟨string⟩: Adds a directory in the search path of the native compiler. This command can be repeated. In this case the first one is the prefered location.
--cs-option-file=⟨file⟩: Specify command line options from a file. The file may contain all valid CoverageScanner command line options and the command line options of the native tool. It must contain one argument per line. Leading and trailing spaces are removed and empty lines are ignored, but no other input processing is done. The option can be repeated.
--cs-file-name-lower-case: Convert absolute file names to lower case. (For backward compatibility with the version 4.1)
--cs-no-pch: If set, precompiled headers are deactivated during the compilation.
--cs-no-cspch: If set, the files with the extension .cspch are not generated. This files are only used to enhance the compilation speed when using precompiled headers.

9.3 Instrumenting using preprocessor defines

CoverageScanner activates also the instrumentation if some defines are present in the command line option. This permits to instrument code with an IDE which does not permits to add custom command line options to the compiler or linker.
Example: Defining COVERAGESCANNER_COVERAGE_ON is equivalent of adding --cs-on to the command line.

Define	Equivalence
COVERAGESCANNER_RUNTIME_LOG	--cs-verbose=api
COVERAGESCANNER_DUMP_ON_EVENT	--cs-dump-on-event=Global\COVERAGE
COVERAGESCANNER_COVERAGE_ON	--cs-on
COVERAGESCANNER_COVERAGE_OFF	--cs-off
COVERAGESCANNER_COVERAGE_HIT	--cs-hit
COVERAGESCANNER_COVERAGE_COUNT	--cs-count
COVERAGESCANNER_COVERAGE_BASIC_BLOCK	--cs-statement-block
COVERAGESCANNER_COVERAGE_DECISION	--cs-decision
COVERAGESCANNER_COVERAGE_CONDITION	--cs-condition
COVERAGESCANNER_COVERAGE_MCC	--cs-mcc
COVERAGESCANNER_NO_CSHARP_DYNAMIC	--cs-no-csharp-dynamic
COVERAGESCANNER_NO_LINE_DIRECTIVE	--cs-no-line-directive
COVERAGESCANNER_CSHARP_DYNAMIC	--cs-csharp-dynamic
COVERAGESCANNER_COVERAGE_LOCK_CSEXE	--cs-lock-csexe
COVERAGESCANNER_COVERAGE_NOLOCK_CSEXE	--cs-nolock-csexe
COVERAGESCANNER_COVERAGE_PARTIAL_INSTRUMENTATION	--cs-partial-instrumentation
COVERAGESCANNER_COVERAGE_FULL_INSTRUMENTATION	--cs-full-instrumentation
COVERAGESCANNER_COVERAGE_NO_EXCEPTIONS	--cs-no-exceptions
COVERAGESCANNER_COVERAGE_NO_ASSIGNMENTS	--cs-no-assignments
COVERAGESCANNER_MINIMAL_API	--cs-minimal-api
COVERAGESCANNER_COVERAGE_COMBINE_SWITCH_CASES	--cs-combine-switch-cases
COVERAGESCANNER_OUTPUT_ABS	--cs-output=Global\%A

9.4 Regular Expressions

Regular expressions are composed of items (see table 9.1 for the full list) and combining operators. These can be:

[…]: The brackets are used to define a set of characters. For example, [123] corresponds to the characters 1, 2 or 3. It is possible to define a range using the minus sign: [a-z] corresponds to all characters between a and z.
[^…]: The caret defines a set of characters which should not match. For example, [^0-9] corresponds to any character except a digit.
?: The question mark after a regular expression item makes it optional.
Example: ab? matches the string a or ab.
+: The plus operator makes it possible to repeat the regular expression item.
Example: ab+ matches every strings ab…b.
*: The star operator after a regular expression item signifies that the item is optional and can be repeated.
Example: ab* matches every string ab…b and a.
|: The pipe operator specifies an alternative.
Example: a|b matches the character a or b.
(…): The parenthesis groups expressions into sub-expressions.
Example: (true)|(false) matches the string true or false.
Regular Expression Items: The regular expression items are ASCII or magic characters (See table 9.1 for the complete list). If a magic character needs to be used as an ASCII character, it has to be escaped with a backslash (\).

Element Description Equivalence Reverse Element

^ The caret marks the beginning of the string. For example, ^c: will only match file names with an absolute path on the drive C:. If you wish to match a literal ^ you must escape it by writing \^.

$ The dollar marks the end of the string. For example \.cpp$ will match every C++ file name. If you wish to match a literal $ you must escape it by writing \$.

\< Match the start of a word.

\> Match the end of a word.

. Any character

\ Escape character. Example: \. corresponds to the character ’.’ and not any character

\m Alphanumeric character [0-9a-zA-Z] \M

\a Alphabetic character [a-zA-Z] \A

\b Blank character [ \t] \B

\c Control character \C

\d Digit [0-9] \D

\g Printable character except space [] \G

\l Lower-case character [a-z] \L

\p Printable character \P

\n Printable character except space or alphanumeric character \N

\s White-space characters (space, form-feed , newline , carriage return , horizontal tab and vertical tab) [ \f\n\r\t\v] \S

\u Uppercase letter [A-Z] \U

\x Hexadecimal digits [0-9a-fA-F] \X

\w Alphanumeric character or underscore [0-9a-zA-Z_] \W

Table 9.1: Non ASCII Regular Expression Items

Chapter 10 Library calls

10.1 C and C++ Library

The CoverageScanner library is generated during instrumentation and enables the user

to initialize the measurement system and select the name of the .csexe file,
to install a handler which saves the execution report on exit,
in a unit test scenario, to pass information about the tests to the execution report, especially the name of the test, comments and the test result,
to handle dynamically loaded libraries, and
to customize the output system for special needs.

The library functions are accessible from any instrumented file, without the need for an #include directive. When a file is instrumented, a preprocessor symbol __COVERAGESCANNER__ is defined: It can be used to exclude calls to the library functions from the compilation when instrumentation is switched off.

10.1.1 __coveragescanner_install()

Syntax:

void __coveragescanner_install(const char *appname)

This function is not needed for gcc, clang or Microsoft^® Visual Studio^®.

Initialize the CoverageScanner library. It should be the first function call in the main() function. The parameter appname contains the name of the executable. It is used to set the name of the measurement file to ⟨appname⟩.csmes.

__coveragescanner_install() registers an exit handler via atexit() in order to save the execution report whenever the application terminates. The handler calls the function __coveragescanner_save() to store the execution traces at the end of the program. It is called when the program terminates regularly and also if the signals SIGABRT, SIGTERM, SIGFPE, SIGILL, SIGINT, SIGSEGV and SIGTERM are received.

Suggested usage:

int main(argc,char *argv[])
{
#ifdef __COVERAGESCANNER__
__coveragescanner_install(argv[0]);
#endif
...
}

Platform dependencies

With gcc, clang or Microsoft^® Visual Studio^®, CoverageScanner automatically installs a minimal handler. It saves the execution in the file ⟨program_name⟩.csmes on a normal exit of the application. Calling __coveragescanner_install() allows to set the file name of the execution report and also saves the report at an abnormal exit, like a crash or an interrupt by a signal.

__coveragescanner_install() is not available for a compiler if its profile parameter CUSTOM_SETUP is set to NONE (see Chapter 12).

10.1.2 __coveragescanner_testname()

Syntax:

void __coveragescanner_testname(const char *name)

Set the name of the current test. It will be saved in the execution report and be displayed in the "Executions" window (see Chapter 18.1) when the .csmes file is loaded into CoverageBrowser.

All code that is executed until the end of the program or the next call of __coveragescanner_save() is considered part of the test name. If tests get the same name, CoverageBrowser disambiguates them by numbers, like “MyTest (2)”.

Test names may be hierarchical, with hierarchy levels separated by slashes: If a program defines two tests, “group/test1” and “group/test2”, CoverageBrowser displays them as two tests, “test1” and “test2” under a common heading, “group”.

This and the following functions until __coveragescanner_save() are especially intended for the use with unit test frameworks (see Chapter 32).

10.1.3 __coveragescanner_teststate()

Syntax:

void __coveragescanner_teststate(const char *state)

Set the state of the current test. The parameter state may have the following values:

"PASSED": to indicate that the test was successful.
"FAILED": to indicate that the test was not successful.
"INCIDENT": to indicate that the test was not successful. (similar to failed)
"CHECK_MANUALLY": to indicate that it was not possible to determine whether the test was successful.
"SKIPPED": to indicate that the test was skipped.

If the function is called twice, the first state is overwritten. The test state will be saved in the execution report and be displayed in the "Executions" window (see Chapter 18.1) when the .csmes file is loaded into CoverageBrowser.

10.1.4 __coveragescanner_add_html_comment()

Syntax:

void __coveragescanner_add_html_comment(const char *comment)

Set an HTML comment to the current execution. There is only one HTML comment active at any time, but it can be put together with several calls of __coveragescanner_add_html_comment(). In this case, the values of the various comment parameters are concatenated.

The full comment must follow the HTML syntax, but only the content of the <body> tag is used. A minimal comment might therefore be something like “<html><body>My comment</body></html>”.

10.1.5 __coveragescanner_clear_html_comment()

Syntax:

void __coveragescanner_clear_html_comment()

Remove the comment added by calls of the function __coveragescanner_add_html_comment().

10.1.6 __coveragescanner_save()

Syntax:

void __coveragescanner_save()

Save the execution report and reset the status of all instrumentations. The coverage counters for each line of code and the execution status of the current test are reset, but the HTML comment stays unchanged.

10.1.7 __coveragescanner_clear()

Syntax:

void __coveragescanner_clear()

Reset the coverage counters for all lines of code.

This is useful in a unit testing framework. After the framework has started, __coveragescanner_reset() can be called. Then the activity of the framework at startup does not become part of the code coverage.

10.1.8 __coveragescanner_filename()

Syntax:

void __coveragescanner_filename(const char *name)

Set the file name of the execution report. The extension ’.csexe’ is added automatically. If name is NULL, the generation of execution reports is disabled.

name may contain the following escape sequences:

%p: The process identifier, if it is provided by the platform, otherwise the empty string.
%w: The working directory. The value is computed when the CoverageBrowser library is initialized; it does not change afterwards.
%t: The current time, or the empty string if it cannot be computed.
%d: The current date, or the empty string if it cannot be computed.

Platform dependencies

The escape sequences are only available for a compiler if its profile parameter FILE_FORMAT_SPECIFIER is set to YES (see Chapter 12).

Date and time may not be available on some embedded platforms.

10.1.9 __coveragescanner_get_filename()

Syntax:

const char * __coveragescanner_get_filename()

Function which permits to retrieve the ’.csexe’ file name.

10.1.10 __coveragescanner_register_library()

For the use of this and the following function, see Chapter 31.

Syntax:

int __coveragescanner_register_library(const char *library_name)

Register a shared library that was loaded on demand. The function must be called after a library has been loaded with dlopen() (UNIX^®) or LoadLibrary() (Microsoft^® Windows). After it is registered, the code coverage of the library is saved in the same coverage report file as the coverage of the main application.

It is possible to call __coveragescanner_register_library() more than once, but every call must be matched by a corresponding call of __coveragescanner_unregister_library(). For each library there is a use counter to keep track of the registrations.

Returned values:

0: Success.
-1: Error: library could not be loaded.
-2: Error: invalid library name.
1: Success, but the library is already registered. The use count of the library has been incremented.
2: Success, but the library is not instrumented.

Platform dependencies

__coveragescanner_register_library() and __coveragescanner_unregister_library() are not available for a compiler if its profile parameter PLUGIN_REGISTRATION_API is set to NO (see Chapter 12).

10.1.11 __coveragescanner_unregister_library()

Syntax:

int __coveragescanner_unregister_library(const char *library_name)

De-register a shared library that was loaded on demand. The function must be called before a library is unloaded with dlclose() (UNIX^®) or CloseHandle() (Microsoft^® Windows).

Returned values:

0: Success.
-1: Error: library was not registered.
-2: Error: invalid library name.
1: Success, but the library was not unregistered because its use count was not null.
2: Success, but the library is not instrumented.

10.1.12 __coveragescanner_set_custom_io()

Syntax:

void __coveragescanner_set_custom_io(
    char *(*csfgets)(char *s, int size, void *stream),
    int (*csfputs)(const char *s, void *stream),
    void *(*csfopenappend)(const char *path),
    void *(*csfopenread)(const char *path),
    void *(*csfopenwrite)(const char *path),
    int (*csfclose)(void *fp),
    int (*csremove)(const char *filename) )

Define your own set of I/O functions.

Parameters:

csfgets: Read at most size - 1 characters from stream and store them into the buffer pointed to by s. Reading stops after an EOF or a newline is read. If a newline is read, it is stored in the buffer. A ‘\0’ is stored after the last character in the buffer.
csfputs: Write the string s to stream, without its trailing ’\0’.
csfopenappend: Open the file path for appending text at the end.
csfopenread: Open the file path for reading.
csfopenwrite: Open the file path for writing.
csfclose: Flush and close the stream pointed to by fp.
csremove: Remove the file filename from the file system.

By default, CoverageScanner writes the execution report (the .csexe file) to the file systems with help of common C library functions. In some situations, e.g. with embedded systems, it is necessary to use other methods. For this reason, CoverageScanner provides __coveragescanner_set_custom_io(), which allows to replace the I/O functions used by __coveragescanner_save().

Default implementation:

char *csfgets(char *s, int size, void *stream) { return fgets(s,size,(FILE *)stream); }
int csfputs(const char *s, void *stream)       { return fputs(s, (FILE *)stream); }
void *csfopenappend(const char *path)          { return (void*)fopen(path,"a+"); }
void *csfopenread(const char *path)            { return (void*)fopen(path,"r"); }
void *csfopenwrite(const char *path)           { return (void*)fopen(path,"w"); }
int csremove(const char *filename)             { return remove(filename); }
int csfclose(void *fp)                         { return fclose((FILE*)fp); }

Examples are available in Chapter 35.

10.2 C# Library

CoverageScanner library is generated during the link process and enables the user to:

Generate the execution report.
Give a name to the executed tests.
Install a signal handler which saved the execution report on exit.

Additionally CoverageScanner sets the preprocessor define __COVERAGESCANNER__ which excludes this function from a normal compilation.

10.2.1 CoverageScanner.__coveragescanner_init()

Syntax:

void CoverageScanner.__coveragescanner_init()

CoverageScanner.__coveragescanner_init() initialize explicitly the CoverageScanner library. Calling this function is only necessary on C# DLL which are not calling the static module initializer automatically.

10.2.2 CoverageScanner.__coveragescanner_testname()

Syntax:

void CoverageScanner.__coveragescanner_testname(string name)

CoverageScanner.__coveragescanner_testname() sets the name of the test which is currently being executed. It will be saved to the execution report and is displayed in the "Executions" window (see Chapter 18.1) when the loaded in CoverageBrowser.

10.2.3 CoverageScanner.__coveragescanner_teststate()

Syntax:

void CoverageScanner.__coveragescanner_teststate(string state)

CoverageScanner.__coveragescanner_teststate() sets the state of the test which is currently being executed. The string parameter state can have the following values:

"PASSED": indicates that the test was successfully executed.
"FAILED": indicates that the test was not successfully passed.
"INCIDENT": indicates that the test was not successfully executed. (similar to failed)
"CHECK_MANUALLY": indicates that it was not possible to determinate if the test was successfully executed.
"SKIPPED": indicates that the test was skipped.

It will be saved to the execution report and is displayed in the "Executions" window (see Chapter 18.1) when the loaded in CoverageBrowser.

10.2.4 CoverageScanner.__coveragescanner_add_html_comment()

Syntax:

void __coveragescanner_add_html_comment(string comment)

__coveragescanner_add_html_comment() append a comment to the current execution. The comments needs to follow the HTML syntax but only the body is parsed. (The contents of the “<HEAD>” tag is ignored). This function can be called several times, in this case the content is appended.

10.2.5 CoverageScanner.__coveragescanner_clear_html_comment()

Syntax:

void __coveragescanner_clear_html_comment()

__coveragescanner_add_html_comment() clear comments added using void __coveragescanner_add_html_comment(string comment).

10.2.6 CoverageScanner.__coveragescanner_save()

Syntax:

void CoverageScanner.__coveragescanner_save()

CoverageScanner.__coveragescanner_save() saves the execution report and resets the status of all instrumentations.

10.2.7 CoverageScanner.__coveragescanner_clear()

Syntax:

void CoverageScanner.__coveragescanner_clear()

CoverageScanner.__coveragescanner_clear() resets the status of all instrumentations.

10.2.8 CoverageScanner.__coveragescanner_filename()

Syntax:

void CoverageScanner.__coveragescanner_filename(string name)

this function sets the file name of the execution report. The extension ’.csexe’ is added automatically.

Setting the execution report file name is necessary if the initialization function __coveragescanner_install() is not used.

10.2.9 CoverageScanner.__coveragescanner_set_custom_io()

Syntax:

void CoverageScanner.__coveragescanner_set_custom_io(
    __cs_fgets_delegate cs_fgets,
    __cs_fputs_delegate cs_fputs,
    __cs_fopenappend_delegate cs_fopenappend,
    __cs_fopenread_delegate cs_fopenread,
    __cs_fopenwrite_delegate cs_fopenwrite,
    __cs_fclose_delegate cs_fclose,
    __cs_remove_delegate cs_remove)

Parameters:

csfgets: Type:public delegate string __cs_fgets_delegate(System.IO.Stream stream)
csfgets reads in at most one less than size characters from stream and stores them into the buffer pointed to by s. Reading stops after an EOF or a newline. If a newline is read, it is stored into the buffer. A ’\0’ is stored after the last character in the buffer.
csfputs: Type:public delegate void __cs_fputs_delegate(string s, System.IO.Stream stream)
csfputs writes the string s to stream, without its trailing ’\0’.
csfopenappend: Type:public delegate System.IO.Stream __cs_fopenappend_delegate(string path)
csfopenappend open the file path for writing at the end.
csfopenread: Type:public delegate System.IO.Stream __cs_fopenread_delegate(string path)
csfopenread open the file path for reading.
csfopenwrite: Type:public delegate System.IO.Stream __cs_fopenwrite_delegate(string path)
csfopenwrite open the file path for writing.
csfclose: Type:public delegate void __cs_fclose_delegate(System.IO.Stream fp)
The csfclose function will flush and close the stream pointed to by fp.
csremove: Type:public delegate void __cs_remove_delegate(string n)
csremove removes filename from the file system.

CoverageScanner writes the execution report (.csexe file) into file using the common C# file IO functions. In some situations, for embedded systems for example, it is necessary to use an other way for recording it. For this reason, CoverageScanner provides CoverageScanner.__coveragescanner_set_custom_io() which permits to replace the IO functions used by CoverageScanner.__coveragescanner_save().

Chapter 11 Controlling the instrumentation during the compilation

CoverageScanner offers the possibility to modify the coverage settings of some source code parts during the compilation. This permits, for example, to exclude some source code from the coverage analysis.

11.1 Source Code Annotations

Source code annotations are specific comments which permits to validate some source code parts. Two kind of annotations are existing:

Comments: Comments are simple code comments which can be used for giving advice to the tester. They do not have any impact on the code coverage
Manual Validations: Manual validations permit to indicate that some lines of code should be considered as validated. Manual validations have the same effect on code coverage as executing the source lines.

Source code annotations can directly be edited with CoverageBrowser or generated by writing specific comments into the source code.

11.1.1 Comments

To generate comments for a single source line it is only necessary to start a C or C++ comment with the keyword “coco:⟨comment⟩”. This will insert a comment for all instrumentations in the current line.

Example: In the following example, the comment “To test the failure, change the current working directory to a read-only directory” will be added to the instrumentations of the line 4.

   1 void write_log( const char *text )
   2 {
   3    FILE * f = fopen( "log.txt", "a+" );
   4    if ( f ) /* coco: To test the failure,
   5                      change the current working
   6                      directory to a read-only directory */
   7    {
   8        fputs( text, f ):
   9        fclose( f );
  10    }
  11 }

Comments can also be generated for multiples source lines using the keywords “coco begin:⟨comment⟩” and “coco end”.

Example: In the following example, the comment “To test the failure, change the current working directory to a read-only directory” will be added to the instrumentations of the lines of the function write_log().

   1 void write_log( const char *text )
   2 {
   3    /* coco begin:  To test the failure,
   4                    change the current working
   5                    directory to a read-only directory */
   6    FILE * f = fopen( "log.txt", "a+" );
   7    if ( f )
   8    {
   9        fputs( text, f ):
  10        fclose( f );
  11    }
  12    /* coco end */
  13 }

11.1.2 Manual Validation

Manually validated instrumentation can be generated with a comment in the code that starts with the keywords “coco validated: ⟨comment⟩”. The ⟨comment⟩ will later occur in the coverage report. To validate a multi-line region of code, one can use the keywords “coco begin validated: ⟨comment⟩” and “coco end”. In order to be compatible with PureCoverage adjustments, CoverageScanner also recognizes “purecov:” line comments with the keywords “inspected” or “tested”, or alternatively “begin inspected”/“begin tested” and “end inspected”/“end tested” for multi-line annotations.

Example: In the following example, the comment “This function does not need to be tested, only used for debugging.” will be added to the instrumentations of the function write_log().

   1 void write_log( const char *text )
   2 {
   3    // coco begin validated: This function does not need to be tested, only used for debugging.
   4    FILE * f = fopen( "log.txt", "a+" );
   5    if ( f )
   6    {
   7        fputs( text, f ):
   8        fclose( f );
   9    }
  10 }
  11 // coco end

Note that the “coco end” comment is placed after the end of the function. This is because Coco measures code coverage of a function at its very end, there where the final closing brace is located. When we want to mark a complete function a covered, we need to include the last closing brace in the region between the manual validation comments.

Including the function header by placing the “coco begin” comment in front of the function is however not important.

11.2 C and C++ Pragmas

CoverageScanner defines C and C++ pragmas to control the instrumentation during the compilation. All control pragmas are handled in a stack: They are valid until the end of the source file or until a #pragma CoverageScanner(pop) is encountered.

The pragmas have the following syntax:
#pragma CoverageScanner ( string )
or: __pragma ( CoverageScanner ( string ) )
or: _Pragma ( "CoverageScanner ( string )" )

List of supported pragmas:

#pragma CoverageScanner(cov-on): Enable code coverage instrumentation.
#pragma CoverageScanner(cov-off): Disable code coverage instrumentation.
#pragma CoverageScanner(cov-hit): Instruments using code coverage hit.
#pragma CoverageScanner(cov-count): Instruments using code coverage count.
#pragma CoverageScanner(cov-statement-block): Select statement block coverage as instrumentation method.
#pragma CoverageScanner(cov-decision): Select decision coverage as instrumentation method.
#pragma CoverageScanner(cov-condition): Select condition coverage as instrumentation method.
#pragma CoverageScanner(cov-partial-instrumentation): Partial instrumentation of conditions and decisions.
#pragma CoverageScanner(cov-full-instrumentation): Full instrumentation of conditions and decisions.
#pragma CoverageScanner(cov-assignment-on): Instrument Boolean expressions in assignments.
#pragma CoverageScanner(cov-assignment-off): Do not instrument Boolean expressions in assignments.
#pragma CoverageScanner(cov-return-on): Instrument Boolean expressions in return statements.
#pragma CoverageScanner(cov-return-off): Do not instrument Boolean expressions in return statements.
#pragma CoverageScanner(cov-switch-case-off): Do not instrument all cases of a switch statement.
#pragma CoverageScanner(cov-switch-case-on): Instrument all cases in a switch statement.
#pragma CoverageScanner(pop): Restore the instrumentation options from before the call of the latest CoverageScanner pragma.

11.3 C# regions

CoverageScanner defines C# extensions of the #region keyword which permits to control during the compilation the generation of the instrumentation. The #region extension have the following syntax:
#region CoverageScanner ( string )

The keyword #endregion restores the generation options.

List of supported regions:

#region CoverageScanner(cov-on): Enable code coverage instrumentation.
#region CoverageScanner(cov-off): Disable code coverage instrumentation.
#region CoverageScanner(cov-hit): Instrument using code coverage hit.
#region CoverageScanner(cov-count): Instrument using code coverage count.
#region CoverageScanner(cov-statement-block): Select statement block coverage as instrumentation method.
#region CoverageScanner(cov-decision): Select decision coverage as instrumentation method.
#region CoverageScanner(cov-condition): Select condition coverage as instrumentation method.
#region CoverageScanner(cov-partial-instrumentation): Partial instrumentation of conditions and decisions.
#region CoverageScanner(cov-full-instrumentation): Full instrumentation of conditions and decisions.
#region CoverageScanner(cov-assignment-on): Instrument Boolean expressions in assignments.
#region CoverageScanner(cov-assignment-off): Do not instrument Boolean expressions in assignments.
#region CoverageScanner(cov-switch-case-off): Do not instrument all cases in a switch statement.
#region CoverageScanner(cov-switch-case-on): Instrument all cases in a switch statement.

Chapter 12 CoverageScanner Adaptation to a Tool Suite

If Squish Coco should be used with a new kind of compiler or tool chain, a profile must be written to adapt the CoverageScanner to the compiler. This chapter describes the content of profiles; for the use of profiles with Squish Coco, see Chapter 8.1.¹

The profile lets CoverageScanner:

interpret the command line of the compiler (see Chapter 12.5).
interpret the command line of the linker (see Chapter 12.4).
customize the output of the coverage analysis² (see Chapter 12.8).

The profile is a text file with a name of the form ’⟨tool name⟩.cspro’. It must be located in the Squish Coco installation directory. A profile may contain:

Comments: Lines that start with a # character are treated as comments.
Global parameters: A profile parameter can be assigned a value with the following syntax:
⟨parameter⟩=⟨value⟩
Only one definition per line is allowed.
Parameters for a specific architecture: It is also possible to have a specific version of a parameter that is used only with certain architectures. For this one puts the name of the architecture in brackets behind the parameter, in the following way:
⟨parameter⟩[⟨architecture⟩]=⟨value⟩
Such a definition must be placed after the global parameter definition.

The architecture is determined automatically, but it can also be specified with --cs-architecture.

12.1 Profile Parameters for Architecture Settings

ARCHITECTURE=⟨string⟩: List of command line arguments which specify the architecture used during the compilation. This parameter should be placed in the first lines of the profile.
ARCHITECTURE_APPEND=⟨YES/NO/ALLOW⟩: If set, the argument of the command line option, which defines the architecture, is directly appended (no space characters are placed between the option and the arguments).

12.2 Profile Parameters for Instrumentation Settings

COVERAGESCANNER_DUMP_ON_EVENT=⟨regular expression⟩: Regular expression which activate the Windows event handler listening the global event Global\COVERAGE.
COVERAGESCANNER_RUNTIME_LOG=⟨regular expression⟩: Regular expression which activate the verbose mode of the CoverageScanner API.
COVERAGESCANNER_COVERAGE_ON=⟨regular expression⟩: Regular expression which activate the code coverage analysis (equivalent to --cs-on) if this expression match on a command line argument.
SOURCE_IGNORE_INSTRUMENTATION=⟨list⟩: List of source file which are not instrumented. The list is a list of wildcard expressions which matches absolute file paths. Environment variables can be access by placing the name between two dollars. (ex: $HOME$ to access to HOME environment variable)

12.3 Profile Parameters for Preprocessor Settings

PREPROCESSOR_HIDE_OPTION_NO_ARG=⟨string⟩

List of single options (without arguments) which should not be transmitted to the native preprocessor.

PREPROCESSOR_HIDE_OPTION_ONE_ARG=⟨string⟩

List of options with one argument which should not be transmitted to the native preprocessor.

PREPROCESSOR_HIDE_OPTION_ONE_ARG_APPEND=⟨YES/NO/ALLOW⟩

If set, the argument of the options to hide is directly appended (no space characters are placed between the option and the arguments).

PREPROCESSOR_KEEP_OPTION_ONE_ARG=⟨string⟩

List of options with one argument which must be transmitted to the native preprocessor.

PREPROCESSOR_KEEP_OPTION_ONE_ARG_APPEND=⟨YES/NO/ALLOW⟩

If set, the argument of the options which must be transmitted is directly appended (no space characters are placed between the option and the arguments).

PREPROCESSOR_DEFINE_OPTION=⟨string⟩

Preprocessor command line option which permits to enter C or C++ defines. (ex: -D)

PREPROCESSOR_DEFINE_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Allows appending the preprocessor defines just after its command line option string. (without spaces, ex: -DNDEBUG)

PREPROCESSOR_INCLUDE_OPTION=⟨string⟩

Preprocessor command line option which permits to include directly some source files. (ex: /FI)

PREPROCESSOR_INCLUDE_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Allows appending the include file name defines just after its command line option string. (without spaces, ex: /FImyheader.h)

PREPROCESSOR_DEFINE_SEPARATOR_OPTION=⟨string⟩

Separator of the define list. For example, if set to ,, CoverageScanner will detect the defines DEF1 and DEF2 when parsing the string DEF1,DEF2.

PREPROCESSOR_CMD=⟨string⟩

Preprocessor command line. CoverageScanner does only analyse preprocessed files. The command generated the C or C++ file used for the code coverage analysis.
The following variables are available:

$TMP1$…$TMP9$: Temporary files names. The temporary files are removed on exit.
$OPTIONS$: Preprocessing options. The preprocessing option are extracted from the command line arguments and contains the list of includes, defines, etc…
$TOOL$: Compiler command (TOOL variable).
$ARCHITECTURE$: Architecture detected or specified by --cs-architecture.
$PROFILE_PATH$: Path of the profile file.
$SOURCE$: Source file name.
$OUTPUT$: Preprocessor output file name. If this variable is present in the command line, it contains the name of a temporary filename used as output for the preprocessor. If not present, it is assumed that the preprocessor generate its output to stdout.

The preprocessor output is stdout. If this parameter is omitted in the configuration, the preprocessor step is skipped.

The preprocessor command must set the define __COVERAGESCANNER__ to 1.

(ex: $TOOL$ $OPTIONS$ -D__COVERAGESCANNER__=1 -E $SOURCE$)

12.4 Profile Parameters for Linker Settings

LINKER_HIDE_OPTION_NO_ARG=⟨string⟩

List of single options (without arguments) which should not be transmitted to the native linker.

LINKER_HIDE_OPTION_ONE_ARG=⟨string⟩

List of options with one argument which should not be transmitted to the native linker.

LINKER_HIDE_OPTION_ONE_ARG_APPEND=⟨YES/NO/ALLOW⟩

If set, the argument of the options to hide is directly appended (no space characters are placed between the option and the arguments).

OBJ_EXT=⟨string⟩

List of extension for object files separated with a semicolon. (ex: .obj)

DYN_LIB_EXT=⟨string⟩

List of extensions for dynamic libraries separated with a semicolon. (ex: .dll)

STATIC_LIB_EXT=⟨string⟩

List of extensions for static libraries separated with a semicolon. (ex: .lib)

UNIX_LIBRARY_NAME=⟨YES/NO⟩

The library name follows the Unix standard.

LINK_LIBRARY_OPTION=⟨string⟩

Link option which permits to select libraries (ex:-l).

LINK_LIBRARY_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the library directly after the link option string (ex: -lfoo) if LINK_LIBRARY_OPTION_APPEND is set.

LINK_OUTPUT_OPTION=⟨string⟩

Linker output option (ex:-o)

LINK_OUTPUT_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the linker output file directly after the option string (without spaces, ex: -ofoo.o) if LINK_OUTPUT_OPTION_APPEND is set.

LINK_OUTPUT_DEFAULT=⟨string⟩

Linker output default filename.
The following variable is available:

$TMP1$…$TMP9$: Temporary files names. The temporary files are removed on exit.
$BASENAME_SRC$: Base name of the the first source file. The base name is the filename without extension.

(ex: $BASENAME_SRC$.exe)

LINK_ADDITIONAL_ARGUMENTS=⟨list⟩

Additional arguments passed to the linker when instrumenting the source code.

DEFAULT_LIB_PATH=⟨string⟩

List of directories which contains the shared libraries (ex: /usr/library;/usr/share/library).

DLL_OPTION=⟨string⟩

Linker command line option which permits to generate a shared library or a DLL (ex: /DLL).

DLL_OUTPUT_STATIC_LIB=⟨string⟩

Static library (associated with the DLL) output file name (ex: /IMPLIB:foo.lib).

DLL_OUTPUT_STATI_LIB_APPEND=⟨YES/NO/ALLOW⟩

Append the static library (associated with the DLL) output file directly after the option string (without spaces, ex: /IMPLIB:foo.lib) if DLL_OUTPUT_STATIC_LIB_APPEND is set.

STATIC_LIB_AS_DEFAULT=⟨YES/NO⟩

Instrumentation database name takes as base name the static library name associated with a DLL.

LIBRARY_PATH_OPTION=⟨string⟩

Link option which permits to add additional directories to the path of directories (ex:-L)

LIBRARY_PATH_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the directory name directly after the option string (ex: -L/foo) if LIBRARY_PATH_OPTION_APPEND is set.

AR_COMMAND_FORMAT_OPTION=⟨YES/NO⟩

The GNU librarian (ar) has a specific command line syntax which is supported when this option is set.

STDIN_MRI_SCRIPT_OPTION=⟨list⟩

This option indicates that an MRI script is used to generate a library. The script is provided by the standard input.

GENERATE_COVERAGESCANNER_LIBRARY=⟨YES/NO⟩

If set, the CoverageScanner library is generated during the linking operation. This should be disabled when generating static libraries.

SKIP_GENERATE_COVERAGESCANNER_LIBRARY_OPTION=⟨string⟩

Permits to skip the generation of CoverageScanner library if a specific option appears in the command line.

AUTODETECT_MS_RUNTIME=⟨YES/NO⟩

Detect automatically the runtime library used when generating an application using Microsoft^® Visual Studio^®. This option compiles the CoverageScanner library with /MT, /MD or /ML if --cs-libgen is not used to set it. If --cs-libgen set /MT, /MD or /ML, this option does not have any effect.

AUTODETECT_MS_RUNTIME_OPTION=⟨list⟩

List of command line option which selects the runtime library (for Microsoft^® Visual Studio^®: /MT;/MD;/ML;/MLd;/MTd;/MDd)

INSTRUMENTATION_TABLES_LINKED_DURING_RUNTIME=⟨YES/NO⟩

Instead of linking all instrumentation tables when calling the linker, link it during the runtime of the application.

INSTRUMENTATION_TABLES_LINKED_DURING_RUNTIME_SUPPORT=⟨YES/NO⟩

Specify if linking all instrumentation tables during the runtime of the application is supported or not.

PLUGIN_REGISTRATION_API=⟨YES/NO⟩

If set, __coveragescanner_register_library() and __coveragescanner_unregister_library() are provided bythe CoverageScanner API to register instrumented plugins during the execution.

FILE_FORMAT_SPECIFIER=⟨YES/NO⟩

If set, file format specifier (see command line option --cs-output) are supported at the runtime.

INSTRUMENTATION_TABLES_OF_DLL_LINKED_DURING_RUNTIME=⟨YES/NO⟩

Instead of linking all instrumentation tables of DLL when calling the linker, link it during the runtime of the application.

COVERAGESCANNER_REGISTRATION_UID=⟨YES/NO⟩

Generate an unique symbol in each static and dynamic library to retrieve the code coverage counters.

INJECT_COVERAGESCANNER_LIBRARY_AT_END=⟨YES/NO⟩

If YES, the CoverageScanner library is always inserted at the end of the linker command line arguments.

GNU_LINKER_SCRIPT=⟨YES/NO⟩

Support of GNU linker scripts. CoverageScanner will then try to recognize a script by trying to parse it.

GNU_LINKER_SCRIPT_OPTION=⟨string⟩

Command line option which permits to specify a GNU linker script.

GNU_LINKER_SCRIPT_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the gnu linker script directly after the linker script command line option option string (ex: -Tfoo.script) if GNU_LINKER_SCRIPT_OPTION_APPEND is set.

VS_DEF_FILE_OPTION=⟨string⟩

Command line option for specifying the module definition file (.def file).
(ex: VS_DEF_FILE_OPTION=/DEF:)

VS_DEF_FILE_OPTION_APPEND=⟨YES/NO/ALLOW⟩

If set, the command line option for specifying the module definition file is directly appended to the file name (no space characters are placed between the option and the arguments).

12.5 Profile Parameters for Compiler Settings

COMPILER_ONLY=⟨YES/NO⟩

If true, the native tool is only a compiler which has no linker capabilities.

COMPILER_HIDE_OPTION_ONE_ARG=⟨string⟩

List of options with one argument which should not be transmitted to the native compiler.

COMPILER_HIDE_OPTION_ONE_ARG_APPEND=⟨YES/NO/ALLOW⟩

If set, the argument of the options to hide is directly appended (no space characters are placed between the option and the arguments).

BYTECODE_EMULATOR=⟨string⟩

If set, the call of the native toolchain is made by calling a byte code intepreter.

Example: BYTECODE_EMULATOR=/math/to/mono.exe permits for force the call of mcs.exe in a specific Mono emulator.

TOOL=⟨string⟩

Native compiler/linker command (example: gcc).
The following variables are available:

$PROFILE$: Profile name without extension.

REMOVE_EXT=⟨string⟩

List of file extension, separated with a semicolon, of files to remove from the command line arguments.

IGNORE_EXT=⟨string⟩

List of file extension, separated with a semicolon, of files to ignore. Ignored files are not instrumented.

C#_EXT=⟨string⟩

List of extension for C# files separated with a semicolon. (ex: .cs)

C_EXT=⟨string⟩

List of extension for C files separated with a semicolon. (ex: .c)

CPP_EXT=⟨string⟩

List of extension for C++ files separated with a semicolon. (ex: .cpp;.cxx)

CPP_LANGUAGE_OPTION=⟨string⟩

List of command line options which are switching the compiler in C++ mode.

C_LANGUAGE_OPTION=⟨string⟩

List of command line options which are switching the compiler in C mode.

LANGUAGE_SELECTION_OPTION=⟨string⟩

List of command line options which permits to select the computing language (C, or C++).

LANGUAGE_SELECTION_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the selected language directly after the option string.

LANGUAGE_SELECTION_OPTION_C_KEYWORD=⟨string⟩

List of arguments of the language selection command line option which force the switching in C mode.

LANGUAGE_SELECTION_OPTION_CPP_KEYWORD=⟨string⟩

List of arguments of the language selection command line option which force the switching in C++ mode.

COMPILER_CMD=⟨string⟩

Compiler command line.
The compiler command line is used to generate the CoverageScanner library during the linking phase.
The following variables are available:

$TMP1$…$TMP9$: Temporary files names. The temporary files are removed on exit.
$COMPILER$: Compiler command (COMPILER variable).
$SOURCE$: Source file name.
$DESTINATION$: Destination file name.
$LIBGEN$: Contents of the command line option --cs-libgen.

(ex: $COMPILER$ -c $SOURCE$ -o $DESTINATION$)

COMPILER_CMD_OPTION_NO_ARG=⟨string⟩

List of single options (without arguments) which are extracted from the command line and which are used for compiling the CoverageScanner library.

COMPILER_CMD_OPTION_ONE_ARG=⟨string⟩

List of options with one argument which are extracted from the command line and which are used for compiling the CoverageScanner library.

COMPILER_CMD_OPTION_ONE_ARG_APPEND=⟨YES/NO/ALLOW⟩

If set, the argument of the options to use for the compilation is directly appended (no space characters are placed between the option and the arguments).

COMPILER_ADDITIONAL_ARGUMENTS=⟨string⟩

Additional arguments passed to the compiler when instrumenting the source code.

COMPILE_OPTION=⟨string⟩

Compile command line option. (ex: -c)

COMPILER_OUTPUT_OPTION=⟨string⟩

Compiler output option. (ex: -o)

COMPILER_OUTPUT_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the compiler output directly after the option string (without spaces, ex: -ofoo.o) if COMPILER_OUTPUT_OPTION_APPEND is true.

COMPILER_OUTPUT_DEFAULT=⟨string⟩

Compiler output default filename.
The following variable is available:

$TMP1$…$TMP9$: Temporary files names. The temporary files are removed on exit.
$BASENAME_SRC$: Base name of the first source file. The base name is the filename without extension.

(ex: $BASENAME_SRC$.obj)

CALLING_CONVENTION=⟨string⟩

CALLING_CONVENTION sets the calling convention (__stdcall, __cdecl or __fastcall) on Windows platform.

FUNCTION_ATTRIBUTE=⟨string⟩

FUNCTION_ATTRIBUTE sets additional compiler attribute to each function of the CoverageScanner library.

DESTRUCTOR_ATTRIBUTE=⟨string⟩

DESTRUCTOR_ATTRIBUTE sets additional compiler attribute which permits to the functions, which reset the code coverage information when the application get shutdown or when a dynamic library get unloaded, to be automatically called. This attribute is is only necessary when the instrumentation tables are registered during the runtime.

CONSTRUCTOR_ATTRIBUTE=⟨string⟩

CONSTRUCTOR_ATTRIBUTE sets additional compiler attribute which permits to the functions, which initialize the code coverage information when the application starts, to be automatically called. This attribute is is only necessary when the instrumentation tables are registered during the runtime.

DESTRUCTOR_PRAGMA=⟨string⟩

DESTRUCTOR_PRAGMA sets additional compiler pragma attribute which permits to the functions, which reset the code coverage information when the application get shutdown or when a dynamic library get unloaded, to be automatically called. The variable $SYMBOL$ is parsed and is replaced through the symbol on which the pragma is applyed. This attribute is is only necessary when the instrumentation tables are registered during the runtime.

CONSTRUCTOR_PRAGMA=⟨string⟩

CONSTRUCTOR_PRAGMA sets additional compiler attribute which permits to the functions, which initialize the code coverage information when the application starts, to be automatically called. The variable $SYMBOL$ is parsed and is replaced through the symbol on which the pragma is applyed. This attribute is is only necessary when the instrumentation tables are registered during the runtime.

DLL_EXPORT=⟨string⟩

DLL_EXPORT contains the compiler attribute which permits to export a symbol from a DLL/shared library.

DLL_IMPORT=⟨string⟩

DLL_IMPORT contains the compiler attribute which permits to import a symbol from a DLL/shared library.

FORCE_DLL_EXPORT=⟨YES/NO⟩

FORCE_DLL_EXPORT permits to force the usage of DLL_EXPORT attribute during the linking phase instead of DLL_IMPORT attribute.

FORCE_DLL_EXPORT_OPTION=⟨string⟩

FORCE_DLL_EXPORT_OPTION permits to force the usage of DLL_EXPORT attribute when a appears in the command line.

PARALLEL_COMPILATION_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Indicates if the number of processors are directly appended to the command which enables the parallel build.

PARALLEL_COMPILATION_OPTION=⟨list⟩

Command line option which enables the parallel build. If this command line argument is followed by an integer, this value indicates the maximum number of parallel build to execute.

SYSTEM_INCLUDES=⟨list⟩

List of system include directories. (ex: /usr/include)

INCLUDE_PATH_OPTION=⟨string⟩

Compiler option which permits to add additional include directories (ex:-I)

INCLUDE_PATH_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the include directory name directly after the option string (ex: -I/foo) if INCLUDE_PATH_OPTION_APPEND is set.

CUSTOM_MALLOC_INCLUDE=⟨string⟩

Additional include for a custom malloc()/free() function (ex: <stdlib.h>)

CUSTOM_MALLOC_FUNCTION=⟨string⟩

Custom body of a malloc() function. The body should return a void* and the parameter int size indicate the number of bytes allocated. (ex: return malloc((size_t)size);)

CUSTOM_FREE_FUNCTION=⟨string⟩

Custom body of a free() function. The parameter void* ptr is the pointer to free. (ex: free(ptr);)

LOCALE_SYSTEM_FILE_ENCODING=⟨YES/NO⟩

If YES, the locale system configuration of text encoding is used for compiling a source file.

OBJECT_DIR_OPTION=⟨string⟩

Compiler option which permits to specify the directory on which the objects are stored. (ex: -object-dir=debug/)

OBJECT_DIR_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the directory directly after the option string (without spaces, ex: -object-dir=foo)

WARNINGS_TO_DISABLE=⟨list⟩

List of compiler warnings to disable. Each item of the list will be used to generate a compiler pragma which permits to enable/disable a compilation warning.

WARNING_DISABLE_PRAGMA=⟨string⟩

Preprocessor directive which permits to disable a compiler warning. The variable $WARNING$ will be parsed and contains the warning number which should be disabled and \n is expanded as a cariage return. (ex: #pragma warning disable $WARNING$)

WARNING_ENABLE_PRAGMA=⟨string⟩

Preprocessor directive which permits to enable/restore a compiler warning. The variable $WARNING$ will be parsed and contains the warning number which should be enabled and \n is expanded as a cariage return. (ex: #pragma warning restore $WARNING$)

COVERAGESCANNER_CSHARP_DYNAMIC=⟨string⟩

Regular expression which enable the support of the C# dynamic type. (ex: ^/define:.*\<COVERAGESCANNER_CSHARP_DYNAMIC\>.*$)

COVERAGESCANNER_NO_CSHARP_DYNAMIC=⟨string⟩

Regular expression which disable the support of the C# dynamic type. (ex: ^/define:.*\<COVERAGESCANNER_NO_CSHARP_DYNAMIC\>.*$)

ACTIVATE_CSHARP_DYNAMIC=⟨string⟩

Command line argument which sets the define __COVERAGESCANNER_CSHARP_DYNAMIC__ to enable the C# dynamic support. (ex: /define:__COVERAGESCANNER_CSHARP_DYNAMIC__)

12.6 Profile Parameters for Precompiled Headers Support

PCH_EXT=⟨string⟩

List of extension for precompiled header files separated with a semicolon. (ex: .pch)

CREATE_PCH_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Indicates if the PCH header generated is directly appended to the command line option.

CREATE_PCH_OPTION=⟨list⟩

List of command line options which are generating precompiled headers. (ex: /Yc)

USE_PCH_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Indicates if the PCH header used is directly appended to the command line option.

USE_PCH_OPTION=⟨list⟩

List of command line options which permits to select a precompiled header. (ex: /Yu)

PCH_OUTPUT_OPTION=⟨string⟩

Command line option to specify the precompiled header output. (ex: /Fp)

PCH_OUTPUT_OPTION_APPEND=⟨YES/NO/ALLOW⟩

Append the precompiled header output directly after the option string (without spaces, ex: -Fpfoo.pch) if PCH_OUTPUT_OPTION_APPEND is true.

PCH_OUTPUT_DEFAULT=⟨string⟩

Default precompiled header output file name.
The following variable is available:

$TMP1$…$TMP9$: Temporary files names. The temporary files are removed on exit.
$BASENAME_SRC$: Base name of the first source file. The base name is the filename without extension.

(ex: $BASENAME_SRC$.pdb)

12.7 Profile Parameters for Performance Measurement

PERF_CLOCK_HEADER=⟨list⟩: Additional C header used to access to the performance counters.
PERF_CLOCK_TYPE=⟨string⟩: Type name for the performance counters (ex: clock_t)
PERF_CLOCK_READ=⟨string⟩: Function which permits to read the performance counters, The variable $OUT$ is the output parameter of this call.
PERF_CLOCK_ADD=⟨string⟩: Function which permits to add two performance counters. The variable $A$ and $B$ are the input parameters of this call. The variable $O$ stores the output result.
PERF_CLOCK_ADD_ATOMIC=⟨string⟩: Function which permits to add a value to performance counters. The variable $I$ is the value to add. The variable $O$ is modified and stores the output result. This operation need to be atomic because it is used in a multithreading context,
PERF_CLOCK_SUB=⟨string⟩: Function which permits to subtract two performance counters. The variable $A$ and $B$ are the input parameters of this call. The variable $O$ stores the output result.
PERF_CLOCK_CONVERT=⟨string⟩: Function which permits to convert a performance counters to a string. The variable $I$ and $O$ are the input and output parameters of this call. The output is a fixed point floating point number which correspond to the time in second.

12.8 Profile Parameters for Custom IO

CSEXE_FOPEN=⟨string⟩

’fopen function used by the generation of the execution report file.

CSEXE_FCLOSE=⟨string⟩

’fclose function used by the generation of the execution report file.

CSEXE_FPUTS=⟨string⟩

fputs function used by the generation of the execution report file.

CUSTOM_SETUP=⟨NONE/POSIX/MS/GNU/MSCE/C++⟩

NONE: if set to NONE the function __coveragescanner_install() will not be provided by CoverageScannerṪhis parameter should be set to NONE on embedded systems which do not provide the functions signal() and atexit().
The code coverage information is saved only when __coveragescanner_save() is called.
POSIX: CoverageScanner provides a function __coveragescanner_install(), which installs a handler which saves the execution report when the application terminates. The handler is installed using POSIX functions (signal() and atexit()).
If __coveragescanner_install() is not called, the code coverage information is only saved when __coveragescanner_save() is called.
GNU: This is similar to the POSIX setting except that, if __coveragescanner_install() is not called, a default handler is used which saves the code coverage data in the file coverage.csmes on a normal application exit.
If __coveragescanner_install() is not called, the code coverage information is not saved on abnormal exit (crash, software interruption, …).
MS: Same as GNU but for Microsoft^® Visual Studio^® compiler.
C++: Install a handler written in C++ which saves the code coverage data in the file coverage.csmes upon normal application exit. CoverageScanner provides a function __coveragescanner_install(), which only changes the name of the destination file.
MSCE: Same as C++ but for Microsoft^® eMbedded Visual C++^® compiler.

12.9 Miscellaneous Profile Parameters

PCH_HIDE_OPTION_NO_ARG=⟨string⟩

List of single options (without arguments) which should not be transmitted to the native tool (compiler or linker) when precompiled headers are disabled using --cs-no-pch.
(ex: -Yd;/Yd for disabling the precompiled headers on Microsoft^® Visual Studio^®)

PCH_HIDE_OPTION_ONE_ARG=⟨string⟩

List of options with one argument which should not be transmitted to the native tool (compiler or linker) when precompiled headers are disabled using --cs-no-pch.
(ex: -Yl;-Yc;-Yu;-YX;/Yl;/Yc;/Yu;/YX for disabling the precompiled headers on Microsoft^® Visual Studio^®)

PCH_HIDE_OPTION_ONE_ARG_APPEND=⟨YES/NO/ALLOW⟩

If set, the argument of the options to hide is directly appended (no space characters are placed between the option and the arguments) when precompiled headers are disabled using --cs-no-pch.

HIDE_OPTION_NO_ARG=⟨string⟩

List of single options (without arguments) which should not be transmitted to the native tool (compiler or linker).
(ex: -Yd;/Yd for disabling the precompiled headers on Microsoft^® Visual Studio^®)

HIDE_OPTION_ONE_ARG=⟨string⟩

List of options with one argument which should not be transmitted to the native tool (compiler or linker).
(ex: -Yl;-Yc;-Yu;-YX;/Yl;/Yc;/Yu;/YX for disabling the precompiled headers on Microsoft^® Visual Studio^®)

HIDE_OPTION_ONE_ARG_APPEND=⟨YES/NO/ALLOW⟩

If set, the argument of the options to hide is directly appended (no space characters are placed between the option and the arguments).

PDB_EXT=⟨string⟩

List of extension for debug information files separated with a semicolon. (ex: .pdb)

PDB_OUTPUT_OPTION=⟨string⟩

Command line option for specifying the debug information file.
(ex: PDB_OUTPUT_OPTION=/Fd)

PDB_OUTPUT_OPTION_APPEND=⟨YES/NO/ALLOW⟩

If set, the command line option for specifying the debug information file is directly appended to the file name (no space characters are placed between the option and the arguments).

SBR_EXT=⟨string⟩

List of extension for symbol browser files separated with a semicolon. (ex: .sbr)

SBR_OUTPUT_OPTION=⟨string⟩

Command line option for specifying the symbol browser information file.
(ex: SBR_OUTPUT_OPTION=/Fr;/FR)

SBR_OUTPUT_OPTION_APPEND=⟨YES/NO/ALLOW⟩

If set, the command line option for specifying the symbol browser information file is directly appended to the file name (no space characters are placed between the option and the arguments).

USE_RESPONSE_FILE=⟨YES/NO/ALLOW⟩

Pack all compiler/linker command line option into a response file. This is generally necessary on Microsoft^® Windows due to the command line limitation length. The option ALLOW consists of using a response file only if a response file is used in the command line arguments of the native compiler. A response file is only used if the if the command line size reach a limit defined by MINIMUM_COMMAND_LINE_SIZE_FOR_RESPONSE_FILE.

MINIMUM_COMMAND_LINE_SIZE_FOR_RESPONSE_FILE=⟨integer⟩

If the command line arguments are lower that the specified size, no response file is used.

MAXIMUM_COMMAND_LINE_SIZE_FOR_RESPONSE_FILE=⟨integer⟩

Ensures that, if a command line size does overflow this value, a response file is used.

RESPONSE_FILE_EXT=⟨string⟩

List of file extensions for the response file.

RESPONSE_FILE_OPTION=⟨list⟩

Command line option for specifying the response file.
(ex: RESPONSE_FILE_OPTION=@)

RESPONSE_FILE_OPTION_APPEND=⟨YES/NO/ALLOW⟩

If set, the command line option for specifying the response file is directly appended to the file name (no space characters are placed between the option and the arguments).

CODE_STYLE=⟨C++/C#⟩

Language supported.

EXIT_FUNCTIONS=⟨string⟩

List of functions which causes an application exit.
(ex: EXIT_FUNCTIONS=abort;exit)

ENABLE_COVERAGESCANNER_PER_DEFAULT=⟨YES/NO⟩

Enable code coverage analysis per default. This is equivalent to implicitly set the command line option --cs-on. This option has only an impact if the native executable has the same name as CoverageScanner wrapper.

DEACTIVATE_COVERAGESCANNER=⟨YES/NO⟩

Disable CoverageScanner globally if set to YES.

DEACTIVATE_COVERAGESCANNER_OPTION_NO_ARG=⟨string⟩

List of command line option which deactivates CoverageScanner.
(ex: DEACTIVATE_COVERAGESCANNER_OPTION_NO_ARG=-M;-MM;-MD;-MMD)

DEACTIVATE_COVERAGESCANNER_OPTION_ONE_ARG=⟨string⟩

List of command line option with one argument which deactivates CoverageScanner.

DEACTIVATE_COVERAGESCANNER_OPTION_ONE_ARG_APPEND=⟨YES/NO/ALLOW⟩

If set, the command line option which disables CoverageScanner is directly followed by an argument (no space characters are placed between the option and the arguments).

COVERAGESCANNER_LIBRARY_OBJECT=⟨string⟩

Name of the CoverageScanner object containing its library code. On Unix, its default value is __cs_library.o. On Microsoft^® Windows, its default value is __cs_library.obj.

EXIT_VALUE_ON_SUCCESS=⟨list⟩

List of exit value that are return by the native linker or compiler and which means that the command was sucessfull.

ERROR_FORMAT=⟨string⟩

Format of the errors. The following items are parsed:

%m: Error message.
%f: File name.
%l: Line.
%c: Column.

ERROR_FORMAT_LINE=⟨string⟩

Same as ERROR_FORMAT but used when no column information are available.

ADDITIONAL_ARGUMENT_SEPARATOR=⟨string⟩

Additional character used as separator for the command line arguments.
(ex: ADDITIONAL_ARGUMENT_SEPARATOR=, for VisualDSP++ compiler)

CORRECT_FILENAME_IN_COMPILER_MESSAGE=⟨YES/NO⟩

If enabled, CoverageScanner replace in the compiler/linker messages the file name used for the instrumentation through the real source filename of the project.

SUPPRESS_APTH_ENTRY=⟨YES/NO⟩

If set to YES, CoverageScanner alter the PATH variable and removes its own location when calling the native compiler.

ATEXIT=⟨string⟩

Command line used to register the application exit handler which saves the execution report upon the application exit.

FORCE_ESCAPING_RULES_RESPONSE_FILE=⟨NO/MS/POSIX⟩

Rules for escaping command line arguments in response files:

POSIX: Escaping rules for UNIX^® platforms
MS: Escaping rules for Microsoft^® Windows.
NO: Native escaping rules for the current platform.

FILESYSTEM_8.3=⟨YES/NO⟩

If set, the extension of the execution report file name is .cse. If the application file name is application.exe the generated report will be application.cse in this case and not application.exe.csexe

OUTPUT_BUFFER_SIZE=⟨integer⟩

Size of the internal buffer used for generating an execution report. A higher value permits a better performance because it minimize the I/O system calls. For embedded system, 64 should be a good value and for other platforms 32768 is recommanded.

12.10 Instrumentation Parameters

RETURN_INSTRUMENTED_IN_EXPRESSION=⟨YES/NO⟩: If true, return statement are instrumented into the returned expression (ex:return inst[0]++, x;).

Element	Description	Equivalence	Reverse Element
`^`	The caret marks the beginning of the string. For example, `^c:` will only match file names with an absolute path on the drive `C:`. If you wish to match a literal `^` you must escape it by writing `\^`.
`$`	The dollar marks the end of the string. For example `\.cpp$` will match every C++ file name. If you wish to match a literal `$` you must escape it by writing `\$`.
`\<`	Match the start of a word.
`\>`	Match the end of a word.
`.`	Any character
`\`	Escape character. Example: `\.` corresponds to the character ’`.`’ and not any character
`\m`	Alphanumeric character	`[0-9a-zA-Z]`	`\M`
`\a`	Alphabetic character	`[a-zA-Z]`	`\A`
`\b`	Blank character	`[ \t]`	`\B`
`\c`	Control character		`\C`
`\d`	Digit	`[0-9]`	`\D`
`\g`	Printable character except space	`[]`	`\G`
`\l`	Lower-case character	`[a-z]`	`\L`
`\p`	Printable character		`\P`
`\n`	Printable character except space or alphanumeric character		`\N`
`\s`	White-space characters (space, form-feed , newline , carriage return , horizontal tab and vertical tab)	`[ \f\n\r\t\v]`	`\S`
`\u`	Uppercase letter	`[A-Z]`	`\U`
`\x`	Hexadecimal digits	`[0-9a-fA-F]`	`\X`
`\w`	Alphanumeric character or underscore	`[0-9a-zA-Z_]`	`\W`

Squish Coco

Code Coverage Measurement for Tcl, QML, C# and C/C++

Part IV CoverageScanner Reference

Chapter 8 Introduction

8.1 Invoking CoverageScanner

Chapter 9 Command Line Arguments

9.1 Environment variables

9.2 List of options

9.2.1 Coverage modes

9.2.2 Fine-tuning of the instrumentation

9.2.3 File and path inclusion

Relative paths

9.2.4 Function inclusion

9.2.5 Debugging

9.2.6 Execution report

9.2.7 Command line modification

9.2.8 Generated code

9.2.9 Miscellaneous

9.3 Instrumenting using preprocessor defines

9.4 Regular Expressions

Chapter 10 Library calls

10.1 C and C++ Library

10.1.1 __coveragescanner_install()

Platform dependencies

10.1.2 __coveragescanner_testname()

10.1.3 __coveragescanner_teststate()

10.1.4 __coveragescanner_add_html_comment()

10.1.5 __coveragescanner_clear_html_comment()

10.1.6 __coveragescanner_save()

10.1.7 __coveragescanner_clear()

10.1.8 __coveragescanner_filename()

Platform dependencies

10.1.9 __coveragescanner_get_filename()

10.1.10 __coveragescanner_register_library()

Platform dependencies

10.1.11 __coveragescanner_unregister_library()

10.1.12 __coveragescanner_set_custom_io()

10.2 C# Library

10.2.1 CoverageScanner.__coveragescanner_init()

10.2.2 CoverageScanner.__coveragescanner_testname()

10.2.3 CoverageScanner.__coveragescanner_teststate()

10.2.4 CoverageScanner.__coveragescanner_add_html_comment()

10.2.5 CoverageScanner.__coveragescanner_clear_html_comment()

10.2.6 CoverageScanner.__coveragescanner_save()

10.2.7 CoverageScanner.__coveragescanner_clear()

10.2.8 CoverageScanner.__coveragescanner_filename()

10.2.9 CoverageScanner.__coveragescanner_set_custom_io()

Chapter 11 Controlling the instrumentation during the compilation

11.1 Source Code Annotations

11.1.1 Comments

11.1.2 Manual Validation

11.2 C and C++ Pragmas

11.3 C# regions

Chapter 12 CoverageScanner Adaptation to a Tool Suite

12.1 Profile Parameters for Architecture Settings

12.2 Profile Parameters for Instrumentation Settings

12.3 Profile Parameters for Preprocessor Settings

12.4 Profile Parameters for Linker Settings

12.5 Profile Parameters for Compiler Settings

12.6 Profile Parameters for Precompiled Headers Support

12.7 Profile Parameters for Performance Measurement

12.8 Profile Parameters for Custom IO

12.9 Miscellaneous Profile Parameters

12.10 Instrumentation Parameters

Part IV
CoverageScanner Reference