-------------------------------------------------
- README file for the LTP GCOV extension (LCOV) -
- Last changes: 2019-02-28                      -
-------------------------------------------------

Further README contents
-----------------------
  1. Included files
  3. An example of how to access kernel coverage data
  4. An example of how to access coverage data for a user space program


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


3. An example of how to access kernel coverage data
---------------------------------------------------
Requirements: get and install the gcov-kernel package from

  http://sourceforge.net/projects/ltp

Copy the resulting gcov kernel module file to either the system wide modules
directory or the same directory as the Perl scripts. 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.
