third_party/lcov-1.9/man/lcov.1

   1 .TH lcov 1 "LCOV 1.9" 2010\-08\-06 "User Manuals"
   2 .SH NAME
   3 lcov \- a graphical GCOV front\-end
   4 .SH SYNOPSIS
   5 .B lcov
   6 .BR \-c | \-\-capture
   7 .RS 5
   8 .br
   9 .RB [ \-d | \-\-directory
  10 .IR directory ]
  11 .RB [ \-k | \-\-kernel\-directory
  12 .IR directory ]
  13 .br
  14 .RB [ \-o | \-\-output\-file
  15 .IR tracefile ]
  16 .RB [ \-t | \-\-test\-name
  17 .IR testname ]
  18 .br
  19 .RB [ \-b | \-\-base\-directory
  20 .IR directory ]
  21 .RB [ \-i | \-\-initial ]
  22 .RB [ \-\-gcov\-tool
  23 .IR tool ]
  24 .br
  25 .RB [ \-\-checksum ]
  26 .RB [ \-\-no\-checksum ]
  27 .RB [ \-\-no\-recursion ]
  28 .RB [ \-f | \-\-follow ]
  29 .br
  30 .RB [ \-\-compat\-libtool ]
  31 .RB [ \-\-no\-compat\-libtool ]
  32 .RB [ \-\-ignore\-errors
  33 .IR errors ]
  34 .br
  35 .RB [ \-\-to\-package
  36 .IR package ]
  37 .RB [ \-\-from\-package
  38 .IR package ]
  39 .RB [ \-q | \-\-quiet ]
  40 .br
  41 .RB [ \-\-no\-markers ]
  42 .br
  43 .RE
  44
  45 .B lcov
  46 .BR \-z | \-\-zerocounters
  47 .RS 5
  48 .br
  49 .RB [ \-d | \-\-directory
  50 .IR directory ]
  51 .RB [ \-\-no\-recursion ]
  52 .RB [ \-f | \-\-follow ]
  53 .br
  54 .RB [ \-q | \-\-quiet ]
  55 .br
  56 .RE
  57
  58 .B lcov
  59 .BR \-l | \-\-list
  60 .I tracefile
  61 .RS 5
  62 .br
  63 .RB [ \-q | \-\-quiet ]
  64 .RB [ \-\-list\-full\-path ]
  65 .RB [ \-\-no\-list\-full\-path ]
  66 .br
  67 .RE
  68
  69 .B lcov
  70 .BR \-a | \-\-add\-tracefile
  71 .I tracefile
  72 .RS 5
  73 .br
  74 .RB [ \-o | \-\-output\-file
  75 .IR tracefile ]
  76 .RB [ \-\-checksum ]
  77 .RB [ \-\-no\-checksum ]
  78 .br
  79 .RB [ \-q | \-\-quiet ]
  80 .br
  81 .RE
  82
  83 .B lcov
  84 .BR \-e | \-\-extract
  85 .I tracefile pattern
  86 .RS 5
  87 .br
  88 .RB [ \-o | \-\-output\-file
  89 .IR tracefile ]
  90 .RB [ \-\-checksum ]
  91 .RB [ \-\-no\-checksum ]
  92 .br
  93 .RB [ \-q | \-\-quiet ]
  94 .RE
  95
  96 .B lcov
  97 .BR \-r | \-\-remove
  98 .I tracefile pattern
  99 .RS 5
 100 .br
 101 .RB [ \-o | \-\-output\-file
 102 .IR tracefile ]
 103 .RB [ \-\-checksum ]
 104 .RB [ \-\-no\-checksum ]
 105 .br
 106 .RB [ \-q | \-\-quiet ]
 107 .br
 108 .RE
 109
 110 .B lcov
 111 .BR \-\-diff
 112 .IR "tracefile diff"
 113 .RS 5
 114 .br
 115 .RB [ \-o | \-\-output\-file
 116 .IR tracefile ]
 117 .RB [ \-\-checksum ]
 118 .RB [ \-\-no\-checksum ]
 119 .br
 120 .RB [ \-\-convert\-filenames ]
 121 .RB [ \-\-strip
 122 .IR depth ]
 123 .RB [ \-\-path
 124 .IR path ]
 125 .RB [ \-q | \-\-quiet ]
 126 .br
 127 .RE
 128
 129 .B lcov
 130 .RB [ \-h | \-\-help ]
 131 .RB [ \-v | \-\-version ]
 132 .RS 5
 133 .br
 134 .RE
 135
 136 .SH DESCRIPTION
 137 .B lcov
 138 is a graphical front\-end for GCC's coverage testing tool gcov. It collects
 139 line, function and branch coverage data for multiple source files and creates
 140 HTML pages containing the source code annotated with coverage information.
 141 It also adds overview pages for easy navigation within the file structure.
 142
 143 Use
 144 .B lcov
 145 to collect coverage data and
 146 .B genhtml
 147 to create HTML pages. Coverage data can either be collected from the
 148 currently running Linux kernel or from a user space application. To do this,
 149 you have to complete the following preparation steps:
 150
 151 For Linux kernel coverage:
 152 .RS
 153 Follow the setup instructions for the gcov\-kernel infrastructure:
 154 .I http://ltp.sourceforge.net/coverage/gcov.php
 155 .br
 156
 157
 158 .RE
 159 For user space application coverage:
 160 .RS
 161 Compile the application with GCC using the options
 162 "\-fprofile\-arcs" and "\-ftest\-coverage".
 163 .RE
 164
 165 Please note that this man page refers to the output format of
 166 .B lcov
 167 as ".info file" or "tracefile" and that the output of GCOV
 168 is called ".da file".
 169 .SH OPTIONS
 170
 171
 172 .B \-a
 173 .I tracefile
 174 .br
 175 .B \-\-add\-tracefile
 176 .I tracefile
 177 .br
 178 .RS
 179 Add contents of
 180 .IR tracefile .
 181
 182 Specify several tracefiles using the \-a switch to combine the coverage data
 183 contained in these files by adding up execution counts for matching test and
 184 filename combinations.
 185
 186 The result of the add operation will be written to stdout or the tracefile
 187 specified with \-o.
 188
 189 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
 190 at a time.
 191
 192 .RE
 193
 194 .B \-b
 195 .I directory
 196 .br
 197 .B \-\-base\-directory
 198 .I directory
 199 .br
 200 .RS
 201 .RI "Use " directory
 202 as base directory for relative paths.
 203
 204 Use this option to specify the base directory of a build\-environment
 205 when lcov produces error messages like:
 206
 207 .RS
 208 ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c
 209 .RE
 210
 211 In this example, use /home/user/project as base directory.
 212
 213 This option is required when using lcov on projects built with libtool or
 214 similar build environments that work with a base directory, i.e. environments,
 215 where the current working directory when invoking the compiler is not the same
 216 directory in which the source code file is located.
 217
 218 Note that this option will not work in environments where multiple base
 219 directories are used. In that case repeat the lcov call for each base directory
 220 while using the \-\-ignore\-errors option to prevent lcov from exiting when the
 221 first source code file could not be found. This way you can get partial coverage
 222 information for each base directory which can then be combined using the \-a
 223 option.
 224 .RE
 225
 226 .B \-c
 227 .br
 228 .B \-\-capture
 229 .br
 230 .RS
 231 Capture coverage data.
 232
 233 By default captures the current kernel execution counts and writes the
 234 resulting coverage data to the standard output. Use the \-\-directory
 235 option to capture counts for a user space program.
 236
 237 The result of the capture operation will be written to stdout or the tracefile
 238 specified with \-o.
 239
 240 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
 241 at a time.
 242 .RE
 243
 244 .B \-\-checksum
 245 .br
 246 .B \-\-no\-checksum
 247 .br
 248 .RS
 249 Specify whether to generate checksum data when writing tracefiles.
 250
 251 Use \-\-checksum to enable checksum generation or \-\-no\-checksum to
 252 disable it. Checksum generation is
 253 .B disabled
 254 by default.
 255
 256 When checksum generation is enabled, a checksum will be generated for each
 257 source code line and stored along with the coverage data. This checksum will
 258 be used to prevent attempts to combine coverage data from different source
 259 code versions.
 260
 261 If you don't work with different source code versions, disable this option
 262 to speed up coverage data processing and to reduce the size of tracefiles.
 263 .RE
 264
 265 .B \-\-compat\-libtool
 266 .br
 267 .B \-\-no\-compat\-libtool
 268 .br
 269 .RS
 270 Specify whether to enable libtool compatibility mode.
 271
 272 Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-libtool
 273 to disable it. The libtool compatibility mode is
 274 .B enabled
 275 by default.
 276
 277 When libtool compatibility mode is enabled, lcov will assume that the source
 278 code relating to a .da file located in a directory named ".libs" can be
 279 found in its parent directory.
 280
 281 If you have directories named ".libs" in your build environment but don't use
 282 libtool, disable this option to prevent problems when capturing coverage data.
 283 .RE
 284
 285 .B \-\-convert\-filenames
 286 .br
 287 .RS
 288 Convert filenames when applying diff.
 289
 290 Use this option together with \-\-diff to rename the file names of processed
 291 data sets according to the data provided by the diff.
 292 .RE
 293
 294 .B \-\-diff
 295 .I tracefile
 296 .I difffile
 297 .br
 298 .RS
 299 Convert coverage data in
 300 .I tracefile
 301 using source code diff file
 302 .IR difffile .
 303
 304 Use this option if you want to merge coverage data from different source code
 305 levels of a program, e.g. when you have data taken from an older version
 306 and want to combine it with data from a more current version.
 307 .B lcov
 308 will try to map source code lines between those versions and adjust the coverage
 309 data respectively.
 310 .I difffile
 311 needs to be in unified format, i.e. it has to be created using the "\-u" option
 312 of the
 313 .B diff
 314 tool.
 315
 316 Note that lines which are not present in the old version will not be counted
 317 as instrumented, therefore tracefiles resulting from this operation should
 318 not be interpreted individually but together with other tracefiles taken
 319 from the newer version. Also keep in mind that converted coverage data should
 320 only be used for overview purposes as the process itself introduces a loss
 321 of accuracy.
 322
 323 The result of the diff operation will be written to stdout or the tracefile
 324 specified with \-o.
 325
 326 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
 327 at a time.
 328 .RE
 329
 330 .B \-d
 331 .I directory
 332 .br
 333 .B \-\-directory
 334 .I  directory
 335 .br
 336 .RS
 337 Use .da files in
 338 .I directory
 339 instead of kernel.
 340
 341 If you want to work on coverage data for a user space program, use this
 342 option to specify the location where the program was compiled (that's
 343 where the counter files ending with .da will be stored).
 344
 345 Note that you may specify this option more than once.
 346 .RE
 347
 348 .B \-e
 349 .I tracefile
 350 .I pattern
 351 .br
 352 .B \-\-extract
 353 .I tracefile
 354 .I pattern
 355 .br
 356 .RS
 357 Extract data from
 358 .IR tracefile .
 359
 360 Use this switch if you want to extract coverage data for only a particular
 361 set of files from a tracefile. Additional command line parameters will be
 362 interpreted as shell wildcard patterns (note that they may need to be
 363 escaped accordingly to prevent the shell from expanding them first).
 364 Every file entry in
 365 .I tracefile
 366 which matches at least one of those patterns will be extracted.
 367
 368 The result of the extract operation will be written to stdout or the tracefile
 369 specified with \-o.
 370
 371 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
 372 at a time.
 373 .RE
 374
 375 .B \-f
 376 .br
 377 .B \-\-follow
 378 .br
 379 .RS
 380 Follow links when searching for .da files.
 381 .RE
 382
 383 .B \-\-from\-package
 384 .I package
 385 .br
 386 .RS
 387 Use .da files in
 388 .I package
 389 instead of kernel or directory.
 390
 391 Use this option if you have separate machines for build and test and
 392 want to perform the .info file creation on the build machine. See
 393 \-\-to\-package for more information.
 394 .RE
 395
 396 .B \-\-gcov\-tool
 397 .I tool
 398 .br
 399 .RS
 400 Specify the location of the gcov tool.
 401 .RE
 402
 403 .B \-h
 404 .br
 405 .B \-\-help
 406 .br
 407 .RS
 408 Print a short help text, then exit.
 409 .RE
 410
 411 .B \-\-ignore\-errors
 412 .I errors
 413 .br
 414 .RS
 415 Specify a list of errors after which to continue processing.
 416
 417 Use this option to specify a list of one or more classes of errors after which
 418 lcov should continue processing instead of aborting.
 419
 420 .I errors
 421 can be a comma\-separated list of the following keywords:
 422
 423 .B gcov:
 424 the gcov tool returned with a non\-zero return code.
 425
 426 .B source:
 427 the source code file for a data set could not be found.
 428 .RE
 429
 430 .B \-i
 431 .br
 432 .B \-\-initial
 433 .RS
 434 Capture initial zero coverage data.
 435
 436 Run lcov with \-c and this option on the directories containing .bb, .bbg
 437 or .gcno files before running any test case. The result is a "baseline"
 438 coverage data file that contains zero coverage for every instrumented line.
 439 Combine this data file (using lcov \-a) with coverage data files captured
 440 after a test run to ensure that the percentage of total lines covered is
 441 correct even when not all source code files were loaded during the test.
 442
 443 Recommended procedure when capturing data for a test case:
 444
 445 1. create baseline coverage data file
 446 .RS
 447 # lcov \-c \-i \-d appdir \-o app_base.info
 448 .br
 449
 450 .RE
 451 2. perform test
 452 .RS
 453 # appdir/test
 454 .br
 455
 456 .RE
 457 3. create test coverage data file
 458 .RS
 459 # lcov \-c \-d appdir \-o app_test.info
 460 .br
 461
 462 .RE
 463 4. combine baseline and test coverage data
 464 .RS
 465 # lcov \-a app_base.info \-a app_test.info \-o app_total.info
 466 .br
 467
 468 .RE
 469 .RE
 470
 471 .B \-k
 472 .I subdirectory
 473 .br
 474 .B \-\-kernel\-directory
 475 .I subdirectory
 476 .br
 477 .RS
 478 Capture kernel coverage data only from
 479 .IR subdirectory .
 480
 481 Use this option if you don't want to get coverage data for all of the
 482 kernel, but only for specific subdirectories. This option may be specified
 483 more than once.
 484
 485 Note that you may need to specify the full path to the kernel subdirectory
 486 depending on the version of the kernel gcov support.
 487 .RE
 488
 489 .B \-l
 490 .I tracefile
 491 .br
 492 .B \-\-list
 493 .I tracefile
 494 .br
 495 .RS
 496 List the contents of the
 497 .IR tracefile .
 498
 499 Only one of  \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
 500 at a time.
 501 .RE
 502
 503 .B \-\-list\-full\-path
 504 .br
 505 .B \-\-no\-list\-full\-path
 506 .br
 507 .RS
 508 Specify whether to show full paths during list operation.
 509
 510 Use \-\-list\-full\-path to show full paths during list operation
 511 or \-\-no\-list\-full\-path to show shortened paths. Paths are
 512 .B shortened
 513 by default.
 514 .RE
 515
 516 .B \-\-no\-markers
 517 .br
 518 .RS
 519 Use this option if you want to get coverage data without regard to exclusion
 520 markers in the source code file. See
 521 .BR "geninfo " (1)
 522 for details on exclusion markers.
 523 .RE
 524
 525 .B \-\-no\-recursion
 526 .br
 527 .RS
 528 Use this option if you want to get coverage data for the specified directory
 529 only without processing subdirectories.
 530 .RE
 531
 532 .B \-o
 533 .I tracefile
 534 .br
 535 .B \-\-output\-file
 536 .I tracefile
 537 .br
 538 .RS
 539 Write data to
 540 .I tracefile
 541 instead of stdout.
 542
 543 Specify "\-" as a filename to use the standard output.
 544
 545 By convention, lcov\-generated coverage data files are called "tracefiles" and
 546 should have the filename extension ".info".
 547 .RE
 548
 549 .B \-\-path
 550 .I path
 551 .br
 552 .RS
 553 Strip path from filenames when applying diff.
 554
 555 Use this option together with \-\-diff to tell lcov to disregard the specified
 556 initial path component when matching between tracefile and diff filenames.
 557 .RE
 558
 559 .B \-q
 560 .br
 561 .B \-\-quiet
 562 .br
 563 .RS
 564 Do not print progress messages.
 565
 566 This option is implied when no output filename is specified to prevent
 567 progress messages to mess with coverage data which is also printed to
 568 the standard output.
 569 .RE
 570
 571 .B \-r
 572 .I tracefile
 573 .I pattern
 574 .br
 575 .B \-\-remove
 576 .I tracefile
 577 .I pattern
 578 .br
 579 .RS
 580 Remove data from
 581 .IR tracefile .
 582
 583 Use this switch if you want to remove coverage data for a particular
 584 set of files from a tracefile. Additional command line parameters will be
 585 interpreted as shell wildcard patterns (note that they may need to be
 586 escaped accordingly to prevent the shell from expanding them first).
 587 Every file entry in
 588 .I tracefile
 589 which matches at least one of those patterns will be removed.
 590
 591 The result of the remove operation will be written to stdout or the tracefile
 592 specified with \-o.
 593
 594 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
 595 at a time.
 596 .RE
 597
 598 .B \-\-strip
 599 .I depth
 600 .br
 601 .RS
 602 Strip path components when applying diff.
 603
 604 Use this option together with \-\-diff to tell lcov to disregard the specified
 605 number of initial directories when matching tracefile and diff filenames.
 606 .RE
 607
 608 .B \-t
 609 .I testname
 610 .br
 611 .B \-\-test\-name
 612 .I testname
 613 .br
 614 .RS
 615 Specify test name to be stored in the tracefile.
 616
 617 This name identifies a coverage data set when more than one data set is merged
 618 into a combined tracefile (see option \-a).
 619
 620 Valid test names can consist of letters, decimal digits and the underscore
 621 character ("_").
 622 .RE
 623
 624 .B \-\-to\-package
 625 .I package
 626 .br
 627 .RS
 628 Store .da files for later processing.
 629
 630 Use this option if you have separate machines for build and test and
 631 want to perform the .info file creation on the build machine. To do this,
 632 follow these steps:
 633
 634 On the test machine:
 635 .RS
 636 .br
 637 \- run the test
 638 .br
 639 \- run lcov \-c [\-d directory] \-\-to-package
 640 .I file
 641 .br
 642 \- copy
 643 .I file
 644 to the build machine
 645 .RE
 646 .br
 647
 648 On the build machine:
 649 .RS
 650 .br
 651 \- run lcov \-c \-\-from-package
 652 .I file
 653 [\-o and other options]
 654 .RE
 655 .br
 656
 657 This works for both kernel and user space coverage data. Note that you might
 658 have to specify the path to the build directory using \-b with
 659 either \-\-to\-package or \-\-from-package. Note also that the package data
 660 must be converted to a .info file before recompiling the program or it will
 661 become invalid.
 662 .RE
 663
 664 .B \-v
 665 .br
 666 .B \-\-version
 667 .br
 668 .RS
 669 Print version number, then exit.
 670 .RE
 671
 672 .B \-z
 673 .br
 674 .B \-\-zerocounters
 675 .br
 676 .RS
 677 Reset all execution counts to zero.
 678
 679 By default tries to reset kernel execution counts. Use the \-\-directory
 680 option to reset all counters of a user space program.
 681
 682 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified
 683 at a time.
 684 .RE
 685
 686 .SH FILES
 687
 688 .I /etc/lcovrc
 689 .RS
 690 The system\-wide configuration file.
 691 .RE
 692
 693 .I ~/.lcovrc
 694 .RS
 695 The per\-user configuration file.
 696 .RE
 697
 698 .SH AUTHOR
 699 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
 700
 701 .SH SEE ALSO
 702 .BR lcovrc (5),
 703 .BR genhtml (1),
 704 .BR geninfo (1),
 705 .BR genpng (1),
 706 .BR gendesc (1),
 707 .BR gcov (1)