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