gcov

Generate a coverage report named file.cpp.gcov

$ gcov [path/to/file.cpp]

$ gcov [[-a|--all-blocks]] [path/to/file.cpp]

$ gcov [[-b|--branch-probabilities]] [path/to/file.cpp]

$ gcov [[-c|--branch-counts]] [path/to/file.cpp]

$ gcov [[-n|--no-output]] [path/to/file.cpp]

$ gcov [[-f|--function-summaries]] [path/to/file.cpp]

gcov [OPTIONS] SOURCE_FILES

-h, --help
    Displays a help message and exits.

-v, --version
    Prints the gcov version number and exits.

-a, --all-blocks
    Show information for every basic block, not just lines.

-b, --branches
    Display branch probability information, showing how often each branch was taken or not taken.

-f, --function-summaries
    Display a summary of how many times each function in the source file was called.

-o <directory|file>, --object-directory <directory>, --object-file <file>
    Specifies the directory where the .gcno and .gcda files are located, or the specific object file.

-i, --json-format
    Output the coverage results in JSON format (available in newer GCC/gcov versions).

-l, --long-file-names
    Use long, full path filenames in the output, useful when multiple files with the same name exist.

-p, --preserve-paths
    Preserve the full path information from the object file when generating output, rather than just the filename.

gcov is a command-line utility that provides code coverage analysis for programs compiled with GCC. It works by processing profile data generated during program execution, which is created when the code is compiled with specific GCC flags (typically -fprofile-arcs -ftest-coverage).

After an instrumented program runs, gcov analyzes the generated .gcda (data) and .gcno (notes) files to produce human-readable .gcov reports. These reports indicate how many times each line of code was executed, identify lines that were never reached, and provide detailed branch coverage information.

It is an invaluable tool for software testing, helping developers measure the effectiveness of their test suites, pinpoint untested code paths, and ensure comprehensive code coverage, thereby improving software quality and reliability.

gcov requires the program to be compiled with specific GCC flags (-fprofile-arcs -ftest-coverage) to generate the necessary profiling data.

It must be run in an environment where the original source files and the generated .gcda and .gcno files are accessible, usually in the same directory as the object file or specified via -o.

It's a low-level tool; for generating graphical or aggregate reports, it's often used in conjunction with other tools like lcov.

The typical workflow for using gcov involves three main steps:
1. Compilation: Compile your source code with GCC using the -fprofile-arcs -ftest-coverage flags.
2. Execution: Run the compiled executable. This generates .gcda files containing execution counts.
3. Analysis: Run gcov on the original source files. gcov processes the .gcda and .gcno files to generate .gcov output files, showing line-by-line coverage.

gcov relies on and produces specific file types:
.gcno (graph notes): Generated during compilation with -ftest-coverage, contains control flow graph and source line information.
.gcda (graph data): Generated during program execution, contains execution counts for basic blocks and arcs.
.gcov (coverage output): Generated by gcov, a human-readable text file showing coverage statistics for each line of the source file.

gcov has been an integral part of the GNU Compiler Collection (GCC) since its early versions, evolving alongside the compiler itself. Initially, it provided basic line coverage. Over time, its capabilities expanded to include branch coverage, function summaries, and more sophisticated output formats, including the recent addition of JSON output, reflecting the growing demand for automated and parseable coverage data in modern CI/CD pipelines. It has consistently served as the foundational tool for code coverage analysis within the GNU/Linux ecosystem.

gcc(1), gprof(1), lcov(1), genhtml(1)