When an application is instrumented with Squish Coco and problems arise, it is often helpful to run the compilation in the verbose build mode.

This is especially useful when some of the program files are excluded from the instrumentation. With the verbose build enabled, one can see which files are read, which of them are included in the instrumentation, and which command line option was responsible for the inclusion. This also helps to find the reason why a function was not included in the code coverage.

The “Verbose Build” checkbox in the add-on.

The verbose build mode is enabled by adding the option –cs-verbose=build to the command line parameters. How this is done differs, but in most cases it will be added to the options in the environment variable COVERAGE_FLAGS. If you use instead the Visual Studio add-in, you can find in it a checkbox, “Verbose Build”, which also sets the flag. (See the image to the right.)

There is also a related option, —cs-verbose-filename, which allows to direct the verbose output to a file. In the add-on, one can instead enter the file name into the “File:” field below the checkbox.

An example for the verbose output

As an illustration, we will show now the verbose output for the compilation of one of the files in the parser example in the documentation. In the following, we will see the output that is generated for the compilation of a single file, error.cpp in this case. The original compilation command was

g++ -c -g -D_REENTRANT -I../../cppunit-1.12.1/include -o error.o error.cpp

When the file is compiled in an instrumented build, the call of g++ is replaced with a call of the compiler wrapper for g++. The wrapper then instruments the file and calls the original compiler afterwards.

If the option –cs-verbose=build is set, the wrapper generates the following additional output for error.cpp.

Note: The output can become very long and contain long lines. A few of the lines in the following listing have been removed and replaced with a […]. By clicking on the Ξ symbol at the top right of each of the following listings you can enable line wrapping and see the complete lines.

Info (Squish Coco): Current Working Directory:/home/markus/parser_v1
Info (Squish Coco): Command Line: g++ -c -g -D_REENTRANT -I../../cppunit-1.12.1/include -o error.o error.cpp
Info (Squish Coco): Command Line for 'error.cpp': 'g++' '-c' '-g' '-D_REENTRANT' '-I../../cppunit-1.12.1/include' '-o' 'error.o' 'error.cpp'
Info (Squish Coco): File Included: 'error.cpp' -> '/error.cpp' (--cs-include-path='/home/markus/parser_v1' on '/home/markus/parser_v1')
Info (Squish Coco): File Included: '/home/markus/parser_v1//' -> '/home/markus/parser_v1' (--cs-include-file-abs-wildcard='*' on '/home/markus/parser_v1')
Info (Squish Coco): File Excluded: '/usr/include/stdc-predef.h' (--cs-exclude-file-abs-wildcard='/usr/*' on '/usr/include/stdc-predef.h')
Info (Squish Coco): File Included: 'error.h' -> '/error.h' (--cs-include-path='/home/markus/parser_v1' on '/home/markus/parser_v1')
Info (Squish Coco): File Excluded: '/usr/include/c++/4.9/cstdio' (--cs-exclude-file-abs-wildcard='/usr/*' on '/usr/include/c++/4.9/cstdio')
[...]
Info (Squish Coco): File Excluded: '/usr/include/string.h' (--cs-exclude-file-abs-wildcard='/usr/*' on '/usr/include/string.h')
Info (Squish Coco): File Excluded: '/usr/include/xlocale.h' (--cs-exclude-file-abs-wildcard='/usr/*' on '/usr/include/xlocale.h')
Info (Squish Coco): Compilation Command: /usr/bin/g++ -c -g -I../../cppunit-1.12.1/include -o error.o /tmp/omgce8_error.cpp.csmes_feo.cpp

Description of the example

There are three kinds of lines in the verbose output. All of them start with the words “Info (Squish Coco)“.

1. One line shows the working directory of the compiler.
2. Two lines show the original command line of the compiler
3. Many lines show which files take part in the instrumentation
4. A final line shows the compiler command for the instrumented program.

We will now look at them in greater detail.

The current working directory

Info (Squish Coco): Current Working Directory:/home/markus/parser_v1

This is the working directory from which CoverageScanner has been called. The output helps to interpret the relative path names in the command lines that are reported below.

The compiler command line

Info (Squish Coco): Command Line: g++ -c -g -D_REENTRANT -I../../cppunit-1.12.1/include -o error.o error.cpp
Info (Squish Coco): Command Line for 'error.cpp': 'g++' '-c' '-g' '-D_REENTRANT' '-I../../cppunit-1.12.1/include' '-o' 'error.o' 'error.cpp'

The command line with which the complier wrapper is called is shown twice. The first line is the short form and often better readable. This may however lead to problems if there are file paths with spaces in it. In the second line, all command line arguments are written in quotes. This avoids the problem.

Which files are included?

The following lines are usually the most important ones. They show which files were instrumented and which were not. Since the form of these lines varies a bit, we show here the first four lines of the example again.

Info (Squish Coco): File Included: 'error.cpp' -> '/error.cpp' (--cs-include-path='/home/markus/parser_v1' on '/home/markus/parser_v1')
Info (Squish Coco): File Included: '/home/markus/parser_v1//' -> '/home/markus/parser_v1' (--cs-include-file-abs-wildcard='*' on '/home/markus/parser_v1')
Info (Squish Coco): File Excluded: '/usr/include/stdc-predef.h' (--cs-exclude-file-abs-wildcard='/usr/*' on '/usr/include/stdc-predef.h')
Info (Squish Coco): File Included: 'error.h' -> '/error.h' (--cs-include-path='/home/markus/parser_v1' on '/home/markus/parser_v1')

For the source file that is compiled and for every file that is directly or indirectly included by it, it is shown whether it is also included or excluded in the instrumentation. It is also shown which option caused the decision.

The debug line has the following content:

1. The inclusion decision. It is either “File Included” or “File excluded“.
2. The name of the file that is included or excluded. If necessary, the file name is normalized. Then both the original and the normalized name are shown, as in the second line of the example: “‘/home/markus/parser_v1//’ -> ‘/home/markus/parser_v1′” . If no change is needed, only one version of the file name is shown, as in the third line.
3. The command line option which matches the file, together with the full path of the file that it matches. An example is “(–cs-exclude-file-abs-wildcard=’/usr/*’ on ‘/usr/include/stdc-predef.h’)”  in the second line. It shows that the rule to exclude all files in the /usr/ directory has matched the file path /usr/include/stdc-predef.h and that therefore the file stdc-predef.h was not instrumented.

Note that Coco adds some exclusion rules on its own, which are also reported as command-line flags. All inclusion/exclusion rules in the example output are in fact default rules. But the output for the rules that were set by the user is the same.

The command to compile the instrumented file

This is the command that Coco uses to compile the code it has instrumented. The most important difference to the command at the beginning is that now a temporary file is compiled, namely the instrumented version of the original source file.

Info (Squish Coco): Compilation Command: /usr/bin/g++ -c -g -I../../cppunit-1.12.1/include -o error.o /tmp/omgce8_error.cpp.csmes_feo.cpp

Here we see that the new compiled file is /tmp/omgce8_error.cpp.csmes_feo.cpp. The name is a mangled form of that of the original file, error.cpp.

The post Debugging Coco with the verbose build mode appeared first on froglogic.