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

third_party/lcov/man/lcov.1

Index: third_party/lcov/man/lcov.1
===================================================================
--- third_party/lcov/man/lcov.1	(revision 0)
+++ third_party/lcov/man/lcov.1	(revision 0)
@@ -0,0 +1,557 @@
+.TH lcov 1 "LCOV 1.7" 2008\-11\-17 "User Manuals"
+.SH NAME
+lcov \- a graphical GCOV front\-end
+.SH SYNOPSIS
+.B lcov
+.RB [ \-h | \-\-help ]
+.RB [ \-v | \-\-version ]
+.RB [ \-q | \-\-quiet ]
+.RS 5
+.br
+.RB [ \-z | \-\-zerocounters ]
+.RB [ \-c | \-\-capture ]
+.br
+.RB [ \-a | \-\-add\-tracefile
+.IR tracefile ]
+.br
+.RB [ \-e | \-\-extract
+.IR tracefile ]
+.br
+.RB [ \-r | \-\-remove
+.IR tracefile ]
+.br
+.RB [ \-l | \-\-list
+.IR tracefile ]
+.br
+.RB [ \-\-diff
+.IR "tracefile diff" ]
+.br
+.RB [ \-i | \-\-initial ]
+.RB [ \-t | \-\-test\-name
+.IR testname ]
+.br
+.RB [ \-o | \-\-output\-file
+.IR filename ]
+.br
+.RB [ \-d | \-\-directory
+.IR directory ]
+.br
+.RB [ \-f | \-\-follow ]
+.br
+.RB [ \-k | \-\-kernel\-directory
+.IR directory ]
+.br
+.RB [ \-b | \-\-base\-directory
+.IR directory ]
+.br
+.RB [ \-\-convert\-filenames ]
+.RB [ \-\-strip
+.IR depth ]
+.RB [ \-\-path
+.IR path ]
+.br
+.RB [ \-\-checksum ]
+.RB [ \-\-no\-checksum ]
+.br
+.RB [ \-\-compat\-libtool ]
+.RB [ \-\-no\-compat\-libtool ]
+.br
+.RB [ \-\-gcov\-tool
+.IR tool ]
+.RB [ \-\-ignore\-errors
+.IR errors ]
+.br
+.RB [ \-\-no\-recursion ]
+.SH DESCRIPTION
+.B lcov
+is a graphical front\-end for GCC's coverage testing tool gcov. It collects
+gcov data for multiple source files and creates HTML pages containing the
+source code annotated with coverage information. It also adds overview pages
+for easy navigation within the file structure.
+
+Use
+.B lcov
+to collect coverage data and
+.B genhtml
+to create HTML pages. Coverage data can either be collected from the
+currently running Linux kernel or from a user space application. To do this,
+you have to complete the following preparation steps:
+
+For Linux kernel coverage:
+.RS
+Follow the installation instructions for the gcov\-kernel patch:
+.I http://ltp.sourceforge.net/coverage/gcov.php
+
+.RE
+For user space application coverage:
+.RS
+Compile the application with GCC using the options
+"\-fprofile\-arcs" and "\-ftest\-coverage".
+.RE
+
+Please note that this man page refers to the output format of
+.B lcov
+as ".info file" or "tracefile" and that the output of GCOV
+is called ".da file".
+.SH OPTIONS
+
+
+.B \-a
+.I tracefile
+.br
+.B \-\-add\-tracefile
+.I tracefile
+.br
+.RS
+Add contents of
+.IR tracefile .
+
+Specify several tracefiles using the \-a switch to combine the coverage data
+contained in these files by adding up execution counts for matching test and
+filename combinations.
+
+The result of the add operation will be written to stdout or the tracefile
+specified with \-o.
+
+Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
+at a time.
+
+.RE
+
+.B \-b
+.I directory
+.br
+.B \-\-base\-directory
+.I directory
+.br
+.RS
+.RI "Use " directory
+as base directory for relative paths.
+
+Use this option to specify the base directory of a build\-environment
+when lcov produces error messages like:
+
+.RS
+ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c
+.RE
+
+In this example, use /home/user/project as base directory.
+
+This option is required when using lcov on projects built with libtool or
+similar build environments that work with a base directory, i.e. environments,
+where the current working directory when invoking the compiler is not the same
+directory in which the source code file is located.
+
+Note that this option will not work in environments where multiple base
+directories are used. In that case repeat the lcov call for each base directory
+while using the \-\-ignore\-errors option to prevent lcov from exiting when the
+first source code file could not be found. This way you can get partial coverage
+information for each base directory which can then be combined using the \-a
+option.
+.RE
+
+.B \-c
+.br
+.B \-\-capture
+.br
+.RS
+Capture coverage data.
+
+By default captures the current kernel execution counts and writes the
+resulting coverage data to the standard output. Use the \-\-directory
+option to capture counts for a user space program.
+
+The result of the capture operation will be written to stdout or the tracefile
+specified with \-o.
+
+Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
+at a time.
+.RE
+
+.B \-\-checksum
+.br
+.B \-\-no\-checksum
+.br
+.RS
+Specify whether to generate checksum data when writing tracefiles.
+
+Use \-\-checksum to enable checksum generation or \-\-no\-checksum to
+disable it. Checksum generation is
+.B disabled
+by default.
+
+When checksum generation is enabled, a checksum will be generated for each
+source code line and stored along with the coverage data. This checksum will
+be used to prevent attempts to combine coverage data from different source
+code versions.
+
+If you don't work with different source code versions, disable this option
+to speed up coverage data processing and to reduce the size of tracefiles.
+.RE
+
+.B \-\-compat\-libtool
+.br
+.B \-\-no\-compat\-libtool
+.br
+.RS
+Specify whether to enable libtool compatibility mode.
+
+Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-libtool
+to disable it. The libtool compatibility mode is
+.B enabled
+by default.
+
+When libtool compatibility mode is enabled, lcov will assume that the source
+code relating to a .da file located in a directory named ".libs" can be
+found in its parent directory.
+
+If you have directories named ".libs" in your build environment but don't use
+libtool, disable this option to prevent problems when capturing coverage data.
+.RE
+
+.B \-\-convert\-filenames
+.br
+.RS
+Convert filenames when applying diff.
+
+Use this option together with \-\-diff to rename the file names of processed
+data sets according to the data provided by the diff.
+.RE
+
+.B \-\-diff
+.I tracefile
+.I difffile
+.br
+.RS
+Convert coverage data in
+.I tracefile
+using source code diff file
+.IR difffile .
+
+Use this option if you want to merge coverage data from different source code
+levels of a program, e.g. when you have data taken from an older version
+and want to combine it with data from a more current version.
+.B lcov
+will try to map source code lines between those versions and adjust the coverage
+data respectively.
+.I difffile
+needs to be in unified format, i.e. it has to be created using the "\-u" option
+of the
+.B diff
+tool.
+
+Note that lines which are not present in the old version will not be counted
+as instrumented, therefore tracefiles resulting from this operation should
+not be interpreted individually but together with other tracefiles taken
+from the newer version. Also keep in mind that converted coverage data should
+only be used for overview purposes as the process itself introduces a loss
+of accuracy.
+
+The result of the diff operation will be written to stdout or the tracefile
+specified with \-o.
+
+Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
+at a time.
+.RE
+
+.B \-d
+.I directory
+.br
+.B \-\-directory
+.I  directory
+.br
+.RS
+Use .da files in
+.I directory
+instead of kernel.
+
+If you want to work on coverage data for a user space program, use this
+option to specify the location where the program was compiled (that's
+where the counter files ending with .da will be stored).
+
+Note that you may specify this option more than once.
+.RE
+
+.B \-e
+.I tracefile
+.I pattern
+.br
+.B \-\-extract
+.I tracefile
+.I pattern
+.br
+.RS
+Extract data from
+.IR tracefile .
+
+Use this switch if you want to extract coverage data for only a particular
+set of files from a tracefile. Additional command line parameters will be
+interpreted as shell wildcard patterns (note that they may need to be
+escaped accordingly to prevent the shell from expanding them first).
+Every file entry in
+.I tracefile
+which matches at least one of those patterns will be extracted.
+
+The result of the extract operation will be written to stdout or the tracefile
+specified with \-o.
+
+Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
+at a time.
+.RE
+
+.B \-f
+.br
+.B \-\-follow
+.br
+.RS
+Follow links when searching for .da files.
+.RE
+
+.B \-\-gcov\-tool
+.I tool
+.br
+.RS
+Specify the location of the gcov tool.
+.RE
+
+.B \-h
+.br
+.B \-\-help
+.br
+.RS
+Print a short help text, then exit.
+.RE
+
+.B \-\-ignore\-errors
+.I errors
+.br
+.RS
+Specify a list of errors after which to continue processing.
+
+Use this option to specify a list of one or more classes of errors after which
+lcov should continue processing instead of aborting.
+
+.I errors
+can be a comma\-separated list of the following keywords:
+
+.B gcov:
+the gcov tool returned with a non\-zero return code.
+
+.B source:
+the source code file for a data set could not be found.
+.RE
+
+.B \-i
+.br
+.B \-\-initial
+.RS
+Capture initial zero coverage data.
+
+Run lcov with \-c and this option on the directories containing .bb, .bbg
+or .gcno files before running any test case. The result is a "baseline"
+coverage data file that contains zero coverage for every instrumented line.
+Combine this data file (using lcov \-a) with coverage data files captured
+after a test run to ensure that the percentage of total lines covered is
+correct even when not all source code files were loaded during the test.
+
+Recommended procedure when capturing data for a test case:
+
+1. create baseline coverage data file
+.RS
+# lcov \-c \-i \-d appdir \-o app_base.info
+.br
+
+.RE
+2. perform test
+.RS
+# appdir/test
+.br
+
+.RE
+3. create test coverage data file
+.RS
+# lcov \-c \-d appdir \-o app_test.info
+.br
+
+.RE
+4. combine baseline and test coverage data
+.RS
+# lcov \-a app_base.info \-a app_test.info \-o app_total.info
+.br
+
+.RE
+.RE
+
+.B \-k
+.I subdirectory
+.br
+.B \-\-kernel\-directory
+.I subdirectory
+.br
+.RS
+Capture kernel coverage data only from
+.IR subdirectory .
+
+Use this option if you don't want to get coverage data for all of the
+kernel, but only for specific subdirectories.
+
+Note that you may specify this option more than once.
+.RE
+
+.B \-l
+.I tracefile
+.br
+.B \-\-list
+.I tracefile
+.br
+.RS
+List the contents of the
+.IR tracefile .
+
+Only one of  \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
+at a time.
+.RE
+
+.B \-\-no\-recursion
+.br
+.RS
+Use this option if you want to get coverage data for the specified directory
+only without processing subdirectories.
+.RE
+
+.B \-o
+.I tracefile
+.br
+.B \-\-output\-file
+.I tracefile
+.br
+.RS
+Write data to
+.I tracefile
+instead of stdout.
+
+Specify "\-" as a filename to use the standard output.
+
+By convention, lcov\-generated coverage data files are called "tracefiles" and
+should have the filename extension ".info".
+.RE
+
+.B \-\-path
+.I path
+.br
+.RS
+Strip path from filenames when applying diff.
+
+Use this option together with \-\-diff to tell lcov to disregard the specified
+initial path component when matching between tracefile and diff filenames.
+.RE
+
+.B \-q
+.br
+.B \-\-quiet
+.br
+.RS
+Do not print progress messages.
+
+This option is implied when no output filename is specified to prevent
+progress messages to mess with coverage data which is also printed to
+the standard output.
+.RE
+
+.B \-r
+.I tracefile
+.I pattern
+.br
+.B \-\-remove
+.I tracefile
+.I pattern
+.br
+.RS
+Remove data from
+.IR tracefile .
+
+Use this switch if you want to remove coverage data for a particular
+set of files from a tracefile. Additional command line parameters will be
+interpreted as shell wildcard patterns (note that they may need to be
+escaped accordingly to prevent the shell from expanding them first).
+Every file entry in
+.I tracefile
+which matches at least one of those patterns will be removed.
+
+The result of the remove operation will be written to stdout or the tracefile
+specified with \-o.
+
+Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
+at a time.
+.RE
+
+.B \-\-strip
+.I depth
+.br
+.RS
+Strip path components when applying diff.
+
+Use this option together with \-\-diff to tell lcov to disregard the specified
+number of initial directories when matching tracefile and diff filenames.
+.RE
+
+.B \-t
+.I testname
+.br
+.B \-\-test\-name
+.I testname
+.br
+.RS
+Specify test name to be stored in the tracefile.
+
+This name identifies a coverage data set when more than one data set is merged
+into a combined tracefile (see option \-a).
+
+Valid test names can consist of letters, decimal digits and the underscore
+character ("_").
+.RE
+
+.B \-v
+.br
+.B \-\-version
+.br
+.RS
+Print version number, then exit.
+.RE
+
+.B \-z
+.br
+.B \-\-zerocounters
+.br
+.RS
+Reset all execution counts to zero.
+
+By default tries to reset kernel execution counts. Use the \-\-directory
+option to reset all counters of a user space program.
+
+Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
+at a time.
+.RE
+
+.SH FILES
+
+.I /etc/lcovrc
+.RS
+The system\-wide configuration file.
+.RE
+
+.I ~/.lcovrc
+.RS
+The per\-user configuration file.
+.RE
+
+.SH AUTHOR
+Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
+
+.SH SEE ALSO
+.BR lcovrc (5),
+.BR genhtml (1),
+.BR geninfo (1),
+.BR genpng (1),
+.BR gendesc (1),
+.BR gcov (1)