third_party/lcov/man/lcovrc.5

   1 .TH lcovrc 5 "LCOV 1.10" 2012\-10\-10 "User Manuals"
   2
   3 .SH NAME
   4 lcovrc \- lcov configuration file
   5
   6 .SH DESCRIPTION
   7 The
   8 .I lcovrc
   9 file contains configuration information for the
  10 .B lcov
  11 code coverage tool (see
  12 .BR lcov (1)).
  13 .br
  14
  15 The system\-wide configuration file is located at
  16 .IR /etc/lcovrc .
  17 To change settings for a single user, place a customized copy of this file at
  18 location
  19 .IR ~/.lcovrc .
  20 Where available, command\-line options override configuration file settings.
  21
  22 Lines in a configuration file can either be:
  23 .IP "     *"
  24 empty lines or lines consisting only of white space characters. These lines are
  25 ignored.
  26 .IP "     *"
  27 comment lines which start with a hash sign ('#'). These are treated like empty
  28 lines and will be ignored.
  29 .IP "     *"
  30 statements in the form
  31 .RI ' key " = " value '.
  32 A list of valid statements and their description can be found in
  33 section 'OPTIONS' below.
  34 .PP
  35
  36 .B Example configuration:
  37 .IP
  38 #
  39 .br
  40 # Example LCOV configuration file
  41 .br
  42 #
  43 .br
  44
  45 # External style sheet file
  46 .br
  47 #genhtml_css_file = gcov.css
  48 .br
  49
  50 # Coverage rate limits
  51 .br
  52 genhtml_hi_limit = 90
  53 .br
  54 genhtml_med_limit = 75
  55 .br
  56
  57 # Width of line coverage field in source code view
  58 .br
  59 genhtml_line_field_width = 12
  60 .br
  61
  62 # Width of branch coverage field in source code view
  63 .br
  64 genhtml_branch_field_width = 16
  65 .br
  66
  67 # Width of overview image
  68 .br
  69 genhtml_overview_width = 80
  70 .br
  71
  72 # Resolution of overview navigation
  73 .br
  74 genhtml_nav_resolution = 4
  75 .br
  76
  77 # Offset for source code navigation
  78 .br
  79 genhtml_nav_offset = 10
  80 .br
  81
  82 # Do not remove unused test descriptions if non\-zero
  83 .br
  84 genhtml_keep_descriptions = 0
  85 .br
  86
  87 # Do not remove prefix from directory names if non\-zero
  88 .br
  89 genhtml_no_prefix = 0
  90 .br
  91
  92 # Do not create source code view if non\-zero
  93 .br
  94 genhtml_no_source = 0
  95 .br
  96
  97 # Specify size of tabs
  98 .br
  99 genhtml_num_spaces = 8
 100 .br
 101
 102 # Highlight lines with converted\-only data if non\-zero
 103 .br
 104 genhtml_highlight = 0
 105 .br
 106
 107 # Include color legend in HTML output if non\-zero
 108 .br
 109 genhtml_legend = 0
 110 .br
 111
 112 # Include HTML file at start of HTML output
 113 .br
 114 #genhtml_html_prolog = prolog.html
 115 .br
 116
 117 # Include HTML file at end of HTML output
 118 .br
 119 #genhtml_html_epilog = epilog.html
 120 .br
 121
 122 # Use custom HTML file extension
 123 .br
 124 #genhtml_html_extension = html
 125 .br
 126
 127 # Compress all generated html files with gzip.
 128 .br
 129 #genhtml_html_gzip = 1
 130 .br
 131
 132 # Include sorted overview pages
 133 .br
 134 genhtml_sort = 1
 135 .br
 136
 137 # Include function coverage data display
 138 .br
 139 #genhtml_function_coverage = 1
 140 .br
 141
 142 # Include branch coverage data display
 143 .br
 144 #genhtml_branch_coverage = 1
 145 .br
 146
 147 # Specify the character set of all generated HTML pages
 148 .br
 149 genhtml_charset=UTF\-8
 150 .br
 151
 152 # Location of the gcov tool
 153 .br
 154 #geninfo_gcov_tool = gcov
 155 .br
 156
 157 # Adjust test names if non\-zero
 158 .br
 159 #geninfo_adjust_testname = 0
 160 .br
 161
 162 # Calculate a checksum for each line if non\-zero
 163 .br
 164 geninfo_checksum = 0
 165 .br
 166
 167 # Enable libtool compatibility mode if non\-zero
 168 .br
 169 geninfo_compat_libtool = 0
 170 .br
 171
 172 # Specify whether to capture coverage data for external source
 173 .br
 174 # files
 175 .br
 176 #geninfo_external = 1
 177 .br
 178
 179 # Use gcov's --all-blocks option if non-zero
 180 .br
 181 #geninfo_gcov_all_blocks = 1
 182 .br
 183
 184 # Specify compatiblity modes (same as \-\-compat option
 185 .br
 186 # of geninfo)
 187 .br
 188 #geninfo_compat = libtool=on, hammer=auto, split_crc=auto
 189 .br
 190
 191 # Adjust path to source files by removing or changing path
 192 .br
 193 # components that match the specified pattern (Perl regular
 194 .br
 195 # expression format)
 196 .br
 197 #geninfo_adjust_src_path = /tmp/build => /usr/src
 198
 199 # Specify if geninfo should try to automatically determine
 200 .br
 201 # the base-directory when collecting coverage data.
 202 .br
 203 geninfo_auto_base = 1
 204 .br
 205
 206 # Directory containing gcov kernel files
 207 .br
 208 lcov_gcov_dir = /proc/gcov
 209 .br
 210
 211 # Location for temporary directories
 212 .br
 213 lcov_tmp_dir = /tmp
 214 .br
 215
 216 # Show full paths during list operation if non\-zero
 217 .br
 218 lcov_list_full_path = 0
 219 .br
 220
 221 # Specify the maximum width for list output. This value is
 222 .br
 223 # ignored when lcov_list_full_path is non\-zero.
 224 .br
 225 lcov_list_width = 80
 226 .br
 227
 228 # Specify the maximum percentage of file names which may be
 229 .br
 230 # truncated when choosing a directory prefix in list output.
 231 .br
 232 # This value is ignored when lcov_list_full_path is non\-zero.
 233 .br
 234 lcov_list_truncate_max = 20
 235
 236 # Specify if function coverage data should be collected and
 237 .br
 238 # processed.
 239 .br
 240 lcov_function_coverage = 1
 241 .br
 242
 243 # Specify if branch coverage data should be collected and
 244 .br
 245 # processed.
 246 .br
 247 lcov_branch_coverage = 0
 248 .br
 249 .PP
 250
 251 .SH OPTIONS
 252
 253 .BR genhtml_css_file " ="
 254 .I filename
 255 .IP
 256 Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by
 257 .BR genhtml .
 258 During output generation, a copy of this file will be placed in the output
 259 directory.
 260 .br
 261
 262 This option corresponds to the \-\-css\-file command line option of
 263 .BR genhtml .
 264 .br
 265
 266 By default, a standard CSS file is generated.
 267 .PP
 268
 269 .BR genhtml_hi_limit "  ="
 270 .I hi_limit
 271 .br
 272 .BR genhtml_med_limit " ="
 273 .I med_limit
 274 .br
 275 .IP
 276 Specify coverage rate limits for classifying file entries. Use this option to
 277 modify the coverage rates (in percent) for line, function and branch coverage at
 278 which a result is classified as high, medium or low coverage. This
 279 classification affects the color of the corresponding entries on the overview
 280 pages of the HTML output:
 281 .br
 282
 283 High:   hi_limit  <= rate <= 100        default color: green
 284 .br
 285 Medium: med_limit <= rate < hi_limit    default color: orange
 286 .br
 287 Low:    0         <= rate < med_limit   default color: red
 288 .br
 289
 290 Defaults are 90 and 75 percent.
 291 .PP
 292
 293 .BR genhtml_line_field_width " ="
 294 .I number_of_characters
 295 .IP
 296 Specify the width (in characters) of the source code view column containing
 297 line coverage information.
 298 .br
 299
 300 Default is 12.
 301 .PP
 302
 303 .BR genhtml_branch_field_width " ="
 304 .I number_of_characters
 305 .IP
 306 Specify the width (in characters) of the source code view column containing
 307 branch coverage information.
 308 .br
 309
 310 Default is 16.
 311 .PP
 312
 313 .BR genhtml_overview_width " ="
 314 .I pixel_size
 315 .IP
 316 Specify the width (in pixel) of the overview image created when generating HTML
 317 output using the \-\-frames option of
 318 .BR genhtml .
 319 .br
 320
 321 Default is 80.
 322 .PP
 323
 324 .BR genhtml_nav_resolution " ="
 325 .I lines
 326 .IP
 327 Specify the resolution of overview navigation when generating HTML output using
 328 the \-\-frames option of
 329 .BR genhtml .
 330 This number specifies the maximum difference in lines between the position a
 331 user selected from the overview and the position the source code window is
 332 scrolled to.
 333 .br
 334
 335 Default is 4.
 336 .PP
 337
 338
 339 .BR genhtml_nav_offset " ="
 340 .I lines
 341 .IP
 342 Specify the overview navigation line offset as applied when generating HTML
 343 output using the \-\-frames option of
 344 .BR genhtml.
 345 .br
 346
 347 Clicking a line in the overview image should show the source code view at
 348 a position a bit further up, so that the requested line is not the first
 349 line in the window.  This number specifies that offset.
 350 .br
 351
 352 Default is 10.
 353 .PP
 354
 355
 356 .BR genhtml_keep_descriptions " ="
 357 .IR 0 | 1
 358 .IP
 359 If non\-zero, keep unused test descriptions when generating HTML output using
 360 .BR genhtml .
 361 .br
 362
 363 This option corresponds to the \-\-keep\-descriptions option of
 364 .BR genhtml .
 365 .br
 366
 367 Default is 0.
 368 .PP
 369
 370 .BR genhtml_no_prefix " ="
 371 .IR 0 | 1
 372 .IP
 373 If non\-zero, do not try to find and remove a common prefix from directory names.
 374 .br
 375
 376 This option corresponds to the \-\-no\-prefix option of
 377 .BR genhtml .
 378 .br
 379
 380 Default is 0.
 381 .PP
 382
 383 .BR genhtml_no_source " ="
 384 .IR 0 | 1
 385 .IP
 386 If non\-zero, do not create a source code view when generating HTML output using
 387 .BR genhtml .
 388 .br
 389
 390 This option corresponds to the \-\-no\-source option of
 391 .BR genhtml .
 392 .br
 393
 394 Default is 0.
 395 .PP
 396
 397 .BR genhtml_num_spaces " ="
 398 .I num
 399 .IP
 400 Specify the number of spaces to use as replacement for tab characters in the
 401 HTML source code view as generated by
 402 .BR genhtml .
 403 .br
 404
 405 This option corresponds to the \-\-num\-spaces option of
 406 .BR genthml .
 407 .br
 408
 409 Default is 8.
 410
 411 .PP
 412
 413 .BR genhtml_highlight " ="
 414 .IR 0 | 1
 415 .IP
 416 If non\-zero, highlight lines with converted\-only data in
 417 HTML output as generated by
 418 .BR genhtml .
 419 .br
 420
 421 This option corresponds to the \-\-highlight option of
 422 .BR genhtml .
 423 .br
 424
 425 Default is 0.
 426 .PP
 427
 428 .BR genhtml_legend " ="
 429 .IR 0 | 1
 430 .IP
 431 If non\-zero, include a legend explaining the meaning of color coding in the HTML
 432 output as generated by
 433 .BR genhtml .
 434 .br
 435
 436 This option corresponds to the \-\-legend option of
 437 .BR genhtml .
 438 .br
 439
 440 Default is 0.
 441 .PP
 442
 443 .BR genhtml_html_prolog " ="
 444 .I filename
 445 .IP
 446 If set, include the contents of the specified file at the beginning of HTML
 447 output.
 448
 449 This option corresponds to the \-\-html\-prolog option of
 450 .BR genhtml .
 451 .br
 452
 453 Default is to use no extra prolog.
 454 .PP
 455
 456 .BR genhtml_html_epilog " ="
 457 .I filename
 458 .IP
 459 If set, include the contents of the specified file at the end of HTML output.
 460
 461 This option corresponds to the \-\-html\-epilog option of
 462 .BR genhtml .
 463 .br
 464
 465 Default is to use no extra epilog.
 466 .PP
 467
 468 .BR genhtml_html_extension " ="
 469 .I extension
 470 .IP
 471 If set, use the specified string as filename extension for generated HTML files.
 472
 473 This option corresponds to the \-\-html\-extension option of
 474 .BR genhtml .
 475 .br
 476
 477 Default extension is "html".
 478 .PP
 479
 480 .BR genhtml_html_gzip " ="
 481 .IR 0 | 1
 482 .IP
 483 If set, compress all html files using gzip.
 484
 485 This option corresponds to the \-\-html\-gzip option of
 486 .BR genhtml .
 487 .br
 488
 489 Default extension is 0.
 490 .PP
 491
 492 .BR genhtml_sort " ="
 493 .IR 0 | 1
 494 .IP
 495 If non\-zero, create overview pages sorted by coverage rates when generating
 496 HTML output using
 497 .BR genhtml .
 498 .br
 499
 500 This option can be set to 0 by using the \-\-no\-sort option of
 501 .BR genhtml .
 502 .br
 503
 504 Default is 1.
 505 .PP
 506
 507 .BR genhtml_function_coverage " ="
 508 .IR 0 | 1
 509 .IP
 510 If non\-zero, include function coverage data when generating HTML output using
 511 .BR genhtml .
 512 .br
 513
 514 This option can be set to 0 by using the \-\-no\-function\-coverage option of
 515 .BR genhtml .
 516 .br
 517
 518 Default is 1.
 519 .PP
 520
 521 .BR genhtml_branch_coverage " ="
 522 .IR 0 | 1
 523 .IP
 524 If non\-zero, include branch coverage data when generating HTML output using
 525 .BR genhtml .
 526 .br
 527
 528 This option can be set to 0 by using the \-\-no\-branch\-coverage option of
 529 .BR genhtml .
 530 .br
 531
 532 Default is 1.
 533 .PP
 534
 535 .BR genhtml_charset " ="
 536 .I charset
 537 .IP
 538 Specify the character set of all generated HTML pages.
 539 .br
 540
 541 Use this option if the source code contains characters which are not
 542 part of the default character set. Note that this option is ignored
 543 when a custom HTML prolog is specified (see also
 544 .BR genhtml_html_prolog ).
 545 .br
 546
 547 Default is UTF-8.
 548 .PP
 549 .BR geninfo_gcov_tool " ="
 550 .I path_to_gcov
 551 .IP
 552 Specify the location of the gcov tool (see
 553 .BR gcov (1))
 554 which is used to generate coverage information from data files.
 555 .br
 556
 557 Default is 'gcov'.
 558 .PP
 559
 560 .BR geninfo_adjust_testname " ="
 561 .IR 0 | 1
 562 .IP
 563 If non\-zero,  adjust test names to include operating system information
 564 when capturing coverage data.
 565 .br
 566
 567 Default is 0.
 568 .PP
 569
 570 .BR geninfo_checksum " ="
 571 .IR 0 | 1
 572 .IP
 573 If non\-zero, generate source code checksums when capturing coverage data.
 574 Checksums are useful to prevent merging coverage data from incompatible
 575 source code versions but checksum generation increases the size of coverage
 576 files and the time used to generate those files.
 577 .br
 578
 579 This option corresponds to the \-\-checksum and \-\-no\-checksum command line
 580 option of
 581 .BR geninfo .
 582 .br
 583
 584 Default is 0.
 585 .PP
 586
 587 .BR geninfo_compat_libtool " ="
 588 .IR 0 | 1
 589 .IP
 590 If non\-zero, enable libtool compatibility mode. When libtool compatibility
 591 mode is enabled, lcov will assume that the source code relating to a .da file
 592 located in a directory named ".libs" can be found in its parent directory.
 593 .br
 594
 595 This option corresponds to the \-\-compat\-libtool and \-\-no\-compat\-libtool
 596 command line option of
 597 .BR geninfo .
 598 .br
 599
 600 Default is 1.
 601 .PP
 602
 603 .BR geninfo_external " ="
 604 .IR 0 | 1
 605 .IP
 606 If non\-zero, capture coverage data for external source files.
 607
 608 External source files are files which are not located in one of the directories
 609 (including sub-directories)
 610 specified by the \-\-directory or \-\-base\-directory options of
 611 .BR lcov / geninfo .
 612
 613 Default is 1.
 614 .PP
 615
 616 .BR geninfo_gcov_all_blocks " ="
 617 .IR 0 | 1
 618 .IP
 619 If non\-zero, call the gcov tool with option --all-blocks.
 620
 621 Using --all-blocks will produce more detailed branch coverage information for
 622 each line. Set this option to zero if you do not need detailed branch coverage
 623 information to speed up the process of capturing code coverage or to work
 624 around a bug in some versions of gcov which will cause it to endlessly loop
 625 when analysing some files.
 626
 627 Default is 1.
 628 .PP
 629
 630 .BR geninfo_compat " ="
 631 .IR mode = value [, mode = value ,...]
 632 .IP
 633 Specify that geninfo should enable one or more compatibility modes
 634 when capturing coverage data.
 635
 636 This option corresponds to the \-\-compat command line option of
 637 .BR geninfo .
 638
 639 Default is 'libtool=on, hammer=auto, split_crc=auto'.
 640 .PP
 641
 642 .BR geninfo_adjust_src_path " ="
 643 .IR pattern " => " replacement
 644 .br
 645 .BR geninfo_adjust_src_path " ="
 646 .I pattern
 647 .IP
 648 Adjust source paths when capturing coverage data.
 649
 650 Use this option in situations where geninfo cannot find the correct
 651 path to source code files of a project. By providing a
 652 .I pattern
 653 in Perl regular expression format (see
 654 .BR perlre (1))
 655 and an optional replacement string, you can instruct geninfo to
 656 remove or change parts of the incorrect source path.
 657
 658 .B Example:
 659 .br
 660
 661 1. When geninfo reports that it cannot find source file
 662 .br
 663
 664     /path/to/src/.libs/file.c
 665 .br
 666
 667 while the file is actually located in
 668 .br
 669
 670     /path/to/src/file.c
 671 .br
 672
 673 use the following parameter:
 674 .br
 675
 676     geninfo_adjust_src_path = /.libs
 677
 678 This will remove all "/.libs" strings from the path.
 679
 680 2. When geninfo reports that it cannot find source file
 681 .br
 682
 683     /tmp/build/file.c
 684 .br
 685
 686 while the file is actually located in
 687 .br
 688
 689     /usr/src/file.c
 690 .br
 691
 692 use the following parameter:
 693 .br
 694
 695     geninfo_adjust_src_path = /tmp/build => /usr/src
 696 .br
 697
 698 This will change all "/tmp/build" strings in the path to "/usr/src".
 699 .PP
 700
 701 .BR geninfo_auto_base " ="
 702 .IR 0 | 1
 703 .IP
 704 If non\-zero, apply a heuristic to determine the base directory when
 705 collecting coverage data.
 706 .br
 707
 708 Use this option when using geninfo on projects built with libtool or
 709 similar build environments that work with multiple base directories,
 710 i.e. environments, where the current working directory when invoking the
 711 compiler ist not the same directory in which the source code file is
 712 located, and in addition, is different between files of the same project.
 713 .br
 714
 715 Default is 1.
 716 .PP
 717
 718 .BR lcov_gcov_dir " ="
 719 .I path_to_kernel_coverage_data
 720 .IP
 721 Specify the path to the directory where kernel coverage data can be found
 722 or leave undefined for auto-detection.
 723 .br
 724
 725 Default is auto-detection.
 726 .PP
 727
 728 .BR lcov_tmp_dir " ="
 729 .I temp
 730 .IP
 731 Specify the location of a directory used for temporary files.
 732 .br
 733
 734 Default is '/tmp'.
 735 .PP
 736
 737 .BR lcov_list_full_path " ="
 738 .IR 0 | 1
 739 .IP
 740 If non-zero, print the full path to source code files during a list operation.
 741 .br
 742
 743 This option corresponds to the \-\-list\-full\-path option of
 744 .BR lcov .
 745 .br
 746
 747 Default is 0.
 748 .PP
 749
 750 .BR lcov_list_max_width " ="
 751 .IR width
 752 .IP
 753 Specify the maximum width for list output. This value is ignored when
 754 lcov_list_full_path is non\-zero.
 755 .br
 756
 757 Default is 80.
 758 .PP
 759
 760 .BR lcov_list_truncate_max
 761 .B " ="
 762 .IR percentage
 763 .IP
 764 Specify the maximum percentage of file names which may be truncated when
 765 choosing a directory prefix in list output. This value is ignored when
 766 lcov_list_full_path is non\-zero.
 767 .br
 768
 769 Default is 20.
 770 .PP
 771
 772 .BR lcov_function_coverage " ="
 773 .IR 0 | 1
 774 .IP
 775 Specify whether lcov should handle function coverage data.
 776 .br
 777
 778 Setting this option to 0 can reduce memory and CPU time consumption
 779 when lcov is collecting and processing coverage data, as well as
 780 reduce the size of the resulting data files. Note that setting
 781 .B genhtml_function_coverage
 782 will override this option for HTML generation.
 783 .br
 784
 785 Default is 1.
 786 .PP
 787
 788 .BR lcov_branch_coverage " ="
 789 .IR 0 | 1
 790 .IP
 791 Specify whether lcov should handle branch coverage data.
 792 .br
 793
 794 Setting this option to 0 can reduce memory and CPU time consumption
 795 when lcov is collecting and processing coverage data, as well as
 796 reduce the size of the resulting data files. Note that setting
 797 .B genhtml_branch_coverage
 798 will override this option for HTML generation.
 799 .br
 800
 801 Default is 0.
 802 .PP
 803
 804 .SH FILES
 805
 806 .TP
 807 .I /etc/lcovrc
 808 The system\-wide
 809 .B lcov
 810 configuration file.
 811
 812 .TP
 813 .I ~/.lcovrc
 814 The individual per\-user configuration file.
 815 .PP
 816
 817 .SH SEE ALSO
 818 .BR lcov (1),
 819 .BR genhtml (1),
 820 .BR geninfo (1),
 821 .BR gcov (1)