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               [--no-recursion] directory [--external] [--no-external]
17               [--config-file config-file] [--no-markers]
18               [--derive-func-data] [--compat mode=on|off|auto]
19               [--rc keyword=value]
20               [--include pattern] [--exclude pattern]
21

DESCRIPTION

23       geninfo  converts  all GCOV coverage data files found in directory into
24       tracefiles, which the genhtml tool can convert to HTML output.
25
26       Unless the --output-filename option is specified,  geninfo  writes  its
27       output to one file per .da file, the name of which is generated by sim‐
28       ply appending ".info" to the respective .da file name.
29
30       Note that the current user needs write access to both directory as well
31       as to the original source code location. This is necessary because some
32       temporary files have to be created there during the conversion process.
33
34       Note also that geninfo is called from within lcov,  so  that  there  is
35       usually no need to call it directly.
36
37       Exclusion markers
38
39       To  exclude specific lines of code from a tracefile, you can add exclu‐
40       sion markers to the source code. Additionally you can exclude  specific
41       branches from branch coverage without excluding the involved lines from
42       line and function coverage. Exclusion markers are  keywords  which  can
43       for  example  be  added in the form of a comment.  See lcovrc(5) how to
44       override some of them.
45
46       The following markers are recognized by geninfo:
47
48       LCOV_EXCL_LINE
49              Lines containing this marker will be excluded.
50       LCOV_EXCL_START
51              Marks the beginning of an excluded section. The current line  is
52              part of this section.
53       LCOV_EXCL_STOP
54              Marks  the end of an excluded section. The current line not part
55              of this section.
56       LCOV_EXCL_BR_LINE
57              Lines containing this marker will be excluded from branch cover‐
58              age.
59       LCOV_EXCL_BR_START
60              Marks  the  beginning of a section which is excluded from branch
61              coverage. The current line is part of this section.
62       LCOV_EXCL_BR_STOP
63              Marks the end of a section which is excluded from branch  cover‐
64              age. The current line not part of this section.
65
66

OPTIONS

68       -b directory
69       --base-directory directory
70              Use directory as base directory for relative paths.
71
72              Use  this  option to specify the base directory of a build-envi‐
73              ronment when geninfo produces error messages like:
74
75                     ERROR: could not read source file /home/user/project/sub‐
76                     dir1/subdir2/subdir1/subdir2/file.c
77
78              In this example, use /home/user/project as base directory.
79
80              This  option  is  required  when using geninfo on projects built
81              with libtool or similar build environments that work with a base
82              directory,  i.e.  environments, where the current working direc‐
83              tory when invoking the compiler is not  the  same  directory  in
84              which the source code file is located.
85
86              Note that this option will not work in environments where multi‐
87              ple base directories are used. In that  case  use  configuration
88              file setting geninfo_auto_base=1 (see lcovrc(5)).
89
90       --checksum
91       --no-checksum
92              Specify  whether  to  generate checksum data when writing trace‐
93              files.
94
95              Use --checksum to enable checksum generation or --no-checksum to
96              disable it. Checksum generation is disabled by default.
97
98              When  checksum  generation is enabled, a checksum will be gener‐
99              ated for each source code line and stored along with the  cover‐
100              age data. This checksum will be used to prevent attempts to com‐
101              bine coverage data from different source code versions.
102
103              If you don't work with different source code  versions,  disable
104              this  option  to speed up coverage data processing and to reduce
105              the size of tracefiles.
106
107       --compat mode=value[,mode=value,...]
108              Set compatibility mode.
109
110              Use --compat to specify that geninfo should enable one  or  more
111              compatibility  modes  when capturing coverage data. You can pro‐
112              vide a comma-separated list of mode=value pairs to  specify  the
113              values for multiple modes.
114
115              Valid values are:
116
117              on
118                     Enable compatibility mode.
119              off
120                     Disable compatibility mode.
121              auto
122                     Apply  auto-detection  to determine if compatibility mode
123                     is required. Note that auto-detection  is  not  available
124                     for all compatibility modes.
125
126              If no value is specified, 'on' is assumed as default value.
127
128              Valid modes are:
129
130              libtool
131                     Enable this mode if you are capturing coverage data for a
132                     project that was built using the libtool  mechanism.  See
133                     also --compat-libtool.
134
135                     The default value for this setting is 'on'.
136
137              hammer
138                     Enable this mode if you are capturing coverage data for a
139                     project that was built using a version of  GCC  3.3  that
140                     contains  a modification (hammer patch) of later GCC ver‐
141                     sions. You can identify a modified GCC  3.3  by  checking
142                     the  build  directory of your project for files ending in
143                     the extension '.bbg'. Unmodified versions of GCC 3.3 name
144                     these files '.bb'.
145
146                     The default value for this setting is 'auto'.
147
148              split_crc
149                     Enable this mode if you are capturing coverage data for a
150                     project that was built using a version of  GCC  4.6  that
151                     contains  a  modification  (split  function checksums) of
152                     later GCC versions. Typical error messages  when  running
153                     geninfo  on  coverage  data produced by such GCC versions
154                     are ´out of memory' and 'reached unexpected end of file'.
155
156                     The default value for this setting is 'auto'
157
158
159       --compat-libtool
160       --no-compat-libtool
161              Specify whether to enable libtool compatibility mode.
162
163              Use --compat-libtool to enable  libtool  compatibility  mode  or
164              --no-compat-libtool  to  disable  it.  The libtool compatibility
165              mode is enabled by default.
166
167              When libtool compatibility mode is enabled, geninfo will  assume
168              that  the source code relating to a .da file located in a direc‐
169              tory named ".libs" can be found in its parent directory.
170
171              If you have directories named ".libs" in your build  environment
172              but  don't  use libtool, disable this option to prevent problems
173              when capturing coverage data.
174
175       --config-file config-file
176              Specify a configuration file to use.
177
178              When this option is specified, neither the system-wide  configu‐
179              ration  file  /etc/lcovrc,  nor  the per-user configuration file
180              ~/.lcovrc is read.
181
182              This option may be useful when there is a need  to  run  several
183              instances  of  geninfo with different configuration file options
184              in parallel.
185
186       --derive-func-data
187              Calculate function coverage data from line coverage data.
188
189              Use this option to collect function coverage data, even  if  the
190              version  of  the gcov tool installed on the test system does not
191              provide this data. lcov will instead  derive  function  coverage
192              data  from  line coverage data and information about which lines
193              belong to a function.
194
195       --exclude pattern
196              Exclude source files matching pattern.
197
198              Use this switch if you want to exclude coverage data for a  par‐
199              ticular  set of source files matching any of the given patterns.
200              Multiple patterns can be specified by using  multiple  --exclude
201              command line switches. The patterns will be interpreted as shell
202              wildcard patterns (note that they may need to be escaped accord‐
203              ingly to prevent the shell from expanding them first).
204
205              Can  be  combined  with  the --include command line switch. If a
206              given file matches both the include pattern and the exclude pat‐
207              tern, the exclude pattern will take precedence.
208
209       --external
210       --no-external
211              Specify  whether  to  capture  coverage data for external source
212              files.
213
214              External source files are files which are not located in one  of
215              the  directories  specified  by --directory or --base-directory.
216              Use --external to include external source files while  capturing
217              coverage data or --no-external to ignore this data.
218
219              Data for external source files is included by default.
220
221       -f
222       --follow
223              Follow links when searching .da files.
224
225       --gcov-tool tool
226              Specify the location of the gcov tool.
227
228       -h
229       --help
230              Print a short help text, then exit.
231
232       --include pattern
233              Include source files matching pattern.
234
235              Use  this switch if you want to include coverage data for only a
236              particular set of source files matching any of  the  given  pat‐
237              terns.  Multiple  patterns  can  be  specified by using multiple
238              --include command line switches. The  patterns  will  be  inter‐
239              preted as shell wildcard patterns (note that they may need to be
240              escaped accordingly to prevent the  shell  from  expanding  them
241              first).
242
243       --ignore-errors errors
244              Specify a list of errors after which to continue processing.
245
246              Use  this option to specify a list of one or more classes of er‐
247              rors after which geninfo should continue processing  instead  of
248              aborting.
249
250              errors can be a comma-separated list of the following keywords:
251
252              gcov: the gcov tool returned with a non-zero return code.
253
254              source: the source code file for a data set could not be found.
255
256       -i
257       --initial
258              Capture initial zero coverage data.
259
260              Run  geninfo with this option on the directories containing .bb,
261              .bbg or .gcno files before running any test case. The result  is
262              a  "baseline" coverage data file that contains zero coverage for
263              every instrumented line and function.  Combine  this  data  file
264              (using  lcov  -a) with coverage data files captured after a test
265              run to ensure that the percentage of total lines covered is cor‐
266              rect  even when not all object code files were loaded during the
267              test.
268
269              Note: currently, the --initial option does not  generate  branch
270              coverage information.
271
272       --no-markers
273              Use  this option if you want to get coverage data without regard
274              to exclusion markers in the source code file.
275
276       --no-recursion
277              Use this option if you want to get coverage data for the  speci‐
278              fied directory only without processing subdirectories.
279
280       -o output-filename
281       --output-filename output-filename
282              Write all data to output-filename.
283
284              If  you want to have all data written to a single file (for eas‐
285              ier handling), use this option to specify the  respective  file‐
286              name.  By  default,  one tracefile will be created for each pro‐
287              cessed .da file.
288
289       -q
290       --quiet
291              Do not print progress messages.
292
293              Suppresses all informational progress output. When  this  switch
294              is enabled, only error or warning messages are printed.
295
296       --rc keyword=value
297              Override a configuration directive.
298
299              Use this option to specify a keyword=value statement which over‐
300              rides the corresponding configuration statement  in  the  lcovrc
301              configuration  file.  You can specify this option more than once
302              to override multiple configuration  statements.   See  lcovrc(5)
303              for a list of available keywords and their meaning.
304
305       -t testname
306       --test-name testname
307              Use  test case name testname for resulting data. Valid test case
308              names can consist of letters, decimal digits and the  underscore
309              character ('_').
310
311              This  proves  useful when data from several test cases is merged
312              (i.e. by simply  concatenating  the  respective  tracefiles)  in
313              which case a test name can be used to differentiate between data
314              from each test case.
315
316       -v
317       --version
318              Print version number, then exit.
319
320
321

FILES

323       /etc/lcovrc
324              The system-wide configuration file.
325
326       ~/.lcovrc
327              The per-user configuration file.
328
329       Following is a quick description of the tracefile  format  as  used  by
330       genhtml, geninfo and lcov.
331
332       A tracefile is made up of several human-readable lines of text, divided
333       into sections. If available, a tracefile begins with the testname which
334       is stored in the following format:
335
336         TN:<test name>
337
338       For  each  source  file  referenced in the .da file, there is a section
339       containing filename and coverage data:
340
341         SF:<absolute path to the source file>
342
343       Following is a list of line numbers for each function name found in the
344       source file:
345
346         FN:<line number of function start>,<function name>
347
348       Next,  there  is a list of execution counts for each instrumented func‐
349       tion:
350
351         FNDA:<execution count>,<function name>
352
353       This list is followed by two lines containing the number  of  functions
354       found and hit:
355
356         FNF:<number of functions found>
357         FNH:<number of function hit>
358
359       Branch coverage information is stored which one line per branch:
360
361         BRDA:<line number>,<block number>,<branch number>,<taken>
362
363       Block  number  and  branch  number are gcc internal IDs for the branch.
364       Taken is either '-' if the basic block containing the branch was  never
365       executed or a number indicating how often that branch was taken.
366
367       Branch coverage summaries are stored in two lines:
368
369         BRF:<number of branches found>
370         BRH:<number of branches hit>
371
372       Then  there  is  a  list of execution counts for each instrumented line
373       (i.e. a line which resulted in executable code):
374
375         DA:<line number>,<execution count>[,<checksum>]
376
377       Note that there may be an optional checksum present  for  each  instru‐
378       mented  line.  The  current  geninfo implementation uses an MD5 hash as
379       checksumming algorithm.
380
381       At the end of a section, there is a summary about how many  lines  were
382       found and how many were actually instrumented:
383
384         LH:<number of lines with a non-zero execution count>
385         LF:<number of instrumented lines>
386
387       Each sections ends with:
388
389         end_of_record
390
391       In  addition  to  the  main source code file there are sections for all
392       #included files which also contain executable code.
393
394       Note that the absolute path of a source file is generated by interpret‐
395       ing  the contents of the respective .bb file (see gcov (1) for more in‐
396       formation on this file type). Relative filenames are prefixed with  the
397       directory in which the .bb file is found.
398
399       Note  also that symbolic links to the .bb file will be resolved so that
400       the actual file path is used instead of the path to a  link.  This  ap‐
401       proach  is  necessary  for  the  mechanism  to work with the /proc/gcov
402       files.
403
404

AUTHOR

406       Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
407
408

SEE ALSO

410       lcov(1), lcovrc(5), genhtml(1), genpng(1), gendesc(1), gcov(1)
411
412
413
4142021-07-22                         LCOV 1.14                        geninfo(1)
Impressum