• README file for the LTP GCOV extension (LCOV) -
• Last changes: 2022-06-03 -

Description

LCOV is an extension of GCOV, a GNU tool which provides information about what parts of a program are actually executed (i.e. "covered") while running a particular test case. The extension consists of a set of Perl scripts which build on the textual GCOV output to implement the following enhanced functionality:

* HTML based output: coverage rates are additionally indicated using bar
  graphs and specific colors.

* Support for large projects: overview pages allow quick browsing of
  coverage data by providing three levels of detail: directory view,
  file view and source code view.

LCOV was initially designed to support Linux kernel coverage measurements, but works as well for coverage measurements on standard user space applications.

Further README contents

1. Included files

2. Installing LCOV

3. An example of how to access kernel coverage data

4. An example of how to access coverage data for a user space program

5. Questions and Comments

6. Important files

README - This README file CHANGES - List of changes between releases bin/lcov - Tool for capturing LCOV coverage data bin/genhtml - Tool for creating HTML output from LCOV data bin/gendesc - Tool for creating description files as used by genhtml bin/geninfo - Internal tool (creates LCOV data files) bin/genpng - Internal tool (creates png overviews of source files) bin/install.sh - Internal tool (takes care of un-/installing) man - Directory containing man pages for included tools example - Directory containing an example to demonstrate LCOV lcovrc - LCOV configuration file Makefile - Makefile providing 'install' and 'uninstall' targets

2. Installing LCOV

The LCOV package is available as either RPM or tarball from:

https://github.com/linux-test-project/lcov/releases

To install the tarball, unpack it to a directory and run:

make install

Use Git for the most recent (but possibly unstable) version:

git clone https://github.com/linux-test-project/lcov.git

Change to the resulting lcov directory and type:

make install

3. An example of how to access Linux kernel coverage data

Requirements: Follow the Linux kernel coverage setup instructions at:

https://docs.kernel.org/dev-tools/gcov.html

As root, do the following:

a) Resetting counters

 lcov --zerocounters

b) Capturing the current coverage state to a file

 lcov --capture --output-file kernel.info

c) Getting HTML output

 genhtml kernel.info

Point the web browser of your choice to the resulting index.html file.

4. An example of how to access coverage data for a user space program

Requirements: compile the program in question using GCC with the options -fprofile-arcs and -ftest-coverage. During linking, make sure to specify -lgcov or -coverage.

Assuming the compile directory is called "appdir", do the following:

a) Resetting counters

 lcov --directory appdir --zerocounters

b) Capturing the current coverage state to a file

 lcov --directory appdir --capture --output-file app.info

 Note that this step only works after the application has
 been started and stopped at least once. Otherwise lcov will
 abort with an error mentioning that there are no data/.gcda files.

c) Getting HTML output

 genhtml app.info

Point the web browser of your choice to the resulting index.html file.

Please note that independently of where the application is installed or from which directory it is run, the --directory statement needs to point to the directory in which the application was compiled.

For further information on the gcc profiling mechanism, please also consult the gcov man page.

5. Questions and comments

See the included man pages for more information on how to use the LCOV tools.

In case of further questions, feel free to open a new issue using the issue tracker on the LCOV code repository site at:

https://github.com/linux-test-project/lcov