Tcov

tcov
Developer(s) Oracle Corporation
Operating system Solaris
Type Code Coverage
License Free for download and use as described in the Sun Studio product license.
Website developers.sun.com

Tcov is a source code coverage analysis and statement-by-statement profiling tool for software written in Fortran, C and C++. Tcov generates exact counts of the number of times each statement in a program is executed and annotates source code to add instrumentation. It is a standard utility, provided free of cost with Sun Studio software under Sun Studio product license.[1]

The tcov utility gives information on how often a program executes segments of code. It produces a copy of the source file, annotated with execution frequencies. The code can be annotated at the basic block level or the source line level. As the statements in a basic block are executed the same number of times, a count of basic block executions equals number of times each statement in the block is executed. The tcov utility does not produce any time-based data.

Description

tcov produces a test coverage analysis of a compiled program. tcov takes source files as arguments and produces an annotated source listing. Each basic block of code (or each line if the particular option to tcov is specified) is prefixed with the number of times it has been executed; lines that have not been executed are prefixed with "#####".

The tcov utility also places a summary at the end of the annotated program listing. The statistics for the most frequently executed basic blocks are listed in order of execution frequency. The line number is the number of the first line in the block.

There are two implementations of tcov:

Enhanced coverage analysis overcomes some of the shortcomings of the original analysis tool, such as:[4]

Implementation

To generate annotated source code, following three steps are required:[5]

Each subsequent run accumulates more coverage data into the profile data file. Data for each object file is zeroed out the first time the program is executed after recompilation. Data for the entire program is zeroed by removing the tcovd file.[6]

The above steps are explained for both original and enhanced tcov below:

Old Style coverage analysis

Source code is compiled with -xa option for C program and -a option for Fortran and C++ programs. The compiler creates a coverage data file with the suffix .d for each object file. The coverage data file is created in the directory specified by the environment variable TCOVDIR. If TCOVDIR is not set, the coverage data file is created in the current directory. The above instrumented build is run and at program completion, the .d files are updated. Finally, tcov command is run to generate the annotated source files. The syntax of the tcov command is as follows:

tcov options source-file-list

Here, source-file-list is a list of the source code filenames. For a list of options, The default output of tcov is a set of files, each with the suffix .tcov, which can be changed with the -o filename option.

A program compiled for code coverage analysis can be run multiple times (with potentially varying input); tcov can be used on the program after each run to compare behavior.

New Style coverage analysis

Source code is compiled with -xprofile=tcov option. Unlike original mode, enhanced tcov doesn't generate any files at compile time.[7] The above instrumented build is run and at program completion, a directory is created to store the profile data, and a single coverage data file called tcovd is created in that directory. tcovd holds the information about the line numbers, and the execution count. It is a plain text file. By default, the directory is created in the location where program is run, and it is named after executable and suffixed by .profile. The directory is also known as the profile bucket. The location of profile bucket can be overridden by setting SUN_PROFDATA_DIR or SUN_PROFDATA environment variables. Finally, tcov command is run to generate the annotated source files. The syntax of the tcov command is same as for original command, except for the mandatory -x option.

tcov options -x profilebucket source-file-list

The only difference in command from original tcov is the mandatory addition is of -x dir option to denote enhanced tcov.

Example

The following program, written in C programming language, loops overs the integers 1 to 9 and tests their divisibility with the modulus (%) operator.

#include <stdio.h>

int
main (void)
{
  int i;

  for (i = 1; i < 10; i++)
    {
      if (i % 3 == 0)
        printf ("%d is divisible by 3\n", i);
      if (i % 11 == 0)
        printf ("%d is divisible by 11\n", i);
    }

  return 0;
}

To enable coverage testing the program must be compiled with the following options:

for old style code coverage,

cc -xa cov.c

and for new style code coverage,

cc -xprofile=tcov -o cov cov.c

where cov.c is the name of the program file. This creates an instrumented executable which contains additional instructions that record the number of times each line of the program is executed. -o option is used to set the name of the executable. The executable must then be run to create the coverage data. The creation and location of this file is different for old- and new- style code analysis. In old style analysis, this file with extension .d, created after compilation, either in TCOVDIR directory or current one, is updated with coverage data. In new style analysis, coverage data file, with name tcovd, is created in <executable name>.profile directory. This data can be analyzed using the tcov command and the name of a source file:

for old style code coverage,

tcov cov.c

and for new style code coverage,

tcov -x cov.profile cov.c

the addition argument in new style analysis is profile bucket. The tcov command produces an annotated version of the original source file, with the file extension ‘.tcov’, containing counts of the number of times each line was executed:

        #include <stdio.h>

        int
        main (void)
        {
     1    int i;

    10    for (i = 1; i < 10; i++)
            {
     9        if (i % 3 == 0)
     3          printf ("%d is divisible by 3\n", i);
     9        if (i % 11 == 0)
######          printf ("%d is divisible by 11\n", i);
     9      }

     1    return 0;
     1  }

The tcov utility also places a summary at the end of the annotated program listing. The statistics for the most frequently executed basic blocks are listed in order of execution frequency. The line number is the number of the first line in the block.

Command line options

Tcov command line utility supports following options while generating annotated files from profile data:[8]

See also

References

This article is issued from Wikipedia - version of the Monday, March 07, 2016. The text is available under the Creative Commons Attribution/Share Alike but additional terms may apply for the media files.