| .TH geninfo 1 "LCOV 1.10" 2012\-10\-10 "User Manuals" |
| .SH NAME |
| geninfo \- Generate tracefiles from .da files |
| .SH SYNOPSIS |
| .B geninfo |
| .RB [ \-h | \-\-help ] |
| .RB [ \-v | \-\-version ] |
| .RB [ \-q | \-\-quiet ] |
| .br |
| .RS 8 |
| .RB [ \-i | \-\-initial ] |
| .RB [ \-t | \-\-test\-name |
| .IR test\-name ] |
| .br |
| .RB [ \-o | \-\-output\-filename |
| .IR filename ] |
| .RB [ \-f | \-\-follow ] |
| .br |
| .RB [ \-b | \-\-base\-directory |
| .IR directory ] |
| .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 ] |
| .I directory |
| .RB [ \-\-external ] |
| .RB [ \-\-no\-external ] |
| .br |
| .RB [ \-\-config\-file |
| .IR config\-file ] |
| .RB [ \-\-no\-markers ] |
| .br |
| .RB [ \-\-derive\-func\-data ] |
| .RB [ \-\-compat |
| .IR mode =on|off|auto] |
| .br |
| .RB [ \-\-rc |
| .IR keyword = value ] |
| .RE |
| .SH DESCRIPTION |
| .B geninfo |
| converts all GCOV coverage data files found in |
| .I directory |
| into tracefiles, which the |
| .B genhtml |
| tool can convert to HTML output. |
| |
| Unless the \-\-output\-filename option is specified, |
| .B geninfo |
| writes its |
| output to one file per .da file, the name of which is generated by simply |
| appending ".info" to the respective .da file name. |
| |
| Note that the current user needs write access to both |
| .I directory |
| as well as to the original source code location. This is necessary because |
| some temporary files have to be created there during the conversion process. |
| |
| Note also that |
| .B geninfo |
| is called from within |
| .BR lcov , |
| so that there is usually no need to call it directly. |
| |
| .B Exclusion markers |
| |
| To exclude specific lines of code from a tracefile, you can add exclusion |
| markers to the source code. Exclusion markers are keywords which can for |
| example be added in the form of a comment. |
| |
| The following markers are recognized by geninfo: |
| |
| LCOV_EXCL_LINE |
| .RS |
| Lines containing this marker will be excluded. |
| .br |
| .RE |
| LCOV_EXCL_START |
| .RS |
| Marks the beginning of an excluded section. The current line is part of this |
| section. |
| .br |
| .RE |
| LCOV_EXCL_STOP |
| .RS |
| Marks the end of an excluded section. The current line not part of this |
| section. |
| .RE |
| .br |
| |
| .SH OPTIONS |
| |
| .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 geninfo 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 geninfo 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 \-\-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 geninfo 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 geninfo 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, geninfo 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 geninfo |
| with different configuration file options in parallel. |
| .RE |
| |
| .B \-\-derive\-func\-data |
| .br |
| .RS |
| Calculate function coverage data from line coverage data. |
| |
| Use this option to collect function coverage data, even if the version of the |
| gcov tool installed on the test system does not provide this data. lcov will |
| instead derive function coverage data from line coverage data and |
| information about which lines belong to a function. |
| .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 \-f |
| .br |
| .B \-\-follow |
| .RS |
| Follow links when searching .da files. |
| .RE |
| |
| .B \-\-gcov\-tool |
| .I tool |
| .br |
| .RS |
| Specify the location of the gcov tool. |
| .RE |
| |
| .B \-h |
| .br |
| .B \-\-help |
| .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 |
| geninfo 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 geninfo with 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 and function. |
| 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 object code files were loaded during the test. |
| |
| Note: currently, the \-\-initial option does not generate branch coverage |
| information. |
| .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. |
| .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 |
| |
| .BI "\-o " output\-filename |
| .br |
| .BI "\-\-output\-filename " output\-filename |
| .RS |
| Write all data to |
| .IR output\-filename . |
| |
| If you want to have all data written to a single file (for easier |
| handling), use this option to specify the respective filename. By default, |
| one tracefile will be created for each processed .da file. |
| .RE |
| |
| .B \-q |
| .br |
| .B \-\-quiet |
| .RS |
| Do not print progress messages. |
| |
| Suppresses all informational progress output. When this switch is enabled, |
| only error or warning messages are printed. |
| .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 |
| |
| .BI "\-t " testname |
| .br |
| .BI "\-\-test\-name " testname |
| .RS |
| Use test case name |
| .I testname |
| for resulting data. Valid test case names can consist of letters, decimal |
| digits and the underscore character ('_'). |
| |
| This proves useful when data from several test cases is merged (i.e. by |
| simply concatenating the respective tracefiles) in which case a test |
| name can be used to differentiate between data from each test case. |
| .RE |
| |
| .B \-v |
| .br |
| .B \-\-version |
| .RS |
| Print version number, then exit. |
| .RE |
| |
| |
| .SH FILES |
| |
| .I /etc/lcovrc |
| .RS |
| The system\-wide configuration file. |
| .RE |
| |
| .I ~/.lcovrc |
| .RS |
| The per\-user configuration file. |
| .RE |
| |
| Following is a quick description of the tracefile format as used by |
| .BR genhtml ", " geninfo " and " lcov . |
| |
| A tracefile is made up of several human\-readable lines of text, |
| divided into sections. If available, a tracefile begins with the |
| .I testname |
| which is stored in the following format: |
| |
| TN:<test name> |
| |
| For each source file referenced in the .da file, there is a section containing |
| filename and coverage data: |
| |
| SF:<absolute path to the source file> |
| |
| Following is a list of line numbers for each function name found in the |
| source file: |
| |
| FN:<line number of function start>,<function name> |
| |
| Next, there is a list of execution counts for each instrumented function: |
| |
| FNDA:<execution count>,<function name> |
| |
| This list is followed by two lines containing the number of functions found |
| and hit: |
| |
| FNF:<number of functions found> |
| FNH:<number of function hit> |
| |
| Branch coverage information is stored which one line per branch: |
| |
| BRDA:<line number>,<block number>,<branch number>,<taken> |
| |
| Block number and branch number are gcc internal IDs for the branch. Taken is |
| either '-' if the basic block containing the branch was never executed or |
| a number indicating how often that branch was taken. |
| |
| Branch coverage summaries are stored in two lines: |
| |
| BRF:<number of branches found> |
| BRH:<number of branches hit> |
| |
| Then there is a list of execution counts for each instrumented line |
| (i.e. a line which resulted in executable code): |
| |
| DA:<line number>,<execution count>[,<checksum>] |
| |
| Note that there may be an optional checksum present for each instrumented |
| line. The current |
| .B geninfo |
| implementation uses an MD5 hash as checksumming algorithm. |
| |
| At the end of a section, there is a summary about how many lines |
| were found and how many were actually instrumented: |
| |
| LH:<number of lines with a non\-zero execution count> |
| LF:<number of instrumented lines> |
| |
| Each sections ends with: |
| |
| end_of_record |
| |
| In addition to the main source code file there are sections for all |
| #included files which also contain executable code. |
| |
| Note that the absolute path of a source file is generated by interpreting |
| the contents of the respective .bb file (see |
| .BR "gcov " (1) |
| for more information on this file type). Relative filenames are prefixed |
| with the directory in which the .bb file is found. |
| |
| Note also that symbolic links to the .bb file will be resolved so that the |
| actual file path is used instead of the path to a link. This approach is |
| necessary for the mechanism to work with the /proc/gcov files. |
| |
| .SH AUTHOR |
| Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> |
| |
| .SH SEE ALSO |
| .BR lcov (1), |
| .BR lcovrc (5), |
| .BR genhtml (1), |
| .BR genpng (1), |
| .BR gendesc (1), |
| .BR gcov (1) |