Gcov

gcov

Operating system	Unix-like
Type	Code coverage
License	GNU General Public License and other free software licenses
Website	gcc.gnu.org/onlinedocs/gcc/Gcov.html

Gcov is a source code coverage analysis and statement-by-statement profiling tool. Gcov generates exact counts of the number of times each statement in a program is executed and annotates source code to add instrumentation. Gcov comes as a standard utility with the GNU Compiler Collection (GCC) suite.

The gcov 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 gcov utility does not produce any time-based data and works only on code compiled with the GCC suite. The manual claims it is not compatible with any other profiling or test coverage mechanism, but it works with llvm-generated files too.

Description

gcov produces a test coverage analysis of a specially instrumented program. The options -fprofile-arcs -ftest-coverage should be used to compile the program for coverage analysis (first option to record branch statistics and second to save line execution count); -fprofile-arcs should also be used to link the program. After running such program will create several files with ".bb" ".bbg" and ".da" extensions (suffixes), which can be analysed by gcov. It takes source files as command-line arguments and produces an annotated source listing. Each line of source code is prefixed with the number of times it has been executed; lines that have not been executed are prefixed with "#####".

gcov creates a logfile called sourcefile.gcov which indicates how many times each line of a source file sourcefile.c has executed. This annotated source file can be used with gprof, another profiling tool, to extract timing information about the program.

Example

The following program, written in C, loops over 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:

$ gcc -Wall -fprofile-arcs -ftest-coverage 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. The option -ftest-coverage adds instructions for counting the number of times individual lines are executed, while -fprofile-arcs incorporates instrumentation code for each branch of the program. Branch instrumentation records how frequently different paths are taken through ‘if’ statements and other conditionals.

The executable can then be run to analyze the code and create the coverage data.

$ ./a.out

The data from the run is written to several coverage data files with the extensions ‘.bb’ ‘.bbg’ and ‘.da’ respectively in the current directory.

If the program execution varies based on the input parameters or data, it can be run multiple times and the results will accumulate in the coverage data files for overall analysis.

This data can be analyzed using the gcov command and the name of a source file:

$ gcov cov.c 
 88.89% of 9 source lines executed in file cov.c
Creating cov.c.gcov

The gcov command produces an annotated version of the original source file, with the file extension ‘.gcov’, 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 line counts can be seen in the first column of the output. Lines which were not executed are marked with hashes ‘######’.

Command-line options

Gcov command line utility supports following options while generating annotated files from profile data:

• -h (--help): Display help about using gcov (on the standard output), and exit without doing any further processing.
• -v (--version): Display the gcov version number (on the standard output), and exit without doing any further processing.
• -a (--all-blocks): Write individual execution counts for every basic block. Normally gcov outputs execution counts only for the main blocks of a line. With this option you can determine if blocks within a single line are not being executed.
• -b (--branch-probabilities): Write branch frequencies to the output file, and write branch summary info to the standard output. This option allows you to see how often each branch in your program was taken. Unconditional branches will not be shown, unless the -u option is given.
• -c (--branch-counts): Write branch frequencies as the number of branches taken, rather than the percentage of branches taken.
• -n (--no-output): Do not create the gcov output file.
• -l (--long-file-names): Create long file names for included source files. For example, if the header file x.h contains code, and was included in the file a.c, then running gcov on the file a.c will produce an output file called a.c##x.h.gcov instead of x.h.gcov. This can be useful if x.h is included in multiple source files and you want to see the individual contributions. If you use the `-p' option, both the including and included file names will be complete path names.
• -p (--preserve-paths): Preserve complete path information in the names of generated .gcov files. Without this option, just the filename component is used. With this option, all directories are used, with `/' characters translated to `#' characters, . directory components removed and unremoveable .. components renamed to `^'. This is useful if sourcefiles are in several different directories.
• -r (--relative-only): Only output information about source files with a relative pathname (after source prefix elision). Absolute paths are usually system header files and coverage of any inline functions therein is normally uninteresting.
• -f (--function-summaries): Output summaries for each function in addition to the file level summary.
• -o directory|file (--object-directory directory or --object-file file): Specify either the directory containing the gcov data files, or the object path name. The .gcno, and .gcda data files are searched for using this option. If a directory is specified, the data files are in that directory and named after the input file name, without its extension. If a file is specified here, the data files are named after that file, without its extension.
• -s directory (--source-prefix directory): A prefix for source file names to remove when generating the output coverage files. This option is useful when building in a separate directory, and the pathname to the source directory is not wanted when determining the output file names. Note that this prefix detection is applied before determining whether the source file is absolute.
• -u (--unconditional-branches): When branch probabilities are given, include those of unconditional branches. Unconditional branches are normally not interesting.
• -d (--display-progress): Display the progress on the standard output.

Coverage summaries

Lcov is a graphical front-end for gcov. It collects gcov data for multiple source files and creates HTML pages containing the source code annotated with coverage information. It also adds overview pages for easy navigation within the file structure. Lcov supports statement, function, and branch coverage measurement. There is also a Windows version.

Gcovr provides a utility for managing the use of gcov and generating summarized code coverage results. This command is inspired by the Python coverage.py package, which provides a similar utility in Python. Gcovr produces either compact human-readable summary reports, machine readable XML reports or a graphical HTML summary. The XML reports generated by gcovr can be used by Jenkins to provide graphical code coverage summaries. Gcovr supports statement and branch coverage measurement

SCov is a utility that processes the intermediate text format generated by gcov (using gcov -i) to generate reports on code coverage. These reports can be a simple text report, or HTML pages with more detailed reports.

See also

• Tcov – code coverage tool for Solaris provided in Sun Studio suite
• Trucov - intended to improve on Gcov with machine readable output