1geninfo(1) User Manuals geninfo(1)
2
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 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 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 Note also that geninfo is called from within lcov, so that there is
35 usually no need to call it directly.
36 Exclusion markers
38 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 The following markers are recognized by geninfo:
47 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
68 -b directory
69 --base-directory directory
70 Use directory as base directory for relative paths.
71 Use this option to specify the base directory of a build-envi‐
73 ronment when geninfo produces error messages like:
74 ERROR: could not read source file /home/user/project/sub‐
76 dir1/subdir2/subdir1/subdir2/file.c
77 In this example, use /home/user/project as base directory.
79 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 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 --checksum
91 --no-checksum
92 Specify whether to generate checksum data when writing trace‐
93 files.
94 Use --checksum to enable checksum generation or --no-checksum to
96 disable it. Checksum generation is disabled by default.
97 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 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 --compat mode=value[,mode=value,...]
108 Set compatibility mode.
109 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 Valid values are:
116 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 If no value is specified, 'on' is assumed as default value.
127 Valid modes are:
129 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 The default value for this setting is 'on'.
136 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 The default value for this setting is 'auto'.
147 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 The default value for this setting is 'auto'
157 --compat-libtool
160 --no-compat-libtool
161 Specify whether to enable libtool compatibility mode.
162 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 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 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 --config-file config-file
176 Specify a configuration file to use.
177 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 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 --derive-func-data
187 Calculate function coverage data from line coverage data.
188 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 --exclude pattern
196 Exclude source files matching pattern.
197 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 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 --external
210 --no-external
211 Specify whether to capture coverage data for external source
212 files.
213 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 Data for external source files is included by default.
220 -f
222 --follow
223 Follow links when searching .da files.
224 --gcov-tool tool
226 Specify the location of the gcov tool.
227 -h
229 --help
230 Print a short help text, then exit.
231 --include pattern
233 Include source files matching pattern.
234 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 --ignore-errors errors
244 Specify a list of errors after which to continue processing.
245 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 errors can be a comma-separated list of the following keywords:
251 gcov: the gcov tool returned with a non-zero return code.
253 source: the source code file for a data set could not be found.
255 -i
257 --initial
258 Capture initial zero coverage data.
259 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 Note: currently, the --initial option does not generate branch
270 coverage information.
271 --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 --no-recursion
277 Use this option if you want to get coverage data for the speci‐
278 fied directory only without processing subdirectories.
279 -o output-filename
281 --output-filename output-filename
282 Write all data to output-filename.
283 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 -q
290 --quiet
291 Do not print progress messages.
292 Suppresses all informational progress output. When this switch
294 is enabled, only error or warning messages are printed.
295 --rc keyword=value
297 Override a configuration directive.
298 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 -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 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 -v
317 --version
318 Print version number, then exit.
319
323 /etc/lcovrc
324 The system-wide configuration file.
325 ~/.lcovrc
327 The per-user configuration file.
328 Following is a quick description of the tracefile format as used by
330 genhtml, geninfo and lcov.
331 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 TN:<test name>
337 For each source file referenced in the .da file, there is a section
339 containing filename and coverage data:
340 SF:<absolute path to the source file>
342 Following is a list of line numbers for each function name found in the
344 source file:
345 FN:<line number of function start>,<function name>
347 Next, there is a list of execution counts for each instrumented func‐
349 tion:
350 FNDA:<execution count>,<function name>
352 This list is followed by two lines containing the number of functions
354 found and hit:
355 FNF:<number of functions found>
357 FNH:<number of function hit>
358 Branch coverage information is stored which one line per branch:
360 BRDA:<line number>,<block number>,<branch number>,<taken>
362 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 Branch coverage summaries are stored in two lines:
368 BRF:<number of branches found>
370 BRH:<number of branches hit>
371 Then there is a list of execution counts for each instrumented line
373 (i.e. a line which resulted in executable code):
374 DA:<line number>,<execution count>[,<checksum>]
376 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 At the end of a section, there is a summary about how many lines were
382 found and how many were actually instrumented:
383 LH:<number of lines with a non-zero execution count>
385 LF:<number of instrumented lines>
386 Each sections ends with:
388 end_of_record
390 In addition to the main source code file there are sections for all
392 #included files which also contain executable code.
393 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 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
406 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
407
410 lcov(1), lcovrc(5), genhtml(1), genpng(1), gendesc(1), gcov(1)
4112022-01-20 LCOV 1.14 geninfo(1)