1geninfo(1) User Manuals geninfo(1)
2
3
4
6 geninfo - Generate tracefiles from .da files
7
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
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
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
247 errors 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
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
396 information on this file type). Relative filenames are prefixed with
397 the 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
401 approach is necessary for the mechanism to work with the /proc/gcov
402 files.
403
404
406 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
407
408
410 lcov(1), lcovrc(5), genhtml(1), genpng(1), gendesc(1), gcov(1)
411
412
413
4142019-07-25 LCOV 1.14 geninfo(1)