third_party/lcov/man/genhtml.1

   1 .TH genhtml 1 "LCOV 1.10" 2012\-10\-10 "User Manuals"
   2 .SH NAME
   3 genhtml \- Generate HTML view from LCOV coverage data files
   4 .SH SYNOPSIS
   5 .B genhtml
   6 .RB [ \-h | \-\-help ]
   7 .RB [ \-v | \-\-version ]
   8 .RS 8
   9 .br
  10 .RB [ \-q | \-\-quiet ]
  11 .RB [ \-s | \-\-show\-details ]
  12 .RB [ \-f | \-\-frames ]
  13 .br
  14 .RB [ \-b | \-\-baseline\-file  ]
  15 .IR baseline\-file
  16 .br
  17 .RB [ \-o | \-\-output\-directory
  18 .IR output\-directory ]
  19 .br
  20 .RB [ \-t | \-\-title
  21 .IR title ]
  22 .br
  23 .RB [ \-d | \-\-description\-file
  24 .IR description\-file ]
  25 .br
  26 .RB [ \-k | \-\-keep\-descriptions ]
  27 .RB [ \-c | \-\-css\-file
  28 .IR css\-file ]
  29 .br
  30 .RB [ \-p | \-\-prefix
  31 .IR prefix ]
  32 .RB [ \-\-no\-prefix ]
  33 .br
  34 .RB [ \-\-no\-source ]
  35 .RB [ \-\-num\-spaces
  36 .IR num ]
  37 .RB [ \-\-highlight ]
  38 .br
  39 .RB [ \-\-legend ]
  40 .RB [ \-\-html\-prolog
  41 .IR prolog\-file ]
  42 .br
  43 .RB [ \-\-html\-epilog
  44 .IR epilog\-file ]
  45 .RB [ \-\-html\-extension
  46 .IR extension ]
  47 .br
  48 .RB [ \-\-html\-gzip ]
  49 .RB [ \-\-sort ]
  50 .RB [ \-\-no\-sort ]
  51 .br
  52 .RB [ \-\-function\-coverage ]
  53 .RB [ \-\-no\-function\-coverage ]
  54 .br
  55 .RB [ \-\-branch\-coverage ]
  56 .RB [ \-\-no\-branch\-coverage ]
  57 .br
  58 .RB [ \-\-demangle\-cpp ]
  59 .RB [ \-\-ignore\-errors
  60 .IR errors  ]
  61 .br
  62 .RB [ \-\-config\-file
  63 .IR config\-file ]
  64 .RB [ \-\-rc
  65 .IR keyword = value ]
  66 .br
  67 .IR tracefile(s)
  68 .RE
  69 .SH DESCRIPTION
  70 Create an HTML view of coverage data found in
  71 .IR tracefile .
  72 Note that
  73 .I tracefile
  74 may also be a list of filenames.
  75
  76 HTML output files are created in the current working directory unless the
  77 \-\-output\-directory option is used. If
  78 .I tracefile
  79 ends with ".gz", it is assumed to be GZIP\-compressed and the gunzip tool
  80 will be used to decompress it transparently.
  81
  82 Note that all source code files have to be present and readable at the
  83 exact file system location they were compiled.
  84
  85 Use option
  86 .I \--css\-file
  87 to modify layout and colors of the generated HTML output. Files are
  88 marked in different colors depending on the associated coverage rate. By
  89 default, the coverage limits for low, medium and high coverage are set to
  90 0\-75%, 75\-90% and 90\-100% percent respectively. To change these
  91 values, use configuration file options
  92 .IR genhtml_hi_limit " and " genhtml_med_limit .
  93
  94 Also note that when displaying percentages, 0% and 100% are only printed when
  95 the values are exactly 0% and 100% respectively. Other values which would
  96 conventionally be rounded to 0% or 100% are instead printed as nearest
  97 non-boundary value. This behavior is in accordance with that of the
  98 .BR gcov (1)
  99 tool.
 100
 101 .SH OPTIONS
 102 .B \-h
 103 .br
 104 .B \-\-help
 105 .RS
 106 Print a short help text, then exit.
 107
 108 .RE
 109 .B \-v
 110 .br
 111 .B \-\-version
 112 .RS
 113 Print version number, then exit.
 114
 115 .RE
 116 .B \-q
 117 .br
 118 .B \-\-quiet
 119 .RS
 120 Do not print progress messages.
 121
 122 Suppresses all informational progress output. When this switch is enabled,
 123 only error or warning messages are printed.
 124
 125 .RE
 126 .B \-f
 127 .br
 128 .B \-\-frames
 129 .RS
 130 Use HTML frames for source code view.
 131
 132 If enabled, a frameset is created for each source code file, providing
 133 an overview of the source code as a "clickable" image. Note that this
 134 option will slow down output creation noticeably because each source
 135 code character has to be inspected once. Note also that the GD.pm Perl
 136 module has to be installed for this option to work (it may be obtained
 137 from http://www.cpan.org).
 138
 139 .RE
 140 .B \-s
 141 .br
 142 .B \-\-show\-details
 143 .RS
 144 Generate detailed directory view.
 145
 146 When this option is enabled,
 147 .B genhtml
 148 generates two versions of each
 149 file view. One containing the standard information plus a link to a
 150 "detailed" version. The latter additionally contains information about
 151 which test case covered how many lines of each source file.
 152
 153 .RE
 154 .BI "\-b " baseline\-file
 155 .br
 156 .BI "\-\-baseline\-file " baseline\-file
 157 .RS
 158 Use data in
 159 .I baseline\-file
 160 as coverage baseline.
 161
 162 The tracefile specified by
 163 .I baseline\-file
 164 is read and all counts found in the original
 165 .I tracefile
 166 are decremented by the corresponding counts in
 167 .I baseline\-file
 168 before creating any output.
 169
 170 Note that when a count for a particular line in
 171 .I baseline\-file
 172 is greater than the count in the
 173 .IR tracefile ,
 174 the result is zero.
 175
 176 .RE
 177 .BI "\-o " output\-directory
 178 .br
 179 .BI "\-\-output\-directory " output\-directory
 180 .RS
 181 Create files in
 182 .I output\-directory.
 183
 184 Use this option to tell
 185 .B genhtml
 186 to write the resulting files to a directory other than
 187 the current one. If
 188 .I output\-directory
 189 does not exist, it will be created.
 190
 191 It is advisable to use this option since depending on the
 192 project size, a lot of files and subdirectories may be created.
 193
 194 .RE
 195 .BI "\-t " title
 196 .br
 197 .BI "\-\-title " title
 198 .RS
 199 Display
 200 .I title
 201 in header of all pages.
 202
 203 .I title
 204 is written to the header portion of each generated HTML page to
 205 identify the context in which a particular output
 206 was created. By default this is the name of the tracefile.
 207
 208 .RE
 209 .BI "\-d " description\-file
 210 .br
 211 .BI "\-\-description\-file " description\-file
 212 .RS
 213 Read test case descriptions from
 214 .IR description\-file .
 215
 216 All test case descriptions found in
 217 .I description\-file
 218 and referenced in the input data file are read and written to an extra page
 219 which is then incorporated into the HTML output.
 220
 221 The file format of
 222 .IR "description\-file " is:
 223
 224 for each test case:
 225 .RS
 226 TN:<testname>
 227 .br
 228 TD:<test description>
 229
 230 .RE
 231
 232 Valid test case names can consist of letters, numbers and the underscore
 233 character ('_').
 234 .RE
 235 .B \-k
 236 .br
 237 .B \-\-keep\-descriptions
 238 .RS
 239 Do not remove unused test descriptions.
 240
 241 Keep descriptions found in the description file even if the coverage data
 242 indicates that the associated test case did not cover any lines of code.
 243
 244 This option can also be configured permanently using the configuration file
 245 option
 246 .IR genhtml_keep_descriptions .
 247
 248 .RE
 249 .BI "\-c " css\-file
 250 .br
 251 .BI "\-\-css\-file " css\-file
 252 .RS
 253 Use external style sheet file
 254 .IR css\-file .
 255
 256 Using this option, an extra .css file may be specified which will replace
 257 the default one. This may be helpful if the default colors make your eyes want
 258 to jump out of their sockets :)
 259
 260 This option can also be configured permanently using the configuration file
 261 option
 262 .IR genhtml_css_file .
 263
 264 .RE
 265 .BI "\-p " prefix
 266 .br
 267 .BI "\-\-prefix " prefix
 268 .RS
 269 Remove
 270 .I prefix
 271 from all directory names.
 272
 273 Because lists containing long filenames are difficult to read, there is a
 274 mechanism implemented that will automatically try to shorten all directory
 275 names on the overview page beginning with a common prefix. By default,
 276 this is done using an algorithm that tries to find the prefix which, when
 277 applied, will minimize the resulting sum of characters of all directory
 278 names.
 279
 280 Use this option to specify the prefix to be removed by yourself.
 281
 282 .RE
 283 .B \-\-no\-prefix
 284 .RS
 285 Do not remove prefix from directory names.
 286
 287 This switch will completely disable the prefix mechanism described in the
 288 previous section.
 289
 290 This option can also be configured permanently using the configuration file
 291 option
 292 .IR genhtml_no_prefix .
 293
 294 .RE
 295 .B \-\-no\-source
 296 .RS
 297 Do not create source code view.
 298
 299 Use this switch if you don't want to get a source code view for each file.
 300
 301 This option can also be configured permanently using the configuration file
 302 option
 303 .IR genhtml_no_source .
 304
 305 .RE
 306 .BI "\-\-num\-spaces " spaces
 307 .RS
 308 Replace tabs in source view with
 309 .I num
 310 spaces.
 311
 312 Default value is 8.
 313
 314 This option can also be configured permanently using the configuration file
 315 option
 316 .IR genhtml_num_spaces .
 317
 318 .RE
 319 .B \-\-highlight
 320 .RS
 321 Highlight lines with converted\-only coverage data.
 322
 323 Use this option in conjunction with the \-\-diff option of
 324 .B lcov
 325 to highlight those lines which were only covered in data sets which were
 326 converted from previous source code versions.
 327
 328 This option can also be configured permanently using the configuration file
 329 option
 330 .IR genhtml_highlight .
 331
 332 .RE
 333 .B \-\-legend
 334 .RS
 335 Include color legend in HTML output.
 336
 337 Use this option to include a legend explaining the meaning of color coding
 338 in the resulting HTML output.
 339
 340 This option can also be configured permanently using the configuration file
 341 option
 342 .IR genhtml_legend .
 343
 344 .RE
 345 .BI "\-\-html\-prolog " prolog\-file
 346 .RS
 347 Read customized HTML prolog from
 348 .IR prolog\-file .
 349
 350 Use this option to replace the default HTML prolog (the initial part of the
 351 HTML source code leading up to and including the <body> tag) with the contents
 352 of
 353 .IR prolog\-file .
 354 Within the prolog text, the following words will be replaced when a page is generated:
 355
 356 .B "@pagetitle@"
 357 .br
 358 The title of the page.
 359
 360 .B "@basedir@"
 361 .br
 362 A relative path leading to the base directory (e.g. for locating css\-files).
 363
 364 This option can also be configured permanently using the configuration file
 365 option
 366 .IR genhtml_html_prolog .
 367
 368 .RE
 369 .BI "\-\-html\-epilog " epilog\-file
 370 .RS
 371 Read customized HTML epilog from
 372 .IR epilog\-file .
 373
 374 Use this option to replace the default HTML epilog (the final part of the HTML
 375 source including </body>) with the contents of
 376 .IR epilog\-file .
 377
 378 Within the epilog text, the following words will be replaced when a page is generated:
 379
 380 .B "@basedir@"
 381 .br
 382 A relative path leading to the base directory (e.g. for locating css\-files).
 383
 384 This option can also be configured permanently using the configuration file
 385 option
 386 .IR genhtml_html_epilog .
 387
 388 .RE
 389 .BI "\-\-html\-extension " extension
 390 .RS
 391 Use customized filename extension for generated HTML pages.
 392
 393 This option is useful in situations where different filename extensions
 394 are required to render the resulting pages correctly (e.g. php). Note that
 395 a '.' will be inserted between the filename and the extension specified by
 396 this option.
 397
 398 This option can also be configured permanently using the configuration file
 399 option
 400 .IR genhtml_html_extension .
 401 .RE
 402
 403 .B \-\-html\-gzip
 404 .RS
 405 Compress all generated html files with gzip and add a .htaccess file specifying
 406 gzip\-encoding in the root output directory.
 407
 408 Use this option if you want to save space on your webserver. Requires a
 409 webserver with .htaccess support and a browser with support for gzip
 410 compressed html.
 411
 412 This option can also be configured permanently using the configuration file
 413 option
 414 .IR genhtml_html_gzip .
 415
 416 .RE
 417 .B \-\-sort
 418 .br
 419 .B \-\-no\-sort
 420 .RS
 421 Specify whether to include sorted views of file and directory overviews.
 422
 423 Use \-\-sort to include sorted views or \-\-no\-sort to not include them.
 424 Sorted views are
 425 .B enabled
 426 by default.
 427
 428 When sorted views are enabled, each overview page will contain links to
 429 views of that page sorted by coverage rate.
 430
 431 This option can also be configured permanently using the configuration file
 432 option
 433 .IR genhtml_sort .
 434
 435 .RE
 436 .B \-\-function\-coverage
 437 .br
 438 .B \-\-no\-function\-coverage
 439 .RS
 440 Specify whether to display function coverage summaries in HTML output.
 441
 442 Use \-\-function\-coverage to enable function coverage summaries or
 443 \-\-no\-function\-coverage to disable it. Function coverage summaries are
 444 .B enabled
 445 by default
 446
 447 When function coverage summaries are enabled, each overview page will contain
 448 the number of functions found and hit per file or directory, together with
 449 the resulting coverage rate. In addition, each source code view will contain
 450 a link to a page which lists all functions found in that file plus the
 451 respective call count for those functions.
 452
 453 This option can also be configured permanently using the configuration file
 454 option
 455 .IR genhtml_function_coverage .
 456
 457 .RE
 458 .B \-\-branch\-coverage
 459 .br
 460 .B \-\-no\-branch\-coverage
 461 .RS
 462 Specify whether to display branch coverage data in HTML output.
 463
 464 Use \-\-branch\-coverage to enable branch coverage display or
 465 \-\-no\-branch\-coverage to disable it. Branch coverage data display is
 466 .B enabled
 467 by default
 468
 469 When branch coverage display is enabled, each overview page will contain
 470 the number of branches found and hit per file or directory, together with
 471 the resulting coverage rate. In addition, each source code view will contain
 472 an extra column which lists all branches of a line with indications of
 473 whether the branch was taken or not. Branches are shown in the following format:
 474
 475  ' + ': Branch was taken at least once
 476 .br
 477  ' - ': Branch was not taken
 478 .br
 479  ' # ': The basic block containing the branch was never executed
 480 .br
 481
 482 Note that it might not always be possible to relate branches to the
 483 corresponding source code statements: during compilation, GCC might shuffle
 484 branches around or eliminate some of them to generate better code.
 485
 486 This option can also be configured permanently using the configuration file
 487 option
 488 .IR genhtml_branch_coverage .
 489
 490 .RE
 491 .B \-\-demangle\-cpp
 492 .RS
 493 Specify whether to demangle C++ function names.
 494
 495 Use this option if you want to convert C++ internal function names to
 496 human readable format for display on the HTML function overview page.
 497 This option requires that the c++filt tool is installed (see
 498 .BR c++filt (1)).
 499
 500 .RE
 501 .B \-\-ignore\-errors
 502 .I errors
 503 .br
 504 .RS
 505 Specify a list of errors after which to continue processing.
 506
 507 Use this option to specify a list of one or more classes of errors after which
 508 geninfo should continue processing instead of aborting.
 509
 510 .I errors
 511 can be a comma\-separated list of the following keywords:
 512
 513 .B source:
 514 the source code file for a data set could not be found.
 515 .RE
 516
 517 .B \-\-config\-file
 518 .I config\-file
 519 .br
 520 .RS
 521 Specify a configuration file to use.
 522
 523 When this option is specified, neither the system\-wide configuration file
 524 /etc/lcovrc, nor the per\-user configuration file ~/.lcovrc is read.
 525
 526 This option may be useful when there is a need to run several
 527 instances of
 528 .B genhtml
 529 with different configuration file options in parallel.
 530 .RE
 531
 532 .B \-\-rc
 533 .IR keyword = value
 534 .br
 535 .RS
 536 Override a configuration directive.
 537
 538 Use this option to specify a
 539 .IR keyword = value
 540 statement which overrides the corresponding configuration statement in
 541 the lcovrc configuration file. You can specify this option more than once
 542 to override multiple configuration statements.
 543 See
 544 .BR lcovrc (5)
 545 for a list of available keywords and their meaning.
 546 .RE
 547
 548 .SH FILES
 549
 550 .I /etc/lcovrc
 551 .RS
 552 The system\-wide configuration file.
 553 .RE
 554
 555 .I ~/.lcovrc
 556 .RS
 557 The per\-user configuration file.
 558 .RE
 559
 560 .SH AUTHOR
 561 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
 562
 563 .SH SEE ALSO
 564 .BR lcov (1),
 565 .BR lcovrc (5),
 566 .BR geninfo (1),
 567 .BR genpng (1),
 568 .BR gendesc (1),
 569 .BR gcov (1)