Coverage Measurement and Profiling

In order to use gcov, you must use GCC as your compiler. In addition, you must pass the options -fprofile-arcs -ftest-coverage during compilation. This causes GCC to insert additional code into the created object files to record the information needed by gcov and save it to disk.

The gcov data is written in the same directory as your source files, using a .da extension instead of .c. Nothing is written until you run your program. You can run your program multiple times to accumulate measurements, for example, trying different command-line options or input data.

Per the GCC documentation, the object file contains the absolute pathname of the .da file. So, it is not possible to move your source files after building and continue to collect coverage measurements. Doing so produces the error message arc profiling: Can't open output file filename when attempting to save the coverage data. gcov also shows results for only a single file at a time, and it does not provide a summarization method.

Creating gcov reports is straightforward. I use glib (the base library for Gtk+ and GNOME, see www.gtk.org) as an example. First, download glib from the Gtk+ site or a mirror. I used glib-2.2.1, which was the latest at the time of this writing.

To turn on coverage measurement, set the environment variable CFLAGS to -fprofile-arcs -ftest-coverage and run the standard ./configure; make; make check. This should work for any software that follows the GNU guidelines.

After make check has completed, it is possible to use gcov to create coverage reports. The most basic report we can access is a statement coverage report:

[zfrey@warthog glib]$ gcov garray.c
 68.37% of 215 source lines executed in file garray.c
Creating garray.c.gcov.

Besides printing out summary statistics, gcov creates an annotated source listing. For each executable line, this listing shows either the number of times it has been executed or a flag indicating it never has been executed (Listing 1).

      GArray* g_array_sized_new
                  (gboolean zero_terminated,
                   gboolean clear,
                   guint    elt_size,
                   guint    reserved_size)
40    {
40      GRealArray *array;

40      G_LOCK (array_mem_chunk);
40      if (!array_mem_chunk)
14        array_mem_chunk = g_mem_chunk_new
                           ("array mem chunk",
                            sizeof (GRealArray),
                            1024, G_ALLOC_AND_FREE);

40      array = g_chunk_new (GRealArray,
                             array_mem_chunk);

To see the branch coverage, use the -b option:

[zfrey@warthog glib]$ gcov -b garray.c
 68.37% of 215 source lines executed in file garray.c
 59.02% of 122 branches executed in file garray.c
 46.72% of 122 branches taken at least once in file garray.c
 45.35% of 86 calls executed in file garray.c
Creating garray.c.gcov.

The annotated source file now contains the branch data (Listing 2).

        GArray* g_array_sized_new (
                         gboolean zero_terminated,
                         gboolean clear,
                         guint    elt_size,
                         guint    reserved_size)
  40    {
  40      GRealArray *array;

  40      G_LOCK (array_mem_chunk);
branch 0 taken = 40%
branch 1 taken = 58%
call 2 returns = 100%
branch 3 taken = 100%
call 4 returns = 100%
  40      if (!array_mem_chunk)
branch 0 taken = 65%
  14        array_mem_chunk = g_mem_chunk_new (
                            "array mem chunk",
call 0 returns = 100%
                             sizeof (GRealArray),
                             1024, G_ALLOC_AND_FREE);
                             1024, G_ALLOC_AND_FREE);

  40      array = g_chunk_new (GRealArray,
                               array_mem_chunk);
call 0 returns = 100%

To see coverage broken down by function within the source file, use the -f option. This can be combined with -b to get the branch coverage data on a per-function basis as well. Unfortunately, gcov does not provide a way to summarize results over multiple source files.

GGCov is a Gtk+-based GUI front end for gcov written by Greg Banks and available at www.alphalink.com.au/~gnb/ggcov. I was able to download the latest version (0.1.1 at the time), compile and install with it no problems. This was done using ./configure; make; make install and allowing /usr/local as the prefix.

To use GGCov, cd to the directory with your source files and launch GGCov. GGCov then looks for all the files in that directory with coverage measurements and creates a summary (Figure 1). This is something you cannot do with GNU gcov by itself.

Figure 1. A GGCov Summary Report

Selecting the Filename button activates a drop-down list of all files in the directory that have coverage information. Selecting a filename returns the statistics for that file.

Figure 2. A GGCov Report by File

Selecting the Function button activates a drop-down list of all the functions from all the files in the directory that have coverage information. Selecting a function name returns the statistics for that function (Figure 3).

Figure 3. A GGCov Report by Function

As if that weren't enough power, the Range button allows the selection of a file and a line number range and creates a summary for only the functions within that range. All views except the Overall summary have a View button, which brings up a new window containing the annotated source display for the selected file.

Overall, I found the basic functionality of GGCov easy to use and helpful. GGCov also contains features for displaying call graphs; unfortunately, on Red Hat 8.0 the glib example caused GGCov to segfault. I contacted Greg Banks, who said the call graph features were the most immature and that he hopes to address these problems in the next few releases.