In this section:

Overview

Coverage analysis is automatically built into your program by default when you use Insure++. You can use the tca at any time after you have run your code command to find any unexecuted blocks. For clarity, the process is broken down into three steps.

• Compiling applications and building their coverage analysis database (usually named tca.map).
• Running test cases against applications that have been compiled with coverage analysis enabled, which creates entries in the TCA log file (usually named tca.log).
• Running the TCA analysis tool to generate coverage analysis reports from the given coverage log file(s).

You can make your program displays a coverage analysis report when it exits by adding the summarize coverage value to your Advanced Options on Windows or by add the insure++.summarize coverage option to your .psrc file on Unix.

The coverage_switches option lets you set flags to control the output just as though you were passing those switches to the tca command.

Step 1: Compile Time

At compile time, Insure++ creates a database of each file processed, describing how many blocks and statements are in each file and function. This database is called a map file, because it provides TCA with a map of how your program is laid out. By default, the name of this file is tca.map, but you can change the name of this file by adding a coverage_map_file value to your Advanced Options (Windows) or .psrc file (Unix).

Ideally, all the files in your application should store their information in the same map file. If your source code is spread across several directories, you will probably want to set the map filename using a full path. For example:

coverage_map_file c:\usr\project.map (Windows)

insure++.coverage_map_file ~/project.map (Unix)

If you compile several files simultaneously and they are all trying to modify the same map file, you may end up with a corrupt map file. In this case, you will need to delete the original map file and recompile the application you are interested in.

If you are only interested in coverage information and not debugging, you can add the -Zcov option to the insure command lines that build your program. You must use the -Zcov option at both compilation and linking.

Step 2: Runtime

At runtime, your program compiled with Insure++ writes a log file that records the blocks that were actually executed during a specific run. By default, this file is called tca.log, but you can change the name of this file by adding a coverage_log_file value to your Advanced Options (Windows) or .psrc file (Unix). Normally, each time you run your program the new log information will be combined with the existing log file unless the data is incompatible. Data may not be compatible because you changed your code and recompiled, for example.

Another useful option is to generate a new log file each time your application runs. You can do this by taking advantage of the %n filename option, for example:

coverage_log_file tca.log.%n (Windows)

insure++.coverage_log_file tca.log.%n (Unix)

In this example, each run would make a new file, such as tca.log.0, tca.log.1, and so forth. If your program forks, you will need to use this option so that each child creates its own log file.

Step 3: Using TCA to Display Information

After you have created one or more log files, you can use the tca command to get the information in which you are interested. TCA normally sends its reports to console (Windows) or stdout (Unix). If you would like to use the graphical version to generate coverage reports, see The TCA Display for more information.

You can specify any number of log files on the command line, and TCA will combine the data before displaying the results. If the log files are not compatible. For example, TCA will throw out the files that do not match the first log file if they are from different applications. 

TCA will also need to read the map file created at compilation time. Since this name is stored in the log file, you won't normally need to specify it. By default, TCA will give you a quick summary of how much of your code was tested. Using different options, you can get detailed reports of coverage by file, function, or even block. For each block, TCA can tell you how many times it was executed, summing over all the log files unless coverage_boolean was on at compile time (default).

If a single statement spans several lines of source code, TCA treats the statement as lying on the last line; this is only important for understanding the output of TCA, and does not affect how coverage statistics are calculated.