lcov

lcov [OPTIONS]
Common usage:
lcov --directory DIR --capture --output-file FILE.info
lcov --add-tracefile FILE1.info --add-tracefile FILE2.info --output-file MERGED.info
lcov --list FILE.info
lcov --remove FILE.info PATTERN --output-file FILTERED.info
lcov --zerocounters --directory DIR

--capture, -c
    Capture coverage data from the specified directory containing .gcda and .gcno files.

--directory DIR, -d DIR
    Specify the base directory where compiled files and gcov data reside.

--output-file FILE, -o FILE
    Write the generated LCOV tracefile to the specified path.

--add-tracefile FILE, -a FILE
    Add the contents of an existing LCOV tracefile to the current data set.

--list, -l
    List the contents of an LCOV tracefile, displaying coverage statistics in plain text.

--remove FILE PATTERN, -r FILE PATTERN
    Remove coverage data from a tracefile for files matching the specified pattern(s).

--zerocounters, -z
    Reset all execution counters in .gcda files within the specified directory, preparing for a new coverage run.

--no-external
    Exclude coverage data for files located outside the specified base directory.

--rc KEY=VALUE
    Set an LCOV configuration variable, e.g., 'lcov_branch_coverage=1' to enable branch coverage.

lcov is a command-line utility that collects and processes code coverage data generated by the GNU Code Coverage tool (gcov). It's part of the LCOV project, which provides a set of tools for creating coverage reports for C/C++ and Fortran programs.

Its primary function is to consolidate data from multiple gcov output files (.gcda and .gcno), which represent execution counts and notes from program compilation, respectively. lcov can capture fresh coverage data, merge existing coverage tracefiles, remove irrelevant data, and list statistics. The output is typically an LCOV tracefile (.info format), which is then commonly used by genhtml to produce comprehensive, human-readable HTML reports highlighting lines of code executed, branches taken, and overall coverage percentages. This makes lcov an essential tool for assessing test suite effectiveness and code quality.

lcov relies on code being compiled with gcov instrumentation flags (e.g., -fprofile-arcs -ftest-coverage) and requires the presence of both .gcda (execution data) and .gcno (profiling notes) files. Inconsistent file paths between compilation and execution environments can lead to incorrect or incomplete coverage data. Processing very large codebases might be resource-intensive.

A common workflow for using lcov and its companion tool genhtml to generate code coverage reports:
1. Compile Code: Compile your C/C++ code with gcov instrumentation flags. For example:
gcc -fprofile-arcs -ftest-coverage my_program.c -o my_program
2. Run Tests/Application: Execute your compiled program or test suite to generate .gcda files containing execution counts:
./my_program (or run your automated test suite)
3. Capture Coverage: Use lcov to collect the .gcda and .gcno data and output it into an LCOV tracefile (.info format):
lcov --capture --directory . --output-file app.info
4. Generate Report: Use genhtml to convert the tracefile into a human-readable HTML report:
genhtml app.info --output-directory coverage_report
5. View Report: Open the generated coverage_report/index.html in a web browser to analyze the code coverage results.

lcov was originally developed by IBM as part of the Linux Test Project. Since its inception in the early 2000s, it has steadily gained traction and become a widely adopted, de-facto standard for C/C++ code coverage analysis within Linux environments, providing robust and flexible tools for developers and quality assurance teams.

gcov(1), genhtml(1), gcc(1), g++(1)