| .TH lcov 1 "LCOV 1.10" 2012\-10\-10 "User Manuals" |
| .SH NAME |
| lcov \- a graphical GCOV front\-end |
| .SH SYNOPSIS |
| .B lcov |
| .BR \-c | \-\-capture |
| .RS 5 |
| .br |
| .RB [ \-d | \-\-directory |
| .IR directory ] |
| .RB [ \-k | \-\-kernel\-directory |
| .IR directory ] |
| .br |
| .RB [ \-o | \-\-output\-file |
| .IR tracefile ] |
| .RB [ \-t | \-\-test\-name |
| .IR testname ] |
| .br |
| .RB [ \-b | \-\-base\-directory |
| .IR directory ] |
| .RB [ \-i | \-\-initial ] |
| .RB [ \-\-gcov\-tool |
| .IR tool ] |
| .br |
| .RB [ \-\-checksum ] |
| .RB [ \-\-no\-checksum ] |
| .RB [ \-\-no\-recursion ] |
| .RB [ \-f | \-\-follow ] |
| .br |
| .RB [ \-\-compat\-libtool ] |
| .RB [ \-\-no\-compat\-libtool ] |
| .RB [ \-\-ignore\-errors |
| .IR errors ] |
| .br |
| .RB [ \-\-to\-package |
| .IR package ] |
| .RB [ \-\-from\-package |
| .IR package ] |
| .RB [ \-q | \-\-quiet ] |
| .br |
| .RB [ \-\-no\-markers ] |
| .RB [ \-\-external ] |
| .RB [ \-\-no\-external ] |
| .br |
| .RB [ \-\-config\-file |
| .IR config\-file ] |
| .RB [ \-\-rc |
| .IR keyword = value ] |
| .br |
| .RB [ \-\-compat |
| .IR mode =on|off|auto] |
| .br |
| .RE |
| |
| .B lcov |
| .BR \-z | \-\-zerocounters |
| .RS 5 |
| .br |
| .RB [ \-d | \-\-directory |
| .IR directory ] |
| .RB [ \-\-no\-recursion ] |
| .RB [ \-f | \-\-follow ] |
| .br |
| .RB [ \-q | \-\-quiet ] |
| .br |
| .RE |
| |
| .B lcov |
| .BR \-l | \-\-list |
| .I tracefile |
| .RS 5 |
| .br |
| .RB [ \-q | \-\-quiet ] |
| .RB [ \-\-list\-full\-path ] |
| .RB [ \-\-no\-list\-full\-path ] |
| .br |
| .RB [ \-\-config\-file |
| .IR config\-file ] |
| .RB [ \-\-rc |
| .IR keyword = value ] |
| .br |
| .RE |
| |
| .B lcov |
| .BR \-a | \-\-add\-tracefile |
| .I tracefile |
| .RS 5 |
| .br |
| .RB [ \-o | \-\-output\-file |
| .IR tracefile ] |
| .RB [ \-\-checksum ] |
| .RB [ \-\-no\-checksum ] |
| .br |
| .RB [ \-q | \-\-quiet ] |
| .RB [ \-\-config\-file |
| .IR config\-file ] |
| .RB [ \-\-rc |
| .IR keyword = value ] |
| .br |
| .RE |
| |
| .B lcov |
| .BR \-e | \-\-extract |
| .I tracefile pattern |
| .RS 5 |
| .br |
| .RB [ \-o | \-\-output\-file |
| .IR tracefile ] |
| .RB [ \-\-checksum ] |
| .RB [ \-\-no\-checksum ] |
| .br |
| .RB [ \-q | \-\-quiet ] |
| .RB [ \-\-config\-file |
| .IR config\-file ] |
| .RB [ \-\-rc |
| .IR keyword = value ] |
| .br |
| .RE |
| |
| .B lcov |
| .BR \-r | \-\-remove |
| .I tracefile pattern |
| .RS 5 |
| .br |
| .RB [ \-o | \-\-output\-file |
| .IR tracefile ] |
| .RB [ \-\-checksum ] |
| .RB [ \-\-no\-checksum ] |
| .br |
| .RB [ \-q | \-\-quiet ] |
| .RB [ \-\-config\-file |
| .IR config\-file ] |
| .RB [ \-\-rc |
| .IR keyword = value ] |
| .br |
| .RE |
| |
| .B lcov |
| .BR \-\-diff |
| .IR "tracefile diff" |
| .RS 5 |
| .br |
| .RB [ \-o | \-\-output\-file |
| .IR tracefile ] |
| .RB [ \-\-checksum ] |
| .RB [ \-\-no\-checksum ] |
| .br |
| .RB [ \-\-convert\-filenames ] |
| .RB [ \-\-strip |
| .IR depth ] |
| .RB [ \-\-path |
| .IR path ] |
| .RB [ \-q | \-\-quiet ] |
| .br |
| .RB [ \-\-config\-file |
| .IR config\-file ] |
| .RB [ \-\-rc |
| .IR keyword = value ] |
| .br |
| .RE |
| |
| .B lcov |
| .BR \-\-summary |
| .I tracefile |
| .RS 5 |
| .br |
| .RB [ \-q | \-\-quiet ] |
| .br |
| .RE |
| |
| .B lcov |
| .RB [ \-h | \-\-help ] |
| .RB [ \-v | \-\-version ] |
| .RS 5 |
| .br |
| .RE |
| |
| .SH DESCRIPTION |
| .B lcov |
| is a graphical front\-end for GCC's coverage testing tool gcov. It collects |
| line, function and branch coverage 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 setup instructions for the gcov\-kernel infrastructure: |
| .I http://ltp.sourceforge.net/coverage/gcov.php |
| .br |
| |
| |
| .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". |
| |
| Also note that when printing percentages, 0% and 100% are only printed when |
| the values are exactly 0% and 100% respectively. Other values which would |
| conventionally be rounded to 0% or 100% are instead printed as nearest |
| non-boundary value. This behavior is in accordance with that of the |
| .BR gcov (1) |
| tool. |
| |
| .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, \-\-diff or \-\-summary 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 use configuration file setting |
| .B geninfo_auto_base=1 |
| (see |
| .BR lcovrc (5)). |
| .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, \-\-diff or \-\-summary 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 |
| .IR mode = value [, mode = value ,...] |
| .br |
| .RS |
| Set compatibility mode. |
| |
| Use \-\-compat to specify that lcov should enable one or more compatibility |
| modes when capturing coverage data. You can provide a comma-separated list |
| of mode=value pairs to specify the values for multiple modes. |
| |
| Valid |
| .I values |
| are: |
| |
| .B on |
| .RS |
| Enable compatibility mode. |
| .RE |
| .B off |
| .RS |
| Disable compatibility mode. |
| .RE |
| .B auto |
| .RS |
| Apply auto-detection to determine if compatibility mode is required. Note that |
| auto-detection is not available for all compatibility modes. |
| .RE |
| |
| If no value is specified, 'on' is assumed as default value. |
| |
| Valid |
| .I modes |
| are: |
| |
| .B libtool |
| .RS |
| Enable this mode if you are capturing coverage data for a project that |
| was built using the libtool mechanism. See also |
| \-\-compat\-libtool. |
| |
| The default value for this setting is 'on'. |
| |
| .RE |
| .B hammer |
| .RS |
| Enable this mode if you are capturing coverage data for a project that |
| was built using a version of GCC 3.3 that contains a modification |
| (hammer patch) of later GCC versions. You can identify a modified GCC 3.3 |
| by checking the build directory of your project for files ending in the |
| extension '.bbg'. Unmodified versions of GCC 3.3 name these files '.bb'. |
| |
| The default value for this setting is 'auto'. |
| |
| .RE |
| .B split_crc |
| .RS |
| Enable this mode if you are capturing coverage data for a project that |
| was built using a version of GCC 4.6 that contains a modification |
| (split function checksums) of later GCC versions. Typical error messages |
| when running lcov on coverage data produced by such GCC versions are |
| \'out of memory' and 'reached unexpected end of file'. |
| |
| The default value for this setting is 'auto' |
| .RE |
| |
| .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 \-\-config\-file |
| .I config\-file |
| .br |
| .RS |
| Specify a configuration file to use. |
| |
| When this option is specified, neither the system\-wide configuration file |
| /etc/lcovrc, nor the per\-user configuration file ~/.lcovrc is read. |
| |
| This option may be useful when there is a need to run several |
| instances of |
| .B lcov |
| with different configuration file options in parallel. |
| .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, \-\-diff or \-\-summary 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 \-\-external |
| .br |
| .B \-\-no\-external |
| .br |
| .RS |
| Specify whether to capture coverage data for external source files. |
| |
| External source files are files which are not located in one of the directories |
| specified by \-\-directory or \-\-base\-directory. Use \-\-external to include |
| external source files while capturing coverage data or \-\-no\-external to |
| ignore this data. |
| |
| Data for external source files is |
| .B included |
| by default. |
| .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, \-\-diff or \-\-summary may be |
| specified at a time. |
| .RE |
| |
| .B \-f |
| .br |
| .B \-\-follow |
| .br |
| .RS |
| Follow links when searching for .da files. |
| .RE |
| |
| .B \-\-from\-package |
| .I package |
| .br |
| .RS |
| Use .da files in |
| .I package |
| instead of kernel or directory. |
| |
| Use this option if you have separate machines for build and test and |
| want to perform the .info file creation on the build machine. See |
| \-\-to\-package for more information. |
| .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. This option may be specified |
| more than once. |
| |
| Note that you may need to specify the full path to the kernel subdirectory |
| depending on the version of the kernel gcov support. |
| .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, \-\-diff or \-\-summary may be |
| specified at a time. |
| .RE |
| |
| .B \-\-list\-full\-path |
| .br |
| .B \-\-no\-list\-full\-path |
| .br |
| .RS |
| Specify whether to show full paths during list operation. |
| |
| Use \-\-list\-full\-path to show full paths during list operation |
| or \-\-no\-list\-full\-path to show shortened paths. Paths are |
| .B shortened |
| by default. |
| .RE |
| |
| .B \-\-no\-markers |
| .br |
| .RS |
| Use this option if you want to get coverage data without regard to exclusion |
| markers in the source code file. See |
| .BR "geninfo " (1) |
| for details on exclusion markers. |
| .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 \-\-rc |
| .IR keyword = value |
| .br |
| .RS |
| Override a configuration directive. |
| |
| Use this option to specify a |
| .IR keyword = value |
| statement which overrides the corresponding configuration statement in |
| the lcovrc configuration file. You can specify this option more than once |
| to override multiple configuration statements. |
| See |
| .BR lcovrc (5) |
| for a list of available keywords and their meaning. |
| .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, \-\-diff or \-\-summary 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 \-\-summary |
| .I tracefile |
| .br |
| .RS |
| Show summary coverage information for the specified tracefile. |
| |
| Note that you may specify this option more than once. |
| |
| Only one of \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be |
| specified at a time. |
| .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 \-\-to\-package |
| .I package |
| .br |
| .RS |
| Store .da files for later processing. |
| |
| Use this option if you have separate machines for build and test and |
| want to perform the .info file creation on the build machine. To do this, |
| follow these steps: |
| |
| On the test machine: |
| .RS |
| .br |
| \- run the test |
| .br |
| \- run lcov \-c [\-d directory] \-\-to-package |
| .I file |
| .br |
| \- copy |
| .I file |
| to the build machine |
| .RE |
| .br |
| |
| On the build machine: |
| .RS |
| .br |
| \- run lcov \-c \-\-from-package |
| .I file |
| [\-o and other options] |
| .RE |
| .br |
| |
| This works for both kernel and user space coverage data. Note that you might |
| have to specify the path to the build directory using \-b with |
| either \-\-to\-package or \-\-from-package. Note also that the package data |
| must be converted to a .info file before recompiling the program or it will |
| become invalid. |
| .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, \-\-diff or \-\-summary 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) |