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
22 geninfo converts all GCOV coverage data files found in directory into
23 tracefiles, which the genhtml tool can convert to HTML output.
24 Unless the --output-filename option is specified, geninfo writes its
26 output to one file per .da file, the name of which is generated by sim‐
27 ply appending ".info" to the respective .da file name.
28 Note that the current user needs write access to both directory as well
30 as to the original source code location. This is necessary because some
31 temporary files have to be created there during the conversion process.
32 Note also that geninfo is called from within lcov, so that there is
34 usually no need to call it directly.
35 Exclusion markers
37 To exclude specific lines of code from a tracefile, you can add exclu‐
39 sion markers to the source code. Additionally you can exclude specific
40 branches from branch coverage without excluding the involved lines from
41 line and function coverage. Exclusion markers are keywords which can
42 for example be added in the form of a comment. See lcovrc(5) how to
43 override some of them.
44 The following markers are recognized by geninfo:
46 LCOV_EXCL_LINE
48 Lines containing this marker will be excluded.
49 LCOV_EXCL_START
50 Marks the beginning of an excluded section. The current line is
51 part of this section.
52 LCOV_EXCL_STOP
53 Marks the end of an excluded section. The current line not part
54 of this section.
55 LCOV_EXCL_BR_LINE
56 Lines containing this marker will be excluded from branch cover‐
57 age.
58 LCOV_EXCL_BR_START
59 Marks the beginning of a section which is excluded from branch
60 coverage. The current line is part of this section.
61 LCOV_EXCL_BR_STOP
62 Marks the end of a section which is excluded from branch cover‐
63 age. The current line not part of this section.
64
67 -b directory
68 --base-directory directory
69 Use directory as base directory for relative paths.
70 Use this option to specify the base directory of a build-envi‐
72 ronment when geninfo produces error messages like:
73 ERROR: could not read source file /home/user/project/sub‐
75 dir1/subdir2/subdir1/subdir2/file.c
76 In this example, use /home/user/project as base directory.
78 This option is required when using geninfo on projects built
80 with libtool or similar build environments that work with a base
81 directory, i.e. environments, where the current working direc‐
82 tory when invoking the compiler is not the same directory in
83 which the source code file is located.
84 Note that this option will not work in environments where multi‐
86 ple base directories are used. In that case use configuration
87 file setting geninfo_auto_base=1 (see lcovrc(5)).
88 --checksum
90 --no-checksum
91 Specify whether to generate checksum data when writing trace‐
92 files.
93 Use --checksum to enable checksum generation or --no-checksum to
95 disable it. Checksum generation is disabled by default.
96 When checksum generation is enabled, a checksum will be gener‐
98 ated for each source code line and stored along with the cover‐
99 age data. This checksum will be used to prevent attempts to com‐
100 bine coverage data from different source code versions.
101 If you don't work with different source code versions, disable
103 this option to speed up coverage data processing and to reduce
104 the size of tracefiles.
105 --compat mode=value[,mode=value,...]
107 Set compatibility mode.
108 Use --compat to specify that geninfo should enable one or more
110 compatibility modes when capturing coverage data. You can pro‐
111 vide a comma-separated list of mode=value pairs to specify the
112 values for multiple modes.
113 Valid values are:
115 on
117 Enable compatibility mode.
118 off
119 Disable compatibility mode.
120 auto
121 Apply auto-detection to determine if compatibility mode
122 is required. Note that auto-detection is not available
123 for all compatibility modes.
124 If no value is specified, 'on' is assumed as default value.
126 Valid modes are:
128 libtool
130 Enable this mode if you are capturing coverage data for a
131 project that was built using the libtool mechanism. See
132 also --compat-libtool.
133 The default value for this setting is 'on'.
135 hammer
137 Enable this mode if you are capturing coverage data for a
138 project that was built using a version of GCC 3.3 that
139 contains a modification (hammer patch) of later GCC ver‐
140 sions. You can identify a modified GCC 3.3 by checking
141 the build directory of your project for files ending in
142 the extension '.bbg'. Unmodified versions of GCC 3.3 name
143 these files '.bb'.
144 The default value for this setting is 'auto'.
146 split_crc
148 Enable this mode if you are capturing coverage data for a
149 project that was built using a version of GCC 4.6 that
150 contains a modification (split function checksums) of
151 later GCC versions. Typical error messages when running
152 geninfo on coverage data produced by such GCC versions
153 are ´out of memory' and 'reached unexpected end of file'.
154 The default value for this setting is 'auto'
156 --compat-libtool
159 --no-compat-libtool
160 Specify whether to enable libtool compatibility mode.
161 Use --compat-libtool to enable libtool compatibility mode or
163 --no-compat-libtool to disable it. The libtool compatibility
164 mode is enabled by default.
165 When libtool compatibility mode is enabled, geninfo will assume
167 that the source code relating to a .da file located in a direc‐
168 tory named ".libs" can be found in its parent directory.
169 If you have directories named ".libs" in your build environment
171 but don't use libtool, disable this option to prevent problems
172 when capturing coverage data.
173 --config-file config-file
175 Specify a configuration file to use.
176 When this option is specified, neither the system-wide configu‐
178 ration file /etc/lcovrc, nor the per-user configuration file
179 ~/.lcovrc is read.
180 This option may be useful when there is a need to run several
182 instances of geninfo with different configuration file options
183 in parallel.
184 --derive-func-data
186 Calculate function coverage data from line coverage data.
187 Use this option to collect function coverage data, even if the
189 version of the gcov tool installed on the test system does not
190 provide this data. lcov will instead derive function coverage
191 data from line coverage data and information about which lines
192 belong to a function.
193 --external
195 --no-external
196 Specify whether to capture coverage data for external source
197 files.
198 External source files are files which are not located in one of
200 the directories specified by --directory or --base-directory.
201 Use --external to include external source files while capturing
202 coverage data or --no-external to ignore this data.
203 Data for external source files is included by default.
205 -f
207 --follow
208 Follow links when searching .da files.
209 --gcov-tool tool
211 Specify the location of the gcov tool.
212 -h
214 --help
215 Print a short help text, then exit.
216 --ignore-errors errors
218 Specify a list of errors after which to continue processing.
219 Use this option to specify a list of one or more classes of
221 errors after which geninfo should continue processing instead of
222 aborting.
223 errors can be a comma-separated list of the following keywords:
225 gcov: the gcov tool returned with a non-zero return code.
227 source: the source code file for a data set could not be found.
229 -i
231 --initial
232 Capture initial zero coverage data.
233 Run geninfo with this option on the directories containing .bb,
235 .bbg or .gcno files before running any test case. The result is
236 a "baseline" coverage data file that contains zero coverage for
237 every instrumented line and function. Combine this data file
238 (using lcov -a) with coverage data files captured after a test
239 run to ensure that the percentage of total lines covered is cor‐
240 rect even when not all object code files were loaded during the
241 test.
242 Note: currently, the --initial option does not generate branch
244 coverage information.
245 --no-markers
247 Use this option if you want to get coverage data without regard
248 to exclusion markers in the source code file.
249 --no-recursion
251 Use this option if you want to get coverage data for the speci‐
252 fied directory only without processing subdirectories.
253 -o output-filename
255 --output-filename output-filename
256 Write all data to output-filename.
257 If you want to have all data written to a single file (for eas‐
259 ier handling), use this option to specify the respective file‐
260 name. By default, one tracefile will be created for each pro‐
261 cessed .da file.
262 -q
264 --quiet
265 Do not print progress messages.
266 Suppresses all informational progress output. When this switch
268 is enabled, only error or warning messages are printed.
269 --rc keyword=value
271 Override a configuration directive.
272 Use this option to specify a keyword=value statement which over‐
274 rides the corresponding configuration statement in the lcovrc
275 configuration file. You can specify this option more than once
276 to override multiple configuration statements. See lcovrc(5)
277 for a list of available keywords and their meaning.
278 -t testname
280 --test-name testname
281 Use test case name testname for resulting data. Valid test case
282 names can consist of letters, decimal digits and the underscore
283 character ('_').
284 This proves useful when data from several test cases is merged
286 (i.e. by simply concatenating the respective tracefiles) in
287 which case a test name can be used to differentiate between data
288 from each test case.
289 -v
291 --version
292 Print version number, then exit.
293
297 /etc/lcovrc
298 The system-wide configuration file.
299 ~/.lcovrc
301 The per-user configuration file.
302 Following is a quick description of the tracefile format as used by
304 genhtml, geninfo and lcov.
305 A tracefile is made up of several human-readable lines of text, divided
307 into sections. If available, a tracefile begins with the testname which
308 is stored in the following format:
309 TN:<test name>
311 For each source file referenced in the .da file, there is a section
313 containing filename and coverage data:
314 SF:<absolute path to the source file>
316 Following is a list of line numbers for each function name found in the
318 source file:
319 FN:<line number of function start>,<function name>
321 Next, there is a list of execution counts for each instrumented func‐
323 tion:
324 FNDA:<execution count>,<function name>
326 This list is followed by two lines containing the number of functions
328 found and hit:
329 FNF:<number of functions found>
331 FNH:<number of function hit>
332 Branch coverage information is stored which one line per branch:
334 BRDA:<line number>,<block number>,<branch number>,<taken>
336 Block number and branch number are gcc internal IDs for the branch.
338 Taken is either '-' if the basic block containing the branch was never
339 executed or a number indicating how often that branch was taken.
340 Branch coverage summaries are stored in two lines:
342 BRF:<number of branches found>
344 BRH:<number of branches hit>
345 Then there is a list of execution counts for each instrumented line
347 (i.e. a line which resulted in executable code):
348 DA:<line number>,<execution count>[,<checksum>]
350 Note that there may be an optional checksum present for each instru‐
352 mented line. The current geninfo implementation uses an MD5 hash as
353 checksumming algorithm.
354 At the end of a section, there is a summary about how many lines were
356 found and how many were actually instrumented:
357 LH:<number of lines with a non-zero execution count>
359 LF:<number of instrumented lines>
360 Each sections ends with:
362 end_of_record
364 In addition to the main source code file there are sections for all
366 #included files which also contain executable code.
367 Note that the absolute path of a source file is generated by interpret‐
369 ing the contents of the respective .bb file (see gcov [22m(1) for more
370 information on this file type). Relative filenames are prefixed with
371 the directory in which the .bb file is found.
372 Note also that symbolic links to the .bb file will be resolved so that
374 the actual file path is used instead of the path to a link. This
375 approach is necessary for the mechanism to work with the /proc/gcov
376 files.
377
380 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
381
384 lcov(1), lcovrc(5), genhtml(1), genpng(1), gendesc(1), gcov(1)
3852016-12-19 LCOV 1.13 geninfo(1)