# 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

- gendesc - generate a test case description file
- genhtml - generate HTML view from LCOV coverage data files
- geninfo - translate GCOV data to LCOV format
- genpng - generate overview PNG file from coverage data
- lcov - capture and manipulate coverage data from lcov tracefiles or gcov.
- lcovrc - configuration file for LCOV tools containing default options and settings.
- llvm2lcov - Translate `llvm-cov` profdata to LCOV format
- perl2lcov - Translate Perl coverage data to lcov format.
- py2lcov - Translate Python `Coverage.py` data to lcov format
- spreadsheet.py - Convert LCOV profile data to Excel spreadsheet
- LCOV Callback Scripts

# 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.