LCOV Documentation (2.5)

LCOV is a graphical tool which collects and aggregates coverage data from multiple sources then generates HTML reports to visualize the data. It supports line, function, branch and MC/DC coverage. LCOV was originally written to display coverage data GCC’s coverage testing tool gcov - but has been enhanced to support multiple tools and languages - including C/C++, Perl, Python, Java and SystemVerilog.

Manual Pages

Callback Scripts

LCOV provides callback scripts to customize version control system integration, coverage criteria enforcement and various other purposes:

  • Annotate scripts:

    • --annotate-script option

    • extract file author/date data (examples: gitblame.pm, p4annotate.pm)

  • Version scripts:

    • --version-script option

    • extract and compare file versions (examples: gitversion.pm, batchGitVersion.pm, P4version.pm, get_signature)

  • Diff scripts:

    • used by --diff-file option

    • generate unified source text diffs (examples: gitdiff, p4udiff)

  • Criteria scripts:``

    • –criteria-script`` option

    • check and enforce coverage thresholds (examples: criteria.pm, threshold.pm)

  • Subset/code review:

    • --select-script option

    • generate HTML report showing only particular subset of sources (example: select.pm)

  • Unreachable code:

    • –unreachable-script` option

    • tag unreachable expressions so they are not counted/do not appear in the coverage report (example: unreach.pm)

  • Modify code appearance:

    • --simplify-script option

    • shorten very long C++ template names (example: simplify.pm)

  • Find corresponding source file (in non-trivial build environment:

    • --resolve-script option

The callback scripts shipped with the LCOV release are primarily intended only as examples of possible callback implementations. The expectation is that users will want or need to customize the callbacks in order to support their specific environment and requirements.

For details, see the *-script option section in the individual tool man pages (genhtml, llvm2lcov, etc.) Note that not all tools support all options. For example, --diff-file and --annotate-script are supported by genhtml only.

Getting Started

  1. Point your environment to your installation of LCOV - or install LCOV using make install

  2. Prepare your executables:

    • C/C++: compile and link with coverage flags: --coverage or -fprofile-arcs -ftest-coverage.

    • Perl, Python, etc. - see the other tools in this release.

  3. Run your tests

  4. Capture coverage

    • C/C++: lcov --capture --directory . --output-file coverage.info

    • Other languages: see other tools in this release and/or consult your toolchain documentation.

  5. Generate HTML report: genhtml coverage.info --output-directory out

  6. Read the man pages and/or the HTML documentation to discover other capabilities and options.

Example

The LCOV source distribution includes a complete working example in directory $LCOV_HOME/share/lcov/example (or in the example subdirectory, if you are using an lcov source version).

The example demonstrates:

  • Compiling C/C++ code with coverage instrumentation

  • Running tests and capturing coverage data

  • Generating HTML coverage reports

  • Using differential coverage analysis

  • Using coverage and part of your code review process

To see some examples of LCOV generated HTML coverage reports:

$ cp -r $|TOOL_NAME|_HOME/share/lcov/example .
$ cd example
$ make

Review the ‘make’ log and the generated data, and then point a web browser into the resulting reports.

The example builds with GCC by default. You will need to make a few changes if you want to use LLVM instead.

  • Default view:

    • Point your browser to output/index.html

  • Hierarchical view:

    • Point your browser to hierarchical/index.html

    • Note that that the coverage data is the same - only the report format is different:

      • Follows directory structure, similar to MS file viewer (--hierarchical flag)

      • Additional navigation links also enabled (--show-navigation flag)

  • Differential coverage:

    • Point your browser to exampleRepo/differential/index.html

    • This example is slightly complicated because it emulates a moderately realistic project in that it pretends to see project changes:

      • updates to two project source files example.c and iterate.c

      • change to the test suite: only one test of updated code rather than 3 of the original code

      The Makefile simulates this by checking code into a git repo, building an executable and then updating a few source files, rebuilding, and running some tests.

  • Code review:

    • point your browser to exampleRepo/review/index.html

    • This example builds on the Differential coverage example, above to emulate a possible code review methodology in which adds code coverage to the review criteria. The intent is to generate a reduced report which shows only the code changes which negatively affect code coverage - while removing other details which only distract from the review.

      • Use the genhtml --select-script ... feature to show only new source code which was negatively affected by the change under review (uncovered and/or lost code). You might want to modify the select criteria to include positive change (e.g., GNC, GBC, and GIC categories).

      • Real use cases are likely to use more sophisticated select-script callbacks (e.g., to select from a range of changelists).

      • The example uses caching and profile history to improve runtime performance - see the man pages for a more detailed description of the features. There is no effect with a tiny example - but a real project may see benefit. The spreadsheet.py application script can be used to convert JSON profile files into more readable excel spreadsheets. This can be useful to see the effect (if any) of the caching and/or history features, and can show where time is spent for your example. This can be helpful, to suggest opportunities to optimize the LCOV implementation.

Feel free to edit the Makefile or to run the lcov utilities directly, to see the effect of other options that you find in the lcov man pages.

AUTHOR

Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>

Original LCOV implementation

Henry Cox <henry.cox@mediatek.com>

Differential coverage, age/author binning, etc..

LCOV Community

Ideas, suggestions, fixes…lots of help

License

LCOV is licensed under the GNU General Public License. See the LICENSE file for details.