|coveragescannertcl [⟨cs-options⟩] ⟨application arguments⟩|
CoverageScannerTcl is a utility which collects code coverage information of a Tcl-based execution. It will collect all scripts parsed by the embedded Tcl interpreter and determine which parts were actually executed.
Once the application exits a pair of
files will be written out that contain the code instrumentation
information and execution data, respectively.
See (see Chapter 16) for a recommended set of --cs-exclude-code-regexp switches for typical Tcl/Tk applications.
Create a file
hello.tcl with the following content:
Two files are generated:
To import the execution report into its instrumentation database, execute:
In some UNIX®systems (like Debian Linux™), more than one Tcl version can be present at the same time. The executables are then distinguished by their names. On such a system, the tclsh executable of Tcl v8.5 may be called tclsh8.5.
We can then run CoverageScannerTcl such that it calls
tclsh8.5. On its own, this would however change the names of
the generated files into tclsh8.5.csmes and
tclsh8.5.csexe. We can correct this with another commandline
--cs-output=tclsh. The first command in the example
above now becomes:
Afterwards, the rest of the example can be done as before.
Copy the sample to your working diretcory
Edit Makefile and adjust the following variables
to match your system’s library names and include paths.
Build the C++ executable with:
Test the simple Tk GUI with an invocation of the launcher script:
Launch the application under test via the Tcl coverage scanning tool :
The GUI will show up as normal while code coverage is monitored. At this point
the application might already be shut down via the "File->Exit" menu entry or the
[X] button in the window’s title bar.
Observe the two files
generated. The latter contains data about the code covered in the last
execution. The former is a measurement database containing information about
the instrumented code and possibly imported previous executions. In this case
the base name of the output files was set via the --cs-output switch. If
omitted it will be deduced from the application name.
The results can be view interactively in the GUI provided by Coco. Run
to launch it. Select "File->Open…" to open the
tcl.csmes file. You’ll
see all Tcl files and procedures listed in the Sources and Methods tab,
respectively. When selecting either of them a source code viewer will open that
shows instrumented code with a gray background color.
Note that the coloring is still limited to instrumented, i.e. seen code only.
To check which code got actually executed (or not) select "File->Load
Execution Report…" and open
Now red and green colors denoting positive and negative coverage will
show up for files, procedures and the code itself.
As you might have noticed that above ad-hoc run produced results for several unnamed and internal files. These stem from internal Tcl/Tk files or e.g. mouse event handlers that result in on-the-fly eval calls. Compared to the application-specific Tcl files the coverage information for these internal pieces of code is of little interest.
The easiest way to hide the non-relevant pieces of code is through usage of the various --cs-exclude-code options. A recommended list of switches will be shown in the repetition of the previous run with filtering options applied:
When viewing the new
tcl.csmes in CoverageBrowser you’ll
notice that the list of files is reduced to the relevant
All of text, XML and HTML reports can be generated from the CoverageBrowser GUI. With future automation of nightly test runs or Continuous Integration (CI) in mind we’ll create the report from the command line. And for this very purpose we’ll also pretend that the execution data has not been imported into the measurement database, yet. This step can be accomplished like this from the command line:
proto.csmes file now contains everything we need to generated a report:
The resulting report.html file (including a
can now be visited with a Web browser. It includes a listing of executions,
source files, functions and metrics on a global level, per file and per
While Tcl code can be instrumented for coverage analysis on-the-fly this step requires a rebuild for C or C++ applications. But this can be accomplished with almost no change to your regular application build. Here are the two possible approaches:
We’ll make use of approach number 2. First, clean the existing object files:
Then, recompile the application with a changed PATH and a switch that enables the compiler wrappers. For brevity, we’ll do this all in a single line:
As a result we’ll not only get the main executable (
proto.exe) but also a
corresponding instrumentation file
proto.exe.csmes. Information about the
instrumented code (gray background color) can optionally be reviewed at this
Let’s run the application
and quit it via its GUI right after.
The current working directory will now contain a
proto.exe.csexe containing information about completed execution.
Same as with Tcl the results can now be reviewed in CoverageBrowser. A short cut invocation that opens both the instrumentation and execution files is shown here:
The process of a report generation works analogous to the approach shown for Tcl code above.
Coverage data for the Tcl and C/C++ parts of a hybrid application can be gathered independently as shown above. Either in a single or multiple executions. The only extra step needed is the merging of the data into a single measurement database. Which then can be used to generate a single, combined report taking both languages into account.
Assuming the instrumentation of the C/C++ code is still in place we can gather coverage data for both types of languages with a single run:
proto.exe.csmes file still in place from the application
rebuild we’ll now have two sets of files:
Instead of using the Coverage Browser GUI we’ll again use the command line tools. In the first step we’ll merge the instrumentation files stemming from the two languages into one:
To save some disk space the
--append option can be used rather
than creating the new
In the second step the two execution files are merged using the
merge policy for the 2nd language:
For the merge to actually happen the
title has to be identical.
Select "Source Files" to see both Tcl (various files) and C++ code
main.cpp) being listed in a combined report.