| .TH geninfo 1 "LCOV 1.7" 2008\-11\-17 "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 |
| .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. |
| .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 repeat the geninfo call for each base |
| directory while using the \-\-ignore\-errors option to prevent geninfo 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 \-\-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, 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 \-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. 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. |
| .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 |
| |
| .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> |
| |
| 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 genhtml (1), |
| .BR genpng (1), |
| .BR gendesc (1), |
| .BR gcov (1) |