Debian Codegraph @

man/genhtml.1

raw
1 \" Define path to scripts
2 .ds scriptdir scripts
3
4 \" Define project URL
5 .ds lcovurl https://github.com/linux\-test\-project/lcov
6
7 .TH genhtml 1 "LCOV 2.0" 2023\-05\-17 "User Manuals"
8 .SH NAME
9 genhtml \- Generate HTML view from LCOV coverage data files
10 .SH SYNOPSIS
11 .B genhtml
12 .RB [ \-h | \-\-help ]
13 .RB [ \-\-version ]
14 .RS 8
15 .br
16 .RB [ \-q | \-\-quiet ]
17 .RB [ \-v | \-\-verbose ]
18 .br
19 .RB [ \-\-debug ] [ \-\-validate ]
20 .br
21 .RB [ \-s | \-\-show\-details ]
22 .br
23 .RB [ \-f | \-\-frames ]
24 .br
25 .RB [ \-b | \-\-baseline\-file
26 .IR baseline\-file\-pattern ]
27 .br
28 .RB [ \-o | \-\-output\-directory
29 .IR output\-directory ]
30 .br
31 .RB [ \-\-header-title
32 .IR banner ]
33 .br
34 .RB [ \-\-footer
35 .IR string ]
36 .br
37 .RB [ \-t | \-\-title
38 .IR title ]
39 .br
40 .RB [ \-d | \-\-description\-file
41 .IR description\-file ]
42 .br
43 .RB [ \-k | \-\-keep\-descriptions ]
44 .RB [ \-c | \-\-css\-file
45 .IR css\-file ]
46 .br
47 .RB [ \-p | \-\-prefix
48 .IR prefix ]
49 .RB [ \-\-no\-prefix ]
50 .br
51 .RB [ \-\-build\-directory
52 .IR directory ]
53 .br
54 .RB [ \-\-source\-directory
55 .IR dirname ]
56 .br
57 .RB [ \-\-no\-source ]
58 .RB [ \-\-no\-html ]
59 .br
60 .RB [ \-\-num\-spaces
61 .IR num ]
62 .RB [ \-\-highlight ]
63 .br
64 .RB [ \-\-legend ]
65 .RB [ \-\-html\-prolog
66 .IR prolog\-file ]
67 .br
68 .RB [ \-\-html\-epilog
69 .IR epilog\-file ]
70 .RB [ \-\-html\-extension
71 .IR extension ]
72 .br
73 .RB [ \-\-html\-gzip ]
74 .RB [ \-\-sort\-tables ]
75 .RB [ \-\-no\-sort ]
76 .br
77 .RB [ \-\-function\-coverage ]
78 .RB [ \-\-no\-function\-coverage ]
79 .br
80 .RB [ \-\-branch\-coverage ]
81 .RB [ \-\-no\-branch\-coverage ]
82 .br
83 .RB [ \-\-mcdc\-coverage ]
84 .br
85 .RB [ \-\-demangle\-cpp
86 .IR [ param ] ]
87 .br
88 .RB [ \-\-msg\-log
89 .IR [ log_file_name ] ]
90 .br
91 .RB [ \-\-ignore\-errors
92 .IR errors ]
93 .br
94 .RB [\-\-expect\-message\-count
95 .IR message_type=expr[,message_type=expr..]]
96 .br
97 .RB [ \-\-keep\-going ]
98 .RB [ \-\-config\-file
99 .IR config\-file ]
100 .br
101 .RB [ \-\-profile
102 .IR [profile\-file ]
103 .br
104 .RB [ \-\-rc
105 .IR keyword = value ]
106 .br
107 .RB [ \-\-precision
108 .IR num ]
109 .RB [ \-\-missed ]
110 .br
111 .RB [ \-\-merge\-aliases ]
112 .br
113 .RB [ \-\-suppress\-aliases ]
114 .br
115 .RB [ \-\-forget\-test\-names ]
116 .br
117 .RB [ \-\-dark\-mode ]
118 .br
119 .RB [ \-\-baseline\-title
120 .IR title ]
121 .br
122 .RB [ \-\-baseline\-date
123 .IR date ]
124 .br
125 .RB [ \-\-current\-date
126 .IR date ]
127 .br
128 .RB [ \-\-diff\-file
129 .IR diff\-file ]
130 .br
131 .RB [ \-\-annotate\-script
132 .IR script ]
133 .br
134 .RB [ \-\-context\-script
135 .IR script ]
136 .br
137 .RB [ \-\-criteria\-script
138 .IR script ]
139 .br
140 .RB [ \-\-version\-script
141 .IR script ]
142 .br
143 .RB [ \-\-resolve\-script
144 .IR script ]
145 .br
146 .RB [ \-\-select\-script
147 .IR script ]
148 .br
149 .RB [ \-\-checksum ]
150 .br
151 .RB [ \-\-fail\-under\-branches
152 .IR percentage ]
153 .br
154 .RB [ \-\-fail\-under\-lines
155 .IR percentage ]
156 .br
157 .RB [ \-\-new\-file\-as\-baseline ]
158 .br
159 .RB [ \-\-elide\-path\-mismatch ]
160 .br
161 .RB [ \-\-synthesize\-missing ]
162 .br
163 .RB [ \-\-date\-bins
164 .IR day[,day,...]]
165 .br
166 .RB [ \-\-date\-labels
167 .IR string[,string,...]]
168 .br
169 .RB [ \-\-show\-owners
170 .IR [ all ] ]
171 .br
172 .RB [ \-\-show\-noncode ]
173 .br
174 .RB [ \-\-show\-zero\-columns ]
175 .br
176 .RB [ \-\-show\-navigation ]
177 .br
178 .RB [ \-\-show\-proportions ]
179 .br
180 .RB [ \-\-simplified-colors ]
181 .br
182 .RB [ \-\-hierarchical ]
183 .RB [ \-\-flat ]
184 .br
185 .RB [ \-\-filter
186 .IR filters ]
187 .br
188 .RB [ \-\-include
189 .IR glob_pattern ]
190 .br
191 .RB [ \-\-exclude
192 .IR glob_pattern ]
193 .br
194 .RB [ \-\-erase\-functions
195 .IR regexp_pattern ]
196 .br
197 .RB [ \-\-substitute
198 .IR regexp_pattern ]
199 .br
200 .RB [ \-\-omit\-lines
201 .IR regexp_pattern ]
202 .br
203 .RB [ \-\-parallel | -j
204 .IR [integer] ]
205 .br
206 .RB [ \-\-memory
207 .IR integer_num_Mb ]
208 .br
209 .RB [ \-\-tempdir
210 .IR dirname ]
211 .br
212 .RB [ \-\-preserve ]
213 .br
214 .RB [ \-\-save ]
215 .br
216 .RB [ \-\-sort\-input ]
217 .br
218 .RB [ \-\-serialize
219 .IR serialize_output_file ]
220 .br
221 .IR tracefile_pattern(s)
222 .RE
223 .SH DESCRIPTION
224
225 .B genhtml
226 creates an HTML view of coverage data found in tracefiles
227 .B geninfo
228 and
229 .B lcov
230 tools which are found from glob-match pattern(s)
231 .I tracefile_pattern.
232 See man
233 .B geninfo(1) for a description of the tracefile format.
234
235 Features include:
236
237 .IP \(bu 3
238 Differential coverage comparison against baseline coverage data
239 .PP
240 .IP \(bu 3
241 Annotation of reports with date and owner information ("binning")
242 .PP
243
244 The basic concepts of differential coverage and date/owner binning are described in the paper found at
245 .I https://arxiv.org/abs/2008.07947
246
247 .SS Differential coverage
248
249 Differential coverage compares two versions of source code - the baseline and the current versions - and the coverage results for each to segment the code into categories.
250 .br
251
252 To create a differential coverage report,
253 .B genhtml
254 requires
255
256 .IP 1. 3
257 one or more
258 .I baseline\-files
259 specified via
260 .BR \-\-baseline\-file ,
261 and
262 .PP
263 .IP 2. 3
264 a patch file in unified format specified using
265 .BR \-\-diff\-file .
266 .PP
267 .br
268
269 Both
270 .I tracefile_pattern
271 and
272 .I baseline\-file
273 are treated as glob patterns which match one or more files.
274 .br
275
276 The difference in coverage between the set of
277 .I tracefiles
278 and
279 .I baseline\-files
280 is classified line-by-line into categories based on changes in 2 aspects:
281
282 .IP 1. 3
283 .BR "Test coverage results" :
284 a line of code can be tested (1), untested (0),
285 or unused (#). An unused line is a source code line that has no associated
286 coverage data, for example due to a disabled #ifdef statement.
287 .br
288 .PP
289
290 .IP 2. 3
291 .BR "Source code changes" :
292 a line can be unchanged, added (+\ =>), or removed (=>\ \-).
293 Note that the diff-file format used by
294 .B genhtml
295 reports changes in lines as removal of old line and addition of new line.
296 .br
297 .PP
298
299 Below are the resulting 12 categories, sorted by priority (assuming that untested code is more interesting than tested code, and new code is more interesting than old code):
300 .br
301
302 .RE
303 .B UNC
304 .RS
305 Uncovered New Code (+ => 0): newly added code is not tested.
306 .br
307 .RE
308
309 .B LBC
310 .RS
311 Lost Baseline Coverage (1 => 0): unchanged code is no longer tested.
312 .br
313 .RE
314
315 .B UIC
316 .RS
317 Uncovered Included Code (# => 0): previously unused code is untested.
318 .br
319 .RE
320
321 .B UBC
322 .RS
323 Uncovered Baseline Code (0 => 0): unchanged code was untested before, is untested now.
324 .br
325 .RE
326
327 .B GBC
328 .RS
329 Gained Baseline Coverage (0 => 1): unchanged code is tested now.
330 .br
331 .RE
332
333 .B GIC
334 .RS
335 Gained Included Coverage (# => 1): previously unused code is tested now.
336 .br
337 .RE
338
339 .B GNC
340 .RS
341 Gained New Coverage (+ => 1): newly added code is tested.
342 .br
343 .RE
344
345 .B CBC
346 .RS
347 Covered Baseline Code (1 => 1): unchanged code was tested before and is still tested.
348 .br
349 .RE
350
351 .B EUB
352 .RS
353 Excluded Uncovered Baseline (0 => #): previously untested code is unused now.
354 .br
355 .RE
356
357 .B ECB
358 .RS
359 Excluded Covered Baseline (1 => #): previously tested code is unused now.
360 .br
361 .RE
362
363 .B DUB
364 .RS
365 Deleted Uncovered Baseline (0 => \-): previously untested code has been deleted.
366 .br
367
368 Note: Because these lines are not represented in the current source version,
369 they are only represented in the classification summary table.
370 .RE
371
372 .B DCB
373 .RS
374 Deleted Covered Baseline (1 => \-): previously tested code has been deleted.
375 .br
376
377 Note: Because these lines are not represented in the current source version,
378 they are only represented in the classification summary table.
379 .br
380 .RE
381
382 The differential coverage report colorizes categorized regions in the source code view using unique colors for each. You can use the
383 .B \-\-simplified\-colors
384 option to instead use one color for 'covered' code and another for 'uncovered'.
385
386 .SS Date and owner binning
387
388 .B "Date binning"
389 annotates coverage reports with age-of-last-change information to distinguish
390 recently added or modified code which has not been tested from older, presumed
391 stable code which is also not tested.
392 .B "Owner binning"
393 adds annotation identifying the author of changes.
394 .br
395
396 Both age and ownership reporting can be used to enhance team efforts to maintain
397 good coverage discipline by spotlighting coverage shortfalls in recently
398 modified code, even in the absence of baseline coverage data.
399 .br
400
401 To enable date and owner binning, the
402 .B \-\-annotate\-script
403 option must be used to specify a script that provides source code line age and
404 ownership information.
405 .br
406
407 For each source line, age is the interval since the most recent modification date
408 and the owner is the user identity responsible for the most recent change to that line.
409 .br
410
411 Line coverage overall totals and counts for each of the 12 classification categories are
412 collected for each of the specified age ranges (see the
413 .B \-\-date\-bins
414 option, below).
415
416 .SS Script conventions
417
418 Some
419 .B genhtml
420 options expect the name of an external script or tool as argument. These
421 scripts are then run as part of the associated function. This includes the
422 following options:
423
424 .RS
425 .B \-\-annotate\-script
426 .br
427 .B \-\-context\-script
428 .br
429 .B \-\-criteria\-script
430 .br
431 .B \-\-resolve\-script
432 .br
433 .B \-\-select\-script
434 .br
435 .B \-\-version\-script
436 .br
437 .RE
438
439 While each script performs a separate function there are some common aspects
440 in the way these options are handled:
441
442 .IP 1. 3
443 If the callback script name ends in
444 .B \.pm
445 then the script is assumed to be a Perl module.
446 .br
447 A perl module may offer performance advantages over an external script, as it is compiled once and loaded into the interpreter and because it can load and maintain internal state.
448 .br
449 The module is expected to export a method 'new', which is
450 called with the script name and the script parameters (if any) as arguments. It is expected to return an object which implements several standard methods:
451 .br
452 .I $callback_obj = packagename\-\>new(perl_module_file, args);
453 .RS 3
454 .IP version\-script 3
455 .I $version = $callback_obj->extract_version($source_file_ename);
456 .br
457 .I $match = $callback_obj->check_version($old_version, $new_version, $source_file_name);
458 .br
459 .RS
460 .IP $match 3
461 is expected to be 1 (true) if the version keys refer to the came file and 0 (false) otherwise.
462 .PP
463
464 .IP $version 3
465 is a string representing a unique identifier of the particular version of the file
466 .PP
467 .RE
468
469 See example implementations
470 .I $LCOV_HOME/share/lcov/support-scripts/gitversion.pm
471 and
472 .I $LCOV_HOME/share/lcov/support-scripts/getp4version.pm.
473 .PP
474 .IP annotate\-script 3
475 .I ($status, $array) = $callback_obj->annotate($source_file_name);
476 .br
477 .br
478 .br
479
480 where
481 .RS
482 .IP $status 3
483 is 0 if the command succeeded and nonzero otherwise.
484 .I $status
485 is interpreted in same way as the return code from 'system(..)'
486 .PP
487 .IP $array 3
488 is a list of line data of the form:
489 .br
490 .I [$text, $abbrev, $full_name, $when, $changelist].
491 .PP
492 .br
493
494 and
495
496 .IP $text 3
497 is the source text from the corresponding line (without newline termination)
498 .PP
499 .IP $abbrev 3
500 is the "abbreviated author name" responsible for this line of code. This is the name that will be used in the various HTML tables. For example, for brevity/readability, you may want to strip the domain from developers who are inside your organization. If there is no associated author, then the value should be
501 .I \"NONE\".
502 .PP
503 .IP $full_name 3
504 is the "full author name" which is used in annotation tooltips. See the
505 .I genhtml_annotate_tooltip
506 entry in man
507 .B lcovrc(5).
508 .I $fullname
509 may be
510 .I undef
511 if the full name and abbreviated names are the same.
512 .PP
513 .IP $when 3
514 is the timestamp associated with the most recent edit of the corresponding
515 line and may be
516 .I \"NONE\"
517 if there is no associated time.
518 .PP
519 .IP $changelist 3
520 is the commit identifier associated with the most recent change to this line, or
521 .I \"NONE\"
522 if there isn't one.
523 .PP
524
525
526 See example implementations
527 .I $LCOV_HOME/share/lcov/support-scripts/gitblame.pm
528 and
529 .I $LCOV_HOME/share/lcov/support-scripts/p4annotate.pm.
530 .RE
531
532 .IP context\-script
533 .I $hash = $callback_obj->context();
534 .br
535 .br
536
537 where
538 .I $hash
539 is a reference to a hash of key/value pairs which are meaningful to you.
540 This data is stored in the
541 .I profile
542 database. See the 'profile' section in man
543 .B lcovrc(5)
544 for more information.
545
546 If your callback is not a perl module - for example, is a shellscript - then it should return a string such that the first word on each line is the key and the remainder is the associated data. If a key is repeated, then the corresponding data strings are concatenated, separated by newline.
547
548 If you want to record only system information, then a shell callback is likely sufficient. If you want to record any tool-specific/internal information, then you will need to implement a perl module so that your callback will be able to access the information.
549 Note that the constructor of your
550 .I context-script
551 callback (or of any callback) can perform any additional actions which
552 are required - for example, to write additional files, to query or set
553 tool-specific information,
554 .I etc.
555 For example, the example implementation, below, has an option to append
556 comments to the generated .info file.
557
558
559 See the example implementation
560 .I $LCOV_HOME/share/lcov/support-scripts/context.pm.
561 .RE
562
563
564
565 .IP criteria\-script
566 .I ($status, $array) = $callback_obj->check_criteria($obj_name, $type, $json);
567 .br
568 .br
569
570 where
571 .RS
572 .IP $obj_name 3
573 is the source file or directory name, or \"top\" of the object whose coverage criteria is being checked.
574 .PP
575 .IP $type 3
576 is the object type - either
577 .I \"file\", \"directory\", or \"top\".
578 .PP
579 .IP $json 3
580 is the coverage data associated with this object, in JSON format - see below.
581 .PP
582 .IP $status 3
583 is the return status of the operation, interpreted the same way as the
584 .I annotate
585 callback status, described above.
586 .PP
587 .IP $array 3
588 is a reference to a possibly empty list of strings which will be reported by genhtml. The strings are are expected to explain why the coverage criteria failed.
589 .PP
590
591 See example implementations
592 .I $LCOV_HOME/share/lcov/support-scripts/criteria.pm.
593 .RE
594
595 .IP resolve\-script
596 $newpath = $callback_obj->resolve($source_file_name)
597 .br
598 .br
599
600 where
601 .I $newpath
602 is the correct path to the indicated source file or
603 .I undef
604 if the source file is not found by the callback.
605 .PP
606
607 .RE
608
609 .IP 2. 3
610 The option may be specified as a single
611 .I split_char
612 separated string which is divied into words (see
613 .B man lcovrc(5)
614 ), or as a list of arguments.
615 The resulting command line is passed
616 to a shell interpreter to be executed.
617 The command line includes the script path followed by optional additional parameters
618 separated by spaces. Care must be taken to provide proper quoting if script
619 path or any parameter contains spaces or shell special characters.
620 .PP
621
622 .IP 3. 3
623 If an option is specified multiple times, then the parameters are
624 .I not
625 split, but are simply concatenated to form the command line - see the examples, below.
626 .br
627 For simplicity and ease of understanding: your command line should
628 pass all arguments individually, or all as a comma-separated list - not a mix of the two.
629 .PP
630
631 .IP 4. 3
632 .B genhtml
633 passes any additional parameters specified via option arguments
634 between the script path and the parameters required by the script's function.
635 .br
636 .PP
637
638 Example:
639 .br
640
641 .RS
642 genhtml --annotate-script /bin/script.sh
643 .br
644 --annotate-script arg0 ...
645 .br
646
647 results in the same callback as
648
649 .br
650 genhtml --annotate-script "/bin/script.sh arg0" ...
651 .br
652
653 or
654
655 .br
656 genhtml --annotate-script /bin/script.sh,arg0 ...
657 .br
658
659 Note that the first form is preferred.
660
661 .RE
662
663 The resulting
664 .B genhtml
665 callback executes the command line:
666 .br
667
668 .RS
669 /bin/script.sh arg0
670 .I source_file_name
671 .RE
672 .br
673
674 Similarly
675 .br
676 .RS
677 genhtml --annotate-script
678 .I /bin/myMoodule.pm
679 .br
680 --annotate-script arg0 --annotate-script arg1 ...
681 .br
682
683 or
684 .br
685 genhtml --annotate-script
686 .I /bin/myMoodule.pm,arg0,arg1
687 .br
688
689 .br
690 .RE
691
692 result in
693 .B genhtml
694 executing
695 .br
696
697 .RS
698 $annotateCallback = myModule->new(arg0, arg1);
699 .RE
700
701 to initialize the class object -
702 .I arg0
703 and
704 .I arg1
705 passed as strings - and then to execute
706
707 .RS
708 ($status, $arrayRef) = $annotateCallback(
709 .I source_file_name
710 );
711 .RE
712
713 to retrieve the annotation information.
714
715 In contrast, the command
716 .br
717 .RS
718 genhtml --annotate-script
719 .I /bin/myMoodule.pm
720 .br
721 --annotate-script arg0,arg1 ...
722 .RE
723 would result in
724 .B genhtml
725 initializing the callback object via
726 .br
727
728 .RS
729 $annotateCallback = myModule->new("arg0,arg1");
730 .RE
731 where "arg0,arg1" is passed as single comma-separated string.
732
733 Similarly, the command
734 .br
735 .RS
736 genhtml --annotate-script
737 .I /bin/myMoodule.pm,arg0
738 .br
739 --annotate-script arg1 ...
740 .RE
741 would very likely result in an error when genhtml tries to find
742 a script called "/bin/mymodule.pm,arg0".
743
744
745 Note that multiple instances of each script may execute simultaneously if the
746 .B \-\-parallel
747 option was specified. Therefore each script must either be reentrant or should arrange for its own synchronization, if necessary.
748 .br
749 In particular, if your callback is implemented via a perl module:
750 .IP \- 3
751 the class object associated with the module will initialized once (in the parent process)
752 .PP
753 .IP \- 3
754 The callback will occur in the child process (possibly simultaneously with other child processes).
755 .PP
756 As a result: if your callback needs to pass data back to the parent, you will need to arrange a communication mechanism to do so.
757 .br
758
759 .SS Additional considerations
760
761 If the
762 .B \-\-criteria\-script
763 option is used, genhtml will use the referenced script to determine whether your coverage criteria have been met - and will return a non\-zero status and print a message if the criteria are not met.
764 .br
765
766 The
767 .B \-\-version\-script
768 option is used to verify that the same/compatible source code versions are displayed as were used to capture coverage data, as well as to verify that the same source code was used to capture coverage information which is going to be merged and to verify that the source version used for filtering operations is compatible with the version used to generate the data.
769
770 HTML output files are created in the current working directory unless the
771 .B \-\-output\-directory
772 option is used. If
773 .I tracefile
774 or
775 .I baseline\-file
776 ends with ".gz", it is assumed to be GZIP\-compressed and the gunzip tool
777 will be used to decompress it transparently.
778
779 Note that all source code files have to be present and readable at the
780 exact file system location they were compiled, and all path references in the input data ".info" and "diff" files must match exactly (i.e., exact string match).
781 .br
782
783 Further, the
784 .BR \-\-version\-script ", " \-\-annotate\-script ", and " \-\-criteria\-script " scripts "
785 use the same path strings. However, see the
786 .B \-\-substitute
787 and
788 .B \-\-resolve\-script
789 options for a mechanism to adjust extracted paths so they match your source and/or revision control layout.
790
791 .br
792 You can use the
793 .BR check_exisitence_before_callback
794 configuration option to tell the tool to check that the file exists before
795 calling the
796 .BR \-\-version\-script
797 or
798 .BR \-\-annotate\-script
799 callback. See man
800 .B lcovrc(5)
801 for details.
802 .br
803
804 .SS Additional options
805
806 Use option
807 .B \-\-diff\-file
808 to supply a unified diff file that represents the changes to the source
809 code files between the version used to compile and capture the baseline
810 trace files, and the version used to compile and capture the current
811 trace files.
812
813 Use option
814 .B \-\-css\-file
815 to modify layout and colors of the generated HTML output. Files are
816 marked in different colors depending on the associated coverage rate.
817 .br
818
819 By default, the coverage limits for low, medium and high coverage are set to
820 0\-75%, 75\-90% and 90\-100% percent respectively. To change these
821 values, use configuration file options.
822 .br
823
824 .RS
825 .IR genhtml_hi_limit " and " genhtml_med_limit
826 .RE
827 .br
828
829 or type-specific limits:
830 .br
831
832 .RS
833 .IR genhtml_line_hi_limit " and " genhtml_line_med_limit
834 .br
835 .IR genhtml_branch_hi_limit " and " genhtml_branch_med_limit
836 .br
837 .IR genhtml_function_hi_limit " and " genhtml_function_med_limit
838 .br
839 .RE
840
841 See man
842 .B lcovrc(5)
843 for details.
844
845 Also note that when displaying percentages, 0% and 100% are only printed when
846 the values are exactly 0% and 100% respectively. Other values which would
847 conventionally be rounded to 0% or 100% are instead printed as nearest
848 non\-boundary value. This behavior is in accordance with that of the
849 .BR gcov (1)
850 tool.
851
852 By default,
853 .B genhtml
854 reports will include both line and function coverage data.
855 Neither branch or MC/DC data is displayed by default; you can use the
856 .B \-\-branch\-coverage
857 and
858 .B \-\-mcdc\-coverage
859 options to enable branch or MC/DC coverage, respectively - or you can permanently enable branch coverage by adding the appropriate
860 settings to your personal, group, or site lcov configuration file. See the
861 .B branch_coverage
862 and
863 .B mcdc_coverage
864 sections of man
865 .B lcovrc(5)
866 for details.
867
868
869 .SH OPTIONS
870
871 In general, (almost) all
872 .B genhtml
873 options can also be specified in your personal, group, project, or site
874 configuration file - see man
875 .B lcovrc(5)
876 for details.
877
878
879 .B \-h
880 .br
881 .B \-\-help
882 .RS
883 Print a short help text, then exit.
884
885 .RE
886 .B \-\-version
887 .RS
888 Print version number, then exit.
889
890 .RE
891 .B \-v
892 .br
893 .B \-\-verbose
894 .RS
895 Increment informational message verbosity. This is mainly used for script and/or flow debugging - e.g., to figure out which data files are found, where.
896 Also see the \-\-quiet flag.
897
898 .RE
899 .B \-q
900 .br
901 .B \-\-quiet
902 .RS
903 Decrement informational message verbosity.
904
905 Decreased verbosity will suppress 'progress' messages for example - while error and warning messages will continue to be printed.
906
907 .RE
908 .B \-\-debug
909 .RS
910 Increment 'debug messages' verbosity. This is useful primarily to developers who want to enhance the lcov tool suite.
911
912 .RE
913 .B \-\-validate
914 .RS
915 Check the generated HTML to verify that there are no dead hyperlinks and no unused files in the output directory.
916 The checks can also be enabled by setting environment variable
917 .B LCOV_VALIDATE = 1.
918 This option is primarily intended for use by developers who modify the HTML report.
919
920 .RE
921 .B \-\-flat
922 .br
923 .B \-\-hierarchical
924 .RS
925 Use the specified HTML report hierarchy layout.
926 .br
927
928 The default HTML report is 3 levels:
929
930 .RS 2
931 .IP 1. 3
932 .B top\-level:
933 table of all directories,
934 .PP
935
936 .IP 2. 3
937 .B directory:
938 table of source files in a directory, and
939 .PP
940
941 .IP 3. 3
942 .B source file detail:
943 annotated source code.
944 .PP
945 .RE
946
947 Option
948 .B \-\-hierarchical
949 produces a multilevel report which follows the directory structure of the
950 source code (similar to the file tool in Microsoft Windows).
951
952 Option
953 .B \-\-flat
954 produces a two-level HTML report:
955
956 .RS 2
957 .IP 1. 3
958 .B top\-level:
959 table of all project source files, and
960 .PP
961
962 .IP 2. 3
963 .B source file detail:
964 annotated source code.
965 .PP
966 .RE
967
968 The 'flat' view can reduce the number of clicks required to navigate around
969 the coverage report - but is unwieldy except for rather small projects consisting of only a few source files. It can be useful in 'code review' mode, even for very large projects (see the
970 .I \-\-select\-script
971 option).
972 .br
973 Most large projects follow a rational directory structure - which favors the 'hierarchical' report format. Teams responsible for a particular module can focus on a specific subdirectory or set of subdirectories.
974
975 Only one of options
976 .B \-\-flat
977 or
978 .B \-\-hierarchical
979 can be specified at the same time.
980
981 These options can also be persistently set via the lcovrc configuration file
982 using either:
983 .br
984
985 .RS
986 .I genhtml_hierarchical
987 = 1
988 .br
989 .RE
990
991 or
992 .br
993
994 .RS
995 .I genhtml_flat_view
996 = 1
997 .br
998 .RE
999
1000 See man
1001 .B lcovrc(5)
1002 for details.
1003
1004 .RE
1005 .B \-f
1006 .br
1007 .B \-\-frames
1008 .RS
1009 Use HTML frames for source code view.
1010
1011 If enabled, a frameset is created for each source code file, providing
1012 an overview of the source code as a "clickable" image. Note that this
1013 option will slow down output creation noticeably because each source
1014 code character has to be inspected once. Note also that the GD.pm Perl
1015 module has to be installed for this option to work (it may be obtained
1016 from http://www.cpan.org).
1017
1018 This option can also be controlled from the
1019 .I genhtml_frames
1020 entry of the
1021 .B lcovrc
1022 file.
1023
1024 Please note that there is a bug in firefox and in chrome, such that
1025 enabling frames will disable hyperlinks from the 'directory' level summary
1026 table entry to the first line in the corresponding file in the particular
1027 category - e.g., to the first 'MIS' line (vanilla coverage report - see the
1028 .i \-\-show\-navigation
1029 option, below), to
1030 the first 'UNC' branch (differential coverage report), etc.
1031 Hyperlinks from the summary table at the top of the 'source detail' page are not affected.
1032
1033 .RE
1034 .B \-s
1035 .br
1036 .B \-\-show\-details
1037 .RS
1038 Generate detailed directory view.
1039
1040 When this option is enabled,
1041 .B genhtml
1042 generates two versions of each source file file entry in the corresponding summary table:
1043 .IP
1044 one containing the standard information plus a link to a
1045 "detailed" version, and
1046 .PP
1047 .IP
1048 a second which contains the number of coverpoints in the hit by each
1049 testcase.
1050 .br
1051 Note that missed coverpoints are not shown in the per-testcase table entry data.
1052 .PP
1053
1054 The corresponding summary table is found on the 'directory' page of the default 3-level genthm report, or on the top-level page of the 'flat' report (see
1055 .I genhtml \-\-flat ...
1056 ), or on the parent directory page of the 'hierarchical' report (see
1057 .I genhtml \-\-hierarchical ...
1058 ).
1059
1060 Note that this option may significantly increase memory consumption.
1061
1062 .RE
1063 .BI "\-b " baseline\-file\-pattern
1064 .br
1065 .BI "\-\-baseline\-file " baseline\-file\-pattern
1066 .RS
1067 Use data in the files found from glob pattern
1068 .I baseline\-file\-pattern
1069 as coverage baseline.
1070
1071 .B \-\-baseline\-file
1072 may be specified multiple times - for example, if you have multiple trace data files for each of several test suites and you do not want to go through the additional step of merging all of them into a single aggregated data file.
1073
1074 The coverage data files specified by
1075 .I baseline\-file\-pattern
1076 is read and used as the baseline for classifying the change in coverage represented by the coverage counts in
1077 .IR tracefile\-patterns .
1078 If
1079 .I baseline\-file\-pattern
1080 is a directory, then genhtml will search the directory for all files ending in '.info'.
1081 See the
1082 .I info_file_extension
1083 section in
1084 .B man(5) lcovrc
1085 for how to change this pattern.
1086
1087 In general, you should specify a diff file in unified diff format via
1088 .B \-\-diff\-file
1089 when you specify a
1090 .IR \-\-baseline\-file\-pattern .
1091 Without a diff file, genhtml will assume that there are no source differences
1092 between 'baseline' and 'current'.
1093 For example: this might be used to find
1094 incremental changes caused by the addition of more testcases, or to compare
1095 coverage results between gcc versions, or between gcc and llvm.
1096
1097 .RE
1098 .BI "\-\-baseline\-title " title
1099 .RS
1100 Use
1101 .I title
1102 as the descriptive label text for the source of coverage baseline data.
1103
1104 .RE
1105 .BI "\-\-baseline\-date " date
1106 .RS
1107 Use
1108 .I date
1109 as the collection date in text format for the coverage baseline data.
1110 If this argument is not specified, the default is to use the creation time of the first file matched by
1111 .I baseline\-file\-pattern
1112 as the baseline date. If there are multiple baseline files, then the creation date of the first file is used.
1113
1114 .RE
1115 .BI "\-\-current\-date " date
1116 .RS
1117 Use
1118 .I date
1119 as the collection date in text format for the coverage baseline data.
1120 If this argument is not specified, the default is to use the creation time of the current
1121 .IR tracefile .
1122
1123 .RE
1124 .BI "\-\-diff\-file " diff\-file
1125 .RS
1126 Use the
1127 .I diff\-file
1128 as the definition for source file changes between the sample points for
1129 .I baseline\-file\-pattern
1130 and
1131 .IR tracefile(s) .
1132 .br
1133
1134
1135 Note:
1136
1137 .IP - 3
1138 if filters are applied during the creation of a differential coverage report,
1139 (see the
1140 ,I \-\-filter
1141 section, below), then those filters will be applied to the
1142 .I baseline coverage data
1143 (see the
1144 .I \-\-baseline\-file
1145 section, above) as well as to the
1146 .I current coverage data.
1147 It is important that the
1148 .I diff-file
1149 accurately reflect all source code changes so that the baseline coverage data can be correctly filtered.
1150 .PP
1151
1152 .IP - 3
1153 Best practice is to use a
1154 .I \-\-version\-script
1155 callback to verify that source versions match before source-based filtering is applied.
1156 .PP
1157
1158 It is almost always a better idea to filter at capture or aggregate time - not at report generation.
1159
1160 A suitable
1161 .I \"universal diff\"
1162 input file for the
1163 .I \-\-diff\-file
1164 option
1165 can be generated using either the "p4udiff" or "gitdiff" sample scripts that are provided as part of this package, or by using revision control commands directly.
1166
1167 The "p4udiff" or "gitdiff" sample scripts are found in:
1168
1169 .RS
1170 \*[scriptdir]/p4udiff
1171 .br
1172 .RE
1173
1174 and
1175
1176 .RS
1177 \*[scriptdir]/gitdiff
1178 .br
1179 .RE
1180
1181
1182 These scripts simply post\-process the 'p4' or 'git' output to (optionally) remove files that are not of interest and to explicitly note files which have not changed.
1183
1184 .B p4udiff
1185 accepts either a changelist ID or the literal string "sandbox"; "sandbox" indicates that there are modified files which have not been checked in.
1186 See "
1187 .I gitdiff \-\- help
1188 " and "
1189 .I p4udiff \-\- help
1190 " for more information.
1191
1192 It is useful to note unchanged files denoted by lines of the form:
1193 .br
1194
1195 .RS
1196 diff [optional header strings]
1197 .br
1198 === file_path
1199 .RE
1200 .br
1201
1202 in the p4diff/gitdiff output as this knowledge will help to suppress spurious 'path mismatch' warnings. See the
1203 .B \-\-elide\-path\-mismatch
1204 and
1205 .B \-\-build\-directory
1206 entries, below.
1207
1208 In general, you will specify
1209 .B \-\-baseline\-file
1210 when you specify
1211 .BR \-\-diff\-file .
1212 The
1213 .I baseline_files
1214 are used to compute coverage differences (
1215 .I e.g.
1216 gains and losses) between the baseline and current, where the
1217 .I diff_file
1218 is used to compute code changes: source text is
1219 identical between 'baseline' and 'current'.
1220 If you specify
1221 .I baseline_files
1222 but no
1223 .I diff_file,
1224 the tool will assume that there are no code changes between baseline and current.
1225 If you specify a
1226 .I diff_file
1227 but no
1228 .I baseline_files,
1229 the tool will assume that there is no baseline coverage data (no baseline code was covered); as result unchanged code (
1230 .I i.e.,
1231 which does not appear in the
1232 .I diff_file
1233 will be categorized as eiher GIC (covered) or UIC (not covered) while new or changed code will be categorized as either GNC or UNC.
1234
1235 .RE
1236 .BI "\-\-annotate\-script " script
1237 .RS
1238 Use
1239 .I script
1240 to get source code annotation data.
1241
1242 Use this option to specify an external tool or command line that
1243 .B genhtml
1244 can use to obtain source code annotation data such as age and author of the last
1245 change for each source code line.
1246 .br
1247
1248 This option also instructs
1249 .B genhtml
1250 to add a summary table to the HTML report header that shows counts in the various coverage categories, associated with each date bin. In addition, each source code line will show age and owner information.
1251 Annotation data is also used to populate a 'tooltip' which appears when the mouse
1252 hovers over the associated source code. See the
1253 .I genhtml_annotate_tooltip
1254 entry in man
1255 .B lcovrc(5)
1256 for details.
1257 .br
1258
1259 The specified
1260 .I script
1261 is expected to obtain age and ownership information
1262 for each source code line from the revision management system and to output
1263 this information in the format described below.
1264 .br
1265
1266 If the annotate script fails and annotation errors are ignored via
1267 .BR --ignore-errors ,
1268 then
1269 .B genhtml
1270 will try to load the source file normally. If the file is not present or not readable, and the
1271 .B \-\-synthesize\-missing
1272 flag is specified, then
1273 .B genhtml
1274 will synthesize fake data for the file.
1275 .br
1276
1277 .B genhtml
1278 will emit an error if you have specified an annotation script but no files are
1279 successfully annotated (see below).
1280 This can happen, for example, if your P4USER, P4CLIENT,
1281 or P4PORT environment variables are not set correctly -
1282 .I e.g. if the
1283 Jenkins user who generates coverage reports is not the same and the user
1284 who checked out the code and owns the sandbox.
1285 .br
1286
1287 Sample annotation scripts for Perforce ("p4annotate") and git ("gitblame")
1288 are provided as part of this package in the following locations:
1289 .br
1290
1291 .RS
1292 \*[scriptdir]/p4annotate
1293 .br
1294 .RE
1295
1296 and
1297 .br
1298
1299 .RS
1300 \*[scriptdir]/gitblame
1301 .br
1302 .RE
1303
1304 Note that these scripts generate annotations from the file version checked in to the repository - not the locally modified file in the build directory. If you need annotations for locally modified files, you can shelve your changes in P4, or check them in to a local branch in git.
1305
1306 .B "Creating your own script"
1307 .br
1308
1309 When creating your own script, please first see
1310 .B "Script considerations"
1311 above for general calling conventions and script requirements.
1312 .br
1313
1314 .I script
1315 is called by genhtml with the following command line:
1316
1317 .RS
1318 .B script
1319 .I "[additional_parameters] " source_file_name
1320 .RE
1321 .br
1322
1323 where
1324
1325 .RS
1326 .B script
1327 .br
1328 .RS
1329 is the script executable
1330 .br
1331 .RE
1332
1333 .B additional_parameters
1334 .br
1335 .RS
1336 includes any optional parameters specified (see
1337 .B "Script conventions"
1338 above)
1339 .br
1340 .RE
1341
1342 .B source_file_name
1343 .br
1344 .RS
1345 is the source code file name
1346 .br
1347 .RE
1348 .RE
1349
1350 The
1351 .I script
1352 executable should output a line to the standard output stream in the following format for each line in file
1353 .IR source_file_name :
1354 .br
1355
1356 .RS
1357 .IR commit_id | author_data | date | source_code
1358 .br
1359 .RE
1360
1361 where
1362
1363 .RS
1364 .B commit_id
1365 .br
1366 .RS
1367 is an ID identifying the last change to the line or NONE if this file is not
1368 checked in to your revision control system.
1369 .br
1370 .B genhtml
1371 counts the file as not 'successfully annotated' if
1372 .B commit_id
1373 is
1374 .I NONE
1375 and as 'successfully annotated' otherwise.
1376 .br
1377 .RE
1378 .br
1379
1380 .B author_data
1381 .br
1382 .RS
1383 identifies the author of the last change.
1384 .br
1385 For backward compatibility with existing annotate-script implementations,
1386 two
1387 .I author_data
1388 formats are supported:
1389 .IP - 3
1390 .I string
1391 : the string used as both the 'abbreviated name' (used as 'owner' name in
1392 HTML output and callbacks) and as 'full name' (used in tooltip callbacks)
1393 .PP
1394 .IP - 3
1395 .I abbrev_string;full_name
1396 : the
1397 .I author_data
1398 string contains both an 'abbreviated name' and a 'full name' - separated by a semicolon character (';').
1399 .br
1400 This is useful when generating coverage reports for opensource software
1401 components where there are many 'External' contributors who you do not want
1402 to distinguish in 'owner' summary tables but you still want to know who the
1403 actual author was. (See the
1404 .B gitblame
1405 callback script for an example.)
1406 .PP
1407 .br
1408 .RE
1409 .br
1410
1411 .B date
1412 .br
1413 .RS
1414 is the data of last change in W3CDTF format (<YYYY>-<MM>-<DD>T<hh>:<mm>:<ss><TZD>)
1415 .br
1416 .RE
1417 .br
1418
1419 .B source_code
1420 .br
1421 .RS
1422 is the line's source code
1423 .br
1424 .RE
1425 .br
1426 .RE
1427
1428 The script should return 0 (zero) if processing was successful and non\-zero if it encountered an error.
1429 .br
1430
1431 .RE
1432 .BI "\-\-criteria\-script " script
1433 .RS
1434 Use
1435 .I script
1436 to test for coverage acceptance criteria.
1437 .br
1438
1439 Use this option to specify an external tool or command line that
1440 .B genhtml
1441 can use to determine if coverage results meet custom acceptance criteria.
1442 Criteria checking results are shown in the standard output log of
1443 .BR genhtml .
1444 If at least one check fails,
1445 .B genhtml
1446 will exit with a non-zero exit code after completing its processing.
1447 .br
1448
1449 A sample coverage criteria script is provided as part of this package in the
1450 following location:
1451
1452 .RS
1453 \*[scriptdir]/criteria
1454 .br
1455 .RE
1456
1457 The sample script checks that top\-level line coverage meets the criteria "UNC + LBC + UIC == 0" (added code and newly activated code must be tested, and existing tested code must not become untested).
1458 .br
1459
1460 As another example, it is possible to create scripts that mimic the
1461 .B "lcov \-\-fail\-under\-lines"
1462 feature by checking that the ratio of exercised lines to total lines ("(GNC + GIC + CBC) / (GNC + GIC + CBC + UNC + UIC + UBC)") is greater than the threshold - either only at the top level, in every directory, or wherever desired. Similarly, criteria may include branch and function coverage metrics.
1463 .br
1464
1465 By default the criteria script is called for all source code hierarchy levels, i.e.: top-level, directory, and file-level. The
1466 .I criteria_callback_levels
1467 configuration file option can be used to limit the hierarchy levels to any combination of 'top', 'directory', or 'file' levels.
1468 .br
1469
1470 Example:
1471 .br
1472
1473 .RS
1474 genhtml --rc criteria_callback_levels=directory,top ...
1475 .br
1476 .RE
1477
1478 You can increase the amount of data passed to the criteria script using
1479 configuration file option
1480 .IR criteria_callback_data .
1481 By default, only total counts are included. Specifying "date" adds per
1482 date-bin counts, "owner" adds per owner-bin counts.
1483 .br
1484
1485 Example:
1486 .br
1487
1488 .RS
1489 genhtml --rc criteria_callback_data=date,owner ...
1490 .br
1491 .RE
1492
1493 See man
1494 .B lcovrc(5)
1495 for more details.
1496
1497 .B "Creating your own script"
1498 .br
1499
1500 When creating your own script, please first see
1501 .B "Script considerations"
1502 above for general calling conventions and script requirements.
1503 .br
1504
1505 .I script
1506 is run with the following command line for each source code file,
1507 leaf\-directory, and top-level coverage results:
1508
1509 .RS
1510 .B script
1511 .I "[additional_parameters] " "name " " type"
1512 .I "coverage_data"
1513 .br
1514 .RE
1515
1516 where
1517
1518 .RS
1519 .B script
1520 .br
1521 .RS
1522 is the script executable
1523 .br
1524 .RE
1525
1526 .B additional_parameters
1527 .br
1528 .RS
1529 includes any optional parameters specified (see
1530 .B "Script conventions"
1531 above)
1532 .br
1533 .RE
1534
1535 .B name
1536 .br
1537 .RS
1538 is the name of the object for which coverage criteria should be checked,
1539 that is either the source code file name, directory name, or "top" if the
1540 script is called for top-level data
1541 .br
1542 .RE
1543
1544 .B type
1545 .br
1546 .RS
1547 is the type of source code object for which coverage criteria should be
1548 checked, that is one of "file", "directory", or "top"
1549 .br
1550 .RE
1551
1552 .B coverage_data
1553 .br
1554 .RS
1555 is either a coverage data hash or a JSON representation of coverage data hash of the corresponding source code
1556 object.
1557 If the callback is a Perl module, then the it is passes a hash object - other wise, it is passed a JSON representation of that data.
1558 .br
1559 .RE
1560 .RE
1561
1562 The JSON data format is defined as follows:
1563 .br
1564
1565 {
1566 .br
1567 "<type>": {
1568 .br
1569 "found": <count>,
1570 .br
1571 "hit": <count>,
1572 .br
1573 "<category>": <count>,
1574 .br
1575 ...
1576 .br
1577 },
1578 .br
1579 "<bin_type>": {
1580 .br
1581 "<bin_id>" : {
1582 .br
1583 "found": <count>,
1584 .br
1585 "hit": <count>,
1586 .br
1587 "<category>": <count>,
1588 .br
1589 ...
1590 .br
1591 },
1592 .br
1593 ...
1594 .br
1595 },
1596 .br
1597 ...
1598 .br
1599 }
1600 .br
1601
1602 where
1603
1604 .RS
1605 .B type
1606 .br
1607 .RS
1608 specifies the type of coverage as one of "line", "function", or "branch"
1609 .br
1610 .RE
1611
1612 .B bin_type
1613 .br
1614 .RS
1615 specifies the type of per-bin coverage as one of "line_age", "function_age", or "branch_age" for date-bin data, and "line_owners" or "branch_owners" for owner-bin data
1616 .br
1617 .RE
1618
1619 .B bin_id
1620 .br
1621 .RS
1622 specifies the date-bin index for date-bin data, and owner ID for owner-bin data.
1623 .br
1624 .RE
1625
1626 .B found
1627 .br
1628 .RS
1629 defines the number of found lines, functions, or branches
1630 .br
1631 .RE
1632
1633 .B hit
1634 .br
1635 .RS
1636 defines the number of hit lines, functions, or branches
1637 .br
1638 .RE
1639
1640 .B category
1641 .br
1642 .RS
1643 defines the number of lines, functions, or branches that fall in the specified
1644 category (see
1645 .B "Differential coverage"
1646 above)
1647 .br
1648 .RE
1649
1650 .RE
1651
1652 Note that data is only reported for non-empty coverage types and bins.
1653 .br
1654
1655 The script should return 0 (zero) if the criteria are met and non\-zero otherwise.
1656 .br
1657
1658 If desired, it may print a single line output string which will be appended to the error log if the return status is non\-zero. Additionally, non\-empty lines are appended to the genhtml standard output log.
1659 .br
1660
1661 .RE
1662
1663 .B \-\-version\-script
1664 .I script
1665 .br
1666 .RS
1667 Use
1668 .I script
1669 to get source code file version data.
1670
1671 Use this option to specify an external tool or command line that
1672 .B genhtml
1673 can use to obtain a source code file's version ID when generating HTML or
1674 applying source filters (see
1675 .B \-\-filter
1676 option).
1677 .br
1678
1679 A version ID can be a file hash or commit ID from revision control. It is used to check the version of the source file which is loaded against the version which was used to generate coverage data (i.e., the file version seen by lcov/geninfo). It is important that source code versions match - otherwise inconsistent or confusing results may be produced.
1680 .br
1681
1682 Version mismatches typically happen when the tasks of capture, aggregation, and report generation are split between multiple jobs - e.g., when the same source code is used in multiple projects, a unified/global coverage report is required, and the projects accidentally use different revisions.
1683 .br
1684
1685 If your .info (coverage data) file does not contain version information - for example, because it was generated by a tool which did not support versioning - then you can use the
1686 .I compute_file_version " = 1"
1687 config file option to generate the data afterward. A convenient way to do this might be to use
1688 .B lcov
1689 .I \-\-add\-tracefile
1690 to read the original file, insert version information, and write out the result.
1691 See man
1692 .B lcovrc(5)
1693 for more details.
1694
1695
1696 Sample scripts for Perforce ("getp4version"), git ("gitversion") and using an md5 hash ("get_signature") are provided as part of this package in the following locations:
1697 .br
1698
1699 .RS
1700 .I \*[scriptdir]/getp4version
1701 .RE
1702 .br
1703
1704 .RS
1705 .I \*[scriptdir]/gitversion
1706 .RE
1707 .br
1708
1709 and
1710 .br
1711
1712 .RS
1713 .I \*[scriptdir]/get_signature
1714 .RE
1715 .br
1716
1717 Note that you must use the same script/same mechanism to determine the file version when you extract, merge, and display coverage data - otherwise, you may see spurious mismatch reports.
1718 .br
1719
1720 .B "Creating your own script"
1721 .br
1722
1723 When creating your own script, please first see
1724 .B "Script considerations"
1725 above for general calling conventions and script requirements.
1726 .br
1727
1728 .I "script "
1729 is used both to generate and to compare the version ID to enable retaining history between calls or to do more complex processing to determine equivalence.
1730 It will be called by
1731 .B genhtml
1732 with either of the following command lines:
1733 .br
1734
1735 1. Determine source file version ID
1736 .br
1737
1738 .RS
1739 .BI script " source_file_name"
1740 .RE
1741 .br
1742
1743 It should write the version ID of
1744 .I " source_file_name "
1745 to stdout and return a 0 exit status.
1746 If the file is not versioned, it should write an empty string and return a 0 exit status.
1747 .br
1748
1749 2. Compare source file version IDs
1750
1751 .RS
1752 .B script \-\-compare
1753 .I " source_file_name source_file_id"
1754 .br
1755 .I " info_file_id"
1756 .br
1757
1758 .RE
1759 where
1760 .RS
1761 .br
1762
1763 .B "source_file_name"
1764 .RS
1765 is the source code file name
1766 .RE
1767 .br
1768
1769 .B "source_file_id "
1770 .RS
1771 is the version ID returned by calling "script source_file_name"
1772 .RE
1773 .br
1774
1775 .B "info_file_id "
1776 .RS
1777 is the version ID found in the corresponding .info file
1778 .RE
1779 .RE
1780 .br
1781
1782 It should return non\-zero if the IDs do not match.
1783 .br
1784
1785 .RE
1786
1787 .B \-\-resolve\-script
1788 .I script
1789 .br
1790 .RS
1791 Use
1792 .I script
1793 to find the file path for some source file which which appears in
1794 an input data file if the file is not found after applying
1795 .I \-\-substitute
1796 patterns and searching the
1797 .I \-\-source\-directory
1798 list. This option is equivalent to the
1799 .B resolve_script
1800 config file option. See man
1801 .B lcovrc(5)
1802 for details.
1803 .RE
1804
1805 .B \-\-select\-script
1806 .I callback
1807 .br
1808 .RS
1809 Use
1810 .I callback
1811 to decide whether a particular source line is interesting and should be
1812 included in the output data/generated report or not.
1813
1814 This option is equivalent to the
1815 .B select_script
1816 config file option. See man
1817 .B lcovrc(5)
1818 for details.
1819 .RE
1820
1821 .BI "\-\-checksum "
1822 .RS
1823 Specify whether to compare stored tracefile checksum to checksum computed from the source code.
1824
1825 Checksum verification is
1826 .B disabled
1827 by default.
1828
1829 When checksum verification is enabled, a checksum will be computed for each source
1830 code line and compared to the checksum found in the 'current' tracefile.
1831 This will help to prevent attempts to display source code which is not identical
1832 to the code used to generate the coverage data.
1833
1834 Note that this option is somewhat subsumed by the
1835 .B \-\-version\-script
1836 option - which does something similar, but at the 'whole file' level.
1837
1838 .RE
1839 .B \-\-fail\-under\-branches
1840 .I percentage
1841 .br
1842 .RS
1843 Use this option to tell genhtml to exit with a status of 1 if the total
1844 branch coverage is less than
1845 .I percentage.
1846 See
1847 .B man lcov(1)
1848 for more details.
1849
1850 .RE
1851 .B \-\-fail\-under\-lines
1852 .I percentage
1853 .br
1854 .RS
1855 Use this option to tell genhtml to exit with a status of 1 if the total
1856 line coverage is less than
1857 .I percentage.
1858 See
1859 .B man lcov(1)
1860 for more details.
1861
1862
1863 .RE
1864 .B \-\-new\-file\-as\-baseline
1865 .RS
1866 By default, when code is identified on source lines in the 'current' data which were not identified as code in the 'baseline' data, but the source text has not changed, their coverpoints are categorized as "included code":
1867 .I GIC
1868 or
1869 .I UIC.
1870 .br
1871
1872 However, if the configuration of the coverage job has been recently changed to instrument additional files, then all un\-exercised coverpoints in those files will fall into the
1873 .I GIC
1874 category - which may cause certain coverage criteria checks to fail.
1875 .br
1876
1877 When this option is specified, genhtml pretends that the baseline data for the file is the same as the current data - so coverpoints are categorized as
1878 .I CBC
1879 or
1880 .I UBC
1881 which do not trigger the coverage criteria check.
1882
1883 Please note that coverpoints in the file are re\-categorized only if:
1884
1885 .RS
1886 .IP \(bu 3
1887 There is no 'baseline' data for any coverpoint in this file, AND
1888 .PP
1889 .IP \(bu 3
1890 The file pre\-dates the baseline: the oldest line in the file is older than the 'baseline' data file (or the value specified by the
1891 .B \-\-baseline\-date
1892 option).
1893 .PP
1894 .RE
1895
1896 .RE
1897 .BI "\-\-elide\-path\-mismatch"
1898 .RS
1899 Differential categorization uses file pathnames to match coverage entries from the ".info" file with file difference entries in the unified\-diff\-file. If the entries are not identical, then categorization may be incorrect or strange.
1900
1901 When paths do not match, genhtml will produce "path" error messages to tell you about the mismatches.
1902
1903 If mismatches occur, the best solution is to fix the incorrect entries in the .info and/or unified\-diff\-file files. However, fixing these entries is not possible, then you can use this option to attempt to automatically work around them.
1904 .br
1905
1906 When this option is specified, genhtml will pretend that the unified\-diff\-file entry matches the .info file entries if:
1907
1908 .RS
1909 .IP \(bu 3
1910 the same path is found in both the 'baseline' and 'current' .info files, and
1911 .PP
1912 .IP \(bu 3
1913 the basename of the path in the .info file and the path in the unified\-diff\-file are the same, and
1914 .PP
1915 .IP \(bu 3
1916 there is only one unmatched unified\-diff\-file entry with that basename.
1917 .PP
1918 .RE
1919
1920 See the
1921 .B \-\-diff\-file
1922 and
1923 .B \-\-build\-directory
1924 entries for a discussion of how to avoid spurious warnings and/or incorrect matches.
1925
1926 .RE
1927 .BI "\-\-synthesize\-missing"
1928 .RS
1929 Generate (fake) file content if source file does not exist.
1930 This option can be used to work around otherwise fatal annotation errors.
1931
1932 When generating annotated file content,
1933 .B genhtml
1934 assumes that the source was written 'now' (so age is zero), the author is
1935 .I no.body
1936 and the commit ID is
1937 .I synthesized.
1938 These names and ages will appear in your HTML reports.
1939
1940 .br
1941 This option is equivalent config file
1942 .I genhtml_synthesize_missing
1943 parameter; see man
1944 .B lcovrc(5)
1945 for details.
1946
1947
1948 .RE
1949 .BI "\-\-date\-bins " day[,day,...]
1950 .RS
1951 The
1952 .B \-\-date\-bins
1953 option is used to specify age boundaries (cutpoints) for date\-binning classification. Each
1954 .I age
1955 element is expected to be an integer number of days prior to today (or prior to your SOURCE_DATE_EPOCH environment variable, if set). If
1956 .I \-\-date\-bins is not specified, the default is to use 4 age ranges: less than 7 days, 7 to 30 days, 30 to 180 days, and more than 180 days.
1957 This option is equivalent to the
1958 .I genhtml_date_bins
1959 config file option. See man
1960 .B lcovrc(5).
1961
1962 This argument has no effect if there is no
1963 .I source\-annotation\-script .
1964
1965 .RE
1966 .BI "\-\-date\-labels " string[,string,...]
1967 .RS
1968 The
1969 .B \-\-date\-labels
1970 option is used to specify labels used for the 'date\-bin' table entries in the HTML report.
1971 .br
1972 The number of labels should be one greater than the number of cutpoints.
1973 .br
1974 If not specified, the default is to use label strings which specify the
1975 .I [from ..to)
1976 range of ages held by the corresponding bin.
1977
1978 One possible use of this option is to use release names in the tables -
1979 .I i.e.,
1980 to indicate the release in which each particular line first appeared.
1981
1982 This option is equivalent to the
1983 .I genhtml_date_labels
1984 config file option. See man
1985 .B lcovrc(5).
1986
1987 This argument has no effect if there is no
1988 .I source\-annotation\-script .
1989
1990 .RE
1991 .BI "\-\-show\-owners " [all]
1992 .RS
1993 If the
1994 .B \-\-show\-owners
1995 option is used, each coverage report header report contain a summary table, showing counts in the various coverage categories for everyone who appears in the revision control annotation as the most recent editor of the corresponding line. If the optional argument 'all' is not specified, the table will show only users who are responsible for un\-exercised code lines. If the optional argument is specified, then users responsible for any code lines will appear. In both cases, users who are responsible for non\-code lines (e.g, comments) are not shown.
1996 This option does nothing if
1997 .B \-\-annotate\-script
1998 is not used; it needs revision control information provided by calling the script.
1999
2000 Please note: if the
2001 .I all
2002 option is not specified, the summary table will contain "Total" rows for all date/owner bins which are not empty - but there will be no secondary "File/Directory" entries for elements which have no "missed" coverpoints.
2003
2004 .br
2005 This option is equivalent config file
2006 .I genhtml_show_owner_table
2007 parameter; see man
2008 .B lcovrc(5)
2009 for details.
2010
2011 The lcovrc controls
2012 .I owner_table_entries
2013 and
2014 .I truncate_owner_table
2015 can be used to improve readability by limiting the number of authors who are displayed in the table
2016 when the author number is large.
2017 For example, if your configuration is:
2018 .RS
2019 .PP
2020 .I owner_table_entries = 5
2021 .IP
2022 .PP
2023 .I truncate_owner_table = top,directory
2024 .PP
2025 .RE
2026 then the owner table displayed at the top- and directory-levels will be truncated while the table shown at the 'file' level will display the full list.
2027
2028 See man
2029 .B lcovrc(5)
2030 for details.
2031
2032
2033 .RE
2034 .BI "\-\-show\-noncode "
2035 .RS
2036 By default, the source code detail view does not show owner or date annotations in the far-left column for non\-code lines (e.g., comments). If the
2037 .B \-\-show\-noncode
2038 option is used, then the source code view will show annotations for both code and non\-code lines.
2039 This argument has no effect if there is no
2040 .I source\-annotation\-script .
2041
2042 .br
2043 This option is equivalent config file
2044 .I genhtml_show_noncode_owners
2045 parameter; see man
2046 .B lcovrc(5)
2047 for details.
2048
2049
2050 .RE
2051 .BI "\-\-show\-zero\-columns "
2052 .RS
2053 By default, columns whose entries are all zero are removed (not shown) in the summary table at the top of each HTML page.
2054 If the
2055 .B \-\-show\-zero\-columns
2056 option is used, then those columns will be shown.
2057
2058 When columns are retained, then all the tables have the same width/contain the same number of columns - which may be a benefit in some situations.
2059
2060 When columns are removed, then the tables are more compact and easier to read.
2061 This is especially true in relatively mature development environments, when there are very few un-exercised coverpoints in the project.
2062
2063 .RE
2064 .BI "\-\-show\-navigation "
2065 .RS
2066 By default, the summary table in the source code detail view does not contain hyperlinks from the number to the first line in the corresponding category ('Hit' or 'Missed') and from the current location to the next location in the current category, in non-differential coverage reports. (This is the lcov 'legacy' view non-differential reports.)
2067
2068 If the
2069 .B \-\-show\-navigation
2070 option is used, then the source code summary table will be generated with navigation links.
2071 Hyperlinks are always generated for differential coverage reports.
2072
2073 This feature enables developers to find and understand coverage issues more quickly than they might otherwise, if they had to rely on scrolling.
2074
2075 See the
2076 .I \-\-frames
2077 description above for a description of a browser bug which disables
2078 these hyperlinks in certain conditions.
2079
2080 Navigation hyperlinks are always enabled in differential coveage report.
2081
2082 .RE
2083 .BI "\-\-show\-proportions "
2084 .RS
2085 In the 'function coverage detail' table, also show the percentage of lines and branches within the function which are exercised.
2086
2087 This feature enables developers to focus attention on functions which have the largest effect on overall code coverage.
2088
2089 This feature is disabled by default.
2090 Note that this option requires that you use a compiler version which is new enough to support function begin/end line reports or that you configure the tool to derive the required data - see the
2091 .BI derive_function_end_line
2092 discussion in man
2093 .B lcovrc(5).
2094
2095
2096 .RE
2097 .BI "\-\-simplified\-colors "
2098 .RS
2099 By default, each differential category is colorized uniquely in the source code detail view. With this option, only two colors are used: one for covered code and another for uncovered code. Note that ECB and EUB code is neither covered nor uncovered - and so may be difficult to distinguish in the source code view, as they will be presented in normal background color.
2100
2101 .RE
2102 .BI "\-\-exclude "
2103 .I pattern
2104 .RS
2105 pattern is a glob\-match pattern of filenames to exclude from the report.
2106 Files which do NOT match will be included.
2107 See the lcov man page for details.
2108
2109 .RE
2110 .BI "\-\-include "
2111 .I pattern
2112 .RS
2113 pattern is a glob\-match pattern of filenames to include in processing.
2114 Files which do not match will be excluded from the report.
2115 See the lcov man page for details.
2116 .RE
2117
2118 .B \-\-erase\-functions
2119 .I regexp
2120 .br
2121 .RS
2122 Exclude coverage data from lines which fall within a function whose name matches the supplied regexp. Note that this is a mangled or demangled name, depending on whether the
2123 .B \-\-demangle\-cpp
2124 option is used or not.
2125
2126 Note that this option requires that you use a compiler version which is new enough to support function begin/end line reports or that you configure the tool to derive the required data - see the
2127 .BI derive_function_end_line
2128 discussion in man
2129 .B lcovrc(5).
2130
2131
2132 .RE
2133 .B \-\-substitute
2134 .I regexp_pattern
2135 .br
2136 .RS
2137 Apply Perl regexp
2138 .IR regexp_pattern
2139 to source file names found during processing. This is useful when some file paths in the baseline or current .info file do not match your source layout and so the source code is not found.
2140 See the lcov man page for more details.
2141
2142 Note that the substitution patterns are applied to the
2143 .IR \-\-diff\-file
2144 entries as well as the baseline and current .info files.
2145 .RE
2146
2147 .B \-\-omit\-lines
2148 .I regexp_pattern
2149 .br
2150 .RS
2151 Exclude coverage data from lines whose content matches
2152 .IR regexp .
2153
2154 Use this switch if you want to exclude line and branch coverage data for some particular constructs in your code (e.g., some complicated macro).
2155 See the lcov man page for details.
2156
2157 .RE
2158 .BI "\-\-parallel "
2159 .I [ integer ]
2160 .br
2161 .BI "\-j "
2162 .I [ integer ]
2163 .RS
2164 Specify parallelism to use during processing (maximum number of forked child processes). If the optional integer parallelism parameter is zero or is missing, then use to use up the number of cores on the machine. Default is to use a single process (no parallelism).
2165 .br
2166 Also see the
2167 .I memory, memory_percentage, max_fork_fails
2168 and
2169 .I fork_fail_timeout
2170 entries in man
2171 .B lcovrc(5).
2172
2173
2174 .RE
2175 .BI "\-\-memory "
2176 .I integer
2177 .RS
2178 Specify the maximum amount of memory to use during parallel processing, in Mb. Effectively, the process will not fork() if this limit would be exceeded. Default is 0 (zero) - which means that there is no limit.
2179
2180 This option may be useful if the compute farm environment imposes strict limits on resource utilization such that the job will be killed if it tries to use too many parallel children - but the user does not know a priori what the permissible maximum is. This option enables the tool to use maximum parallelism - up to the limit imposed by the memory restriction.
2181
2182 The configuration file
2183 .I memory_percentage
2184 option provided another way to set the maximum memory consumption.
2185 See man
2186 .B lcovrc (5)
2187 for details.
2188
2189
2190 .RE
2191 .BI \-\-filter " filters"
2192 .RS
2193 Specify a list of coverpoint filters to apply to input data.
2194
2195 Note that certain filters apply only to C/C++ source files.
2196 .B genhtml
2197 associates the file extension ('.c', '.vhd',
2198 .I etc.
2199 ) with its source language. See the
2200 .I c_file_extentions
2201 and
2202 .I rtl_file_extensions
2203 sections of man
2204 .B lcovrc(5)
2205 for a description of the default associations and how they can be changed.
2206
2207 Note that filters are applied to both 'branch' and 'MC/DC' coverpoints,
2208 where appropriate: if a particular filter would remove some branch,
2209 then it will also remove corresponding MC/DC coverpoints - for example,
2210 .I "\-\-filter branch"
2211 will remove MC/DC coverpoints if there is no conditional expression on the
2212 corresponding line, and
2213 .I "\-\-filter branch_region"
2214 will remove both branch and MC/DC coverpoints in the marked region.
2215
2216 Most filters need the source code; filters are not applied if the source file is not available. Similarly, for each source file, if the version recorded in the coverage data (the '.info' file)
2217 does not match the version found on the filesystem, then a
2218 .I version
2219 error is reported. If the
2220 .I version
2221 error is ignored, then filtering is not applied to the mismatched file.
2222 See the
2223 .I \-\-version\-script
2224 for more information.
2225
2226 .I filters
2227 can be a comma\-separated list of the following keywords:
2228
2229 .IP branch: 3
2230 ignore branch counts for C/C++ source code lines which do not appear to contain conditionals. These may be generated automatically by the compiler (e.g., from C++ exception handling) - and are not interesting to users.
2231 This option has no effect unless
2232 .B \-\-branch\-coverage
2233 is used.
2234
2235 See also man
2236 .B lcovrc(5)
2237 - which describes several variables which affect branch filtering:
2238 .I filter_lookahead
2239 and
2240 .I filter_bitwise_conditional.
2241
2242 The most common use for branch filtering is to remove compiler-generated branches related to C++ exception handlers. See the no_exception_branch' option in man
2243 .B lcovrc(5)
2244 for a way to remove all identified exception branches.
2245 .PP
2246
2247 .IP brace: 3
2248 ignore line coverage counts on the closing brace of C/C++ code block, if the line contains only a closing brace and the preceding line has the same count or if the close brace has a zero count and either the preceding line has a non\-zero count, or the close brace is not the body of a conditional.
2249
2250 These lines seem to appear and disappear in gcov output - and cause differential coverage to report bogus LBC and/or GIC and/or UIC counts. Bogus LBC or UIC counts are a problem because an automated regression which uses pass criteria "LBC + UIC + UNC == 0" will fail.
2251 .PP
2252
2253 .IP blank: 3
2254 ignore lines which contain only whitespace (or whitespace + comments) whose 'hit' count is zero. These appear to be a 'gcov' artifact related to compiler-generated code - such as exception handlers and destructor calls at the end of scope - and can confuse differential coverage criteria.
2255 .br
2256 If lcovrc option
2257 .I filter_blank_aggressive = 1
2258 is enabled, then blank lines will be ignored whether their 'hit' count is zero or not. Aggressive filtering may be useful in LLVM-generated coverage data, which tends to include large numbers of such lines.
2259 .PP
2260
2261 .IP directive: 3
2262 ignore lines which look like C compiler directives: #ifdef, #include, #define,
2263 .I etc.
2264 These lines are sometimes included by
2265 .I llvm\-cov
2266 when LLVM profile data is translated to LCOV format.
2267 .PP
2268
2269 .IP exception: 3
2270 Exclude branches related to C++ exception handling from branch coverage.
2271 Whether C++ exception branches are identified and removed is dependent on your compiler/toolchain correctly marking them in the generated coverage data.
2272 See the
2273 .I no_exception_branch
2274 section of
2275 .B man lcovrc(5).
2276
2277 .IP initializer: 3
2278 Exclude lines which appear to be part of a C++ std::initializer_list.
2279 .PP
2280
2281 .IP line: 3
2282 alias for "\-\-filter brace,blank".
2283 .PP
2284
2285 .IP mcdc: 3
2286 Remove MC/DC coverpoint which contains single expression, if 'branch' coverpoint
2287 is present on the same line.
2288 Singe-element MC/DC coverpoints are identical to the corresponding branch - except
2289 in the case of compile-time expression evaluation, for example, in a template
2290 function.
2291
2292 .IP orphan: 3
2293 Remove branches which appear by themselves -
2294 .I i.e.,
2295 the branch has only one destination and so cannot be a conditional.
2296 .br
2297 These occur most frequently as a result of exception branch filtering.
2298
2299 .IP range: 3
2300 Ignore line and branch coverpoints on lines which are out-of range/whose line number is beyond the end of the source file. These appear to be gcov artifacts caused by a macro instantiation on the last line of the file.
2301 .PP
2302
2303 .IP region: 3
2304 apply LCOV_EXCL_START/LCOV_EXCL_STOP directives found in source text to the coverpoints found in the current and baseline .info files.
2305 This option may be useful in cases that the source code was not found during 'lcov \-\-capture ...' but is accessible now.
2306 .PP
2307
2308 .IP branch_region: 3
2309 apply LCOV_EXCL_BR_START/LCOV_EXCL_BR_STOP directives found in source text to the coverpoints found in the current and baseline .info files.
2310 This is similar to the 'region option, above - but applies to branch coverpoints only.
2311 .PP
2312
2313 .IP function: 3
2314 combine data for every "unique" function which is defined at the same file/line.
2315 .I geninfo/gcov
2316 seem to have a bug such that they create multiple entries for the same function.
2317 This feature also merges all instances of the same template function/template method.
2318 .PP
2319
2320 .IP trivial: 3
2321 remove trivial functions and associated coverpoints. 'Trivial' functions are
2322 whose body is empty/do not contain any statements. Commonly, these include compiler-generated methods (e.g., default constructors and assignment operators) as well as static initialization wrappers, etc.
2323
2324 Note that the
2325 .I trivial
2326 filter requires function end line information - and so requires that you use a compiler version which is new enough to support begin/end line reports
2327 (
2328 .I e.g.,
2329 gcc/9 or newer) or that you enable lcov/genhtml/geninfo to derive the information:
2330
2331 In man
2332 .B lcovrc(5),
2333 see the
2334 .I derive_function_end_line
2335 setting as well as the
2336 .I trivial_function_threshold
2337 setting. The former is used to turn end line calculation on or off,
2338 and the latter to change the lookahead used to determine whether the
2339 function body is empty.
2340 Also see the
2341 .I lcov_filter_parallel
2342 and
2343 .I lcov_filter_chunk_size
2344 settings, which may improve CPU performance if the number of files to process is very large.
2345 .PP
2346
2347 .RE
2348 .BI "\-o " output\-directory
2349 .br
2350 .BI "\-\-output\-directory " output\-directory
2351 .RS
2352 Create files in
2353 .I output\-directory.
2354
2355 Use this option to tell
2356 .B genhtml
2357 to write the resulting files to a directory other than
2358 the current one. If
2359 .I output\-directory
2360 does not exist, it will be created.
2361
2362 It is advisable to use this option since depending on the
2363 project size, a lot of files and subdirectories may be created.
2364
2365 .RE
2366 .BI "\-t " title
2367 .br
2368 .BI "\-\-title " title
2369 .RS
2370 Display
2371 .I title
2372 in header table of all pages.
2373
2374 .I title
2375 is written to the "Test:"-field in the header table at the top of each
2376 generated HTML page to identify the context in which a particular output
2377 was created. By default, this is the name of the 'current; tracefile.
2378
2379 A common use is to specify a test run name, or a version control system
2380 identifier (perforce changelist or git SHA, for example) that indicates
2381 the code level that was tested.
2382
2383 .RE
2384 .BI "\-\-header\-title " BANNER
2385 .RS
2386 Display
2387 .I BANNER
2388 in header of all pages.
2389
2390 .I BANNER
2391 is written to the header portion of each generated HTML page.
2392 By default, this
2393 simply identifies this as an LCOV (differential) coverage report.
2394
2395 A common use is to specify the name of the project or project branch and the
2396 Jenkins build ID.
2397
2398 .RE
2399 .BI "\-\-footer " FOOTER
2400 .RS
2401 Display
2402 .I FOOTER
2403 in footer of all pages.
2404
2405 .I FOOTER
2406 is written to the footer portion of each generated HTML page.
2407 The default simply identifies the LCOV tool version used to generate the report.
2408
2409 .RE
2410 .BI "\-d " description\-file
2411 .br
2412 .BI "\-\-description\-file " description\-file
2413 .RS
2414 Read test case descriptions from
2415 .IR description\-file .
2416
2417 All test case descriptions found in
2418 .I description\-file
2419 and referenced in the input data file are read and written to an extra page
2420 which is then incorporated into the HTML output.
2421
2422 The file format of
2423 .IR "description\-file " is:
2424
2425 for each test case:
2426 .RS
2427 TN:<testname>
2428 .br
2429 TD:<test description>
2430
2431 .RE
2432
2433 Valid test case names can consist of letters, numbers and the underscore
2434 character ('_').
2435 .RE
2436 .br
2437
2438 .B \-k
2439 .br
2440 .B \-\-keep\-descriptions
2441 .RS
2442 Do not remove unused test descriptions.
2443
2444 Keep descriptions found in the description file even if the coverage data
2445 indicates that the associated test case did not cover any lines of code.
2446
2447 This option can also be configured permanently using the configuration file
2448 option
2449 .IR genhtml_keep_descriptions .
2450
2451 .RE
2452 .BI "\-c " css\-file
2453 .br
2454 .BI "\-\-css\-file " css\-file
2455 .RS
2456 Use external style sheet file
2457 .IR css\-file .
2458
2459 Using this option, an extra .css file may be specified which will replace
2460 the default one. This may be helpful if the default colors make your eyes want
2461 to jump out of their sockets :)
2462
2463 This option can also be configured permanently using the configuration file
2464 option
2465 .IR genhtml_css_file .
2466
2467 .RE
2468 .BI "\-\-build\-directory " dirname
2469 .RS
2470 To support 'linked build directory' structures, add 'dirname' to the list of
2471 places to search for soft links to source files -
2472 .I e.g.,
2473 to handle the case that the links point to source files which are held in your
2474 revision control system, and appear in the
2475 .I \-\-diff\-file
2476 data. In this use case, paths in the coverage data very likely refer to the
2477 structure seen by the compiler during the build - so resolving them back to
2478 the corresponding revsion-controlled source structure is likely to be successful.
2479 .br
2480
2481 Look in
2482 .I dirname
2483 for file paths which appear in
2484 .IR tracefile
2485 \- possibly after substitutions have been applied \-
2486 which are soft links.
2487 Both the original file path and the path to the linked file will resolve to the same
2488 .I \-\-diff\-file entry.
2489
2490 This option can be specified multiple times, to add more directories to the search path.
2491
2492
2493 .RE
2494 .BI "\-\-source\-directory " dirname
2495 .RS
2496 Add 'dirname' to the list of places to look for source files.
2497 .br
2498
2499 For relative source file paths
2500 .I e.g.
2501 paths found in
2502 .IR tracefile,
2503 or in
2504 .IR diff-file
2505 \- possibly after substitutions have been applied -
2506 .B genhtml
2507 will first look for the path from 'cwd' (where genhtml was
2508 invoked) and
2509 then from each alternate directory name in the order specified.
2510 The first location matching location is used.
2511
2512 This option can be specified multiple times, to add more directories to the source search path.
2513
2514
2515 .RE
2516 .BI "\-p " prefix
2517 .br
2518 .BI "\-\-prefix " prefix
2519 .RS
2520 Remove
2521 .I prefix
2522 from all directory names.
2523
2524 Because lists containing long filenames are difficult to read, there is a
2525 mechanism implemented that will automatically try to shorten all directory
2526 names on the overview page beginning with a common prefix. By default,
2527 this is done using an algorithm that tries to find the prefix which, when
2528 applied, will minimize the resulting sum of characters of all directory
2529 names.
2530
2531 Use this option to specify the prefix to be removed by yourself.
2532
2533 .RE
2534 .B \-\-no\-prefix
2535 .RS
2536 Do not remove prefix from directory names.
2537
2538 This switch will completely disable the prefix mechanism described in the
2539 previous section.
2540
2541 This option can also be configured permanently using the configuration file
2542 option
2543 .IR genhtml_no_prefix .
2544
2545 .RE
2546 .B \-\-no\-source
2547 .RS
2548 Do not create source code view.
2549
2550 Use this switch if you don't want to get a source code view for each file.
2551
2552 This option can also be configured permanently using the configuration file
2553 option
2554 .IR genhtml_no_source .
2555
2556 .RE
2557 .B \-\-no\-html
2558 .RS
2559 Do not create HTML report.
2560
2561 Use this switch if you want some artifact of coverage report generation -
2562 .I e.g.,
2563 the coverage criteria check or the serialized coverage DB,
2564 .B etc.
2565 - but do not need the coverage report HTML itself.
2566
2567
2568 .RE
2569 .BI "\-\-num\-spaces " spaces
2570 .RS
2571 Replace tabs in source view with
2572 .I num
2573 spaces.
2574
2575 Default value is 8.
2576
2577 This option can also be configured permanently using the configuration file
2578 option
2579 .IR genhtml_num_spaces .
2580
2581 .RE
2582 .B \-\-highlight
2583 .RS
2584 Highlight lines with converted\-only coverage data.
2585
2586 Use this option in conjunction with the
2587 .B \-\-diff
2588 option of
2589 .B lcov
2590 to highlight those lines which were only covered in data sets which were
2591 converted from previous source code versions.
2592
2593 This option can also be configured permanently using the configuration file
2594 option
2595 .IR genhtml_highlight .
2596
2597 .RE
2598 .B \-\-legend
2599 .RS
2600 Include color legend in HTML output.
2601
2602 Use this option to include a legend explaining the meaning of color coding
2603 in the resulting HTML output.
2604
2605 This option can also be configured permanently using the configuration file
2606 option
2607 .IR genhtml_legend .
2608
2609 .RE
2610 .BI "\-\-html\-prolog " prolog\-file
2611 .RS
2612 Read customized HTML prolog from
2613 .IR prolog\-file .
2614
2615 Use this option to replace the default HTML prolog (the initial part of the
2616 HTML source code leading up to and including the <body> tag) with the contents
2617 of
2618 .IR prolog\-file .
2619 Within the prolog text, the following words will be replaced when a page is generated:
2620
2621 .B "@pagetitle@"
2622 .br
2623 The title of the page.
2624
2625 .B "@basedir@"
2626 .br
2627 A relative path leading to the base directory (e.g., for locating css\-files).
2628
2629 This option can also be configured permanently using the configuration file
2630 option
2631 .IR genhtml_html_prolog .
2632
2633 .RE
2634 .BI "\-\-html\-epilog " epilog\-file
2635 .RS
2636 Read customized HTML epilog from
2637 .IR epilog\-file .
2638
2639 Use this option to replace the default HTML epilog (the final part of the HTML
2640 source including </body>) with the contents of
2641 .IR epilog\-file .
2642
2643 Within the epilog text, the following words will be replaced when a page is generated:
2644
2645 .B "@basedir@"
2646 .br
2647 A relative path leading to the base directory (e.g., for locating css\-files).
2648
2649 This option can also be configured permanently using the configuration file
2650 option
2651 .IR genhtml_html_epilog .
2652
2653 .RE
2654 .BI "\-\-html\-extension " extension
2655 .RS
2656 Use customized filename extension for generated HTML pages.
2657
2658 This option is useful in situations where different filename extensions
2659 are required to render the resulting pages correctly (e.g., php). Note that
2660 a '.' will be inserted between the filename and the extension specified by
2661 this option.
2662
2663 This option can also be configured permanently using the configuration file
2664 option
2665 .IR genhtml_html_extension .
2666 .RE
2667
2668 .B \-\-html\-gzip
2669 .RS
2670 Compress all generated html files with gzip and add a .htaccess file specifying
2671 gzip\-encoding in the root output directory.
2672
2673 Use this option if you want to save space on your webserver. Requires a
2674 webserver with .htaccess support and a browser with support for gzip
2675 compressed html.
2676
2677 This option can also be configured permanently using the configuration file
2678 option
2679 .IR genhtml_html_gzip .
2680
2681 .RE
2682 .B \-\-sort-tables
2683 .br
2684 .B \-\-no\-sort
2685 .RS
2686 Specify whether to include sorted views of file and directory overviews.
2687
2688 This option replaces the deprecated
2689 .I "\-\-sort"
2690 option.
2691 .I "\-\-sort"
2692 is still supported and is treated as an alias of
2693 .I "\-\-sort\-tables"
2694 but will be removed in a subsequent LCOV release.
2695
2696 Use
2697 .B \-\-sort-tables
2698 to include sorted views or
2699 .B \-\-no\-sort
2700 to not include them.
2701 Sorted views are
2702 .B enabled
2703 by default.
2704
2705 When sorted views are enabled, each overview page will contain links to
2706 views of that page sorted by coverage rate.
2707
2708 This option can also be configured permanently using the configuration file
2709 option
2710 .IR genhtml_sort .
2711
2712 .RE
2713 .B \-\-function\-coverage
2714 .br
2715 .B \-\-no\-function\-coverage
2716 .RS
2717 Specify whether to display function coverage summaries in HTML output.
2718
2719 Use \-\-function\-coverage to enable function coverage summaries or
2720 \-\-no\-function\-coverage to disable it. Function coverage summaries are
2721 .B enabled
2722 by default.
2723
2724 This option can also be configured permanently using the configuration file
2725 option
2726 .IR genhtml_function_coverage .
2727
2728 When function coverage summaries are enabled, each overview page will contain
2729 the number of functions found and hit per file or directory, together with
2730 the resulting coverage rate. In addition, each source code view will contain
2731 a link to a page which lists all functions found in that file plus the
2732 respective call count for those functions.
2733 The function coverage page groups the data for every alias of each function, sorted by name or execution count. The representative name of the group of functions is the shorted (i.e., containing the fewest characters).
2734
2735 If using differential coverage and a sufficiently recent compiler version which report both begin and end line of functions (
2736 .I e.g.,
2737 gcc/9 and newer), functions are considered 'new' if any of their source lines have changed.
2738 With older compiler versions, functions are considered 'new' if the function signature has changed or if the entire function is new.
2739
2740 .RE
2741 .B \-\-branch\-coverage
2742 .br
2743 .B \-\-no\-branch\-coverage
2744 .RS
2745 Specify whether to display branch coverage data in HTML output.
2746
2747 Use
2748 .B \-\-branch\-coverage
2749 to enable branch coverage display or
2750 .B \-\-no\-branch\-coverage
2751 to disable it. Branch coverage data display is
2752 .B disabled
2753 by default.
2754
2755 When branch coverage display is enabled, each overview page will contain
2756 the number of branches found and hit per file or directory, together with
2757 the resulting coverage rate. In addition, each source code view will contain
2758 an extra column which lists all branches of a line with indications of
2759 whether the branch was taken or not. Branches are shown in the following format:
2760
2761 ' + ': Branch was taken at least once
2762 .br
2763 ' - ': Branch was not taken
2764 .br
2765 ' # ': The basic block containing the branch was never executed
2766 .br
2767
2768 Note that it might not always be possible to relate branches to the
2769 corresponding source code statements: during compilation, GCC might shuffle
2770 branches around or eliminate some of them to generate better code.
2771
2772 This option can also be configured permanently using the configuration file
2773 option
2774 .IR branch_coverage .
2775
2776 .RE
2777
2778 .B \-\-mcdc\-coverage
2779 .RS
2780 Specify whether to display Modifie Condition / Decision Coverage (MC/DC)
2781 data in HTML output.
2782
2783 MC/DC data display is
2784 .B disabled
2785 by default.
2786
2787 MC/DC coverage is supported for GCC versions 14.2 and higher, or
2788 LLVM 18.1 and higher.
2789 .br
2790 See
2791 .I llvm2lcov \-\-help
2792 for details on MC/DC data capture in LLVM.
2793
2794 When MC/DC display is enabled, each overview page will contain
2795 the number of MC/DC expressions found and hit per file or directory - two senses per expression - together with
2796 the resulting coverage rate. In addition, each source code view will contain
2797 an extra column which lists all expressions and condition senses of a line with indications of
2798 whether the condition was sensitized or not. Conditions are shown in the following format:
2799
2800 .RS 3
2801 .IP T: 3
2802 True sense of subexpression was sensitized: if this subexpression's value had been false, then the condition result would have been different.
2803 .IP t: 3
2804 True sense of subexpression was
2805 .B not
2806 sensitized: the condition result would not change if the subexpression value was different.
2807 .IP F:
2808 False sense of subexpression was sensitized: if this subexpression's value had been true, then the condition result would have been different.
2809 .IP f:
2810 False sense of subexpression was
2811 .B not
2812 sensitized: the condition result would not change if the subexpression value was different.
2813 .RE
2814
2815 Note that branch and MC/DC coverage are identical if the condition is
2816 a simple expression -
2817 .I e.g.,
2818 .RS 3
2819 if (enable) ...
2820 .RE
2821
2822 Note that, where appropriate, filters are applied to both 'branch' and 'MC/DC' coverpoints: if a particular filter would remove some branch,
2823 then it will also remove corresponding MC/DC coverpoints. See the
2824 .I \-\-filter
2825 section, above.
2826
2827 This option can also be configured permanently using the configuration file
2828 option
2829 .IR mcdc_coverage .
2830 See man
2831 .B lcovrc(5) .
2832
2833 Note that MC/DC coverpoints are defined differently by GCC and LLVM.
2834 .IP GCC: 3
2835 evaluates the sensitivity of the condition to the 'true' and 'false' sense of each constituent (leaf) expression independently.
2836 .br
2837 That is: it evaluates the question: does the result of the condition change if
2838 .I this
2839 constituent expression changed from true to false (termed the 'true' sense, above) or from false to true (termed the 'false' sens, above).
2840 .br
2841 For example, the expression
2842 .I A || B
2843 is sensitive to
2844 .I A==true
2845 when
2846 .I B==false,
2847 but is is not sensitive to
2848 .I A==true
2849 when
2850 .I B==true.
2851
2852 .IP LLVM: 3
2853 records the subexpression as covered if and only if there is a pair of evaluations
2854 of the condition such that the condition was
2855 sensitized for both 'true' and 'false' values of the subexpression.
2856 This is defined as an
2857 .I independence pair
2858 in the LLVM documentation.
2859 .PP
2860
2861 That is: the testcase must sensitize both values in order to be marked covered by
2862 LLVM, whereas GCC will independently mark each.
2863 Consequently: in LLVM-generated
2864 .B lcov
2865 reports, either both 'true' and 'false' sensitizations will be covered, or neither will be.
2866 .br
2867 See the examples in tesctcase
2868 .I .../tests/lcov/mcdc.
2869
2870
2871
2872 .RE
2873 .BI "\-\-demangle\-cpp " [param]
2874 .RS
2875 Specify whether to demangle C++ function names.
2876
2877 Use this option if you want to convert C++ internal function names to
2878 human readable format for display on the HTML function overview page.
2879
2880 If called with no parameters, genhtml will use
2881 .I c++filt
2882 for demangling. This requires that the c++filt tool is installed (see
2883 .BR c++filt (1)).
2884
2885 If
2886 .I param
2887 is specified, it is treated as th tool to call to demangle source code.
2888 The
2889 .I \-\-demangle\-cpp
2890 option can be used multiple times to specify the demangling tool and a set of
2891 command line options that are passed to the tool - similar to how the gcc
2892 .I -Xlinker
2893 parameter works. In that case, you callback will be executed as:
2894 .I | demangle_param0 demangle_param1 ...
2895 Note that the demangle tool is called as a pipe and is expected to read from stdin and write to stdout.
2896
2897 .RE
2898 .B \-\-msg\-log
2899 .I [ log_file_name ]
2900 .br
2901 .RS
2902 Specify location to store error and warning messages (in addition to writing to STDERR).
2903 If
2904 .I log_file_name
2905 is not specified, then default location is used.
2906 .RE
2907
2908 .RE
2909 .B \-\-ignore\-errors
2910 .I errors
2911 .br
2912 .RS
2913 Specify a list of errors after which to continue processing.
2914
2915 Use this option to specify a list of error classes after which
2916 .B genhtml
2917 should continue processing with a warning message instead of aborting.
2918 To suppress the warning message, specify the error class twice.
2919 .br
2920
2921 .I errors
2922 can be a comma\-separated list of the following keywords:
2923
2924 .IP annotate: 3
2925 .B \-\-annotate\-script
2926 returned non\-zero exit status - likely a file path or related error. HTML source code display will not be correct and ownership/date information may be missing.
2927 .PP
2928
2929 .IP branch: 3
2930 Branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence.
2931 .PP
2932
2933 .IP callback: 3
2934 Annotate, version, or criteria script error.
2935 .PP
2936
2937 .IP category: 3
2938 Line number categorizations are incorrect in the .info file, so branch coverage line number turns out to not be an executable source line.
2939 .PP
2940
2941 .IP child: 3
2942 child process returned non-zero exit code during
2943 .I \-\-parallel
2944 execution. This typically indicates that the child encountered an error: see the log file immediately above this message.
2945 In contrast: the
2946 .B parallel
2947 error indicates an unexpected/unhandled exception in the child process - not a 'typical' lcov error.
2948 .PP
2949
2950 .IP count: 3
2951 An excessive number of messages of some class has been reported - subsequent messages of that type will be suppressed.
2952 The limit can be controlled by the 'max_message_count' variable. See man
2953 .B lcovrc(5).
2954 .PP
2955
2956 .IP corrupt: 3
2957 Corrupt/unreadable coverage data file found.
2958 .PP
2959
2960 .IP deprecated: 3
2961 You are using a deprecated option.
2962 This option will be removed in an upcoming release - so you should change your
2963 scripts now.
2964 .PP
2965
2966 .IP empty: 3
2967 The patch file specified by the
2968 .B \-\-diff\-file
2969 argument does not contain any differences. This may be OK if there were no source code changes between 'baseline' and 'current' (e.g., the only change was to modify a Makefile) - or may indicate an unsupported file format.
2970 .PP
2971
2972 .IP excessive: 3
2973 your coverage data contains a suspiciously large 'hit' count which is unlikely
2974 to be correct - possibly indicating a bug in your toolchain.
2975 See the
2976 .I excessive_count_threshold
2977 section in man
2978 .B lcorc(5)
2979 for details.
2980 .PP
2981
2982 .IP fork: 3
2983 Unable to create child process during
2984 .I \-\-parallel
2985 execution.
2986 .br
2987 If the message is ignored (
2988 .I \-\-ignore\-errors fork
2989 ), then genhtml
2990 will wait a brief period and then retry the failed execution.
2991 .br
2992 If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find a larger server to run the task.
2993
2994 .PP
2995
2996 .IP format: 3
2997 Unexpected syntax or value found in .info file - for example, negative number or
2998 zero line number encountered.
2999
3000 .PP
3001
3002 .IP inconsistent: 3
3003 This error indicates that your coverage data is internally inconsistent: it makes two or more mutually exclusive claims. For example:
3004 .RS
3005 .IP \- 3
3006 Files have been moved or repository history presented by
3007 .B \-\-diff\-file
3008 data is not consistent with coverage data; for example, an 'inserted' line has baseline coverage data. These issues are likely to be caused by inconsistent handling in the 'diff' data compared to the 'baseline' and 'current' coverage data (e.g., using different source versions to collect the data but incorrectly annotating those differences), or by inconsistent treatment in the 'annotate' script.
3009 Consider using a
3010 .B \-\-version\-script
3011 to guard against version mismatches.
3012 .PP
3013 .IP \- 3
3014 Two or more
3015 .B gcov
3016 data files or
3017 .B lcov
3018 ".info" files report different end lines for the same function. This is likely due either to a gcc/gcov bug or to a source version mismatch.
3019 .br
3020 In this context, if the
3021 .I "inconsistent"
3022 error is ignored, then the tool will record the largest number as the function end line.
3023 .PP
3024 .IP \- 3
3025 Two or more
3026 .B gcov
3027 data files or
3028 .B lcov
3029 ".info" files report different start lines for the same function. This is likely due either to a gcc/gcov bug or to a source version mismatch.
3030 .br
3031 In this context, if the
3032 .I "inconsistent"
3033 error is ignored, then the tool will retain only the first function definition that it saw.
3034 .PP
3035 .IP \- 3
3036 Mismatched function declaration/alias records encountered:
3037 .RS 3
3038 .IP "(backward compatible LCOV format)" 3
3039 function execution count record (
3040 .I FNDA
3041 ) without matching function declaration record (
3042 .I FN
3043 ).
3044 .PP
3045 .IP "(enhanced LCOV format)" 3
3046 function alias record (
3047 .I FNA
3048 ) without matching function declaration record (
3049 .I FLN
3050 ).
3051 .PP
3052 .RE
3053 .PP
3054 .IP \- 3
3055 branch expression (3rd field in the .info file 'BRDA' entry) of merge data does not match
3056
3057 .br
3058 If the error is ignored, the offending record is skipped.
3059 .RE
3060 .PP
3061
3062 .IP internal: 3
3063 internal tool issue detected. Please report this bug along with a testcase.
3064 .PP
3065
3066 .IP mismatch: 3
3067 Incorrect or inconsistent information found in coverage data and/or source code - for example,
3068 the source code contains overlapping exclusion directives.
3069
3070 .PP
3071
3072 .IP missing: 3
3073 remove all coverpoints associated with source files which are not found or are not readable.
3074 This is equivalent to adding a
3075 .I \-\-exclude <name>
3076 pattern for each file which is not found.
3077 .br
3078 If a
3079 .I \-\-resolve\-script
3080 callback is specified, then the file is considered missing if it is not
3081 locally visible and the callback
3082 returns "" (empty string) or 'undef' - otherwise not missing.
3083 .br
3084
3085 .IP negative: 3
3086 negative 'hit' count found.
3087
3088 Note that negative counts may be caused by a known GCC bug - see
3089
3090 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080
3091
3092 and try compiling with "-fprofile-update=atomic". You will need to recompile, re-run your tests, and re-capture coverage data.
3093 .PP
3094
3095
3096 .IP package: 3
3097 A required perl package is not installed on your system. In some cases, it is possible to ignore this message and continue - however, certain features will be disabled in that case.
3098 .PP
3099
3100 .IP parallel: 3
3101 various types of errors related to parallelism -
3102 .I i.e.,
3103 a child process died due to an error. The corresponding error message appears in the log file immediately before the
3104 .I parallel
3105 error.
3106 If you see an error related to parallel execution that seems invalid, it may be a good idea to remove the \-\-parallel flag and try again. If removing the flag leads to a different result, please report the issue (along with a testcase) so that the tool can be fixed.
3107 .PP
3108
3109 .IP path: 3
3110 File name found in
3111 .B \-\-diff\-file
3112 file but does not appear in either baseline or current trace data. These may be mapping issues - different pathname in the tracefile vs. the diff file.
3113 .PP
3114
3115 .IP range: 3
3116 Coverage data refers to a line number which is larger than the number of
3117 lines in the source file. This can be caused by a version mismatch or
3118 by an issue in the
3119 .I gcov
3120 data.
3121 .PP
3122
3123 .IP source: 3
3124 The source code file for a data set could not be found.
3125 .PP
3126
3127 .IP unmapped: 3
3128 Coverage data for a particular line cannot be found, possibly because the source code was not found, or because the line number mapping in the \.info file is wrong.
3129
3130 This can happen if the source file used in HTML generation is not the same as the file used to generate the coverage data - for example, lines have been added or removed.
3131 .PP
3132
3133 .IP unsupported: 3
3134 The requested feature is not supported for this tool configuration. For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases.
3135 .PP
3136
3137 .IP unused: 3
3138 The include/exclude/erase/substitute/omit pattern did not match any file pathnames.
3139 .PP
3140
3141 .IP usage: 3
3142 unsupported usage detected - e.g. an unsupported option combination.
3143 .PP
3144
3145 .IP utility: 3
3146 a tool called during processing returned an error code (e.g., 'find' encountered an unreadable directory).
3147 .PP
3148
3149 .IP version: 3
3150 \-\-version\-script comparison returned non\-zero mismatch indication. It likely that the version of the file which was used in coverage data extraction is different than the source version which was found. File annotations may be incorrect.
3151 .PP
3152
3153 Note that certain error messages are caused by issues that you probably cannot
3154 fix by yourself - for example, bugs in your tool chain which result in
3155 .I inconsistent
3156 coverage DB data (see above).
3157 In those cases, after reviewing the messages you may want to exclude the offending code or the entire offending
3158 file, or you may simply ignore the messages - either by converting to warning or suppressing entirely.
3159 Another alternative is to tell
3160 .B genhtml
3161 about the number of messages you expect - so that it can warn you if something changes
3162 such that the count differs, such that you know to review the messages again.
3163 See the
3164 .I "\-\-expect\-message\-count"
3165 flag, below.
3166
3167 Also see 'man
3168 .B lcovrc(5)
3169 ' for a discussion of the 'max_message_count' parameter which can be used to control the number of warnings which are emitted before all subsequent messages are suppressed. This can be used to reduce log file volume.
3170 .br
3171
3172 .RE
3173 .BI "\-\-expect\-message\-count message_type:expr[,message_type:expr]"
3174 .RS
3175 Give
3176 .B genhtml
3177 a constraint on the number of messages of one or more types which are expected to
3178 be produced during execution. Note that the total includes _all_ messages
3179 of the given type - including those which have been suppressed.
3180 If the constraint is not true, an
3181 error of type
3182 .I "count"
3183 (see above) is generated.
3184 .I message_type
3185 is one of the message mnemonics described above, and
3186 .I expr
3187 may be either
3188 .IP \- 3
3189 an integer - interpreted to mean that there should be exactly that number
3190 of messages of the corresponding type, or
3191 .IP \- 3
3192 a Perl expression containing the substring
3193 .B %C
3194 ; %C is replaced with the total number of messages of the corresponding type and
3195 then evaluated. The constraint is met if the result is non-zero and is not met
3196 otherwise.
3197
3198 For example:
3199 .IP
3200 \-\-expect\-message\-count inconsistent:5
3201 .br
3202 says that we expect exactly 5 messages of type 'inconsistent'.
3203 .PP
3204 .IP
3205 \-\-expect\-message\-count inconsistent:%C==5
3206 .br
3207 also says that we expect exactly 5 messages of this type, but specified
3208 using expression syntax.
3209 .PP
3210 .IP
3211 \-\-expect\-message\-count 'inconsistent : %C > 6 && %C <= 10'
3212 .br
3213 says that we expect the number of messages to be in the range (6:10].
3214 (Note that quoting may be necessary, to protect whitespace from interpretation by
3215 your shell, if you want to improve expression readability by adding spaces to your expression.)
3216 .PP
3217
3218 Multiple constraints can be specified using a comma-separated list or
3219 by using the option multiple times.
3220
3221 This flag is equivalent to the
3222 .I "expect_message_count"
3223 configuration option. See man
3224 .B lcovrc(5)
3225 for more details on the expression syntax and how expressions are interpreted.
3226 The number of messages of the particular type is substituted into the
3227 expression before it is evaluated.
3228
3229 .RE
3230
3231 .BI "\-\-keep\-going "
3232 .RS
3233 Do not stop if error occurs: attempt to generate a result, however flawed.
3234
3235 This command line option corresponds to the
3236 .I stop_on_error
3237 lcovrc option. See man
3238 .B lcovrc(5)
3239 for more details.
3240
3241 .RE
3242
3243 .B \-\-config\-file
3244 .I config\-file
3245 .br
3246 .RS
3247 Specify a configuration file to use.
3248 See man
3249 .B lcovrc(5)
3250 for details of the file format and options. Also see the
3251 .I config_file
3252 entry in the same man page for details on how to include one config file into
3253 another.
3254
3255 When this option is specified, neither the system\-wide configuration file
3256 /etc/lcovrc, nor the per\-user configuration file ~/.lcovrc is read.
3257
3258 This option may be useful when there is a need to run several
3259 instances of
3260 .B genhtml
3261 with different configuration file options in parallel.
3262
3263 Note that this option must be specified in full - abbreviations are not supported.
3264
3265 .RE
3266
3267 .B \-\-profile
3268 .I [ profile\-data\-file ]
3269 .br
3270 .RS
3271 Tell the tool to keep track of performance and other configuration data.
3272 If the optional
3273 .I profile\-data\-file
3274 is not specified, then the profile data is written to a file named
3275 .I "genhtml.json"
3276 in the output directory.
3277
3278 .RE
3279
3280
3281 .B \-\-rc
3282 .IR keyword = value
3283 .br
3284 .RS
3285 Override a configuration directive.
3286
3287 Use this option to specify a
3288 .IR keyword = value
3289 statement which overrides the corresponding configuration statement in
3290 the lcovrc configuration file. You can specify this option more than once
3291 to override multiple configuration statements.
3292 See man
3293 .BR lcovrc (5)
3294 for a list of available keywords and their meaning.
3295 .RE
3296
3297 .BI "\-\-precision " num
3298 .RS
3299 Show coverage rates with
3300 .I num
3301 number of digits after the decimal point.
3302
3303 Default value is 1.
3304
3305 This option can also be configured permanently using the configuration file
3306 option
3307 .IR genhtml_precision .
3308 .RE
3309
3310 .B \-\-merge\-aliases
3311 .RS
3312 Functions whose file/line is the same are considered to be aliases;
3313 .B genthml
3314 uses the shortest name in the list of aliases (fewest characters) as the leader.
3315 .br
3316 This option counts each alias group as a single object - so the 'function'
3317 count will be the number of distinct function groups rather than the total number
3318 of aliases of all functions - and displays them as groups in the 'function detail
3319 table.
3320 .br
3321 Note that this option has an effect only if
3322 .B "\-\-filter function"
3323 has been applied to the coverage DB.
3324 .br
3325
3326 This parameter an be configured via the configuration file
3327 .IR merge_function_aliases
3328 option. See
3329 .B man(5) lcovrc.
3330
3331
3332 .B \-\-suppress\-aliases
3333 .RS
3334 Suppress list of aliases in function detail table.
3335 .br
3336
3337 Functions whose file/line is the same are considered to be aliases;
3338 .B genthml
3339 uses the shortest name in the list of aliases (fewest characters) as the leader.
3340 .br
3341
3342 The number of aliases can be large, for example due to instantiated templates - which can make function coverage results difficult to read. This option removes the list of aliases, making it easier to focus on the overall function coverage number, which is likely more interesting.
3343
3344 Note that this option has an effect only if
3345 .B "\-\-filter function"
3346 has been applied to the coverage DB.
3347
3348 This parameter an be configured via the configuration file
3349 .IR merge_function_aliases
3350 option. See
3351 .B man(5) lcovrc.
3352
3353
3354 .B \-\-forget\-test\-names
3355 .br
3356 .RS
3357 If non\-zero, ignore testcase names in .info file -
3358 .I i.e.,
3359 treat all coverage data as if it came from the same testcase.
3360 This may improve performance and reduce memory consumption if user does
3361 not need per-testcase coverage summary in coverage reports.
3362
3363 This option can also be configured permanently using the configuration file
3364 option
3365 .IR forget_testcase_names .
3366 .RE
3367
3368 .B \-\-missed
3369 .RS
3370 Show counts of missed lines, functions, branches, and MC/DC expressions.
3371
3372 Use this option to change overview pages to show the count of lines, functions,
3373 branches, or MC/DC expressions that were not hit. These counts are represented by negative numbers.
3374
3375 When specified together with \-\-sort\-tables, file and directory views will be sorted
3376 by missed counts.
3377
3378 This option can also be configured permanently using the configuration file
3379 option
3380 .IR genhtml_missed .
3381 .RE
3382
3383 .B \-\-dark\-mode
3384 .RS
3385 Use a light\-display\-on\-dark\-background color scheme rather than the default dark\-display\-on\-light\-background.
3386
3387 The idea is to reduce eye strain due to viewing dark text on a bright screen - particularly at night.
3388 .RE
3389
3390 .B \-\-tempdir
3391 .I dirname
3392 .br
3393 .RS
3394 Write temporary and intermediate data to indicated directory. Default is "/tmp".
3395 .RE
3396
3397 .BI "\-\-preserve "
3398 .RS
3399 Preserve intermediate data files generated by various steps in the tool - e.g., for debugging. By default, these files are deleted.
3400
3401 .RE
3402
3403 .BI "\-\-save "
3404 .RS
3405 Copy
3406 .I unified\-diff\-file, baseline_trace_files,
3407 and
3408 .I tracefile(s)
3409 to
3410 output\-directory.
3411
3412 Keeping copies of the input data files may help to debug any issues or to regenerate report files later.
3413
3414 .RE
3415
3416 .B \-\-sort\-input
3417 .br
3418 .RS
3419 Specify whether to sort file names before capture and/or aggregation.
3420 Sorting reduces certain types of processing order-dependent output differences.
3421 See the
3422 .BI sort_input
3423 section in
3424 man
3425 .B lcovrc(5).
3426
3427 .RE
3428
3429 .BI "\-\-serialize " file_name
3430 .RS
3431 Save coverage database to
3432 .I file_name.
3433
3434 The file is in Perl "Storable" format.
3435
3436 Note that this option may significantly increase
3437 .I genhtml
3438 memory requirements, as a great deal of data must be retained.
3439
3440 .RE
3441
3442 .SH FILES
3443
3444 .I /etc/lcovrc
3445 .RS
3446 The system\-wide configuration file.
3447 .RE
3448
3449 .I ~/.lcovrc
3450 .RS
3451 The per\-user configuration file.
3452 .RE
3453
3454 Sample
3455 .I \-\-diff\-file
3456 data creation scripts:
3457 .RS
3458
3459 .I \*[scriptdir]/p4udiff
3460 .RS
3461 Sample script for use with
3462 .B --diff-file
3463 that creates a unified diff file via
3464 .B Perforce.
3465 .br
3466 .RE
3467
3468 .I \*[scriptdir]/gitdiff
3469 .RS
3470 Sample script for use with
3471 .B --diff-file
3472 that creates a unified diff file via
3473 .B git.
3474 .br
3475 .RE
3476 .RE
3477
3478 Sample
3479 .I \-\-annotate\-script
3480 callback Perl modules:
3481
3482 .RS
3483 .I \*[scriptdir]/p4annotate.pm
3484 .RS
3485 Sample script written as Perl module for use with
3486 .B --annotate-script
3487 that provides annotation data via
3488 .B Perforce.
3489 .br
3490 .RE
3491
3492 .I \*[scriptdir]/gitblame.pm
3493 .RS
3494 Sample script written as Perl module for use with
3495 .B --annotate-script
3496 that provides annotation data via git.
3497 .br
3498 .RE
3499 .RE
3500
3501 Sample
3502 .I \-\-criteria\-script
3503 callback Perl modules:
3504 .RS
3505
3506 .I \*[scriptdir]/criteria.pm
3507 .RS
3508 Sample script written as Perl module for use with
3509 .B --criteria-script
3510 that implements a check for "UNC + LBC + UIC == 0".
3511 .br
3512 .RE
3513
3514 .I \*[scriptdir]/threshold.pm
3515 .RS
3516 Sample script written as Perl module to check for minimum acceptable
3517 line and/or branch and/or and/or MC/DC function coverage.
3518 For example, the
3519 .RS
3520 .I "genhtml --fail_under_lines 75 ..."
3521 .RE
3522 feature can instead be realized by
3523 .RS
3524 .I "genhtml --criteria-script \*[scriptdir]/threshold.pm,--line,75 ..."
3525 .RE
3526 .br
3527 .RE
3528 .RE
3529
3530 Sample
3531 .I \-\-version\-script
3532 callback Perl modules and scripts:
3533 .RS
3534
3535 .I \*[scriptdir]/getp4version
3536 .RS
3537 Sample script for use with
3538 .B \-\-version\-script
3539 that obtains version IDs via
3540 .B Perforce.
3541 .br
3542 .RE
3543
3544 .I \*[scriptdir]/P4version.pm
3545 .RS
3546 A perl module with similar functionality to
3547 .B getp4version
3548 but higher performance.
3549 .br
3550 .RE
3551
3552 .I \*[scriptdir]/get_signature
3553 .RS
3554 Sample script for use with
3555 .B --version-script
3556 that uses md5hash as version IDs.
3557 .br
3558 .RE
3559
3560 .I \*[scriptdir]/gitversion.pm
3561 .RS
3562 A perl module with for use with
3563 .B \-\-version\-script
3564 which retrieves version IDs from
3565 .B git.
3566 .br
3567 .RE
3568
3569 .I \*[scriptdir]/batchGitVersion.pm
3570 .RS
3571 A perl module with similar functionality to
3572 .B gitversion.pm
3573 but higher performance.
3574 .br
3575 .RE
3576 .RE
3577
3578
3579 .SH AUTHORS
3580 Peter Oberparleiter <[email protected]>
3581 .br
3582
3583 Henry Cox <[email protected]>
3584 .RS
3585 Differential coverage and date/owner binning, filtering, error management,
3586 parallel execution sections,
3587 .RE
3588 .br
3589
3590 .SH SEE ALSO
3591 .BR lcov (1),
3592 .BR lcovrc (5),
3593 .BR geninfo (1),
3594 .BR genpng (1),
3595 .BR gendesc (1),
3596 .BR gcov (1)
3597 .br
3598
3599 .I \*[lcovurl]
3600 .br