Tracker library reference

When a Tcl Program is instrumented, it needs a "tracker library", libcoveragescannertcl, to count the number of times the code is executed and later write the .csexe file. This library must be compiled by the user because it needs the same Tcl version as the instrumented program.

Compilation of the tracker library

Linux

The source code of the tracker library is in the subdirectory tclcoverage/src of the Coco installation. With the standard installation, this is the directory /opt/SquishCoco/tclcoverage/src.

1. Before compiling the library, find out where the include directory and the library file of your Tcl installation are.
   • The include directory is the directory in which the file tcl.h is. On a Linux system, it could be /usr/include/tcl8.6.
   • The Tcl library file must have a .a suffix, for example /usr/lib/x86_64-linux-gnu/libtcl8.6.a
2. Create a build directory for libcoveragescannertcl. From the build directory, run CMake with the following parameters:
   • an option -D to set the CMake variable TCL_INCLUDE_PATH to your Tcl include directory,
   • an option -D to set the CMake variable TCL_LIBRARY to your Tcl library file, and
   • the path to the Sources of the Coco Tcl library.

   The resulting CMake call could therefore be

   cmake -DTCL_INCLUDE_PATH=/usr/include/tcl8.6 -DTCL_LIBRARY=/usr/lib/x86_64-linux-gnu/libtcl8.6.a /opt/SquishCoco/tclcoverage/src

3. Compile the tracker library. The result will be a file libcoveragescannertcldll.so in the build directory.

macOS

The source code of the tracker library is in the subdirectory tclcoverage/src of the Coco installation. With the standard installation, this is the directory /Applications/SquishCoco/tclcoverage/src.

1. Before compiling the library, find out where the include directory and the library file of your Tcl installation are.
   • The include directory is the directory in which the file tcl.h is. On a macOS system, it could be /opt/homebrew/include.
   • The Tcl library file must have a .dylib suffix, for example /opt/homebrew/lib/libtcl8.6.dylib
2. Create a build directory for libcoveragescannertcl. From the build directory, run CMake with the following parameters:
   • an option -D to set the CMake variable TCL_INCLUDE_PATH to your Tcl include directory,
   • an option -D to set the CMake variable TCL_LIBRARY to your Tcl library file, and
   • the path to the Sources of the Coco Tcl library.

   The resulting CMake call could therefore be

   cmake -DTCL_INCLUDE_PATH=/opt/homebrew/include -DTCL_LIBRARY=/opt/homebrew/lib/libtcl8.6.dylib /Applications/SquishCoco/tclcoverage/src

3. Compile the tracker library. The result will be a file libcoveragescannertcldll.dylib in the build directory.

Windows

The source code of the tracker library is in the subdirectory tclcoverage\src of the Coco installation. With the standard installation, this could be the directory C:\Program Files\squishcoco\tclcoverage\src.

1. Before compiling the library, find out where the include directory and the library file of your Tcl installation are.
   • The include directory is the directory in which the file tcl.h is. On a Windows system, it could be C:\tcl8.6\x64\include.
   • The Tcl library file must have a .lib suffix, for example C:\tcl8.6\x64\lib\tcl86t.lib
2. Create a build directory for libcoveragescannertcl. From the build directory, run CMake with the following parameters:
   • an option -D to set the CMake variable TCL_INCLUDE_PATH to your Tcl include directory,
   • an option -D to set the CMake variable TCL_LIBRARY to your Tcl library file, and
   • the path to the Sources of the Coco Tcl library.

   The resulting CMake call could therefore be

   cmake -DTCL_INCLUDE_PATH=C:\tcl8.6\x64\include -DTCL_LIBRARY=C:\tcl8.6\x64\lib\tcl86t.lib "C:\Program Files\squishcoco\tclcoverage\src"

3. Compile the tracker library with

   cmake --build .

   The result will be a file Debug\coveragescannertcldll.dll in the build directory.

Use of the tracker library

After the Tcl code is instrumented, it needs the tracker library in order to run. To find it, one must set the environment variable COCOTCLTRACKERDLL to the path to the tracker library.

Under Linux, this could look like this:

$ export COCOTCLTRACKERDLL=/home/user/tclbuild/libcoveragescannertcldll.so
$ tclsh tcalc.tcl

Under macOS, it could be:

$ export COCOTCLTRACKERDLL=/home/user/tclbuild/libcoveragescannertcldll.dylib
$ tclsh tcalc.tcl

while under Windows, it could be

C:\workdir>set COCOTCLTRACKERDLL=C:\home\user\tclbuild\coveragescannertcldll.dll
C:\workdir>tclsh tcalc.tcl

When the instrumented program finishes, it writes its measurements to a file tclcoverage.csexe in its work directory. The files tclcoverage.csmes and tclcoverage.csexe can then be read and processed with the usual Coco tools.