third_party/lcov/README

   1 -------------------------------------------------
   2 - README file for the LTP GCOV extension (LCOV) -
   3 - Last changes: 2012-10-10                      -
   4 -------------------------------------------------
   5
   6 Description
   7 -----------
   8   LCOV is an extension of GCOV, a GNU tool which provides information about
   9   what parts of a program are actually executed (i.e. "covered") while running
  10   a particular test case. The extension consists of a set of Perl scripts
  11   which build on the textual GCOV output to implement the following enhanced
  12   functionality:
  13
  14     * HTML based output: coverage rates are additionally indicated using bar
  15       graphs and specific colors.
  16
  17     * Support for large projects: overview pages allow quick browsing of
  18       coverage data by providing three levels of detail: directory view,
  19       file view and source code view.
  20
  21   LCOV was initially designed to support Linux kernel coverage measurements,
  22   but works as well for coverage measurements on standard user space
  23   applications.
  24
  25
  26 Further README contents
  27 -----------------------
  28   1. Included files
  29   2. Installing LCOV
  30   3. An example of how to access kernel coverage data
  31   4. An example of how to access coverage data for a user space program
  32   5. Questions and Comments
  33
  34
  35
  36 1. Important files
  37 ------------------
  38   README             - This README file
  39   CHANGES            - List of changes between releases
  40   bin/lcov           - Tool for capturing LCOV coverage data
  41   bin/genhtml        - Tool for creating HTML output from LCOV data
  42   bin/gendesc        - Tool for creating description files as used by genhtml
  43   bin/geninfo        - Internal tool (creates LCOV data files)
  44   bin/genpng         - Internal tool (creates png overviews of source files)
  45   bin/install.sh     - Internal tool (takes care of un-/installing)
  46   descriptions.tests - Test descriptions for the LTP suite, use with gendesc
  47   man                - Directory containing man pages for included tools
  48   example            - Directory containing an example to demonstrate LCOV
  49   lcovrc             - LCOV configuration file
  50   Makefile           - Makefile providing 'install' and 'uninstall' targets
  51
  52
  53 2. Installing LCOV
  54 ------------------
  55 The LCOV package is available as either RPM or tarball from:
  56
  57   http://ltp.sourceforge.net/coverage/lcov.php
  58
  59 To install the tarball, unpack it to a directory and run:
  60
  61   make install
  62
  63 Use anonymous CVS for the most recent (but possibly unstable) version:
  64
  65   cvs -d:pserver:anonymous@ltp.cvs.sourceforge.net:/cvsroot/ltp login
  66
  67 (simply press the ENTER key when asked for a password)
  68
  69   cvs -z3 -d:pserver:anonymous@ltp.cvs.sourceforge.net:/cvsroot/ltp export -D now utils
  70
  71 Change to the utils/analysis/lcov directory and type:
  72
  73   make install
  74
  75
  76 3. An example of how to access kernel coverage data
  77 ---------------------------------------------------
  78 Requirements: get and install the gcov-kernel package from
  79
  80   http://sourceforge.net/projects/ltp
  81
  82 Copy the resulting gcov kernel module file to either the system wide modules
  83 directory or the same directory as the Perl scripts. As root, do the following:
  84
  85   a) Resetting counters
  86
  87      lcov --zerocounters
  88
  89   b) Capturing the current coverage state to a file
  90
  91      lcov --capture --output-file kernel.info
  92
  93   c) Getting HTML output
  94
  95      genhtml kernel.info
  96
  97 Point the web browser of your choice to the resulting index.html file.
  98
  99
 100 4. An example of how to access coverage data for a user space program
 101 ---------------------------------------------------------------------
 102 Requirements: compile the program in question using GCC with the options
 103 -fprofile-arcs and -ftest-coverage. During linking, make sure to specify
 104 -lgcov or -coverage.
 105
 106 Assuming the compile directory is called "appdir", do the following:
 107
 108   a) Resetting counters
 109
 110      lcov --directory appdir --zerocounters
 111
 112   b) Capturing the current coverage state to a file (works only after the
 113      application has been started and stopped at least once)
 114
 115      lcov --directory appdir --capture --output-file app.info
 116
 117   c) Getting HTML output
 118
 119      genhtml app.info
 120
 121 Point the web browser of your choice to the resulting index.html file.
 122
 123 Please note that independently of where the application is installed or
 124 from which directory it is run, the --directory statement needs to
 125 point to the directory in which the application was compiled.
 126
 127 For further information on the gcc profiling mechanism, please also
 128 consult the gcov man page.
 129
 130
 131 5. Questions and comments
 132 -------------------------
 133 See the included man pages for more information on how to use the LCOV tools.
 134
 135 Please email further questions or comments regarding this tool to the
 136 LTP Mailing list at ltp-coverage@lists.sourceforge.net
 137