The tcov Profiling Command

The tcov(1) command, when used with programs compiled with the -a, -xa, or -xprofile=tcov options, produces a statement-by-statement profile of the source code showing which statements executed and how often. It also gives a summary of information about the basic block structure of the program.

There are two implementations of tcov coverage analysis. The original tcov is invoked by the -a or -xa compiler options. Enhanced statement level coverage is invoked by the -xprofile=tcov compiler option and the -x tcov option. In either case, the output is a copy of the source files annotated with statement execution counts in the margin. Although these two versions of tcov are essentially the same as far as the Fortran user is concerned (most of the enhancements apply to C++ programs), there will be some performance improvement with the newer style.

"Old Style" tcov Coverage Analysis

Compile the program with the -a (or -xa) option. This produces the file $TCOVDIR/file.d for each source .f file in the compilation. (If environment variable $TCOVDIR is not set at compile time, the .d files are stored in the current directory.)

Run the program (execution must complete normally). This produces updated information in the .d files. To view the coverage analysis merged with the individual source files, run tcov on the source files. The annotated source files are named $TCOVDIR/file.tcov for each source file.

The output produced by tcov shows the number of times each statement was actually executed. Statements that were not executed are marked with ####-> to the left of the statement.

Here is a simple example:

demo% f77 -a -o onetwo -silent one.f two.f
demo% onetwo
       ... output from program
demo% tcov one.f two.f
demo% cat one.tcov two.tcov
                       program one
      1 ->             do i=1,10
     10 ->                   call two(i)
                       end do
      1 ->             end

             Top 10 Blocks
             Line         Count
                3            10
                2             1
                5             1

          3       Basic blocks in this file
          3       Basic blocks executed
      100.00       Percent of the file executed
           12       Total basic block executions
         4.00       Average executions per basic block

                       subroutine two(i)
     10 ->             print*, "two called", i
                       return
                       end

             Top 10 Blocks
             Line         Count
                2            10

          1       Basic blocks in this file
          1       Basic blocks executed
      100.00       Percent of the file executed
           10       Total basic block executions
        10.00       Average executions per basic block
demo%

"New Style" Enhanced tcov Analysis

To use new style tcov, compile with -xprofile=tcov. When the program is run, coverage data is stored in program.profile/tcovd, where program is the name of the executable file. (If the executable were a.out, a.out.profile/tcovd would be created.)

Run tcov -x dirname source_files to create the coverage analysis merged with each source file. The report is written to file.tcov in the current directory.

Running a simple example:

demo% f77 -o onetwo -silent -xprofile=tcov one.f two.f
demo% onetwo
       ... output from program
demo% tcov -x onetwo.profile one.f two.f
demo% cat one.f.tcov two.f.tcov
                       program one
      1 ->             do i=1,10
     10 ->                   call two(i)
                       end do
      1 ->             end
       .....etc
demo%

Environment variables $SUN_PROFDATA and $SUN_PROFDATA_DIR can be used to specify where the intermediary data collection files are kept. These are the *.d and tcovd files created by old and new style tcov, respectively.

Each subsequent run accumulates more coverage data into the tcovd file. Data for each object file is zeroed out the first time the program is executed after the corresponding source file has been recompiled. Data for the entire program is zeroed out by removing the tcovd file.

These environment variables can be used to separate the collected data from different runs. With these variables set, the running program writes execution data to the files in $SUN_PROFDATA_DIR/$SUN_PROFDATA/.

Similarly, the directory that tcov reads is specified by tcov -x $SUN_PROFDATA. If $SUN_PROFDATA_DIR is set, tcov will prepend it, looking for files in $SUN_PROFDATA_DIR/$SUN_PROFDATA/, and not in the working directory.

For the details, see the tcov(1) man page.