1geninfo(1) User Manuals geninfo(1)
6
10 geninfo - Generate tracefiles from GCOV coverage data files
11
13 geninfo [-h|--help] [--version] [-q|--quiet] [-v|--verbose] [--debug]
14 [-i|--initial] [-t|--test-name test-name]
15 [-o|--output-filename filename] [-f|--follow]
16 [-b|--base-directory directory]
17 [--build-directory directory]
18 [--branch-coverage]
19 [--checksum] [--no-checksum]
20 [--compat-libtool] [--no-compat-libtool]
21 [--gcov-tool tool]
22 [--parallel|-j [integer]]
23 [--memory integer_num_Mb]
24 [--ignore-errors errors]
25 [--keep-going]
26 [--preserve]
27 [--filter type]
28 [--demangle-cpp[param]]
29 [--no-recursion] [--external] [--no-external]
30 [--config-file config-file] [--no-markers]
31 [--derive-func-data] [--compat mode=on|off|auto]
32 [--rc keyword=value]
33 [--include glob_pattern]
34 [--exclude glob_pattern]
35 [--erase-functions regexp_pattern]
36 [--substitute regexp_pattern]
37 [--omit-lines regexp_pattern]
38 [--forget-test-names]
39 [--version-script script_file]
40 [--tempdir dirname]
41 directory
42
45 Use geninfo to create LCOV tracefiles from GCC and LLVM/Clang coverage
46 data files (see --gcov-tool for considerations when working with LLVM).
47 You can use genhtml to create an HTML report from a tracefile.
48 Note that geninfo is called by lcov --capture, so there is typically no
50 need to call it directly.
51 Unless the --output-filename option is specified geninfo writes its
53 output to one file with .info filename extension per input file.
54 Note also that the current user needs write access to both directory as
56 well as to the original source code location. This is necessary because
57 some temporary files have to be created there during the conversion
58 process.
59 File types
62 A tracefile is a coverage data file in the format used by all LCOV
63 tools such as geninfo, lcov, and genhtml. By convention, tracefiles
64 have a .info filename extension. See "Tracefile format" below for a de‐
65 scription of the file format.
66 A .gcda file is a compiler-specific file containing run-time coverage
68 data. It is created and updated when a program compiled with GCC/LLVM's
69 --coverage option is run to completion. geninfo reads .gcda files in
70 its default mode of operation. Note: earlier compiler versions used the
71 .da filename extension for this file type.
72 A .gcno file is a compiler-specific file containing static, compile-
74 time coverage data. It is created when source code is compiled with
75 GCC/LLVM's --coverage option. geninfo reads .gcno files when option
76 --initial is specified. Note: earlier compiler versions used .bb and
77 .bbg filename extensions for this file type.
78 A .gcov file is a textual or JSON representation of the data found in
80 .gcda and .gcno files. It is created by the gcov tools that is part of
81 GCC (see --gcov-tool for LLVM considerations). There are multiple gcov
82 file format versions, including textual, intermediate, and JSON format.
83 geninfo internally uses gcov to extract coverage data from .gcda and
84 .gcno files using the best supported gcov file format.
85 See the gcov man page for more information on .gcda, .gcno and .gcov
87 output formats.
88 Exclusion markers
91 To exclude specific lines of code from a tracefile, you can add exclu‐
92 sion markers to the source code. Additionally you can exclude specific
93 branches from branch coverage without excluding the involved lines from
94 line and function coverage. Exclusion markers are keywords which can
95 for example be added in the form of a comment. See lcovrc(5) how to
96 override some of them.
97 The following markers are recognized by geninfo:
99 LCOV_EXCL_LINE
101 Lines containing this marker will be excluded.
102 LCOV_EXCL_START
104 Marks the beginning of an excluded section. The current line is
105 part of this section.
106 LCOV_EXCL_STOP
108 Marks the end of an excluded section. The current line not part
109 of this section.
110 LCOV_EXCL_BR_LINE
112 Lines containing this marker will be excluded from branch cover‐
113 age.
114 LCOV_EXCL_BR_START
116 Marks the beginning of a section which is excluded from branch
117 coverage. The current line is part of this section.
118 LCOV_EXCL_BR_STOP
120 Marks the end of a section which is excluded from branch cover‐
121 age. The current line not part of this section.
122 LCOV_EXCL_EXCEPTION_BR_LINE
124 Lines containing this marker will be excluded from exception
125 branch coverage: Exception branches will be ignored, but non-ex‐
126 ception branches will not be affected.
127 LCOV_EXCL_EXCEPTION_BR_START
129 Marks the beginning of a section which is excluded from excep‐
130 tion branch coverage. The current line is part of this section.
131 LCOV_EXCL_EXCEPTION_BR_STOP
133 Marks the end of a section which is excluded from exception
134 branch coverage. The current line not part of this section
135
138 -b directory
139 --base-directory directory
140 Use directory as base directory for relative paths.
141 Use this option to specify the base directory of a build-envi‐
143 ronment when geninfo produces error messages like:
144 ERROR: could not read source file /home/user/project/sub‐
146 dir1/subdir2/subdir1/subdir2/file.c
147 In this example, use /home/user/project as base directory.
149 This option is required when using geninfo on projects built
151 with libtool or similar build environments that work with a base
152 directory, i.e. environments, where the current working direc‐
153 tory when invoking the compiler is not the same directory in
154 which the source code file is located.
155 Note that this option will not work in environments where multi‐
157 ple base directories are used. In that case use configuration
158 file setting geninfo_auto_base=1 (see lcovrc(5)).
159 --build-directory build_dir
161 Search for .gcno data files from build_dir rather finding them
162 only adjacent to the corresponding .o and/or .gcda file.
163 By default, geninfo expects to find the .gcno and .gcda files
165 (compile- and run-time data, respectively) in the same direc‐
166 tory.
167 When this option is used:
169 geninfo path1 --build-directory path2 ...
171 then geninfo will look for .gcno file
173 path2/relative/path/to/da_base.gcno
175 when it finds .gcda file
177 path1/relative/path/to/da_base.gcda.
179 Use this option when you have used the GCOV_PREFIX environment
181 variable to direct the gcc or llvm runtime environment to write
182 coverage data files to somewhere other than the directory where
183 the code was originally compiled. See gcc(1) and/or search for
184 GCOV_PREFIX and GCOV_PREFIX_STRIP.
185 This option can be used several times to specify multiple alter‐
187 nate directories to look for .gcno files. This may be useful if
188 your application uses code which is compiled in many separate
189 locations - for example, common libraries that are shared be‐
190 tween teams.
191 --branch-coverage
194 Collect retain branch coverage data.
195 This is equivalent to using the option "--rc lcov_branch_cover‐
197 age=1"; the option was added to better match the genhml inter‐
198 face.
199 --checksum
202 --no-checksum
203 Specify whether to generate checksum data when writing trace‐
204 files.
205 Use --checksum to enable checksum generation or --no-checksum to
207 disable it. Checksum generation is disabled by default.
208 When checksum generation is enabled, a checksum will be gener‐
210 ated for each source code line and stored along with the cover‐
211 age data. This checksum will be used to prevent attempts to com‐
212 bine coverage data from different source code versions.
213 If you don't work with different source code versions, disable
215 this option to speed up coverage data processing and to reduce
216 the size of tracefiles.
217 Note that this options is somewhat subsumed by the --ver‐
219 sion-script option - which does something similar, but at the
220 'whole file' level.
221 --compat mode=value[,mode=value,...]
224 Set compatibility mode.
225 Use --compat to specify that geninfo should enable one or more
227 compatibility modes when capturing coverage data. You can pro‐
228 vide a comma-separated list of mode=value pairs to specify the
229 values for multiple modes.
230 Valid values are:
232 on
234 Enable compatibility mode.
235 off
236 Disable compatibility mode.
237 auto
238 Apply auto-detection to determine if compatibility mode
239 is required. Note that auto-detection is not available
240 for all compatibility modes.
241 If no value is specified, 'on' is assumed as default value.
243 Valid modes are:
245 libtool
247 Enable this mode if you are capturing coverage data for a
248 project that was built using the libtool mechanism. See
249 also --compat-libtool.
250 The default value for this setting is 'on'.
252 hammer
254 Enable this mode if you are capturing coverage data for a
255 project that was built using a version of GCC 3.3 that
256 contains a modification (hammer patch) of later GCC ver‐
257 sions. You can identify a modified GCC 3.3 by checking
258 the build directory of your project for files ending in
259 the extension .bbg. Unmodified versions of GCC 3.3 name
260 these files .bb.
261 The default value for this setting is 'auto'.
263 split_crc
265 Enable this mode if you are capturing coverage data for a
266 project that was built using a version of GCC 4.6 that
267 contains a modification (split function checksums) of
268 later GCC versions. Typical error messages when running
269 geninfo on coverage data produced by such GCC versions
270 are ´out of memory' and 'reached unexpected end of file'.
271 The default value for this setting is 'auto'
273 --compat-libtool
276 --no-compat-libtool
277 Specify whether to enable libtool compatibility mode.
278 Use --compat-libtool to enable libtool compatibility mode or
280 --no-compat-libtool to disable it. The libtool compatibility
281 mode is enabled by default.
282 When libtool compatibility mode is enabled, geninfo will assume
284 that the source code relating to a .gcda file located in a di‐
285 rectory named ".libs" can be found in its parent directory.
286 If you have directories named ".libs" in your build environment
288 but don't use libtool, disable this option to prevent problems
289 when capturing coverage data.
290 --config-file config-file
292 Specify a configuration file to use. See the lcovrc man page
293 for details of the file format and options.
294 When this option is specified, neither the system-wide configu‐
296 ration file /etc/lcovrc, nor the per-user configuration file
297 ~/.lcovrc is read.
298 This option may be useful when there is a need to run several
300 instances of geninfo with different configuration file options
301 in parallel.
302 Note that this option must be specified in full - abbreviations
304 are not supported.
305 --derive-func-data
308 Calculate function coverage data from line coverage data.
309 Use this option to collect function coverage data, even if the
311 version of the gcov tool installed on the test system does not
312 provide this data. lcov will instead derive function coverage
313 data from line coverage data and information about which lines
314 belong to a function.
315 --external
317 --no-external
318 Specify whether to capture coverage data for external source
319 files.
320 External source files are files which are not located in one of
322 the directories specified by directory or --base-directory. Use
323 --external to include external source files while capturing cov‐
324 erage data or --no-external to ignore this data.
325 Data for external source files is included by default.
327 -f
329 --follow
330 Follow links when searching .gcda files.
331 --gcov-tool tool
333 Specify the location of the gcov tool.
334 If the --gcov-tool option is used multiple times, then the argu‐
336 ments are concatenated when the callback is executed - similar
337 to how the gcc -Xlinker parameter works. This provides a possi‐
338 bly easier way to pass arguments to your tool, without requiring
339 a wrapper script. In that case, your callback will be executed
340 as: tool-0 'tool-1; ... 'filename'. Note that the second and
341 subsequent arguments are quoted when passed to the shell, in or‐
342 der to handle parameters which contain spaces.
343 A common use for this option is to enable LLVM:
345 geninfo --gcov-tool llvm-cov --gcov-tool gcov ...
347 Note: 'llvm-cov gcov da_file_name' will generate output in gcov-
349 compatible format as required by lcov.
350 If not specified, 'gcov' is used by default.
352 -h
355 --help
356 Print a short help text, then exit.
357 --include pattern
359 Include source files matching pattern.
360 Use this switch if you want to include coverage data for only a
362 particular set of source files matching any of the given pat‐
363 terns. Multiple patterns can be specified by using multiple
364 --include command line switches. The patterns will be inter‐
365 preted as shell wildcard patterns (note that they may need to be
366 escaped accordingly to prevent the shell from expanding them
367 first).
368 See the lcov man page for details
370 --exclude pattern
373 Exclude source files matching pattern.
374 Use this switch if you want to exclude coverage data from a
376 particular set of source files matching any of the given pat‐
377 terns. Multiple patterns can be specified by using multiple
378 --exclude command line switches. The patterns will be inter‐
379 preted as shell wildcard patterns (note that they may need to be
380 escaped accordingly to prevent the shell from expanding them
381 first). Note: The pattern must be specified to match the abso‐
382 lute path of each source file.
383 Can be combined with the --include command line switch. If a
385 given file matches both the include pattern and the exclude pat‐
386 tern, the exclude pattern will take precedence.
387 See the lcov man page for details.
389 --erase-functions regexp
392 Exclude coverage data from lines which fall within a function
393 whose name matches the supplied regexp. Note that this is a
394 mangled or demangled name, depending on whether the --deman‐
395 gle-cpp option is used or not.
396 Note that this option requires that you use a gcc version which
398 is new enough to support function begin/end line reports.
399 --substitute regexp_pattern
402 Apply Perl regexp regexp_pattern to source file names found dur‐
403 ing processing. This is useful when the path name reported by
404 gcov does not match your source layout and the file is not
405 found. See the lcov man page for more details.
406 --omit-lines regexp
409 Exclude coverage data from lines whose content matches regexp.
410 Use this switch if you want to exclude line and branch coverage
412 data for some particular constructs in your code (e.g., some
413 complicated macro). See the lcov man page for details.
414 --forget-test-names
417 If non-zero, ignore testcase names in tracefile - i.e., treat
418 all coverage data as if it came from the same testcase. This
419 may improve performance and reduce memory consumption if user
420 does not need per-testcase coverage summary in coverage reports.
421 This option can also be configured permanently using the config‐
423 uration file option forget_testcase_names.
424 --ignore-errors errors
426 Specify a list of errors after which to continue processing.
427 Use this option to specify a list of one or more classes of er‐
429 rors after which geninfo should continue processing instead of
430 aborting. Note that the tool will generate a warning (rather
431 than a fatal error) unless you ignore the error two (or more)
432 times:
433 geninfo ... --ignore-errors unused,unused
434 errors can be a comma-separated list of the following keywords:
436 branch: branch ID (2nd field in the .info file 'BRDA' entry)
438 does not follow expected integer sequence.
439 callback: Version script error.
441 corrupt: corrupt/unreadable file found.
443 count: An excessive number of messages of some class have been
445 reported - subsequent messages of that type will be suppressed.
446 The limit can be controlled by the 'max_message_count' variable.
447 See the lcovrc man page.
448 deprecated: You are using a deprecated option. This option will
450 be removed in an upcoming release - so you should change your
451 scripts now.
452 empty: the .info data file is empty (e.g., because all the code
454 was 'removed' or excluded.
455 format: unexpected syntax found in .info file.
457 gcov: the gcov tool returned with a non-zero return code.
459 graph: the graph file could not be found or is corrupted.
461 mismatch: Inconsistent entries found in trace file:
463 • branch expression (3rd field in the .info file 'BRDA' entry)
465 of merge data does not match, or
466 • function execution count (FNDA:...) but no function declara‐
469 tion (FN:...).
470 negative: negative 'hit' count found.
472 Note that negative counts may be caused by a known GCC bug - see
474 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080
476 and try compiling with "-fprofile-update=atomic". You will need
478 to recompile, re-run your tests, and re-capture coverage data.
479 package: a required perl package is not installed on your sys‐
481 tem. In some cases, it is possible to ignore this message and
482 continue - however, certain features will be disabled in that
483 case.
484 parallel: various types of errors related to parallelism - e.g.,
486 child process died due to some error. If you see an error re‐
487 lated to parallel execution, it may be a good idea to remove the
488 --parallel flag and try again.
489 source: the source code file for a data set could not be found.
491 unsupported: the requested feature is not supported for this
493 tool configuration. For example, function begin/end line range
494 exclusions use some GCOV features that are not available in
495 older GCC releases.
496 unused: the include/exclude/erase/omit/substitute pattern did
498 not match any file pathnames.
499 version: revision control IDs of the file which we are trying to
501 merge are not the same - line numbering and other information
502 may be incorrect.
503 Also see man lcovrc for a discussion of the 'max_message_count'
505 parameter which can be used to control the number of warnings
506 which are emitted before all subsequent messages are suppressed.
507 This can be used to reduce log file volume.
508 --keep-going
510 Do not stop if error occurs: attempt to generate a result, how‐
511 ever flawed.
512 This command line option corresponds to the stop_on_error [0|1]
514 lcovrc option. See the lcovrc man page for more details.
515 --preserve
518 Preserve intermediate data files (e.g., for debugging).
519 By default, intermediate files are deleted.
521 --filter filters
523 Specify a list of coverpoint filters to apply to input data.
524 See the genhtml man page for details.
525 --demangle-cpp [param]
527 Demangle C++ method and function names in captured output. See
528 the genhtml man page for details.
529 -i
531 --initial
532 Capture initial zero coverage data.
533 Run geninfo with this option on the directories containing .bb,
535 .bbg or .gcno files before running any test case. The result is
536 a "baseline" coverage data file that contains zero coverage for
537 every instrumented line and function. Combine this data file
538 (using lcov -a) with coverage data files captured after a test
539 run to ensure that the percentage of total lines covered is cor‐
540 rect even when not all object code files were loaded during the
541 test.
542 Note: currently, the --initial option does not generate branch
544 coverage information.
545 --no-markers
547 Use this option if you want to get coverage data without regard
548 to exclusion markers in the source code file.
549 --no-recursion
551 Use this option if you want to get coverage data for the speci‐
552 fied directory only without processing subdirectories.
553 -o output-filename
555 --output-filename output-filename
556 Write all data to output-filename.
557 If you want to have all data written to a single file (for eas‐
559 ier handling), use this option to specify the respective file‐
560 name. By default, one tracefile will be created for each pro‐
561 cessed .gcda file.
562 --version-script script
564 Use script to get a source file's version ID from revision con‐
565 trol when extracting data. The ID is used for error checking
566 when merging .info files.
567 See the genhtml man page for more details on the version script.
569 -v
571 --verbose
572 Increment informational message verbosity. This is mainly used
573 for script and/or flow debugging - e.g., to figure out which
574 data file are found, where. Also see the --quiet flag.
575 Messages are sent to stdout unless there is no output file
577 (i.e., if the coverage data is written to stdout rather than to
578 a file) and to stderr otherwise.
579 -q
581 --quiet
582 Decrement informational message verbosity.
583 Decreased verbosity will suppress 'progress' messages for exam‐
585 ple - while error and warning messages will continue to be
586 printed.
587 --debug
589 Increment 'debug messages' verbosity. This is useful primarily
590 to developers who want to enhance the lcov tool suite.
591 --parallel [ integer ]
594 -j [ integer ]
595 Specify parallelism to use during processing (maximum number of
596 forked child processes). If the optional integer parallelism
597 parameter is zero or is missing, then use to use up the number
598 of cores on the machine. Default is not to use a single process
599 (no parallelism).
600 --memory integer
602 Specify the maximum amount of memory to use during parallel pro‐
603 cessing, in Mb. Effectively, the process will not fork() if
604 this limit would be exceeded. Default is 0 (zero) - which means
605 that there is no limit.
606 This option may be useful if the compute farm environment im‐
608 poses strict limits on resource utilization such that the job
609 will be killed if it tries to use too many parallel children -
610 but the user does now know a priori what the permissible maximum
611 is. This option enables the tool to use maximum parallelism -
612 up to the limit imposed by the memory restriction.
613 --rc keyword=value
616 Override a configuration directive.
617 Use this option to specify a keyword=value statement which over‐
619 rides the corresponding configuration statement in the lcovrc
620 configuration file. You can specify this option more than once
621 to override multiple configuration statements. See lcovrc(5)
622 for a list of available keywords and their meaning.
623 -t testname
625 --test-name testname
626 Use test case name testname for resulting data. Valid test case
627 names can consist of letters, decimal digits and the underscore
628 character ('_').
629 This proves useful when data from several test cases is merged
631 (i.e. by simply concatenating the respective tracefiles) in
632 which case a test name can be used to differentiate between data
633 from each test case.
634 --version
636 Print version number, then exit.
637 --tempdir dirname
639 Write temporary and intermediate data to indicated directory.
640 Default is "/tmp".
641
645 Following is a quick description of the tracefile format as used by
646 genhtml, geninfo and lcov.
647 A tracefile is made up of several human-readable lines of text, divided
649 into sections. If available, a tracefile begins with the testname which
650 is stored in the following format:
651 TN:<test name>
653 For each source file referenced in the .gcda file, there is a section
655 containing filename and coverage data:
656 SF:<absolute path to the source file>
658 An optional source code version ID follows:
660 VER:<version ID>
662 If present, the version ID is compared before file entries are merged
664 (see lcov --add-tracefile ), and before the 'source detail' view is
665 generated by genhtml. See the --version-script callback_script docu‐
666 mentation and the sample usage in the lcov regression test examples.
667 Following is a list of line numbers for each function name found in the
669 source file:
670 FN:<line number of function start>,(<line number of function
672 end>,)?<function name>
673 The 'end' line number is optional, and is generated only if the com‐
675 piler/toolchain version is recent enough to generate the data (e.g.,
676 gcc 9 or newer). This data is used to support the --erase-functions
677 and --show-proportions options. If the function end line data is not
678 available, then these features will not work.
679 Next, there is a list of execution counts for each instrumented func‐
681 tion:
682 FNDA:<execution count>,<function name>
684 This list is followed by two lines containing the number of functions
686 found and hit:
687 FNF:<number of functions found>
689 FNH:<number of function hit>
690 Branch coverage information is stored which one line per branch:
692 BRDA:<exception tag><line number>,<block number>,<branch num‐
694 ber>,<taken>
695 Block number and branch number are gcc internal IDs for the branch.
697 Taken is either '-' if the basic block containing the branch was never
698 executed or a number indicating how often that branch was taken. 'ex‐
699 ception tag' is 'e' if this is a branch related to exception handling -
700 and is not present if the branch is not related to exceptions.
701 Branch coverage summaries are stored in two lines:
703 BRF:<number of branches found>
705 BRH:<number of branches hit>
706 Then there is a list of execution counts for each instrumented line
708 (i.e. a line which resulted in executable code):
709 DA:<line number>,<execution count>[,<checksum>]
711 Note that there may be an optional checksum present for each instru‐
713 mented line. The current geninfo implementation uses an MD5 hash as
714 checksumming algorithm.
715 At the end of a section, there is a summary about how many lines were
717 found and how many were actually instrumented:
718 LH:<number of lines with a non-zero execution count>
720 LF:<number of instrumented lines>
721 Each sections ends with:
723 end_of_record
725 In addition to the main source code file there are sections for all
727 #included files which also contain executable code.
728 Note that the absolute path of a source file is generated by interpret‐
730 ing the contents of the respective .gcno file (see gcov [22m(1) for more
731 information on this file type). Relative filenames are prefixed with
732 the directory in which the .gcno file is found.
733 Note also that symbolic links to the .gcno file will be resolved so
735 that the actual file path is used instead of the path to a link. This
736 approach is necessary for the mechanism to work with the /proc/gcov
737 files.
738
742 /etc/lcovrc
743 The system-wide configuration file.
744 ~/.lcovrc
746 The per-user configuration file.
747 /usr/share/lcov/support-scripts/getp4version
749 Sample script for use with --version-script that obtains version
750 IDs via Perforce.
751 /usr/share/lcov/support-scripts/get_signature
753 Sample script for use with --version-script that uses md5hash as
754 version IDs.
755
759 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
760 Henry Cox <henry.cox@mediatek.com>
762 Filtering, error management, parallel execution sections.
763
766 lcov(1), lcovrc(5), genhtml(1), genpng(1), gendesc(1), gcov(1)
767 https://github.com/linux-test-project/lcov
7692023-11-27 LCOV 2.0 geninfo(1)