Menu

Squish Coco

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

Part XI
Coco Internals

Chapter 46  File system and registry

This chapter is about the usage Squish Coco makes of the file system to store permantent settings.

46.1  Location of the installed files

The location of the installed files varies according to the platform.

46.1.1  Microsoft® Windows

The location of the programs can be chosen at installation time. The installer creates and environment variable SQUISHCOCO that contains the path to the installation directory. By default it is either C:\Program Files\squishcoco or C:\Program Files (x86)\squishcoco, depending on the platform. In this documentation we use the expression Windows Coco to refer to it.

This directory contains the following files and directories:

46.1.2  Linux

The location can be chosen at installation time; its default value is /opt/SquishCoco/. The directory has the following subdirectories:

bin/, lib/
The Squish Coco binaries, including the prefix versions of the compiler wrappers and their profile files.
wrapper/bin/
The compiler wrappers as files without the cs prefix.
doc/
Documentation files.
samples/
Example programs and files for the tutorials.

46.1.3  macOS

The programs are installed at /Applications/SquishCoco.

This directory contains the Squish Coco binaries, including the prefixed versions of the compiler wrappers and their profile files. It also contains the documentation. It has the following subdirectories:

wrapper/
The compiler wrappers as files without the cs prefix.
samples/
Example programs and files for the tutorials.

46.2  Location of the license

The professional and the non-commercial edition of Squish Coco use different naming schemes to locate the files and registry keys that contain information about the license. In the following description, the professional edition is primarily described, with the values that change in the noncommercial edition following in parentheses.

46.2.1  Node-locked licenses

When searching for a license, Squish Coco first tries to find a node-locked license.

  1. If the environment variable SQUISHCOCO_LICENSEKEY_DIR is set, Squish Coco treats the content as a directory name and tries to find there the license file. The license file is named .squishcoco-3-license.
  2. It then searches for a license file in the home directory (described below).
  3. If Squish Coco runs under Microsoft® Windows, it searches instead in the registry under HKEY_CURRENT_USER\Software\squishcoco\LicenseKey.

It is possible that a license is present but that it has been deactivated. If Squish Coco finds such a license, it stops searching for another node-locked license and tries to find a license server instead.

Setting SQUISHCOCO_LICENSEKEY_DIR globally for all users is not recommended. It would force all users to use the same license, but each license key is specific to user and host.

46.2.2  Address of the license server

If no node-locked license is found, Squish Coco will try to find the location of a license server.

  1. First it tries to read the specification of a license server from the environment variable SQUISHCOCO_LICENSE_SERVER, if such a variable is present and its value is not the empty string.
  2. If Squish Coco runs under Microsoft® Windows, then it searches in the registry under HKEY_CURRENT_USER\Software\squishcoco\LicenseServer for a specification.
  3. It then tries to read the specification from a file .squishcoco-3-licserver, which is located in the home directory (see below).
  4. It then tries to read the specification from the system file /etc/squishcoco-3-licserver on Unix or %windir%\system32\drivers\etc\squishcoco-3-licserver on Windows.

The specification of the license server consists of a host name or an IP address, possibly followed by a colon and a port number, like ‘myserver.com:49344’.

The home directory

When searching for the home directory, Squish Coco evaluates the following environment variables and takes the first one which is set.

  1. The content of the variable HOMEPATH.
  2. Under Microsoft® Windows, if HOMEPATH is set, either:
    • If HOMEDRIVE is set, the value of HOMEDRIVE + HOMEPATH.
    • Otherwise the content of HOMEPATH.
  3. The content of HOME.
  4. Under Microsoft® Windows, the content of USERPROFILE.

46.3  Location of the temporary files

During compilation, the CoverageScanner creates some temporary files, which it usually deletes automatically after use.

By default, the temporary files are created in the system temporary files directory. This is /tmp on UNIX® systems, and the directory given by the environment variable %TEMP% on Microsoft® Windows. It is possible to change this location by setting the environment variable SQUISHCOCO_TEMP_DIR to the path of another directory. This directory must already exist when the files are written, it is not created automatically.

The automatic deletion of temporary files can be switched off with the command line option --cs-keep-instrumentation-files (see Chapter 9.2.5).

46.4  Location of the program settings

If a program has other permanent settings that must be stored in a file, that file is located in the following directory:

On Windows
%APPDATA%\squishcoco
On Linux
$HOME/.config/squishcoco

46.5  Location of the installation log file

The Windows installer produces a log file at %TEMP%\SquishCoco_logfile\vsaddin.log. It can be consulted after installation problems.

Chapter 47  Supported compilers

The following compilers are currently supported by CoverageScanner:

47.1  C# compilers

The command line C# compiler of Microsoft® Visual Studio® .NET and Mono C# compiler are supported.

Native CommandCoverageScanner Command
mcscsmcs
gmcscsgmcs
dmcscsdmcs
csccscsc

47.2  Microsoft® Visual C++

The command line compiler and linker of Microsoft® Visual C++ and Microsoft® Visual C++ Toolkit 2003 are supported.

Native CommandCoverageScanner Command
clcscl
libcslib
linkcslink

47.3  Intel® C++ Compiler

The C and C++ command line compiler from Intel® is supported.

Native CommandCoverageScanner Command
iclcsicl
icccsicc
icpccsicpc

47.4  GNU gcc

Only the g++ and gcc command line compilers are directly supported.

Native CommandCoverageScanner Command
gcccsgcc
g++csg++
arcsar

Chapter 48  Code insertion

(This chapter is a continuation of the example in Chapter 5.)

CoverageScanner inserts the instrumentation code as illustrated in the following examples. (The inserted code is displayed in bold blue.)

Sequential Statement
The statements are instrumented before their execution. The instrumentation consists in allocating a Boolean variable which detects if the code was executed or not.

Example

a=foo();
a++;
break;

will be changed into:

a=foo();
a++;
{ inst[0]=1; break}

inst[0] is set to 1 if the ‘break’ statement is executed.

Conditional Statements and Boolean Expressions (full instrumentation)
For Boolean expressions the same principle applies except that in addition to recording the execution itself, the state (true or false) is also recorded.

Example

if ( a<b )
  return 1;

will be changed into:

if ( (a<b) ? inst[0]=1 : inst[1]=1,0 )
  return 1;

 inst[0]  is set to 1 if the Boolean expression a<b was true.

inst[1] is set to 1 if the Boolean expression a<b was false.

Conditional Statements and Boolean Expressions (partial instrumentation)
In some cases, recording the value of a Boolean expression is unnecessary for sequential statement instrumentation. For example, the statement if (b) return 0; else return 1; is completely covered by a statement coverage—after all, recording whether b becomes true or false does not provide any extra information. Similarly, for the statement if (b) return 0; it is only necessary to check if b was false. By default, Squish Coco suppresses the generation of redundant instrumentation in order to minimize the instrumented code’s size and to maximize execution speed.

Example

if ( a<b )
  return 1;

will be changed into:

if ( a<b )
  return 1;
else inst[0]=1 ;

inst[0] is set to 1 if the Boolean expression a<b was false. Since the statement coverage records the instruction return 1;, it is not necessary to record if a<b was true;

The generated instrumentation code that needs to be inserted to provide statement coverage for the earlier foo() function example means that the function’s code is transformed to the code shown here:

   1 char inst[5];
   2 void foo()
   3 {
   4   bool found=false;
   5   for (int i=0; (i<100) && (!found); ++i)
   6   {
   7     if (i==50 ) { inst[0]=1;break;}
   8     if (i==20 ) { inst[1]=1;found=true;}
   9     if (i==30 ) { inst[2]=1;found=true;}
  10   inst[3]=1; }
  11   printf("foo\n");
  12 inst[4]=1; }
Figure 48.1: Code coverage instrumentation at statement block level

If we insert the instrumentation code necessary to support decision coverage into this example, the resulting code will look like this:

   1 char inst[13];
   2 void foo()
   3 {
   4   bool found=false;
   5   for (int i=0; ((i<100 && !found)?inst[0]=1:inst[1]=1,0); ++i)
   6   {
   7     if ((i==50?inst[2]=1:inst[3]=1,0){ inst[4]=1; break;}
   8     if ((i==20?inst[5]=1:inst[6]=1,0){inst[7]=1; found=true;}
   9     if ((i==30?inst[8]=1:inst[9]=1,0){inst[10]=1; found=true;}
  10   inst[11]=1; }
  11   printf("foo\n");
  12 inst[12]=1; }
Figure 48.2: Code coverage instrumentation at decision level

If we insert the instrumentation code necessary to support condition coverage into this example, the resulting code will look like this (except that we have wrapped one line to fit better on the page):

   1 char inst[15];
   2 void foo()
   3 {
   4   bool found=false;
   5   for (int i=0;((i<100)?inst[0]=1:inst[1]=1,0) &&
   6        ((!found)?inst[2]=1:inst[3]=1,0); ++i) {
   7     if ((i==50?inst[4]=1:inst[5]=1,0){inst[6]=1; break;}
   8     if ((i==20?inst[7]=1:inst[8]=1,0){inst[9]=1; found=true;}
   9     if ((i==30?inst[10]=1:inst[11]=1,0){inst[12]=1; found=true;}
  10   inst[13]=1; }
  11   printf("foo\n");
  12 inst[14]=1; }
Figure 48.3: Full code coverage instrumentation at condition level

Here is what the code would look like if we inserted the partial instrumentation code for condition coverage (again, with one line wrapped):

   1 char inst[12];
   2 void foo()
   3 {
   4   bool found=false;
   5   for (int i=0; ((i<100)?inst[0]=1:inst[1]=1,0) &&
   6        ((!found)?inst[2]=1:inst[3]=1,0); ++i) {
   7     if (i==50 ) {inst[4]=1; break;} else inst[5]=1;
   8     if (i==20 ) {inst[6]=1; found=true;} else inst[7]=1;
   9     if (i==30 ) {inst[8]=1; found=true;} else inst[9]=1;
  10   inst[10]=1; }
  11   printf("foo\n");
  12 inst[11]=1; }
Figure 48.4: Partial code coverage instrumentation at condition level

Chapter 49  Code Coverage Benchmarks

49.1  Test Algorithm

The sorting algorithm used for the tests is quicksort.
Source code:

To download: sort.c pictures/zoom.png

49.2  Benchmarks

CompilerNormal Execution
(time)
Execution
Branch Coverage
or Function Coverage

(time)
Execution
Decision Coverage
or
Line Coverage

(time)
Execution
Condition Coverage

(time)
GCC without optimization 6840ms8030ms (+17.3%) 9400ms (+37.4%) 9830ms (+43.7%)
GCC with optimization -Os 4160ms4430ms (+6.4%) 6180ms (+48.5%) 6360ms (+52.8%)
GCC with optimization -O1 3530ms4250ms (+20.3%) 5420ms (+53.5%) 5970ms (+69.1%)
GCC with optimization -O2 3950ms4040ms (+2.2%) 5080ms (+28.6%) 5320ms (+34.6%)
GCC with optimization -O3 3860ms4030ms (+4.4%) 5060ms (+31%) 5230ms (+35.4%)
Table 49.1: Benchmark (sorting algorithm)
CompilerNative Compilation
(bytes)
Statement Block Coverage
or
Function Coverage

(bytes)
Decision Coverage
or
Line Coverage

(bytes)
Condition Coverage
(bytes)
GCC without optimization 2128 3452 (+1324) 3996 (+1868) 4052 (+1924)
GCC with optimization -Os 1940 3196 (+1256) 3716 (+1776) 3760 (+1820)
GCC with optimization -O1 1968 3172 (+1204) 3736 (+1768) 3792 (+1824)
GCC with optimization -O2 2100 3452 (+1352) 4096 (+1996) 4160 (+2060)
GCC with optimization -O3 3544 3548 (+4) 4364 (+820) 4428 (+884)
Table 49.2: Sorting algorithm code size of the object

Chapter 50  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.1

The profile lets CoverageScanner:

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.

50.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).

50.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)

50.3  Profile Parameters for Preprocessor Settings

PREPROCESSOR_KEEP_DEFINES=string
List of preprocessor defines that are passed through the preprocessor and the compiler command. Only preprocessor defines that are present in the command line argument of CoverageScanner are concerned.
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 lets you define C or C++ symbols. (ex: -D)
PREPROCESSOR_DEFINE_OPTION_APPEND=YES/NO/ALLOW
Allows appending the preprocessor symbols just after its command line option string. (without spaces, ex: -DNDEBUG)
PREPROCESSOR_INCLUDE_OPTION=string
Preprocessor command line option which lets you include directly some source files. (ex: /FI)
PREPROCESSOR_INCLUDE_OPTION_APPEND=YES/NO/ALLOW
Allows appending the include file name just after its command line option string. (without spaces, ex: /FImyheader.h)
PREPROCESSOR_DEFINE_SEPARATOR_OPTION=string
Separator of the list of preprocessor symbols. For example, if set to ,, CoverageScanner will detect the symbols 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, preprocessor symbols, 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 define the symbol __COVERAGESCANNER__ to 1.
(ex: $TOOL$ $OPTIONS$ -D__COVERAGESCANNER__=1 -E $SOURCE$)

50.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 selects 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 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 generates 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 adds additional directories to the library search path (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
skips the generation of the CoverageScanner library.
LIBGEN_AUTODETECT_ARGS_OPTION_NO_ARG=string
List of single compilation options (without arguments) which should be used for the compilation of the CoverageScanner library.
LIBGEN_AUTODETECT_ARGS_OPTION_ONE_ARG=string
List of compilation options with one argument which should be used for the compilation of the CoverageScanner library.
LIBGEN_AUTODETECT_ARGS_OPTION_ONE_ARG_APPEND=YES/NO/ALLOW
If set, the argument of the options is directly appended (no space characters are placed between the option and the arguments).
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 at application runtime.
INSTRUMENTATION_TABLES_LINKED_DURING_RUNTIME_SUPPORT=YES/NO
Specify if linking all instrumentation tables at application runtime 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 at application runtime.
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.
COSMIC_LINKER_SCRIPT=YES/NO
Support of COSMIC linker scripts. CoverageScanner will then try to recognize a script by trying to parse it.
COSMIC_LINKER_SCRIPT_EXT=string
File extension of the COSMIC linker file.
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 specifies 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 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).

50.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 extensions, separated with a semicolon, of files to remove from the command line arguments.
IGNORE_EXT=string
List of file extensions, separated with a semicolon, of files to ignore. Ignored files are not instrumented.
C#_EXT=string
List of extensions for C# files separated with a semicolon. (ex: .cs)
C_EXT=string
List of extensions for C files separated with a semicolon. (ex: .c)
CPP_EXT=string
List of extensions for C++ files separated with a semicolon. (ex: .cpp;.cxx)
CPP_LANGUAGE_OPTION=string
List of command line options passed to the compiler in C++ mode.
C_LANGUAGE_OPTION=string
List of command line options passed to the compiler in C mode.
LANGUAGE_SELECTION_OPTION=string
List of command line options which 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_AT_END=YES/NO
If no output is specified in the command line, add it explicitly at the end (if YES) or at the beginning of the command line arguments. The default is YES.
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 attributes to each function of the CoverageScanner library.
DESTRUCTOR_ATTRIBUTE=string
DESTRUCTOR_ATTRIBUTE sets an additional compiler attribute which causes the functions, which reset the code coverage information when the application gets shutdown or when a dynamic library get unloaded, to be automatically called. This attribute is is only necessary when the instrumentation tables are registered at runtime.
CONSTRUCTOR_ATTRIBUTE=string
CONSTRUCTOR_ATTRIBUTE sets an additional compiler attribute which causes 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 at runtime.
DESTRUCTOR_PRAGMA=string
DESTRUCTOR_PRAGMA sets additional compiler pragma attribute which cause 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 at runtime.
CONSTRUCTOR_PRAGMA=string
CONSTRUCTOR_PRAGMA sets additional compiler attribute which cause 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 at runtime.
DLL_EXPORT=string
DLL_EXPORT contains the compiler attribute which exports a symbol from a DLL/shared library.
DLL_IMPORT=string
DLL_IMPORT contains the compiler attribute which imports a symbol from a DLL/shared library.
FORCE_DLL_EXPORT=YES/NO
FORCE_DLL_EXPORT forces the usage of DLL_EXPORT attribute during the linking phase instead of DLL_IMPORT attribute.
FORCE_DLL_EXPORT_OPTION=string
FORCE_DLL_EXPORT_OPTION forces the usage of DLL_EXPORT attribute when it 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 builds to execute.
SYSTEM_INCLUDES=list
List of system include directories. (ex: /usr/include)
INCLUDE_PATH_OPTION=string
Compiler option which adds 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 custom malloc()/free() functions (ex: <stdlib.h>)
CUSTOM_MALLOC_FUNCTION=string
Custom body of a malloc() function. The body should return a void* and the parameter int size indicates the number of bytes to be allocated. (ex: return malloc((size_t)size);)
CUSTOM_FREE_FUNCTION=string
Custom body of a free() function. The parameter void* ptr points to the memory to be freed. (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 specifies the directory in 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 enables/disables a compilation warning.
WARNING_DISABLE_PRAGMA=string
Preprocessor directive which disables 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 enables/restores 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 enables the support of the C# dynamic type. (ex: ^/define:.*\<COVERAGESCANNER_CSHARP_DYNAMIC\>.*$)
COVERAGESCANNER_NO_CSHARP_DYNAMIC=string
Regular expression which disables 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__)

50.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 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)

50.7  Profile Parameters for Execution Time 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). The size of the counter must be 64 bits.
PERF_CLOCK_READ=string
Function which reads the performance counters, The variable $OUT$ is the output parameter of this call.
PERF_CLOCK_ADD=string
Function which adds two performance counters. The variable $A$ and $B$ are the input parameters of this call. The variable $O$ stores the output result.
PERF_CLOCK_SUB=string
Function which subtracts 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 converts a performance counter 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 seconds.

50.8  Profile Parameters for Profiling

PROF_CLOCK_HEADER=list
Additional C header used to access to the performance counters.
PROF_CLOCK_ADDITIONAL_ARG=list
Additional linker argument for building the code with a profiler support.
PROF_CLOCK_TYPE=string
Type name for the performance counters (ex: clock_t). The size of the counter must be 64 bits.
PROF_CLOCK_READ=string
Function which reads the performance counters, The variable $OUT$ is the output parameter of this call.
PROF_CLOCK_ADD_ATOMIC=string
Function which adds 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 needs to be atomic because it is used in a multithreading context,
PROF_CLOCK_SUB=string
Function which subtracts two performance counters. The variable $A$ and $B$ are the input parameters of this call. The variable $O$ stores the output result.
PROF_CLOCK_CONVERT=string
Function which converts a performance counter 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.

50.9  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.

50.10  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).
STRIP_CPP_COMMENTS_IN_RESPONSE_FILE=YES/NO
If set, the C/C++ comments are removed in the command line options.
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_TO_STDOUT=YES/NO
Print the error messages to the standard output and not to the error output.
ERROR_FORMAT=string
Format of the errors. The following items are parsed:
%m
Error message.
%f
File name.
%e
File name, C-escaped.
%l
Line.
%c
Column.
%e
Error type (warning, info or error)
%n
New line.
ERROR_FORMAT_LINE=string
Same as ERROR_FORMAT but used when no column information are available.
ERROR_FORMAT_TEXT=string
Same as ERROR_FORMAT but used when no column and line information are available.
ERROR_FORMAT_BEGIN=string
Start banner of the CoverageScanner error messages.
ERROR_FORMAT_END=string
End banner of the CoverageScanner error messages.
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_PATH_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.

50.11  Instrumentation Parameters

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