Practical Guide to C++ Code Coverage Testing with gcov and lcov

Introduction: This article continues from a previous discussion of the gcov tool’s principles and structure, focusing on practical C++ code‑coverage testing. It is divided into three phases: compilation, execution to collect coverage data, and report generation.

1. Compilation Phase – Enable gcov by adding the compiler options -fprofile-arcs -ftest-coverage . The -ftest-coverage flag creates .gcno files containing basic‑block graph information, while -fprofile-arcs causes the execution of the compiled program to produce .gcda files with execution counts. Example compilation commands:

gcc -fprofile-arcs -ftest-coverage -o test test.c

or separate compile and link steps:

gcc -c test.c -ftest-coverage -fprofile-arcs

gcc test.o -o test -lgcov

When using build systems such as make or scons, add the same flags to the compile rules and link with --coverage or -lgcov .

2. Running the Program to Generate Coverage Data – Execute the instrumented binary, e.g., ./test 34 . This creates .gcda files in the build directory. For long‑running server applications that do not exit normally, insert a signal handler to flush coverage data:

extern "C" void __gcov_flush(void);

void gcov_func(int sig)

{

__gcov_flush();

}

int main()

{

signal(SIGUSR1, gcov_func);

// program logic …

}

3. Generating gcov Reports – Use gcov with options to produce detailed reports, for example:

gcov -a -b -c -l -f *.c

The options control output of execution counts per basic block ( -a ), branch frequencies ( -b ), numeric display ( -c ), file name inclusion ( -l ), and function summaries ( -f ). The resulting .gcov files highlight uncovered lines (marked with ##### ).

For cross‑compilation, set the environment variables GCOV_PREFIX and GCOV_PREFIX_STRIP to adjust absolute paths in the generated data.

4. Using lcov to Create HTML Reports – Install lcov (e.g., version 1.14) and capture coverage data:

lcov -c -d . -o test.info --rc lcov_branch_coverage=1

This command scans the current directory for .gcno and .gcda files, captures branch coverage, and writes the information to test.info . The .info file contains records such as TN , SF , FN , FNDA , BRDA , DA , etc., describing test names, source files, function execution counts, branch execution counts, and line execution counts.

Generate a browsable HTML report with:

genhtml --branch-coverage -o html_report --rc lcov_branch_coverage=1 test.info

The -o option specifies the output directory, and the --branch-coverage flag includes branch coverage data. The resulting HTML pages provide a clear visual overview of covered and uncovered code.

Conclusion: By following these steps—compiling with gcov flags, running the instrumented binary (optionally flushing data via a signal), generating raw gcov reports, and converting them to polished HTML with lcov—developers can obtain accurate and actionable C++ code‑coverage metrics.