Coco TCL Tutorial

This is a short tutorial on the use of coveragescannertcl to measure Tcl code coverage.

The example application

Coco comes with a small Tcl application in the subdirectory demoapp_tcl of the Coco installation.

Create a copy of demoapp_tcl in your work space – under Linux with

cp -r /opt/SquishCoco/samples/demoapp_tcl .
cd demoapp_tcl

and under Windows with

xcopy "%SQUISHCOCO%\demoapp_tcl" demoapp_tcl\ /S
cd demoapp_tcl

The directory contains the code for a calculator. You can run it with

tclsh tcalc.tcl

Instrumenting the Tcl script

Now run in the demoapp_tcl directory the command

coveragescannertcl .

The result of this is that the directory contains two new files and one modified file.

• The modified file is tcalc.tcl. It is now instrumented and contains additional commands to measure code coverage. The original version of tcalc.tcl is now renamed to the new file tcalc.tclbak.

  If this were a larger project with many Tcl files, each of then would be instrumented and a backup file created. And coveragescannertcl instruments Tcl files in subdirectories.

• The other new file is tclcoverage.csmes, the coverage database. It contains the information that is needed to display the coverage of tcalc.tcl correctly.

Running the instrumented script

The tracker library

For code coverage, the instrumented script requires a special shared library to store the coverage data and later write them to a .csmes file. The library must be built with the same Tcl version as the Tcl interpreter that runs the instrumented program. To build it, follow section Compilation of the tracker library.

Measuring the coverage

To run, the instrumented script must know where the tracker library is. For this, it uses the environment variable COCOTCLTRACKERDLL, which must be set before the script can run. So under Linux, you could set it with the bash command

export COCOTCLTRACKERDLL=/mydir/libcoveragescannertcldll.so

while under Windwos, you could write

set COCOTCLTRACKERDLL=C:\mydir\libcoveragescannertcldll.so

Now run tcalc.tcl the same way as before. Do something with the calculator, then hit the close button. The work directory will now contain another new file, tclcoverage.csexe, with the coverage measurements.

They can be seen with CoverageBrowser, with the command

coveragebrowser tclcoverage.csmes -e tclcoverage.csexe

Cleaning up

After the coverage is measured, it is time to un-instrument the Tcl files. This is done with the command

coveragescannertcl -r .

The file tcalc.tclbak is now gone, but the coverage measurements, contained in the files tclcoverage.csmes and tclcoverage.csexe, are still there.