lcov-1.7 into third_party for code coverage on POSIX systems....

third_party/lcov/README

Index: third_party/lcov/README
===================================================================
--- third_party/lcov/README	(revision 0)
+++ third_party/lcov/README	(revision 0)
@@ -0,0 +1,128 @@
+-------------------------------------------------
+- README file for the LTP GCOV extension (LCOV) -
+- Last changes: 2008-11-17                      -
+-------------------------------------------------
+
+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
+
+
+
+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)
+  descriptions.tests - Test descriptions for the LTP suite, use with gendesc
+  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:
+     
+  http://ltp.sourceforge.net/coverage/lcov.php
+
+To install the tarball, unpack it to a directory and run:
+
+  make install
+
+Use anonymous CVS for the most recent (but possibly unstable) version:
+
+  cvs -d:pserver:anonymous@ltp.cvs.sourceforge.net:/cvsroot/ltp login
+
+(simply press the ENTER key when asked for a password)
+
+  cvs -z3 -d:pserver:anonymous@ltp.cvs.sourceforge.net:/cvsroot/ltp export -D now utils
+
+Change to the utils/analysis/lcov directory and type:
+
+  make install
+
+
+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. 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 (works only after the
+     application has been started and stopped at least once)
+
+     lcov --directory appdir --capture --output-file app.info
+
+  c) Getting HTML output
+
+     genhtml app.info
+
+Point the web browser of your choice to the resulting index.html file.
+
+
+5. Questions and comments
+-------------------------
+See the included man pages for more information on how to use the LCOV tools.
+
+Please email further questions or comments regarding this tool to the
+LTP Mailing list at ltp-coverage@lists.sourceforge.net  
+