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.