Debian Codegraph @

man/lcovrc.5

raw
1 .TH lcovrc 5 "LCOV 2.0" 2023\-05\-17 "User Manuals"
2
3 .SH NAME
4 lcovrc \- lcov configuration file
5
6 .SH DESCRIPTION
7 The
8 .I lcovrc
9 file contains configuration information for the
10 .B lcov
11 code coverage tool (see
12 .BR lcov (1)).
13 .br
14
15 The system\-wide configuration file is located at
16 .IR $LCOV_HOME/etc/lcovrc .
17 This is typically either
18 .IR /etc/lcovrc
19 or
20 .IR /usr/local/etc/lcovrc
21 but may be wherever you have installed the lcov package.
22 To change settings for a single user, place a customized copy of this file at
23 location
24 .IR ~/.lcovrc .
25 Where available, command\-line options override configuration file settings.
26
27 The
28 .I genhtml, lcov,
29 and
30 .I geninfo
31 commands also support the
32 .I \-\-config\-file
33 option, which can be used to specify one or more files which should be used instead of the system or user default rc files.
34 Multiple options files may be useful if you have both project- and team-specific common options and want to ensure consistency across multiple users. If multiple \-\-config\-file options are applied in the order they appear.
35 Note that the "\-\-config\-file" option name must be specified in full and cannot be abbreviated. An error will occur if the option is not recognized.
36
37 Lines in a configuration file can either be:
38 .IP " *"
39 empty lines or lines consisting only of white space characters. These lines are
40 ignored.
41 .IP " *"
42 comment lines which start with a hash sign ('#'). These are treated like empty
43 lines and will be ignored.
44 .IP " *"
45 statements in the form
46 .RI ' key " = " value '.
47
48 .IP " *"
49 Values may be taken from environment variables via the syntax
50
51 .RI ' key " = " ... $ENV{ENV_VAR_NAME} ...'.
52
53 .RI
54 The substring '$ENV{ENV_VAR_NAME}' is replaced by the value of the environment variable.
55
56 .RI
57 One or more environment variables may be used to set the RC value.
58 'key' is ignored if any of the environment variables are not set in your user environment.
59
60 .PP
61 A list of valid statements and their description can be found in
62 section 'OPTIONS' below.
63 .br
64 .B NOTE
65 that there is no error checking of keys in the options file: spelling errors
66 are simply seen as values which are not used by some particular tool.
67 If you are unsure of whether your options file is read or its values
68 applied, you can use the
69 .I \-\-verbose \-\-verbose
70 flag to enable printing of option value overrides.
71 (The option appears twice to enable a higher level of verbosity.)
72
73 Both 'list' and 'scalar' (non list) options are supported in the lcovrc file.
74
75 For scalar (non list) options:
76 .IP " *"
77 if specified on the command line and in the lcovrc file, the value specified on the command line wins.
78 The value from the RC file is ignored.
79 .IP " *"
80 Scalar options include:
81 .RI 'criteria_script " = " ...'
82 ,
83 .RI 'genhtml_annotate_script " = " ...'
84 ,
85 .RI 'version_script " = " ...'
86 , etc.
87 .PP
88 .PP
89
90 .PP
91 For list options:
92 .IP " *"
93 the RC file entry can be used multiple times; each use appends to the list.
94 .br
95 For example, the entry below will result in two 'omit' patterns which will both be checked:
96 .IP " "
97 # note explicit start/end line markers in the regexp
98 .br
99 omit_lines = ^\\s+//\\s*MY_EXCLUDE_MARKER\\s*$
100 .br
101 # Note that the regexp below matches anywhere on the line
102 .br
103 omit_lines = NR_CM_DBG_PRINT
104
105 .IP " *"
106 If entries are specified on the command line, then the RC file entries are ignored: command line wins.
107 If entries are specified in more than one RC file (i.e., multiple \-\-config\-file arguments are supplied), then RC files are applied in order of appearance, and list entries are appended in order. For most list-type options, order is not important.
108
109
110 .IP " *"
111 list options include:
112 .br
113 .RI " filter = " ...
114 .br
115 .RI " exclude = " ...
116 .br
117 .RI " ignore = " ...
118 .br
119 .RI " substitute = " ...
120 .br
121 .RI " omit_lines = " ...
122 .br
123 .RI " erase_functions = " ...
124 .br
125 .RI " genhtml_annotate_script = " ...
126 .br
127 .I etc.
128 For a complete set of list options, see the documentation of each configuration option, below.
129 .PP
130
131 .PP
132 .PP
133
134 .B Example configuration:
135
136 Note that this example does not include all possible configuration
137 options.
138 .br
139 In general: (almost) all command line options can be specified in
140 the configuration file instead, whereas some configuration file options
141 have no command line equivalent.
142
143 See the OPTIONS section below for details.
144 .IP
145 #
146 .br
147 # Example LCOV configuration file
148 .br
149 #
150 .br
151 # include some other config file
152 .br
153 # e.g, user-specific options. Note the environment variable expansion
154 .br
155 # config_file = $ENV{HOME}/.user_lcovrc
156 .br
157 # or project specific - hard-coded from environment variable
158 .br
159 # config_file = /path/to/myproject/.lcovrc
160 .br
161 # or in the current run directory
162 .br
163 # config_file = $ENV{PWD}/.lcovrc
164 .br
165 .br
166 # External style sheet file
167 .br
168 #genhtml_css_file = gcov.css
169 .br
170
171 # Use 'dark' mode display (light foreground/dark background)
172 .br
173 # rather than default
174 .br
175 #genhtml_dark_mode = 1
176 .br
177
178 # Alternate header text to use at top of each page
179 .br
180 #genhtml_header = Coverage report for my project
181
182 .br
183
184 # Alternate footer text to use at the bottom of each page
185 .br
186 #genhtml_footer = My footer text
187 .br
188
189 # Coverage rate limits
190 .br
191 genhtml_hi_limit = 90
192 .br
193 genhtml_med_limit = 75
194 .br
195
196 # Ignore some errors (comma-separated list)
197 .br
198 #ignore_errors = empty,mismatch
199 .br
200
201 # Stop emitting message after this number have been printed
202 .br
203 # 0 == no limit
204 .br
205 max_message_count = 100
206
207 .br
208 # If nonzero, do not stop when an 'ignorable error' occurs - try
209 .br
210 # to generate a result, however flawed. This is equivalent to
211 .br
212 # the '--keep-going' command line switch.
213 .br
214 # Default is 1: stop when error occurs
215 .br
216 #stop_on_error = 1
217
218 .br
219 # If nonzero, treat warnings as error
220 .br
221 # note that ignored messages will still appear as warnings
222 .br
223 # Default is 0
224 .br
225 #treat_warning_as_error = 1
226
227 .br
228 # If set to non-zero, only issue particular warning once per file
229 .br
230 # Default is 1
231 .br
232 #warn_once_per_file = 1
233
234 .br
235 # extension associated with lcov trace files - glob match pattern
236 .br
237 # used as argument to 'find' - to find coverage files contained in
238 .br
239 # a directory argument
240 .br
241 #info_file_pattern = *.info
242 .br
243
244 # list of file extensions which should be treated as C/C++ code
245 .br
246 # (comma-separated list)
247 .br
248 #c_file_extensions = h,c,cpp,hpp
249 .br
250
251 # list of file extensions which should be treated as RTL code
252 .br
253 # (e.g., Verilog) (comma-separated list)
254 .br
255 #rtl_file_extensions = v,vh,sv
256 .br
257
258 # list of file extensions which should be treated as Java code
259 .br
260 #java_file_extensions = java
261
262 # list of file extensions which should be treated as perl code
263 .br
264 #perl_file_extensions = pl,pm
265 .br
266
267 # list of file extensions which should be treated as python code
268 .br
269 #python_file_extensions = py
270 .br
271
272 # maximum number of lines to look at, when filtering bogus branch expressions
273 .br
274 #filter_lookahead = 5
275 .br
276
277 # if nonzero, bitwise operators '|', '&', '~' indicate conditional expressions
278 .br
279 #filter_bitwise_conditional = 1
280 .br
281 .br
282 # if nonzero, '--filter blank' is applied to blank lines, regardless
283 .br
284 # of their hit count
285 .br
286 #filter_blank_aggressive = 1
287 .br
288 .br
289
290 # Width of line coverage field in source code view
291 .br
292 genhtml_line_field_width = 12
293 .br
294
295 # Width of branch coverage field in source code view
296 .br
297 genhtml_branch_field_width = 16
298 .br
299
300 # Width of MC/DC coverage field in source code view
301 .br
302 genhtml_mcdc_field_width = 14
303 .br
304
305 # width of 'owner' field in source code view - default is 20
306 .br
307 genhtml_owner_field_width = 20
308 .br
309 # width of 'age' field in source code view - default is 5
310 .br
311 genhtml_age_field_width = 5
312 .br
313
314 # Width of overview image
315 .br
316 genhtml_overview_width = 80
317 .br
318
319 # Resolution of overview navigation
320 .br
321 genhtml_nav_resolution = 4
322 .br
323
324 # Offset for source code navigation
325 .br
326 genhtml_nav_offset = 10
327 .br
328
329 # Do not remove unused test descriptions if non\-zero
330 .br
331 genhtml_keep_descriptions = 0
332 .br
333
334 # Do not remove prefix from directory names if non\-zero
335 .br
336 genhtml_no_prefix = 0
337 .br
338
339 # Do not create source code view if non\-zero
340 .br
341 genhtml_no_source = 0
342 .br
343
344 # Specify size of tabs
345 .br
346 genhtml_num_spaces = 8
347 .br
348
349 # Include color legend in HTML output if non\-zero
350 .br
351 genhtml_legend = 0
352 .br
353
354 # Include HTML file at start of HTML output
355 .br
356 #genhtml_html_prolog = prolog.html
357 .br
358
359 # Include HTML file at end of HTML output
360 .br
361 #genhtml_html_epilog = epilog.html
362 .br
363
364 # Use custom HTML file extension
365 .br
366 #genhtml_html_extension = html
367 .br
368
369 # Compress all generated html files with gzip.
370 .br
371 #genhtml_html_gzip = 1
372 .br
373
374 # Include sorted overview pages
375 .br
376 genhtml_sort = 1
377 .br
378
379 # Display coverage data in hierarchical directory structure
380 .br
381 # (rather than flat/3 level)
382 .br
383 #genhtml_hierarchical = 1
384 .br
385
386 # Display coverage data using 'flat' view
387 .br
388 #genhtml_flat_view = 1
389 .br
390
391 # Specify the character set of all generated HTML pages
392 .br
393 genhtml_charset=UTF\-8
394 .br
395
396 # Allow HTML markup in test case description text if non\-zero
397 .br
398 genhtml_desc_html=0
399 .br
400
401 # Specify the precision for coverage rates
402 .br
403 #genhtml_precision=1
404 .br
405
406 # Show missed counts instead of hit counts
407 .br
408 #genhtml_missed=1
409 .br
410
411 # group function aliases in report - see '--merge' section in man(1) genhtml
412 .br
413 #merge_function_aliasess = 1
414 .br
415
416 # If set, suppress list of aliases in function detail table
417 .br
418 #suppress_function_aliases = 1
419 .br
420
421 # If set, derive function end line from line coverpoint data - default ON
422 .br
423 #derive_function_end_line = 1
424 .br
425
426 # If set, derive function end lines for all file types.
427 # By default, we derive end lines for C/C++ files only
428 #
429 .br
430 #derive_end_line_all_files = 0
431 .br
432
433 # Maximum size of function (number lines) which will be checked by '--filter trivial'
434 .br
435 #trivial_function_threshold = 5
436 .br
437
438 # Set threshold for hit count which tool should deem likely to indicate
439 .br
440 # a toolchain bug (corrupt coverage data)
441 .br
442 # excessive_count_theshold = number
443 .br
444
445 # Demangle C++ symbols
446 .br
447 # Call multiple times to specify command and command line arguments
448 .br
449 # ('-Xlinker'-like behaviour)
450 .br
451 #demangle_cpp = c++filt
452 .br
453
454 # Name of the tool used for demangling C++ function names
455 .br
456 # This argument is deprecated - please use demangle_cpp' instead
457 .br
458 #genhtml_demangle_cpp_tool = c++filt
459 .br
460
461 # Specify extra parameters to be passed to the demangling tool
462 .br
463 # this argument is deprecated - use Xlinker-like demangle_cpp
464 .br
465 # parameter instead
466 .br
467 #genhtml_demangle_cpp_params = ""
468 .br
469
470 # Location of the gcov tool
471 .br
472 #geninfo_gcov_tool = gcov
473 .br
474
475 # Adjust test names if non\-zero
476 .br
477 #geninfo_adjust_testname = 0
478 .br
479
480 # Ignore testcase names in .info file
481 forget_testcase_names = 0
482
483 # Calculate and/or compute checksum for each line if non\-zero
484 .br
485 checksum = 0
486 .br
487
488 # Enable libtool compatibility mode if non\-zero
489 .br
490 geninfo_compat_libtool = 0
491 .br
492
493 # Specify whether to capture coverage data for external source
494 .br
495 # files
496 .br
497 #geninfo_external = 1
498 .br
499
500 # Specify whether to capture coverage data from compile-time data files
501 .br
502 # which have no corresponding runtime data.
503 .br
504 #geninfo_capture_all = 1
505 .br
506
507 # Use gcov's --all-blocks option if non-zero
508 .br
509 #geninfo_gcov_all_blocks = 1
510 .br
511
512 # Adjust 'executed' non-zero hit count of lines which contain no branches
513 .br
514 # and have attribute '"unexecuted_blocks": true'
515 .br
516 #geninfo_unexecuted_blocks = 0
517 .br
518
519 # Specify compatibility modes (same as \-\-compat option
520 .br
521 # of geninfo)
522 .br
523 #geninfo_compat = libtool=on, hammer=auto, split_crc=auto
524 .br
525
526 # Adjust path to source files by removing or changing path
527 .br
528 # components that match the specified pattern (Perl regular
529 .br
530 # expression format)
531 .br
532 #geninfo_adjust_src_path = /tmp/build => /usr/src
533
534 # Specify if geninfo should try to automatically determine
535 .br
536 # the base-directory when collecting coverage data.
537 .br
538 geninfo_auto_base = 1
539 .br
540
541 # Use gcov intermediate format? Valid values are 0, 1, auto
542 .br
543 geninfo_intermediate = auto
544 .br
545
546 # Specify if exception branches should be excluded from branch coverage.
547 .br
548 no_exception_branch = 0
549 .br
550
551 # Directory containing gcov kernel files
552 .br
553 lcov_gcov_dir = /proc/gcov
554 .br
555
556 # Location for temporary directories
557 .br
558 lcov_tmp_dir = /tmp
559 .br
560
561 # Show full paths during list operation if non\-zero
562 .br
563 lcov_list_full_path = 0
564 .br
565
566 # Specify the maximum width for list output. This value is
567 .br
568 # ignored when lcov_list_full_path is non\-zero.
569 .br
570 lcov_list_width = 80
571 .br
572
573 # Specify the maximum percentage of file names which may be
574 .br
575 # truncated when choosing a directory prefix in list output.
576 .br
577 # This value is ignored when lcov_list_full_path is non\-zero.
578 .br
579 lcov_list_truncate_max = 20
580
581 # Specify if function coverage data should be collected, processed, and
582 .br
583 # displayed.
584 .br
585 function_coverage = 1
586 .br
587
588 # Specify if branch coverage data should be collected, processed, and
589 .br
590 # displayed.
591 .br
592 branch_coverage = 0
593 .br
594
595 # Specify if Modified Condition / Decision Coveage data should be collected,
596 .br
597 # processed, and displayed.
598 .br
599 mcdc_coverage = 0
600 .br
601
602 # Ask lcov/genhtml/geninfo to return non-zero exit code if branch coverage is
603 .br
604 # below specified threshold percentage.
605 .br
606 fail_under_branches = 75.0
607 .br
608
609 # Ask lcov/genhtml/geninfo to return non-zero exit code if line coverage is
610 .br
611 # below specified threshold percentage.
612 .br
613 #fail_under_lines = 97.5
614 .br
615
616 # Specify JSON module to use, or choose best available if
617 .br
618 # set to auto
619 .br
620 lcov_json_module = auto
621 .br
622
623 # Specify maximum number of parallel slaves
624 .br
625 # default: 1 (no parallelism)
626 .br
627 #parallel = 1
628 .br
629
630 .br
631 # Specify maximum memory to use during parallel processing, in Mb.
632 .br
633 # Do not fork if estimated memory consumption exceeds this number.
634 .br
635 # default: 0 (no limit)
636 .br
637 #memory = 1024
638 .br
639
640 .br
641 # Specify the number of consecutive fork() failures to allow before
642 .br
643 # giving up
644 .br
645 # max_fork_fails = 5
646 .br
647
648 .br
649 # Seconds to wait after failing to fork() before retrying
650 .br
651 # fork_fail_timeout = 10
652 .br
653
654 .br
655 # Throttling control: specify a percentage of system memory to use as
656 .br
657 maximum during parallel processing.
658 .br
659 # Do not fork if estimated memory consumption exceeds the maximum.
660 .br
661 # this value is used only if the maximum memory is not set.
662 .br
663 # default: not set
664 .br
665 #memory_percentage = 75
666 .br
667
668 .br
669 # Character used to split list-type parameters
670 .br
671 # \- for example, the list of "--ignore_errors source,mismatch"
672 .br
673 # default: , (comma)
674 .br
675 #split_char = ,
676 .br
677
678
679 .br
680 # use case insensitive compare to find matching files, for include/exclude
681 .br
682 # directives, etc
683 .br
684 #case_insensitive = 0
685 .br
686
687 .br
688 # override line default line exclusion regexp
689 .br
690 #lcov_excl_line = LCOV_EXCL_LINE
691 .br
692
693 .br
694 # override branch exclusion regexp
695 .br
696 #lcov_excl_br_line = LCOV_EXCL_BR_LINE
697 .br
698
699 .br
700 # override exception branch exclusion regexp
701 .br
702 #lcov_excl_exception_br_line = LCOV_EXCL_EXCEPTION_BR_LINE
703 .br
704
705 .br
706 # override start of exclude region regexp
707 .br
708 #lcov_excl_start = LCOV_EXCL_START
709 .br
710
711 .br
712 # override end of exclude region regexp
713 .br
714 #lcov_excl_stop = LCOV_EXCL_STOP
715 .br
716
717 .br
718 # override start of branch exclude region regexp
719 .br
720 #lcov_excl_br_start = LCOV_EXCL_BR_START
721 .br
722
723 .br
724 # override start of exclude region regexp
725 .br
726 #lcov_excl_br_stop = LCOV_EXCL_BR_STOP
727 .br
728
729 .br
730 # override start of exclude region regexp
731 .br
732 #lcov_excl_exception_br_start = LCOV_EXCL_EXCEPTION_BR_START
733 .br
734
735 .br
736 # override start of exclude region regexp
737 .br
738 #lcov_excl_exception_br_stop = LCOV_EXCL_EXCEPTION_BR_STOP
739
740 .PP
741
742 .SH OPTIONS
743
744 .BR config_file " ="
745 .I filename
746 .IP
747
748 Include another config file.
749
750 Inclusion is equivalent to inserting the text from
751 .I filename
752 at this point in the current file. As a result, settings from the included
753 file are processed after earlier settings in the current file, but before later settings from the current file.
754 As a result:
755
756 .BR "Scalar options"
757 set earlier in the current file are overridden by settings from the included file, and scalar options from the included file are overridden by later setting in the current file.
758
759 .BR "Array options"
760 from earlier in the current file appear before setting from the included file, and array options from later in the current file appear after.
761
762 Config file inclusion is recursive: an included config file may include another file - and so on.
763 Inclusion loops are not supported and will result in a
764 .I usage
765 error.
766
767 The most common usecase for config file inclusion is so that a site-wide or project-wide options file can include a user-specific or module-specific options file - for example, as
768
769 .RS 3
770 .IP
771 ...
772 .br
773 config_file = $ENV{HOME}/.lcovrc_user
774 .br
775 ...
776 .PP
777 .RE
778
779
780 .PP
781
782 .BR genhtml_css_file " ="
783 .I filename
784 .IP
785 Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by
786 .BR genhtml .
787 During output generation, a copy of this file will be placed in the output
788 directory.
789 .br
790
791 This option corresponds to the \-\-css\-file command line option of
792 .BR genhtml .
793 .br
794
795 By default, a standard CSS file is generated.
796 .PP
797
798 .BR genhtml_header " ="
799 .I string
800 .IP
801
802 Specify header text to use ta top of each HTML page.
803 .br
804
805 This option corresponds to the \-\-header\-title command line option of
806 .BR genhtml .
807 .br
808 Default is "LCOV - (differential )? coverage report"
809
810 .PP
811
812 .BR genhtml_footer " ="
813 .I string
814 .IP
815 Specify footer text to use at bottom of each HTML page.
816 .br
817
818 This option corresponds to the \-\-footer command line option of
819 .BR genhtml .
820 .br
821
822 Default is LCOV tool version string.
823
824 .PP
825
826 .BR genhtml_dark_mode " ="
827 .IR 0 | 1
828 .IP
829 If non-zero, display using light text on dark background rather than dark text on light background.
830 .br
831
832 This option corresponds to the \-\-dark\-mode command line option of
833 .BR genhtml .
834 .br
835
836 By default, a 'light' palette is used.
837 .PP
838
839 .BR genhtml_hi_limit " ="
840 .I hi_limit
841 .br
842 .BR genhtml_med_limit " ="
843 .I med_limit
844 .br
845 .IP
846 Specify coverage rate limits for classifying file entries. Use this option to
847 modify the coverage rates (in percent) for line, function and branch coverage at
848 which a result is classified as high, medium or low coverage. This
849 classification affects the color of the corresponding entries on the overview
850 pages of the HTML output:
851 .br
852
853 High: hi_limit <= rate <= 100 default color: green
854 .br
855 Medium: med_limit <= rate < hi_limit default color: yellow
856 .br
857 Low: 0 <= rate < med_limit default color: red
858 .br
859
860 Defaults are 90 and 75 percent.
861
862 There are also options to configure different thresholds for line, branch, and function coverages. See below.
863 .PP
864
865 .BR genhtml_line_hi_limit " ="
866 .I line_hi_limit
867 .br
868 .BR genhtml_line_med_limit " ="
869 .I line_med_limit
870 .br
871 .IP
872 Specify specific threshold for line coverage limits used to decide whether a particular line coverage percentage is classified as high, medium, or low coverage.
873 If the line-specific values are not specified, then the default
874 .I genhtml_med_limit
875 or
876 .I genhtml_hi_limit
877 values are used.
878 .PP
879
880 .BR genhtml_branch_hi_limit " ="
881 .I branch_hi_limit
882 .br
883 .BR genhtml_branch_med_limit " ="
884 .I branch_med_limit
885 .br
886 .IP
887 Specify specific threshold for branch coverage limits used to decide whether a particular branch coverage percentage is classified as high, medium, or low coverage.
888 If the branch-specific values are not specified, then the default
889 .I genhtml_med_limit
890 or
891 .I genhtml_hi_limit
892 values are used.
893 .PP
894
895 .BR genhtml_function_hi_limit " ="
896 .I function_hi_limit
897 .br
898 .BR genhtml_function_med_limit " ="
899 .I function_med_limit
900 .br
901 .IP
902 Specify specific threshold for function coverage limits used to decide whether a particular function coverage percentage is classified as high, medium, or low coverage.
903 If the function-specific values are not specified, then the default
904 .I genhtml_med_limit
905 or
906 .I genhtml_hi_limit
907 value is used.
908 .PP
909
910 .BR rtl_file_extensions " ="
911 .IR str[,str]+
912 .IP
913 Specify a comma-separated list of file extensions which should be assumed to be RTL code (e.g., Verilog).
914 .br
915
916 If not specified, the default set is 'v,vh,sv,vhdl?'.
917 There is no command line option equivalent.
918 .br
919 This option is used by genhtml and lcov.
920
921 .PP
922
923 .BR info_file_pattern " ="
924 .IR str
925 .IP
926 Specify a glob-match pattern associated with lcov trace files (suitable as an argument to 'find'.
927 If not specified, the default is '*.info'.
928
929 .PP
930
931 .BR c_file_extensions " ="
932 .IR str[,str]+
933 .IP
934 Specify a comma-separated list of file extensions which should be assumed to be C/C++ code.
935 .br
936
937 If not specified, the default set is 'c,h,i,C,H,I,icc,cpp,cc,cxx,hh,hpp,hxx'.
938 If you want all files to be treated as C/C++ code, you can use:
939 .I c_file_extensions = .*
940
941 This parameter must be set from the lcovrc file or via the
942 .I \-\-rc name=value
943 command line option; note that you may need to protect the value from shell expansion in the latter case.
944 .br
945
946 .PP
947
948 .BR java_file_extensions " ="
949 .IR str[,str]+
950 .IP
951 Specify a comma-separated list of file extensions which should be assumed to be Java code.
952 .br
953
954 If not specified, the default set is 'java'.
955 If you want all files to be treated as Java code, you can use:
956 .I java_file_extensions = .*
957
958 This parameter must be set from the lcovrc file or via the
959 .I \-\-rc name=value
960 command line option; note that you may need to protect the value from shell expansion in the latter case.
961 .br
962
963 .PP
964
965 .BR perl_file_extensions " ="
966 .IR str[,str]+
967 .IP
968 Specify a comma-separated list of file extensions which should be assumed to be Perl code.
969 .br
970
971 If not specified, the default set is 'pl,pm'.
972 If you want all files to be treated as Perl code, you can use:
973 .I perl_file_extensions = .*
974
975 This parameter must be set from the lcovrc file or via the
976 .I \-\-rc name=value
977 command line option; note that you may need to protect the value from shell expansion in the latter case.
978 .br
979
980 .PP
981
982 .BR python_file_extensions " ="
983 .IR str[,str]+
984 .IP
985 Specify a comma-separated list of file extensions which should be assumed to be Python code.
986 .br
987
988 If not specified, the default set is 'py'.
989 If you want all files to be treated as Python code, you can use:
990 .I python_file_extensions = .*
991
992 This parameter must be set from the lcovrc file or via the
993 .I \-\-rc name=value
994 command line option; note that you may need to protect the value from shell expansion in the latter case.
995 .br
996
997
998 .PP
999
1000 .BR filter_lookahead " ="
1001 .IR integer
1002 .IP
1003 Specify the maximum number of lines to look at when filtering bogus branch expressions.
1004 A larger number may catch more cases, but will increase execution time.
1005 .br
1006
1007 If not specified, the default set is 10.
1008 There is no command line option equivalent.
1009 .br
1010 This option is used by genhtml and lcov.
1011
1012 .PP
1013
1014 .BR filter_bitwise_conditional " ="
1015 .IR 0|1
1016 .IP
1017 If set to non-zero value, bogus branch filtering will assume that expressions containing bitwise operators '&', '|', '~' are conditional expressions - and will not filter them out.
1018 .br
1019
1020 If not specified, the default set is 0 (do not treat them as conditional).
1021 There is no command line option equivalent.
1022 .br
1023 This option is used by genhtml and lcov.
1024
1025 .PP
1026
1027 .BR filter_blank_aggressive " ="
1028 .IR 0|1
1029 .IP
1030 If set to non-zero value, then blank source lines will be ignored whether
1031 or not their 'hit' count is zero.
1032 See the
1033 .I \-\-filter blank
1034 section in man
1035 .B genhtml(1).
1036 .br
1037
1038 If not specified, the default set is 0 (filter blank lines only if they are not hit).
1039 .br
1040 There is no command line option equivalent.
1041
1042 .PP
1043
1044 .BR ignore_errors " ="
1045 .IR message_type(,message_type)*
1046 .IP
1047 Specify a message type which should be ignored.
1048 .br
1049
1050 This option can be used multiple times in the lcovrc file to ignore multiple message types.
1051
1052 This option is equivalent to the \-\-ignore\-errors option to geninfo, genhtml, or lcov. Note that the lcovrc file message list is not applied (those messages NOT ignored) if the '\-\-ignore\-errors' command line option is specified.
1053 .br
1054 This option is used by genhtml, lcov, and geninfo.
1055
1056 .PP
1057
1058 .BR expect_message_count " ="
1059 .IR message_type:expr(,message_type:expr)*
1060 .IP
1061 Specify
1062 a constraint on the number of messages of one or more types which are expected to
1063 be produced during tool execution. If the constraint is not true, an
1064 error of type
1065 .I "count"
1066 will be generated.
1067
1068 Multiple constraints can be specified using a comma-separated list or
1069 by using the option multiple times.
1070
1071
1072 Substitutions are performed on the expression before it is evaluated:
1073
1074 For example:
1075
1076 .RS 3
1077
1078 .IP \- 3
1079 expect_message_count = inconsistent : %C == 5
1080 .br
1081 says that you expect exactly 5 messages of this type
1082 .PP
1083
1084 .IP \- 3
1085 expect_message_count inconsistent : %C > 6 && %C <= 10
1086 .br
1087 says that you expect the number of messages to be in the range (6:10].
1088 .PP
1089
1090 .RE
1091
1092 This option is useful if errors are caused by conditions that you cannot
1093 fix - for example, due to inconsistent coverage data generated by your
1094 toolchain. In those scenarios, you may decide:
1095
1096 .RS 3
1097
1098 .IP \- 3
1099 to exclude the offending code, or
1100 .PP
1101 .IP \- 3
1102 to exclude the entire offending file(s), or
1103 .PP
1104 .IP \- 3
1105 to ignore the
1106 messages, either by converting them to warnings or suppressing them entirely.
1107 .PP
1108 .RE
1109
1110 In the latter case, this option provides some additional safety by warning
1111 you when the count differs due to some change which occurred, giving you
1112 the opportunity to diagnose the change and/or to review message changes.
1113
1114 This option is equivalent to the
1115 .I "\-\-expect\-message\-count"
1116 command line flag.
1117
1118 .PP
1119
1120 .BR max_message_count " ="
1121 .IR integer
1122 .IP
1123 Set the maximum number of warnings of any particular type which should be emitted. This can be used to reduce the size of log files.
1124 .br
1125
1126 No more warnings will be printed after this number is reached. 0 (zero) is interpreted as 'no limit'.
1127 .br
1128 This option is used by genhtml, lcov, and geninfo.
1129
1130 .PP
1131
1132 .BR stop_on_error " = "
1133 .IR 0|1
1134 .IP
1135 If set to 0, tell the tools to ignore errors and keep going to try to generate a result - however flawed or incomplete that result might be.
1136 Note that some errors cannot be ignored and that ignoring some errors may lead to other errors.
1137 .br
1138 The tool will return a non-zero exit code if one or more errors are detected
1139 during execution when
1140 .I stop_on_error
1141 is disabled. That is, the tool will continue execution in the presence
1142 of errors but will return an exit status.
1143
1144 .br
1145
1146 This is equivalent to the
1147 .I '\-\-keep\-going'
1148 command line option.
1149
1150 Default is 1: stop when error occurs.
1151
1152 If the
1153 .I 'ignore_error msgType'
1154 option is also used, then those messages will be treated as warnings rather than errors (or will be entirely suppressed if the message type appears multiple times in the ignore_messages option). Warnings do not cause a non-zero exit status.
1155
1156 This option is used by genhtml, lcov, and geninfo.
1157
1158
1159 .PP
1160
1161 .BR treat_warning_as_error " = "
1162 .IR 0|1
1163 .IP
1164 If set to 1, tell the tools that messages which are normally treated as
1165 warnings (
1166 .I e.g.,
1167 certain usage messages) should be treated as errors.
1168
1169 Note that ignored messages will still appear as warnings: see the
1170 .I ignore_errors
1171 entry, above.
1172
1173 This option is used by genhtml, lcov, and geninfo.
1174
1175 .PP
1176
1177 .BR warn_once_per_file " = "
1178 .IR 0|1
1179 .IP
1180 If set to 1, tell the tools to emit certain errors only once per file
1181 (rather than multiple times, if the issue occurs multiple times in the same
1182 file).
1183
1184 Default is 1: do not report additional errors.
1185
1186 This option is used by genhtml, lcov, and geninfo.
1187
1188 .PP
1189
1190 .BR check_data_consistency " = "
1191 .IR 0|1
1192 .IP
1193 If set to 1, tell the tools to execute certain data consistency checks -
1194 .I e.g.,
1195 that function with a non-zero hit count contains at least one line with a non-zero
1196 hit count - and vice versa.
1197
1198 It may be useful to use this option to disable checking if you have inconsistent
1199 legacy data and have
1200 no way to correct or exclude it.
1201
1202 Default is 1: execute consistency checks.
1203
1204 .PP
1205
1206 .BR genhtml_line_field_width " ="
1207 .I number_of_characters
1208 .IP
1209 Specify the width (in characters) of the source code view column containing
1210 line coverage information.
1211 .br
1212
1213 Default is 12.
1214 .PP
1215
1216 .BR genhtml_branch_field_width " ="
1217 .I number_of_characters
1218 .IP
1219 Specify the width (in characters) of the source code view column containing
1220 branch coverage information.
1221 .br
1222
1223 Default is 16.
1224 .PP
1225
1226 .BR genhtml_mcdc_field_width " ="
1227 .I number_of_characters
1228 .IP
1229 Specify the width (in characters) of the source code view column containing
1230 MC/DC coverage information.
1231 .br
1232
1233 Default is 14.
1234 .PP
1235
1236 .BR genhtml_owner_field_width " ="
1237 .I number_of_characters
1238 .IP
1239 Specify the width (in characters) of the source code view column containing
1240 owner information (as reported by your annotation script. This option has an effect only if you are using a source annotation script: see the \-\-annotation-script option in the genhtml man page.
1241 .br
1242
1243 Default is 20.
1244 .PP
1245
1246 .BR genhtml_age_field_width " ="
1247 .I number_of_characters
1248 .IP
1249 Specify the width (in characters) of the source code view column containing
1250 age of the corresponding block (as reported by your annotation script). This option has an effect only if you are using a source annotation script: see the \-\-annotation-script option in the genhtml man page.
1251 .br
1252
1253 Default is 5.
1254 .PP
1255
1256 .BR genhtml_frames " ="
1257 .I 0 | 1
1258 .IP
1259 Specify whether source detail view should contain a navigation image.
1260 See the
1261 .I \-\-frame
1262 entry in the
1263 .B genhtml
1264 man page.
1265 .PP
1266
1267 .BR genhtml_overview_width " ="
1268 .I pixel_size
1269 .IP
1270 Specify the width (in pixel) of the overview image created when generating HTML
1271 output using the \-\-frames option of
1272 .BR genhtml .
1273 .br
1274
1275 Default is 80.
1276 .PP
1277
1278 .BR genhtml_nav_resolution " ="
1279 .I lines
1280 .IP
1281 Specify the resolution of overview navigation when generating HTML output using
1282 the \-\-frames option of
1283 .BR genhtml .
1284 This number specifies the maximum difference in lines between the position a
1285 user selected from the overview and the position the source code window is
1286 scrolled to.
1287 .br
1288
1289 Default is 4.
1290 .PP
1291
1292
1293 .BR genhtml_nav_offset " ="
1294 .I lines
1295 .IP
1296 Specify the overview navigation line offset as applied when generating HTML
1297 output using the \-\-frames option of
1298 .BR genhtml.
1299 .br
1300
1301 Clicking a line in the overview image should show the source code view at
1302 a position a bit further up, so that the requested line is not the first
1303 line in the window. This number specifies that offset.
1304 .br
1305
1306 Default is 10.
1307 .PP
1308
1309
1310 .BR genhtml_keep_descriptions " ="
1311 .IR 0 | 1
1312 .IP
1313 If non\-zero, keep unused test descriptions when generating HTML output using
1314 .BR genhtml .
1315 .br
1316
1317 This option corresponds to the \-\-keep\-descriptions option of
1318 .BR genhtml .
1319 .br
1320
1321 Default is 0.
1322 .PP
1323
1324 .BR genhtml_no_prefix " ="
1325 .IR 0 | 1
1326 .IP
1327 If non\-zero, do not try to find and remove a common prefix from directory names.
1328 .br
1329
1330 This option corresponds to the \-\-no\-prefix option of
1331 .BR genhtml .
1332 .br
1333
1334 Default is 0.
1335 .PP
1336
1337 .BR genhtml_no_source " ="
1338 .IR 0 | 1
1339 .IP
1340 If non\-zero, do not create a source code view when generating HTML output using
1341 .BR genhtml .
1342 .br
1343
1344 This option corresponds to the \-\-no\-source option of
1345 .BR genhtml .
1346 .br
1347
1348 Default is 0.
1349 .PP
1350
1351 .BR genhtml_num_spaces " ="
1352 .I num
1353 .IP
1354 Specify the number of spaces to use as replacement for tab characters in the
1355 HTML source code view as generated by
1356 .BR genhtml .
1357 .br
1358
1359 This option corresponds to the \-\-num\-spaces option of
1360 .BR genhtml .
1361 .br
1362
1363 Default is 8.
1364
1365 .PP
1366
1367 .BR genhtml_legend " ="
1368 .IR 0 | 1
1369 .IP
1370 If non\-zero, include a legend explaining the meaning of color coding in the HTML
1371 output as generated by
1372 .BR genhtml .
1373 .br
1374
1375 This option corresponds to the \-\-legend option of
1376 .BR genhtml .
1377 .br
1378
1379 Default is 0.
1380 .PP
1381
1382 .BR genhtml_html_prolog " ="
1383 .I filename
1384 .IP
1385 If set, include the contents of the specified file at the beginning of HTML
1386 output.
1387
1388 This option corresponds to the \-\-html\-prolog option of
1389 .BR genhtml .
1390 .br
1391
1392 Default is to use no extra prolog.
1393 .PP
1394
1395 .BR genhtml_html_epilog " ="
1396 .I filename
1397 .IP
1398 If set, include the contents of the specified file at the end of HTML output.
1399
1400 This option corresponds to the \-\-html\-epilog option of
1401 .BR genhtml .
1402 .br
1403
1404 Default is to use no extra epilog.
1405 .PP
1406
1407 .BR genhtml_html_extension " ="
1408 .I extension
1409 .IP
1410 If set, use the specified string as filename extension for generated HTML files.
1411
1412 This option corresponds to the \-\-html\-extension option of
1413 .BR genhtml .
1414 .br
1415
1416 Default extension is "html".
1417 .PP
1418
1419 .BR genhtml_html_gzip " ="
1420 .IR 0 | 1
1421 .IP
1422 If set, compress all html files using gzip.
1423
1424 This option corresponds to the \-\-html\-gzip option of
1425 .BR genhtml .
1426 .br
1427
1428 Default extension is 0.
1429 .PP
1430
1431 .BR genhtml_sort " ="
1432 .IR 0 | 1
1433 .IP
1434 If non\-zero, create overview pages sorted by coverage rates when generating
1435 HTML output using
1436 .BR genhtml .
1437 .br
1438
1439 This option can be set to 0 by using the \-\-no\-sort option of
1440 .BR genhtml .
1441 .br
1442
1443 Default is 1.
1444 .PP
1445
1446 .BR genhtml_hierarchical " ="
1447 .IR 0 | 1
1448 .IP
1449 If non\-zero, the HTML report will follow the hierarchical directory structure of the source code.
1450 .br
1451
1452 This option is equivalent to using the \-\-hierarchical command line option of
1453 .BR genhtml .
1454 'Hierarchical' and 'flat' views are mutually exclusive.
1455 .br
1456
1457 Default is 0.
1458 .PP
1459
1460 .BR genhtml_flat_view " ="
1461 .IR 0 | 1
1462 .IP
1463 If non\-zero, the top-level HTML table will contain all of the files in the project and there will be no intermediate directory pages.
1464 .br
1465
1466 This option is equivalent to using the \-\-flat command line option of
1467 .BR genhtml .
1468 'Hierarchical' and 'flat' views are mutually exclusive.
1469 .br
1470
1471 Default is 0.
1472 .PP
1473
1474 .BR genhtml_show_navigation " ="
1475 .IR 0 | 1
1476 .IP
1477 If non\-zero, the 'source code' view summary table will contain hyperlinks from the number to the first source line in the corresponding category ('Hit' or 'Not hit') in the non-differential coverage report.
1478 Source code hyperlinks are always enabled in differential coverage reports.
1479 .br
1480
1481 This option is equivalent to using the \-\-show\-navigation command line option of
1482 .BR genhtml .
1483 .br
1484
1485 Default is 0.
1486 .PP
1487
1488 .BR genhtml_show_owner_table " ="
1489 .IR 0 | 1 | all
1490 .IP
1491 If non\-zero, equivalent to the genhtml
1492 .I \-\-shwow\-owners
1493 flag: see man
1494 .B genhtml(1)
1495 for details.
1496 .br
1497
1498 Default is 0.
1499 .PP
1500
1501 .BR compact_summary_tables " ="
1502 .IR 0 | 1
1503 .IP
1504 If non\-zero, suppress the 'Total' row in the 'date' and 'owner' summary table if there is only one element in the corresponding bin.
1505 .br
1506 When there are a large number of files with a single author, this can cut the summary table size by almost half.
1507 .br
1508
1509 Default is 1 (enabled).
1510 .PP
1511
1512 .BR owner_table_entries " ="
1513 .IR integer
1514 .IP
1515 This option is used to tell genhtml the number of 'owner' table entries to
1516 retain in the summary table (at the top of the page) if owner table truncation is requested. Authors are sorted by quantity of un-exercised code - so elided entries will be smaller offenders: maximal offenders are retained.
1517 If the option is not set, then owner tables are not truncated.
1518
1519 This option has no effect unless
1520 .I "genhtml \-\-show\-owners"
1521 is enabled.
1522 See the
1523 .I \-\-show-owners
1524 option in
1525 .B genhtml(1)
1526 for details.
1527
1528 .br
1529
1530 Default is not set (
1531 .I i.e.,
1532 do not truncate owner tables).
1533 .PP
1534
1535 .BR truncate_owner_table " ="
1536 .IR comma_separated_list
1537 .IP
1538 This option is used to tell genhtml whether to truncate the 'owner' table
1539 at the top, directory, or file level.
1540 This option acts together with the
1541 .I owner_table_entries
1542 parameter to determine how many author entries are retained.
1543
1544 This option has no effect unless
1545 .I "genhtml \-\-show\-owners"
1546 is enabled and and the
1547 .I owner_table_entries
1548 configuration is set.
1549
1550 If this option is set multiple times in the lcovrc file, the values are
1551 combined to form the list of levels where truncation will occur.
1552 Similarly, if this option is not set and
1553 .I owner_table_entries
1554 is set, then the table will be truncated everywhere.
1555
1556 See the
1557 .I \-\-show-owners
1558 option in
1559 .B genhtml(1)
1560 for details.
1561 .br
1562
1563 Default is to not truncate the list.
1564 .PP
1565
1566
1567
1568 .BR genhtml_show_noncode_owners " ="
1569 .IR 0 | 1
1570 .IP
1571 If non\-zero, equivalent to the genhtml
1572 .I \-\-shwow\-noncode
1573 flag: see man
1574 .B genhtml(1)
1575 for details.
1576 .br
1577
1578 Default is 0.
1579 .PP
1580
1581 .BR genhtml_show_function_proportion " ="
1582 .IR 0 | 1
1583 .IP
1584
1585 If nonzero, add column to "function coverage detail" table to show the proportion of lines and branches within the function which are exercised.
1586 .br
1587
1588 This option is equivalent to using the \-\-show\-proportion command line option of
1589 .BR genhtml .
1590 .br
1591
1592 Default is 0.
1593 .PP
1594
1595 .BR genhtml_synthesize_missing " ="
1596 .IR 0 | 1
1597 .IP
1598 If non\-zero, equivalent to the genhtml
1599 .I \-\-synthesize\-missing
1600 flag: see man
1601 .B genhtml(1)
1602 for details.
1603 .br
1604
1605 Default is 0.
1606 .PP
1607
1608 .BR genhtml_charset " ="
1609 .I charset
1610 .IP
1611 Specify the character set of all generated HTML pages.
1612 .br
1613
1614 Use this option if the source code contains characters which are not
1615 part of the default character set. Note that this option is ignored
1616 when a custom HTML prolog is specified (see also
1617 .BR genhtml_html_prolog ).
1618 .br
1619
1620 Default is UTF-8.
1621 .PP
1622
1623 .BR demangle_cpp " ="
1624 .IR c++filt
1625 .IP
1626 If set, this option tells genhtml/lcov/geninfo to demangle C++ function names in function overviews,
1627 and gives the name of the tool used for demangling.
1628 Set this option to one if you want to convert C++ internal function
1629 names to human readable format for display on the HTML function overview
1630 page.
1631
1632 If the
1633 .I demangle_cpp
1634 option is used multiple times, then the arguments are concatenated when the callback
1635 is executed - similar to how the gcc
1636 .I \-Xlinker
1637 parameter works. This provides a possibly easier way to pass arguments to
1638 your tool, without requiring a wrapper script.
1639 In that case, your callback will be executed as:
1640 .I | tool\-0 'tool\-1; ...
1641 Arguments are quoted when passed to
1642 the shell, in order to handle parameters which contain spaces.
1643
1644 Note that the demangling tool is called via a pipe, and is expected to read from stdin and write to stdout.
1645
1646 This option corresponds to the \-\-demangle\-cpp command line option of
1647 .BR genhtml .
1648 .br
1649
1650 Default is not set (C++ demangling is disabled).
1651 .PP
1652
1653 .BR genhtml_demangle_cpp_tool " ="
1654 .I path_to_c++filt
1655 .IP
1656 Specify the location of the demangle tool (see
1657 .BR c++filt (1))
1658 used to convert C++ internal function names to human readable format
1659 for display on the HTML function overview page.
1660
1661 This option is deprecated and will be removed from a future lcov release.
1662 Please use
1663 .I demangle_cpp = path_to_c++filt
1664 instead.
1665
1666 .PP
1667
1668 .BR genhtml_demangle_cpp_params " ="
1669 .I parameters
1670 .IP
1671 Specify extra parameters to be passed to the demangling tool
1672
1673 Use this option if your environment requires additional parameters such
1674 as --no-strip-underscore for correctly demangling C++ internal function
1675 names. See also
1676 .BR c++filt (1)).
1677 .br
1678
1679 This argument is deprecated. Please use the Xlinker-like
1680 .I demangle_cpp
1681 argument instead.
1682
1683 .PP
1684
1685 .BR genhtml_desc_html " ="
1686 .IR 0 | 1
1687 .IP
1688 If non-zero, test case descriptions may contain HTML markup.
1689
1690 Set this option to one if you want to embed HTML markup (for example to
1691 include links) in test case descriptions. When set to zero, HTML markup
1692 characters will be escaped to show up as plain text on the test case
1693 description page.
1694 .br
1695
1696 Default is 0.
1697 .PP
1698
1699 .BR genhtml_precision " ="
1700 .IR 1 | 2 | 3 | 4
1701 .IP
1702 Specify how many digits after the decimal-point should be used for
1703 displaying coverage rates.
1704 .br
1705
1706 Default is 1.
1707 .PP
1708 .BR merge_function_aliases " ="
1709 .IR 0 | 1
1710 .IP
1711 If non-zero, group function aliases in the function detail tabile.
1712 See man(1) genhtml.
1713 .br
1714
1715 Default is 0.
1716 .PP
1717
1718 .PP
1719 .BR genhtml_missed " ="
1720 .IR 0 | 1
1721 .IP
1722 If non-zero, the count of missed lines, functions, or branches is shown
1723 as negative numbers in overview pages.
1724 .br
1725
1726 Default is 0.
1727 .PP
1728
1729 .BR suppress_function_aliases " ="
1730 .IR 0 | 1
1731 .IP
1732 If non-zero, do not show aliases in the function detail table.
1733 .br
1734 If nonzero, implies that
1735 .B merge_function_aliases
1736 is enabled.
1737 .br
1738 See the genhtml man page for more details.
1739 .br
1740
1741 Default is 0.
1742 .PP
1743
1744 .BR derive_function_end_line " ="
1745 .IR 0 | 1
1746 .IP
1747 If non-zero, use 'line' coverage data to deduce the end line of each function
1748 definition. This is useful when excluding certain functions from your coverage report. See the
1749 .I \-\-erase\-functions,
1750 .I \-\-filter trivial
1751 and
1752 .I \-\-show\-proportion
1753 options.
1754
1755 Default is 1.
1756
1757 This option is not required if you are using gcc/9 or newer; these versions report function begin/end lines directly.
1758
1759 Note that end lines are derived only for C/C++ files unless the
1760 .I derive_function_end_lines_all_files
1761 option is enabled; see the
1762 .I c_file_extensions
1763 setting, above, for the list of extensions used to identify C/C++ these files.
1764 .br
1765 Lambda functions are ignored during end line computation. Note that lambdas
1766 are identified via function name matching - so you must enable demangling
1767 if your toolchain is too old to report demangled names in the GCOV output.
1768 See the
1769 .I demangle_cpp
1770 setting, above.
1771
1772 For languages other than C/C++: end-line derivation may compute the wrong
1773 value -
1774 .I e.g.,
1775 in cases where there are lines of code in global scope following
1776 some function definition. In this case, lcov will incorrectly associate the
1777 following code with the preceding function.
1778 .br
1779 If this creates problems - for example, causes lcov to warn about inconsistent
1780 coveage data - then there are several possible workarounds:
1781
1782 .RS
1783 .IP \- 3
1784 disable end-line derivation -
1785 .I e.g.,
1786 via
1787 .I "\-\-rc derive_function_end_line=0".
1788 .PP
1789 .IP \- 3
1790 exclude the offending code and/or then entire associated file.
1791 .PP
1792 .IP \- 3
1793 ignore the error message,
1794 .I e.g.,
1795 via the
1796 .I \-\-ignore\-errors
1797 command line option
1798 .PP
1799 .IP \- 3
1800 disable coverage DB consistency checks -
1801 .I e.g.,
1802 via
1803 .I "\-\-rc check_data_consistency=0".
1804 .PP
1805 .RE
1806 .
1807 .PP
1808
1809 .BR derive_function_end_line_all_files " ="
1810 .IR 0 | 1
1811 .IP
1812 If non-zero, derive end lines for all functions, regardless of source language.
1813 By default, end lines are computed only in C/C++ files.
1814 .br
1815 This option has no effect if
1816 .I derive_function_end_lines
1817 is disabled.
1818
1819 Default is 0 (disabled).
1820 .PP
1821
1822 .BR trivial_function_threshold " ="
1823 .IR integer
1824 .IP
1825 Set the maximum size of function (in number of lines) which will be checked
1826 by
1827 .I \-\-filter trivial filter.
1828 .br
1829
1830 Default is 5.
1831 .PP
1832
1833 .BR excessive_count_threshold " ="
1834 .IR number
1835 .IP
1836 Set the threshold for hit count that lcov deems excessive/unlikely/indicating
1837 a bug somewhere in your toolchain.
1838 .br For example, it is unlikely that your job can run long enough to rack up
1839 tens of billions of hits.
1840 .br Message type
1841 .B excessive
1842 is used to report potential issue - see the
1843 .B genhtml(1), lcov(1), geninfo(1)
1844 man pages.
1845
1846 Default is not set. (Do not check for excessive counts.)
1847 .PP
1848
1849 .
1850 .BR geninfo_gcov_tool " ="
1851 .I path_to_gcov
1852 .IP
1853 Specify the location of the gcov tool (see
1854 .BR gcov (1))
1855 which is used to generate coverage information from data files.
1856 .br
1857
1858 This option can be used multiple times - e.g., to add arguments to the gcov
1859 callback. See the geninfo man page for details.
1860
1861 .PP
1862
1863 .BR geninfo_adjust_testname " ="
1864 .IR 0 | 1
1865 .IP
1866 If non\-zero, adjust test names to include operating system information
1867 when capturing coverage data.
1868 .br
1869
1870 Default is 0.
1871 .PP
1872
1873 .BR forget_testcase_names " ="
1874 .IR 0 | 1
1875 .IP
1876 If non\-zero, ignore testcase names in .info file.
1877 This may improve performance and reduce memory consumption if user does
1878 not need per-testcase coverage summary in coverage reports.
1879
1880 This is equivalent to the "\-\-forget\-test\-names" lcov/genhtml option.
1881 .br
1882
1883 Default is 0.
1884 .PP
1885
1886 .BR geninfo_checksum " ="
1887 .IR 0 | 1
1888 .br
1889 .BR checksum " ="
1890 .IR 0 | 1
1891 .IP
1892 If non\-zero, generate source code checksums when capturing coverage data.
1893 Checksums are useful to prevent merging coverage data from incompatible
1894 source code versions but checksum generation increases the size of coverage
1895 files and the time used to generate those files.
1896 .br
1897
1898 The backward compatible
1899 .I geninfo_checksum
1900 option is deprecated. Please use
1901 .I checksum
1902 instead. The new option is preferred as it is more clear that the option is used by lcov and genhtml as well as geninfo,
1903 .br
1904
1905 This option can be overridden by the \-\-checksum and \-\-no\-checksum command line
1906 options.
1907 .br
1908
1909 Default is 0.
1910
1911 Note that this options is somewhat subsumed by the
1912 .I version_script
1913 option - which does something similar, but at the 'whole file' level.
1914
1915 .PP
1916
1917 .BR geninfo_compat_libtool " ="
1918 .IR 0 | 1
1919 .IP
1920 If non\-zero, enable libtool compatibility mode. When libtool compatibility
1921 mode is enabled, lcov will assume that the source code relating to a .da file
1922 located in a directory named ".libs" can be found in its parent directory.
1923 .br
1924
1925 This option corresponds to the \-\-compat\-libtool and \-\-no\-compat\-libtool
1926 command line option of
1927 .BR geninfo .
1928 .br
1929
1930 Default is 1.
1931 .PP
1932
1933 .BR geninfo_external " ="
1934 .IR 0 | 1
1935 .IP
1936 If non\-zero, capture coverage data for external source files.
1937
1938 External source files are files which are not located in one of the directories
1939 (including sub-directories)
1940 specified by the \-\-directory or \-\-base\-directory options of
1941 .BR lcov / geninfo .
1942 Also see the
1943 .I \-\-follow
1944 option and the
1945 .I geninfo_follow_symlinks
1946 and
1947 .I geninfo_follow_file_links
1948 for additional path controls.
1949
1950 Default is 1.
1951 .PP
1952
1953 .BR geninfo_capture_all " ="
1954 .IR 0 | 1
1955 .IP
1956 If non\-zero, capture coverage data from both runtime data files as
1957 well as compile time data files which have no corresponding runtime data.
1958 See the
1959 .I \-\-all
1960 flag description in
1961 .B man(1) geninfo
1962 for more information.
1963
1964 Default is 0: do not process bare compile-time data files.
1965 .PP
1966
1967 .BR geninfo_external " ="
1968 .IR 0 | 1
1969 .IP
1970 If non\-zero, capture coverage data for external source files.
1971
1972 External source files are files which are not located in one of the directories
1973 (including sub-directories)
1974 specified by the \-\-directory or \-\-base\-directory options of
1975 .BR lcov / geninfo .
1976 Also see the
1977 .I \-\-follow
1978 option and the
1979 .I geninfo_follow_file_links
1980 for additional path controls.
1981
1982 Default is 1.
1983 .PP
1984
1985 .BR geninfo_follow_symlinks " ="
1986 .IR 0 | 1
1987 .IP
1988 Equivalent to the lcov/geninfo
1989 .I \-\-follow
1990 command line option.
1991 See man
1992 .B geninfo(1)
1993 for details.
1994
1995 Default is 0: do not modify follow symbolic links.
1996 .PP
1997
1998 .BR geninfo_follow_file_links " ="
1999 .IR 0 | 1
2000 .IP
2001 If non\-zero and the lcov/geninfo
2002 .I \-\-follow
2003 command line option is specified, then source file pathnames which contain
2004 symlinks are resolved to their actual target.
2005 Note that the parent directory of the link target may be considered 'external'
2006 and thus be removed by the
2007 .I \-\-no\-external
2008 flag.
2009
2010 Default is 0: do not modify pathnames.
2011 .PP
2012
2013
2014 .BR geninfo_gcov_all_blocks " ="
2015 .IR 0 | 1
2016 .IP
2017 If non\-zero, call the gcov tool with option --all-blocks.
2018
2019 Using --all-blocks will produce more detailed branch coverage information for
2020 each line. Set this option to zero if you do not need detailed branch coverage
2021 information to speed up the process of capturing code coverage or to work
2022 around a bug in some versions of gcov which will cause it to endlessly loop
2023 when analyzing some files.
2024
2025 Default is 1.
2026 .PP
2027
2028 .BR geninfo_unexecuted_blocks " ="
2029 .IR 0 | 1
2030 .IP
2031 If non\-zero, adjust the 'hit' count of lines which have attribute
2032 .I "unexecuted_block": true
2033 but which contain no branches and have a non-zero count.
2034 Assume that these lines are not executed.
2035
2036 Note that this option is effective only for gcov versions 9 and newer.
2037
2038 Default is 0.
2039 .PP
2040
2041 .BR geninfo_compat " ="
2042 .IR mode = value [, mode = value ,...]
2043 .IP
2044 Specify that geninfo should enable one or more compatibility modes
2045 when capturing coverage data.
2046
2047 This option corresponds to the \-\-compat command line option of
2048 .BR geninfo .
2049
2050 Default is 'libtool=on, hammer=auto, split_crc=auto'.
2051 .PP
2052
2053 .BR geninfo_adjust_src_path " ="
2054 .IR pattern " => " replacement
2055 .br
2056 .BR geninfo_adjust_src_path " ="
2057 .I pattern
2058 .IP
2059 Adjust source paths when capturing coverage data.
2060
2061 Use this option in situations where geninfo cannot find the correct
2062 path to source code files of a project. By providing a
2063 .I pattern
2064 in Perl regular expression format (see
2065 .BR perlre (1))
2066 and an optional replacement string, you can instruct geninfo to
2067 remove or change parts of the incorrect source path.
2068
2069 .B Example:
2070 .br
2071
2072 1. When geninfo reports that it cannot find source file
2073 .br
2074
2075 /path/to/src/.libs/file.c
2076 .br
2077
2078 while the file is actually located in
2079 .br
2080
2081 /path/to/src/file.c
2082 .br
2083
2084 use the following parameter:
2085 .br
2086
2087 geninfo_adjust_src_path = /.libs
2088
2089 This will remove all "/.libs" strings from the path.
2090
2091 2. When geninfo reports that it cannot find source file
2092 .br
2093
2094 /tmp/build/file.c
2095 .br
2096
2097 while the file is actually located in
2098 .br
2099
2100 /usr/src/file.c
2101 .br
2102
2103 use the following parameter:
2104 .br
2105
2106 geninfo_adjust_src_path = /tmp/build => /usr/src
2107 .br
2108
2109 This will change all "/tmp/build" strings in the path to "/usr/src".
2110
2111 The
2112 .I adjust_src_path
2113 option is similar to the
2114 .I substitution = ...
2115 option - which is somewhat more general and allows you to specify
2116 multiple substitution patterns. Also see the
2117 .I resolve_script
2118 option.
2119 .PP
2120
2121 .BR source_directory " ="
2122 .IR dirname
2123 .IP
2124
2125 Add 'dirname' to the list of places to look for source files.
2126 Also see the
2127 .I \-\-source\-directory
2128 entry in the
2129 .B lcov, geninfo,
2130 and
2131 .B genhtml
2132 man pages.
2133 .br
2134
2135 For relative source file paths
2136 .I e.g.,
2137 found in some
2138 .IR tracefile
2139 or in gcov output,
2140 first look for the path from 'cwd' (where genhtml was
2141 invoked) and
2142 then from each alternate directory name in the order specified.
2143 The first location matching location is used.
2144
2145 This option can be specified multiple times, to add more directories to the source search path.
2146
2147 Note that the command line option overrides the RC file entries (if any).
2148 .PP
2149
2150 .BR build_directory " ="
2151 .IR dirname
2152 .IP
2153
2154 Add 'dirname' to the list of places to look for matching GCNO files (geninfo) or source file soft links (genhtml).
2155 See the the
2156 .I \-\-build\-directory
2157 description in the
2158 .B geninfo
2159 and in the
2160 .B genhtml
2161 man page.
2162 .br
2163
2164 This option can be specified multiple times, to add more directories to the source search path.
2165
2166 Note that the command line option overrides the RC file entries (if any).
2167 .PP
2168
2169 .BR geninfo_auto_base " ="
2170 .IR 0 | 1
2171 .IP
2172 If non\-zero, apply a heuristic to determine the base directory when
2173 collecting coverage data.
2174 .br
2175
2176 Use this option when using geninfo on projects built with libtool or
2177 similar build environments that work with multiple base directories,
2178 i.e. environments, where the current working directory when invoking the
2179 compiler is not the same directory in which the source code file is
2180 located, and in addition, is different between files of the same project.
2181 .br
2182
2183 Default is 1.
2184 .PP
2185
2186 .BR geninfo_intermediate " ="
2187 .IR 0 | 1 | auto
2188 .IP
2189 Specify whether to use gcov intermediate format
2190 .br
2191
2192 Use this option to control whether geninfo should use the gcov intermediate
2193 format while collecting coverage data. The use of the gcov intermediate format
2194 should increase processing speed. It also provides branch coverage data when
2195 using the \-\-initial command line option.
2196 .br
2197
2198 Valid values are 0 for off, 1 for on, and "auto" to let geninfo automatically
2199 use immediate format when supported by gcov.
2200 .br
2201
2202 Default is "auto".
2203 .PP
2204
2205 .BR geninfo_no_exception_branch " ="
2206 .IR 0 | 1
2207 .br
2208 .BR no_exception_branch " ="
2209 .IR 0 | 1
2210 .IP
2211 Specify whether to exclude exception branches from branch coverage.
2212 Whether C++ exception branches are identified and removed is dependent on your compiler/toolchain correctly marking them in the generated coverage data.
2213
2214 This option is used by lcov, geninfo, genhtml.
2215
2216 The value
2217 .I no_exception_branch = 1
2218 is equivalent to the
2219 .I \-\-filter exception
2220 command line option.
2221
2222 The backward compatible
2223 .I geninfo_no_exception_branch
2224 option is deprecated. Please use
2225 .I no_exception_branch
2226 instead. The new option is preferred as it is more clear that the option is used by lcov and genhtml as well as geninfo,
2227 .br
2228
2229 Default is 0.
2230 .PP
2231
2232 .BR geninfo_chunk_size " ="
2233 .IR integer [%]
2234 .IP
2235 Specify the number of GCDA files which should be processed per-call in each child process.
2236 This parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent - which then affects the queuing delay. Higher queuing delay lowers the effective parallelism.
2237
2238 The default is 80% of
2239 .I total_number_of_gcda_files / maximum_number_of_parallel_children,
2240 the average number of files expected to be processed by each child.
2241 See the
2242 .I \-\-parallel
2243 entry in the
2244 .B geninfo
2245 man page.
2246
2247 The argument may be either an integer value to be used as the chunk size or
2248 a percentage of the average number files processed per child.
2249
2250 This option has no effect unless the
2251 .I \-\-parallel
2252 option has been specified.
2253
2254 .PP
2255 .BR geninfo_interval_update " ="
2256 .IR integer
2257 .IP
2258 Seet the percentage of GCDA files which should be processed between console/progress
2259 updates. This setting may be useful for parameter tuning and debugging apparent performance issues.
2260
2261 The default is 5%.
2262
2263 This option has no effect unless the
2264 .I \-\-parallel
2265 option has been specified.
2266
2267 .PP
2268
2269 .BR lcov_filter_chunk_size " ="
2270 .IR integer [%]
2271 .IP
2272 Specify the number of source files which should be processed per-call in each child process when applying coverpoint filters - see the
2273 .BR filter = ...
2274 parameter, below.
2275 This parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent - which then affects the queuing delay. Higher queuing delay lowers the effective parallelism.
2276
2277 The default is 80% of
2278 .I total_number_of_source_files / maximum_number_of_parallel_children.
2279
2280 The argument may be either an integer value to be used as the chunk size or
2281 a percentage of the average number files processed per child.
2282
2283 This option has no effect unless the
2284 .I \-\-parallel
2285 option has been specified and
2286 .BR lcov_filter_parallel
2287 is not zero.
2288
2289 .PP
2290
2291 .BR lcov_filter_parallel " = 0 | 1"
2292 .IP
2293
2294 This option specifies whether coverpoint filtering should be done serially or in parallel. If the number of files to process is very large, then parallelization may improve performance.
2295
2296 This option has no effect unless the
2297 .I \-\-parallel
2298 option has been specified.
2299
2300 The default is 1 (enabled).
2301
2302
2303 .PP
2304 .BR lcov_gcov_dir " ="
2305 .I path_to_kernel_coverage_data
2306 .IP
2307 Specify the path to the directory where kernel coverage data can be found
2308 or leave undefined for auto-detection.
2309 .br
2310
2311 Default is auto-detection.
2312 .PP
2313
2314 .BR lcov_tmp_dir " ="
2315 .I temp
2316 .IP
2317 Specify the location of a directory used for temporary files.
2318 .br
2319
2320 Default is '/tmp'.
2321 .PP
2322
2323 .BR lcov_list_full_path " ="
2324 .IR 0 | 1
2325 .IP
2326 If non-zero, print the full path to source code files during a list operation.
2327 .br
2328
2329 This option corresponds to the \-\-list\-full\-path option of
2330 .BR lcov .
2331 .br
2332
2333 Default is 0.
2334 .PP
2335
2336 .BR lcov_list_max_width " ="
2337 .IR width
2338 .IP
2339 Specify the maximum width for list output. This value is ignored when
2340 lcov_list_full_path is non\-zero.
2341 .br
2342
2343 Default is 80.
2344 .PP
2345
2346 .BR lcov_list_truncate_max
2347 .B " ="
2348 .IR percentage
2349 .IP
2350 Specify the maximum percentage of file names which may be truncated when
2351 choosing a directory prefix in list output. This value is ignored when
2352 lcov_list_full_path is non\-zero.
2353 .br
2354
2355 Default is 20.
2356 .PP
2357
2358 .BR function_coverage " ="
2359 .IR 0 | 1
2360 .IP
2361 Specify whether lcov/geninfo/genhtml should generate, process, and
2362 display function coverage data.
2363 .br
2364
2365 Turning off function coverage by setting this option to 0 can
2366 sligly reduce memory and CPU time consumption
2367 when lcov is collecting and processing coverage data, as well as
2368 reduce the size of the resulting data files.
2369 .br
2370
2371 This option can be overridden by the
2372 .I \-\-function\-coverage
2373 and
2374 .I \-\-no\-function\-coverage
2375 command line options.
2376 .br
2377
2378
2379 Backward-compatible RC options
2380 .B lcov_function_coverage
2381 and
2382 .B genhtml_function_coverage
2383 are supported but deprecated. Please use the new option instead.
2384 .br
2385
2386 Default is 1.
2387 .PP
2388
2389 .BR branch_coverage " ="
2390 .IR 0 | 1
2391 .IP
2392 Specify whether lcov/geninfo should generate, process, and display branch
2393 coverage data.
2394 .br
2395
2396 Turning off branch coverage by setting this option to 0 can reduce
2397 memory and CPU time consumption
2398 when lcov is collecting and processing coverage data, as well as
2399 reduce the size of the resulting data files.
2400 .br
2401
2402 This option can be overridden by the
2403 .I \-\-branch\-coverage
2404 and
2405 .I \-\-no\-branch\-coverage
2406 command line options.
2407 .br
2408
2409 Backward-compatible RC options
2410 .B lcov_branch_coverage
2411 and
2412 .B genhtml_branch_coverage
2413 are supported but deprecated. Please use the new option instead.
2414 .br
2415
2416
2417 Default is 0.
2418 .PP
2419
2420 .BR mcdc_coverage " ="
2421 .IR 0 | 1
2422 .IP
2423 Specify whether lcov/geninfo should generate, process, and display Modified
2424 Condition / Decision Coverage (MC/DC)
2425 coverage data.
2426 .br
2427
2428 Turning off MC/DC coverage by setting this option to 0 can reduce
2429 memory and CPU time consumption
2430 when lcov is collecting and processing coverage data, as well as
2431 reduce the size of the resulting data files.
2432 .br
2433
2434 This option can be overridden by the
2435 .I \-\-mcdc\-coverage
2436 command line option.
2437 .br
2438
2439 Default is 0 (not enabled).
2440
2441 .br
2442 See the MC/DC section of man
2443 .B genhtml(1)
2444 for more details
2445 .PP
2446
2447 .BR lcov_excl_line " ="
2448 .I expression
2449 .IP
2450 Specify the regular expression of lines to exclude.
2451 Line, branch, and function coverpoints are associated with lines where this regexp is found are dropped.
2452 .br
2453
2454 There are at least 2 (moderately) common use cases for custom exclusion markers:
2455 .br
2456 - You are using multiple tools for coverage analysis, each of which has its own directives, and you don't want to complicate your source code with directives for each of them.
2457 .br
2458 - You want to exclude different regions/different types of code in different contexts - for example, to ignore or not ignore debug/trace code depending on your team.
2459
2460 Default is 'LCOV_EXCL_LINE'.
2461 .PP
2462
2463 .BR lcov_excl_br_line " ="
2464 .I expression
2465 .IP
2466 Specify the regular expression of lines to exclude from branch coverage.
2467 Branch coverpoints are associated with lines where this regexp is found are dropped. (Line and function coverpoints are not affected.)
2468 .br
2469
2470 Default is 'LCOV_EXCL_BR_LINE'.
2471 .PP
2472
2473 .BR lcov_excl_exception_br_line " ="
2474 .I expression
2475 .IP
2476 Specify the regular expression of lines to exclude from exception branch coverage.
2477 Exception-related Branch coverpoints associated with lines where this regexp is found are dropped. (Line, function coverpoints are not affected. Branch coverpoints which are not associated with exceptions are also not affected.)
2478
2479 Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be removed.
2480
2481 .br
2482 Note that this feature requires support from your compiler - and thus may not ignore all exception-related coverpoints.
2483 .br
2484
2485 Default is 'LCOV_EXCL_EXCEPTION_BR_LINE'.
2486 .PP
2487
2488 .BR lcov_excl_start " ="
2489 .IR expression
2490 .IP
2491 Specify the regexp mark the start of an exception region
2492 All coverpoints within exception regions are dropped.
2493 .br
2494
2495 Default is 'LCOV_EXCL_START'.
2496
2497 .PP
2498
2499 .BR lcov_excl_stop " ="
2500 .IR expression
2501 .IP
2502 Specify the regexp mark the end of an exception region
2503 .br
2504
2505 Default is 'LCOV_EXCL_STOP'.
2506
2507 .PP
2508
2509 .BR lcov_excl_br_start " ="
2510 .IR expression
2511 .IP
2512 Specify the regexp used to mark the start of a region where branch coverpoints are excluded.
2513 Line and function coverpoints within the region are not excluded.
2514 .br
2515
2516 Default is 'LCOV_EXCL_BR_START'.
2517
2518 .PP
2519
2520 .BR lcov_excl_br_stop " ="
2521 .IR expression
2522 .IP
2523 Specify the regexp used to mark the end of a region where branch coverpoints are excluded.
2524 .br
2525
2526 Default is 'LCOV_EXCL_BR_STOP'.
2527
2528
2529 .PP
2530
2531 .BR lcov_excl_exception_br_start " ="
2532 .IR expression
2533 .IP
2534 Specify the regexp used to mark the start of a region where branch coverpoints associated with exceptions are excluded.
2535 Line, function, and non-exception branch coverpoints within the region are not excluded.
2536
2537 Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be removed.
2538
2539 Note that exception branch coverpoint identification requires support from your compiler - and thus may not ignore all exception-related coverpoints.
2540 .br
2541
2542 Default is 'LCOV_EXCL_EXCEPTION_BR_START'.
2543
2544 .PP
2545
2546 .BR lcov_excl_exception_br_stop " ="
2547 .IR expression
2548 .IP
2549 Specify the regexp used to mark the end of a region where exception-related branch coverpoints are excluded.
2550 .br
2551
2552 Default is 'LCOV_EXCL_EXECEPTION_BR_STOP'.
2553
2554 .PP
2555
2556 .BR fail_under_branches " ="
2557 .I percentage
2558 .IP
2559 Specify branch coverage threshold: if the branch coverage is below this threshold, lcov/genhtml/geninfo will generate all the normal result files and messages, but will return a non-zero exit code.
2560 .br
2561
2562 This option is equivalent to the \-\-fail\-under\-branches lcov/genhtml/geninfo command line argument. See
2563 .B man lcov(1)
2564 for more detailes.
2565
2566 .br
2567 The default is 0 (no threshold).
2568
2569 .PP
2570
2571 .BR fail_under_lines " ="
2572 .I percentage
2573 .IP
2574 Specify line coverage threshold to lcov. If the line coverage is below this threshold, lcov/genhtml/geninfo will generate all the normal result files and messages, but will return a non-zero exit code.
2575 .br
2576
2577 This option is equivalent to the \-\-fail\-under\-lines lcov/genhtml/geninfo command line argument.
2578
2579 .br
2580 The default is 0 (no threshold).
2581
2582 .PP
2583
2584 .BR profile " ="
2585 .IR filename
2586 .IP
2587 If set, tells genhtml, lcov, or geninfo to generate some execution
2588 time/profile data which can be used to motivate future optimizations.
2589 It is equivalent to the
2590 .I \-\-profile
2591 command line option.
2592
2593 If
2594 .I filename
2595 is empty, then the profile is written to the default location chosen by the application.
2596
2597 .br
2598 This option is used by genhtml, lcov, and geninfo.
2599
2600 The default is unset: no data generated.
2601
2602 .PP
2603
2604 .BR parallel " ="
2605 .IR integer
2606 .IP
2607 Tells genhtml, lcov, or geninfo the maximum number of simultaneous processes
2608 to use. Zero means to use as many cores as are available on the machine.
2609 The default is 1 (one) - which means to process sequentially (no parallelism).
2610
2611 .br
2612 This option is used by genhtml, lcov, and geninfo.
2613
2614 .PP
2615
2616 .BR memory " ="
2617 .IR integer_Mb
2618 .IP
2619 Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing
2620 operations. Effectively, the process will not fork() if this limit would be
2621 exceeded.
2622 Zero means that there is no limit.
2623 The default is 0 (zero) - which that there is no explicit limit.
2624
2625 .br
2626 This option is used by genhtml, lcov, and geninfo.
2627
2628 .PP
2629
2630 .BR memory_percentage " ="
2631 .IR number
2632 .IP
2633 Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing
2634 operations. Maximum is computed as a percentage of the total memory
2635 available on the system; for example, '75' would use limit to 75% of
2636 total memory, whereas 150.5 would limit to 150.5% (
2637 .I i.e.,
2638 larger than the total available.
2639 Effectively, the process will not fork() if this limit would be
2640 exceeded.
2641 Note that this value is used only if the maximum memory value is not
2642 set explicitly - either by a the
2643 .I \-\-memory
2644 command line option or the
2645 .I memory = integer
2646 configuration file setting.
2647
2648 The default is not not set.
2649
2650 .br
2651 This option is used by genhtml, lcov, and geninfo.
2652
2653 .PP
2654
2655 .BR max_fork_fails " ="
2656 .IR integer
2657 .IP
2658 Tells genhtml, lcov, or geninfo the number of consecutive fork() failures
2659 to ignore during
2660 .I \-\-parallel
2661 execution before giving up.
2662 Note that genhtml/lcov/geninfo fail and stop immediately unless the
2663 .I fork
2664 error message ignored - either via the
2665 .I ignore_errors
2666 directive (above), the
2667 .I \-\-ignore\-errors
2668 command line option, or if
2669 .I stop_on_error
2670 is disabled or the
2671 .I \-\-keep-going
2672 command line option is used.
2673
2674 The default fork failure maximum is 5.
2675
2676 .PP
2677
2678 .BR fork_fail_timeout " ="
2679 .IR integer_seconds
2680 .IP
2681 Tells genhtml, lcov, or geninfo how long to wait after a fork() failure
2682 before retrying.
2683
2684 The default is 10 (seconds).
2685
2686 .PP
2687
2688 .BR max_tasks_per_core " ="
2689 .IR integer
2690 .IP
2691 This is the maximum number of files that genhtml will handle in a single
2692 child process during parallel execution.
2693
2694 The default is 20.
2695
2696 .PP
2697
2698 .BR genhtml_date_bins " ="
2699 .IR integer[,integer..]
2700 .IP
2701 This option is equivalent to the "genhtml \-\-date\-bins" option.
2702 See man
2703 .B genhtml(1)
2704 for details.
2705
2706 This option can be used multiple times in the lcovrc file to set multiple cutpoints.
2707
2708 .PP
2709
2710 .BR genhtml_datelabels " ="
2711 .IR string[,string..]
2712 .IP
2713 This option is equivalent to the "genhtml \-\-date\-labels" option.
2714 See man
2715 .B genhtml(1)
2716 for details.
2717
2718 This option can be used multiple times in the lcovrc file to set multiple labels.
2719 The number of labels should equal one greater than number of cutpoints.
2720
2721 .PP
2722
2723 .BR genhtml_annotate_script " ="
2724 .IR path_to_executable | parameter
2725 .IP
2726 This option is equivalent to the "genhtml \-\-annotate\-script" option.
2727
2728 This option can be used multiple times in the lcovrc file to specify both an annotation script and additional options which are passed to the script.
2729
2730 See the genhtml man page for details.
2731
2732 .PP
2733
2734 .BR genhtml_annotate_tooltip " ="
2735 .IR tooltip_string
2736 .IP
2737
2738 This option sets the 'tooltip' popup which appears if user hovers mouse over
2739 the associated source code.
2740 Note that the tooltop is generated only if the annotation-script callback
2741 is successful and returns a commit ID other than "NONE".
2742 Set
2743 .I tooltip_string
2744 to "" (empty string) to force genhtml to not produce the tooltip.
2745
2746 Substitutions are performed on
2747 .I tooltip_string:
2748
2749 .IP " %C:"
2750 commit ID (from annotate callback - see
2751 .I --anotate-script
2752 entry in the
2753 .B genhtml
2754 man page)
2755 .IP " %U:"
2756 commit author abbreviated name (returned by annotate callback)
2757 .IP " %F:"
2758 commit author full name (returned by annotate callback)
2759 .IP " %D:"
2760 commit date (as returned by annotate callback)
2761 .IP " %d:"
2762 commit date with time of day removed (i.e., date part only)
2763 .IP " %A:"
2764 commit age.
2765 .IP " %l"
2766 source line number.
2767
2768 .PP
2769
2770
2771 .BR context_script " ="
2772 .IR path_to_executable_or_module | parameter
2773 .IP
2774 This option is equivalent to the
2775 .I \-\-context\-script
2776 option of genhtml/lcov/geninfo
2777
2778 This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script.
2779
2780 See the genhtml man page for details.
2781
2782 .PP
2783
2784
2785
2786 .BR criteria_script " ="
2787 .IR path_to_executable_or_module | parameter
2788 .IP
2789 This option is equivalent to the
2790 .I \-\-criteria\-script
2791 option of genhtml/lcov/geninfo
2792
2793 This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script.
2794
2795 See the genhtml man page for details.
2796
2797 .PP
2798
2799 .BR criteria_callback_data " ="
2800 .IR comma_separated_list
2801 .IP
2802 This option is used to tell genhtml whether you want date and/or owner summary
2803 data passed back to your criteria callback.
2804 Note that summary data is always passed.
2805
2806 Note that lcov and geninfo do not record date or owner data - and so do not pass
2807 it to the callback.
2808
2809 This option can be used multiple times in the lcovrc file to specify both date and owner data should be returned, or you can specify both in a comma-separated list.
2810 Date and/or owner data will be returned if and only if your genhtml command
2811 has enabled annotation.
2812
2813 If this option is appears multiple times in the lcovrc file; the values are combined to form the list of binning types which are passed to your callback.
2814
2815 See the genhtml man page for details.
2816
2817 .PP
2818
2819 .BR criteria_callback_levels " ="
2820 .IR comma_separated_list
2821 .IP
2822 This option is used to tell genhtml whether criteria callbacks should occur
2823 at the top, directory, or file level.
2824
2825 If this option is appears multiple times in the lcovrc file, the values are combined to form the list of report levels when your callback will be executed.
2826
2827 See the genhtml man page for details.
2828
2829 .PP
2830
2831 .BR check_existence_before_callback " ="
2832 .IR 0 | 1
2833 .IP
2834 This option configures the tool to check that the file exists before calling
2835 the
2836 .I annotate-script
2837 or
2838 .I version-script
2839 callback. If set and file does not exist, a
2840 .B source
2841 error is triggered. (Note that the error may be ignored - see the
2842 .I \-\-ignore\-error
2843 option.)
2844
2845 You may want to NOT check for file existence if your callback looks
2846 up information in a non-local repository.
2847
2848 The default is 1 (check for file existence).
2849
2850 .PP
2851
2852 .BR compute_file_version " ="
2853 .IR 0 | 1
2854 .IP
2855 This option is used to tell the tool to generate missing file version
2856 information when reading a .info (coverage data) file.
2857 Version information may be missing because the data was generated by a tool which did not support versioning, or because the data was generated without the required
2858 .I \-\-version\-script
2859 argument - or for some other reason.
2860
2861 Note that this option has no effect without a version\-script callback -
2862 defined by either the
2863 .I \-\-version\-script
2864 command line option or the
2865 .I version_script
2866 config file option.
2867
2868 The default is 0: do not generate missing information.
2869
2870 .PP
2871
2872 .BR version_script " ="
2873 .IR path_to_executable | parameter
2874 .IP
2875 This option is equivalent to the geninfo/lcov/genhtml "\-\-version\-script" option.
2876
2877 This option can be used multiple times in the lcovrc file to specify both a version script and additional options which are passed to the script.
2878
2879 See the genhtml man page for details.
2880
2881 .PP
2882
2883 .BR resolve_script " ="
2884 .IR path_to_executable | parameter
2885 .IP
2886 This option is equivalent to the geninfo/lcov/genhtml "\-\-resolve\-script" option.
2887
2888 This option can be used multiple times in the lcovrc file to specify both a resolve script and additional options which are passed to the script.
2889
2890 The resolve script provides a mechanism to find a
2891 source or data file that cannot be found by simply modify paths via substitution
2892 patterns (see
2893 .I "substitute = replace_regexp"
2894 above) and searching along the corresponding directory list:
2895 .RS
2896 .IP
2897 .B geninfo:
2898 the
2899 .I "'build_directory = dirname'"
2900 config file entry
2901 or
2902 .I \-\-build\=directory
2903 command line option, used to search for GCNO files,
2904 .PP
2905 .IP
2906 .B geninfo/genhtml/lcov:
2907 the
2908 .I "'source_directory = dirname'"
2909 config file entry
2910 or
2911 .I \-\-source\=directory
2912 command line option, used to search for source files.
2913 .PP
2914 .RE
2915
2916 .RS
2917 The resolve script is called as:
2918 .IP
2919 .B resolve_script
2920 [callback_args]
2921 .I " file_name"
2922 .PP
2923
2924 or
2925 .IP
2926 .I $resolve_callback =
2927 .B resolve_module
2928 .I ->new([callback_args])
2929 .PP
2930 to initialize the callback, then
2931 .IP
2932 .I $resolve_callback->
2933 .B resolve
2934 .I (file_name)
2935 .PP
2936 to find the actual file location.
2937
2938 If necessary, the callback can check the suffix of the filename to determine
2939 whether it should look for either a source or data file.
2940 .PP
2941
2942 The script should return either empty string (file not found/no such file) or the actual
2943 path name. The returned path may be either absolute or relative to CWD.
2944 .RE
2945 .PP
2946
2947 .BR select_script " ="
2948 .IR path_to_executable | parameter
2949 .IP
2950 This option is equivalent to the genhtml "\-\-select\-script" option.
2951
2952 This option can be used multiple times in the lcovrc file to specify both a select script and additional options which are passed to the script.
2953
2954 The select script provides a mechanism to decide whether a particular
2955 source line is interesting - whether it should be included in the
2956 generated
2957 coverage report - or not.
2958
2959 Lines which are not selected but fall within
2960 .I num_context_lines
2961 of a selected line are also included in the report. See below.
2962
2963 Note that selection is fundamentally intended to show regions of code with some surrounding context. It might not do what you expect if there is no code - e.g., if the region of interest has been compiled out via compiler or exclusion directives.
2964 For example: when selecting based on SHA or changelist ID, an inserted comment will not be selected unless it is within
2965 .I num_context_lines
2966 of an inserted or changed line of code.
2967
2968 The select script is called as:
2969
2970 .B " select_script"
2971 [callback_args]
2972 .I lineDataJson annotateDataJson fileName lineNumber
2973
2974 or as:
2975
2976 .I " $selectCallback ="
2977 .B select_module
2978 .I ->new([callback_args])
2979
2980 to initialize the callback object, then as
2981
2982 .I " " $selectCallback
2983 .B select
2984 .I (lineDataRef annotateDataRef fileName lineNumber)
2985
2986 .RS
2987 to determine selection,
2988 where
2989 .IP \- 3
2990 .I fileName
2991 is the name of the source file and
2992 .PP
2993 .IP \- 3
2994 .I lineNumber
2995 is the source file line number, indexed from zero,
2996 .PP
2997 .IP \- 3
2998 .I lineDataJson
2999 is a json-encoded LineData structure (see the lcovutil.pm source code), and
3000 .PP
3001 .IP \- 3
3002 .I annotateDataJson
3003 is the json-encoded data returned by your
3004 .I annotate\-script
3005 (see the
3006 .I \-\-annotate\-script
3007 parameter in man
3008 .B genhtml(1).
3009 ), or the empty string if there are no annotations for this file.
3010 .PP
3011 The module callback is similar except that is is passed objects rather than JSON encodings of the objects.
3012 .RE
3013
3014 The script should return "1" or "0".
3015
3016 See example implementation
3017 .I $LCOV_HOME/share/lcov/support-scripts/select.pm.
3018 .RE
3019
3020
3021 .PP
3022
3023 .BR num_context_lines " = "
3024 .IR integer
3025 .IP
3026 Set the number of lines around each selected line which is included in the
3027 report - see
3028 .I select_script = ...
3029 above and the
3030 .I \-\-select\-script
3031 command line option in man
3032 .B genhtml(1).
3033 .PP
3034
3035 .BR filter " ="
3036 .IR str[,str...]
3037 .IP
3038
3039 This option is equivalent to the \-\-filter option to geninfo, lcov, and genhtml.
3040 See the genhtml man page for details.
3041
3042 This option can be used multiple times in the lcovrc file to enable multiple filters.
3043 The filters specified in the lcovrc file are appended to the list specified on the command line.
3044
3045 .br
3046 This option is used by genhtml, lcov, and geninfo.
3047
3048 .PP
3049
3050 .BR exclude " ="
3051 .IR glob_pattern
3052 .IP
3053
3054 This option is equivalent to the \-\-exclude option to geninfo, lcov, and genhtml.
3055 See the lcov man page for details.;
3056
3057 This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
3058 The patterns specified in the lcovrc file are appended to the list specified on the command line.
3059
3060 .br
3061 This option is used by genhtml, lcov, and geninfo.
3062
3063 .PP
3064
3065 .BR include " ="
3066 .IR glob_pattern
3067 .IP
3068
3069 This option is equivalent to the \-\-include option to geninfo, lcov, and genhtml.
3070 See the lcov man page for details.;
3071
3072 This option can be used multiple times in the lcovrc file to specify multiple patterns to include.
3073 The patterns specified in the lcovrc file are appended to the list specified on the command line.
3074
3075 .br
3076 This option is used by genhtml, lcov, and geninfo.
3077
3078 .PP
3079
3080 .BR substitute " ="
3081 .IR regexp
3082 .IP
3083
3084 This option is equivalent to the \-\-substitute option to geninfo, lcov, and genhtml.
3085 See the lcov man page for details.;
3086
3087 This option can be used multiple times in the lcovrc file to specify multiple substitution patterns.
3088 The patterns specified in the lcovrc file are appended to the list specified on the command line.
3089
3090 .br
3091 This option is used by genhtml, lcov, and geninfo.
3092
3093 .PP
3094
3095 .BR omit_lines " ="
3096 .IR regexp
3097 .IP
3098
3099 This option is equivalent to the \-\-omit\-lines option to geninfo, lcov, and genhtml.
3100 See the genhtml man page for details.
3101
3102 This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
3103 The patterns specified in the lcovrc file are appended to the list specified on the command line.
3104
3105 .br
3106 This option is used by genhtml, lcov, and geninfo.
3107
3108 .PP
3109
3110 .BR erase_functions " ="
3111 .IR regexp
3112 .IP
3113
3114 This option is equivalent to the \-\-erase\-functions option to geninfo, lcov, and genhtml.
3115 See the genhtml man page for details.
3116
3117 This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
3118 The patterns specified in the lcovrc file are appended to the list specified on the command line.
3119
3120 .br
3121 This option is used by genhtml, lcov, and geninfo.
3122
3123 .PP
3124
3125 .BR lcov_json_module " ="
3126 .IR module | auto
3127 .IP
3128 Specify the JSON module to use, or choose best available from a set of
3129 alternatives if set to 'auto'. Note that some JSON modules are slower than
3130 others (notably JSON::PP can be very slow compared to JSON::XS).
3131 .br
3132
3133 Default is 'auto'.
3134
3135 .PP
3136
3137 .BR split_char " ="
3138 .IR char
3139 .IP
3140 Specify the character (or regexp) used to split list-like parameters which have
3141 been passed as a single string.
3142 This parameter is useful in the case that you need want to use a multi-option
3143 string but one or more of the options contains a comma character which would
3144 otherwise be seen as a delimiter.
3145 .br
3146
3147 Default is ',' (comma - no quotes).
3148
3149 .PP
3150
3151 .BR scope_regexp " ="
3152 .IR regexp
3153 .IP
3154 Print debug messages for data in filenames which match
3155 .I regexp.
3156 .br
3157 Only certain categories of message are logged; the set changes from time
3158 to time - depending on debug need.
3159
3160 .PP
3161
3162 .BR case_insensitive " ="
3163 .IR [0|1]
3164 .IP
3165 Specify whether string comparison is case insensitive when finding matching
3166 filenames, checking include/exclude directives, etc.
3167 .br
3168
3169 Note that mixed-case or lower-case pathnames may be passed to your \-\-version\-script and \-\-annotate\-script callbacks when case-insensitive matching is used. Your callbacks must handle potential differences in case.
3170
3171 Default is '0': case sensitive matching.
3172
3173 .PP
3174
3175 .BR sort_input " ="
3176 .IR [0|1]
3177 .IP
3178 Specify whether to sort file names before capture and/or aggregation.
3179 Sorting reduces certain types of processing order-dependent output differences -
3180 .I e.g.,
3181 due to ambiguities in branch data generated by gcc.
3182 .br
3183
3184 Default is '0': no sorting - process files in the order they were specified on the command line and/or were found during traversal of the filesystem.
3185
3186 .PP
3187
3188
3189 .SH FILES
3190
3191 .TP
3192 .I $LCOV_HOME/etc/lcovrc
3193 The system\-wide
3194 .B lcov
3195 configuration file.
3196
3197 .TP
3198 .I ~/.lcovrc
3199 The individual per\-user configuration file.
3200 .PP
3201
3202 .SH SEE ALSO
3203 .BR lcov (1),
3204 .BR genhtml (1),
3205 .BR geninfo (1),
3206 .BR gcov (1)