1geninfo(1)                       User Manuals                       geninfo(1)
2
3
4

NAME

6       geninfo - Generate tracefiles from .da files
7

SYNOPSIS

9       geninfo [-h|--help] [-v|--version] [-q|--quiet]
10               [-i|--initial] [-t|--test-name test-name]
11               [-o|--output-filename filename] [-f|--follow]
12               [-b|--base-directory directory]
13               [--checksum] [--no-checksum]
14               [--compat-libtool] [--no-compat-libtool]
15               [--gcov-tool tool] [--ignore-errors errors]
16               directory
17

DESCRIPTION

19       geninfo  converts  all GCOV coverage data files found in directory into
20       tracefiles, which the genhtml tool can convert to HTML output.
21
22       Unless the --output-filename option is specified,  geninfo  writes  its
23       output to one file per .da file, the name of which is generated by sim‐
24       ply appending ".info" to the respective .da file name.
25
26       Note that the current user needs write access to both directory as well
27       as to the original source code location. This is necessary because some
28       temporary files have to be created there during the conversion process.
29
30       Note also that geninfo is called from within lcov,  so  that  there  is
31       usually no need to call it directly.
32

OPTIONS

34       -b directory
35       --base-directory directory
36              Use directory as base directory for relative paths.
37
38              Use  this  option to specify the base directory of a build-envi‐
39              ronment when geninfo produces error messages like:
40
41                     ERROR: could not read source file /home/user/project/sub‐
42                     dir1/subdir2/subdir1/subdir2/file.c
43
44              In this example, use /home/user/project as base directory.
45
46              This  option  is  required  when using geninfo on projects built
47              with libtool or similar build environments that work with a base
48              directory,  i.e.  environments, where the current working direc‐
49              tory when invoking the compiler is not  the  same  directory  in
50              which the source code file is located.
51
52              Note that this option will not work in environments where multi‐
53              ple base directories are used. In that case repeat  the  geninfo
54              call  for  each  base  directory while using the --ignore-errors
55              option to prevent geninfo from exiting  when  the  first  source
56              code  file could not be found. This way you can get partial cov‐
57              erage information for each base directory which can then be com‐
58              bined using the -a option.
59
60       --checksum
61       --no-checksum
62              Specify  whether  to  generate checksum data when writing trace‐
63              files.
64
65              Use --checksum to enable checksum generation or --no-checksum to
66              disable it. Checksum generation is disabled by default.
67
68              When  checksum  generation is enabled, a checksum will be gener‐
69              ated for each source code line and stored along with the  cover‐
70              age data. This checksum will be used to prevent attempts to com‐
71              bine coverage data from different source code versions.
72
73              If you don't work with different source code  versions,  disable
74              this  option  to speed up coverage data processing and to reduce
75              the size of tracefiles.
76
77       --compat-libtool
78       --no-compat-libtool
79              Specify whether to enable libtool compatibility mode.
80
81              Use --compat-libtool to enable  libtool  compatibility  mode  or
82              --no-compat-libtool  to  disable  it.  The libtool compatibility
83              mode is enabled by default.
84
85              When libtool compatibility mode is enabled, geninfo will  assume
86              that  the source code relating to a .da file located in a direc‐
87              tory named ".libs" can be found in its parent directory.
88
89              If you have directories named ".libs" in your build  environment
90              but  don't  use libtool, disable this option to prevent problems
91              when capturing coverage data.
92
93       -f
94       --follow
95              Follow links when searching .da files.
96
97       --gcov-tool tool
98              Specify the location of the gcov tool.
99
100       -h
101       --help
102              Print a short help text, then exit.
103
104       --ignore-errors errors
105              Specify a list of errors after which to continue processing.
106
107              Use this option to specify a list of  one  or  more  classes  of
108              errors after which geninfo should continue processing instead of
109              aborting.
110
111              errors can be a comma-separated list of the following keywords:
112
113              gcov: the gcov tool returned with a non-zero return code.
114
115              source: the source code file for a data set could not be found.
116
117       -i
118       --initial
119              Capture initial zero coverage data.
120
121              Run geninfo with this option on the directories containing  .bb,
122              .bbg  or .gcno files before running any test case. The result is
123              a "baseline" coverage data file that contains zero coverage  for
124              every  instrumented line. Combine this data file (using lcov -a)
125              with coverage data files captured after a  test  run  to  ensure
126              that  the percentage of total lines covered is correct even when
127              not all source code files were loaded during the test.
128
129       -o output-filename
130       --output-filename output-filename
131              Write all data to output-filename.
132
133              If you want to have all data written to a single file (for  eas‐
134              ier  handling),  use this option to specify the respective file‐
135              name. By default, one tracefile will be created  for  each  pro‐
136              cessed .da file.
137
138       -q
139       --quiet
140              Do not print progress messages.
141
142              Suppresses  all  informational progress output. When this switch
143              is enabled, only error or warning messages are printed.
144
145       -t testname
146       --test-name testname
147              Use test case name testname for resulting data. Valid test  case
148              names  can consist of letters, decimal digits and the underscore
149              character ('_').
150
151              This proves useful when data from several test cases  is  merged
152              (i.e.  by  simply  concatenating  the  respective tracefiles) in
153              which case a test name can be used to differentiate between data
154              from each test case.
155
156       -v
157       --version
158              Print version number, then exit.
159
160
161

FILES

163       /etc/lcovrc
164              The system-wide configuration file.
165
166       ~/.lcovrc
167              The per-user configuration file.
168
169       Following  is  a  quick  description of the tracefile format as used by
170       genhtml, geninfo and lcov.
171
172       A tracefile is made up of several human-readable lines of text, divided
173       into sections. If available, a tracefile begins with the testname which
174       is stored in the following format:
175
176         TN:<test name>
177
178       For each source file referenced in the .da file,  there  is  a  section
179       containing filename and coverage data:
180
181         SF:<absolute path to the source file>
182
183       Following is a list of line numbers for each function name found in the
184       source file:
185
186         FN:<line number of function start>,<function name>
187
188       Then there is a list of execution counts  for  each  instrumented  line
189       (i.e. a line which resulted in executable code):
190
191         DA:<line number>,<execution count>[,<checksum>]
192
193       Note  that  there  may be an optional checksum present for each instru‐
194       mented line. The current geninfo implementation uses  an  MD5  hash  as
195       checksumming algorithm.
196
197       At  the  end of a section, there is a summary about how many lines were
198       found and how many were actually instrumented:
199
200         LH:<number of lines with a non-zero execution count>
201         LF:<number of instrumented lines>
202
203       Each sections ends with:
204
205         end_of_record
206
207       In addition to the main source code file there  are  sections  for  all
208       #included files which also contain executable code.
209
210       Note that the absolute path of a source file is generated by interpret‐
211       ing the contents of the respective .bb file  (see  gcov  (1)  for  more
212       information  on  this  file type). Relative filenames are prefixed with
213       the directory in which the .bb file is found.
214
215       Note also that symbolic links to the .bb file will be resolved so  that
216       the  actual  file  path  is  used  instead  of the path to a link. This
217       approach is necessary for the mechanism to  work  with  the  /proc/gcov
218       files.
219
220

AUTHOR

222       Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
223
224

SEE ALSO

226       lcov(1), genhtml(1), genpng(1), gendesc(1), gcov(1)
227
228
229
2302003-12-19                         lcov 1.6                         geninfo(1)
Impressum