src/third_party/lcov/man/geninfo.1

   1 .TH geninfo 1 "LCOV 1.10" 2012\-10\-10 "User Manuals"
   2 .SH NAME
   3 geninfo \- Generate tracefiles from .da files
   4 .SH SYNOPSIS
   5 .B geninfo
   6 .RB [ \-h | \-\-help ]
   7 .RB [ \-v | \-\-version ]
   8 .RB [ \-q | \-\-quiet ]
   9 .br
  10 .RS 8
  11 .RB [ \-i | \-\-initial ]
  12 .RB [ \-t | \-\-test\-name
  13 .IR test\-name ]
  14 .br
  15 .RB [ \-o | \-\-output\-filename
  16 .IR filename ]
  17 .RB [ \-f | \-\-follow ]
  18 .br
  19 .RB [ \-b | \-\-base\-directory
  20 .IR directory ]
  21 .br
  22 .RB [ \-\-checksum ]
  23 .RB [ \-\-no\-checksum ]
  24 .br
  25 .RB [ \-\-compat\-libtool ]
  26 .RB [ \-\-no\-compat\-libtool ]
  27 .br
  28 .RB [ \-\-gcov\-tool
  29 .IR tool  ]
  30 .RB [ \-\-ignore\-errors
  31 .IR errors  ]
  32 .br
  33 .RB [ \-\-no\-recursion ]
  34 .I directory
  35 .RB [ \-\-external ]
  36 .RB [ \-\-no\-external ]
  37 .br
  38 .RB [ \-\-config\-file
  39 .IR config\-file ]
  40 .RB [ \-\-no\-markers ]
  41 .br
  42 .RB [ \-\-derive\-func\-data ]
  43 .RB [ \-\-compat
  44 .IR  mode =on|off|auto]
  45 .br
  46 .RB [ \-\-rc
  47 .IR keyword = value ]
  48 .RE
  49 .SH DESCRIPTION
  50 .B geninfo
  51 converts all GCOV coverage data files found in
  52 .I directory
  53 into tracefiles, which the
  54 .B genhtml
  55 tool can convert to HTML output.
  56
  57 Unless the \-\-output\-filename option is specified,
  58 .B geninfo
  59 writes its
  60 output to one file per .da file, the name of which is generated by simply
  61 appending ".info" to the respective .da file name.
  62
  63 Note that the current user needs write access to both
  64 .I directory
  65 as well as to the original source code location. This is necessary because
  66 some temporary files have to be created there during the conversion process.
  67
  68 Note also that
  69 .B geninfo
  70 is called from within
  71 .BR lcov ,
  72 so that there is usually no need to call it directly.
  73
  74 .B Exclusion markers
  75
  76 To exclude specific lines of code from a tracefile, you can add exclusion
  77 markers to the source code. Exclusion markers are keywords which can for
  78 example be added in the form of a comment.
  79
  80 The following markers are recognized by geninfo:
  81
  82 LCOV_EXCL_LINE
  83 .RS
  84 Lines containing this marker will be excluded.
  85 .br
  86 .RE
  87 LCOV_EXCL_START
  88 .RS
  89 Marks the beginning of an excluded section. The current line is part of this
  90 section.
  91 .br
  92 .RE
  93 LCOV_EXCL_STOP
  94 .RS
  95 Marks the end of an excluded section. The current line not part of this
  96 section.
  97 .RE
  98 .br
  99
 100 .SH OPTIONS
 101
 102 .B \-b
 103 .I directory
 104 .br
 105 .B \-\-base\-directory
 106 .I directory
 107 .br
 108 .RS
 109 .RI "Use " directory
 110 as base directory for relative paths.
 111
 112 Use this option to specify the base directory of a build\-environment
 113 when geninfo produces error messages like:
 114
 115 .RS
 116 ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c
 117 .RE
 118
 119 In this example, use /home/user/project as base directory.
 120
 121 This option is required when using geninfo on projects built with libtool or
 122 similar build environments that work with a base directory, i.e. environments,
 123 where the current working directory when invoking the compiler is not the same
 124 directory in which the source code file is located.
 125
 126 Note that this option will not work in environments where multiple base
 127 directories are used. In that case use configuration file setting
 128 .B geninfo_auto_base=1
 129 (see
 130 .BR lcovrc (5)).
 131 .RE
 132
 133 .B \-\-checksum
 134 .br
 135 .B \-\-no\-checksum
 136 .br
 137 .RS
 138 Specify whether to generate checksum data when writing tracefiles.
 139
 140 Use \-\-checksum to enable checksum generation or \-\-no\-checksum to
 141 disable it. Checksum generation is
 142 .B disabled
 143 by default.
 144
 145 When checksum generation is enabled, a checksum will be generated for each
 146 source code line and stored along with the coverage data. This checksum will
 147 be used to prevent attempts to combine coverage data from different source
 148 code versions.
 149
 150 If you don't work with different source code versions, disable this option
 151 to speed up coverage data processing and to reduce the size of tracefiles.
 152 .RE
 153
 154 .B \-\-compat
 155 .IR mode = value [, mode = value ,...]
 156 .br
 157 .RS
 158 Set compatibility mode.
 159
 160 Use \-\-compat to specify that geninfo should enable one or more compatibility
 161 modes when capturing coverage data. You can provide a comma-separated list
 162 of mode=value pairs to specify the values for multiple modes.
 163
 164 Valid
 165 .I values
 166 are:
 167
 168 .B on
 169 .RS
 170 Enable compatibility mode.
 171 .RE
 172 .B off
 173 .RS
 174 Disable compatibility mode.
 175 .RE
 176 .B auto
 177 .RS
 178 Apply auto-detection to determine if compatibility mode is required. Note that
 179 auto-detection is not available for all compatibility modes.
 180 .RE
 181
 182 If no value is specified, 'on' is assumed as default value.
 183
 184 Valid
 185 .I modes
 186 are:
 187
 188 .B libtool
 189 .RS
 190 Enable this mode if you are capturing coverage data for a project that
 191 was built using the libtool mechanism. See also
 192 \-\-compat\-libtool.
 193
 194 The default value for this setting is 'on'.
 195
 196 .RE
 197 .B hammer
 198 .RS
 199 Enable this mode if you are capturing coverage data for a project that
 200 was built using a version of GCC 3.3 that contains a modification
 201 (hammer patch) of later GCC versions. You can identify a modified GCC 3.3
 202 by checking the build directory of your project for files ending in the
 203 extension '.bbg'. Unmodified versions of GCC 3.3 name these files '.bb'.
 204
 205 The default value for this setting is 'auto'.
 206
 207 .RE
 208 .B split_crc
 209 .RS
 210 Enable this mode if you are capturing coverage data for a project that
 211 was built using a version of GCC 4.6 that contains a modification
 212 (split function checksums) of later GCC versions. Typical error messages
 213 when running geninfo on coverage data produced by such GCC versions are
 214 \'out of memory' and 'reached unexpected end of file'.
 215
 216 The default value for this setting is 'auto'
 217 .RE
 218
 219 .RE
 220
 221 .B \-\-compat\-libtool
 222 .br
 223 .B \-\-no\-compat\-libtool
 224 .br
 225 .RS
 226 Specify whether to enable libtool compatibility mode.
 227
 228 Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-libtool
 229 to disable it. The libtool compatibility mode is
 230 .B enabled
 231 by default.
 232
 233 When libtool compatibility mode is enabled, geninfo will assume that the source
 234 code relating to a .da file located in a directory named ".libs" can be
 235 found in its parent directory.
 236
 237 If you have directories named ".libs" in your build environment but don't use
 238 libtool, disable this option to prevent problems when capturing coverage data.
 239 .RE
 240
 241 .B \-\-config\-file
 242 .I config\-file
 243 .br
 244 .RS
 245 Specify a configuration file to use.
 246
 247 When this option is specified, neither the system\-wide configuration file
 248 /etc/lcovrc, nor the per\-user configuration file ~/.lcovrc is read.
 249
 250 This option may be useful when there is a need to run several
 251 instances of
 252 .B geninfo
 253 with different configuration file options in parallel.
 254 .RE
 255
 256 .B \-\-derive\-func\-data
 257 .br
 258 .RS
 259 Calculate function coverage data from line coverage data.
 260
 261 Use this option to collect function coverage data, even if the version of the
 262 gcov tool installed on the test system does not provide this data. lcov will
 263 instead derive function coverage data from line coverage data and
 264 information about which lines belong to a function.
 265 .RE
 266
 267 .B \-\-external
 268 .br
 269 .B \-\-no\-external
 270 .br
 271 .RS
 272 Specify whether to capture coverage data for external source files.
 273
 274 External source files are files which are not located in one of the directories
 275 specified by \-\-directory or \-\-base\-directory. Use \-\-external to include
 276 external source files while capturing coverage data or \-\-no\-external to
 277 ignore this data.
 278
 279 Data for external source files is
 280 .B included
 281 by default.
 282 .RE
 283
 284 .B \-f
 285 .br
 286 .B \-\-follow
 287 .RS
 288 Follow links when searching .da files.
 289 .RE
 290
 291 .B \-\-gcov\-tool
 292 .I tool
 293 .br
 294 .RS
 295 Specify the location of the gcov tool.
 296 .RE
 297
 298 .B \-h
 299 .br
 300 .B \-\-help
 301 .RS
 302 Print a short help text, then exit.
 303 .RE
 304
 305 .B \-\-ignore\-errors
 306 .I errors
 307 .br
 308 .RS
 309 Specify a list of errors after which to continue processing.
 310
 311 Use this option to specify a list of one or more classes of errors after which
 312 geninfo should continue processing instead of aborting.
 313
 314 .I errors
 315 can be a comma\-separated list of the following keywords:
 316
 317 .B gcov:
 318 the gcov tool returned with a non\-zero return code.
 319
 320 .B source:
 321 the source code file for a data set could not be found.
 322 .RE
 323
 324 .B \-i
 325 .br
 326 .B \-\-initial
 327 .RS
 328 Capture initial zero coverage data.
 329
 330 Run geninfo with this option on the directories containing .bb, .bbg or .gcno
 331 files before running any test case. The result is a "baseline" coverage data
 332 file that contains zero coverage for every instrumented line and function.
 333 Combine this data file (using lcov \-a) with coverage data files captured
 334 after a test run to ensure that the percentage of total lines covered is
 335 correct even when not all object code files were loaded during the test.
 336
 337 Note: currently, the \-\-initial option does not generate branch coverage
 338 information.
 339 .RE
 340
 341 .B \-\-no\-markers
 342 .br
 343 .RS
 344 Use this option if you want to get coverage data without regard to exclusion
 345 markers in the source code file.
 346 .RE
 347
 348 .B \-\-no\-recursion
 349 .br
 350 .RS
 351 Use this option if you want to get coverage data for the specified directory
 352 only without processing subdirectories.
 353 .RE
 354
 355 .BI "\-o " output\-filename
 356 .br
 357 .BI "\-\-output\-filename " output\-filename
 358 .RS
 359 Write all data to
 360 .IR output\-filename .
 361
 362 If you want to have all data written to a single file (for easier
 363 handling), use this option to specify the respective filename. By default,
 364 one tracefile will be created for each processed .da file.
 365 .RE
 366
 367 .B \-q
 368 .br
 369 .B \-\-quiet
 370 .RS
 371 Do not print progress messages.
 372
 373 Suppresses all informational progress output. When this switch is enabled,
 374 only error or warning messages are printed.
 375 .RE
 376
 377 .B \-\-rc
 378 .IR keyword = value
 379 .br
 380 .RS
 381 Override a configuration directive.
 382
 383 Use this option to specify a
 384 .IR keyword = value
 385 statement which overrides the corresponding configuration statement in
 386 the lcovrc configuration file. You can specify this option more than once
 387 to override multiple configuration statements.
 388 See
 389 .BR lcovrc (5)
 390 for a list of available keywords and their meaning.
 391 .RE
 392
 393 .BI "\-t " testname
 394 .br
 395 .BI "\-\-test\-name " testname
 396 .RS
 397 Use test case name
 398 .I testname
 399 for resulting data. Valid test case names can consist of letters, decimal
 400 digits and the underscore character ('_').
 401
 402 This proves useful when data from several test cases is merged (i.e. by
 403 simply concatenating the respective tracefiles) in which case a test
 404 name can be used to differentiate between data from each test case.
 405 .RE
 406
 407 .B \-v
 408 .br
 409 .B \-\-version
 410 .RS
 411 Print version number, then exit.
 412 .RE
 413
 414
 415 .SH FILES
 416
 417 .I /etc/lcovrc
 418 .RS
 419 The system\-wide configuration file.
 420 .RE
 421
 422 .I ~/.lcovrc
 423 .RS
 424 The per\-user configuration file.
 425 .RE
 426
 427 Following is a quick description of the tracefile format as used by
 428 .BR genhtml ", " geninfo " and " lcov .
 429
 430 A tracefile is made up of several human\-readable lines of text,
 431 divided into sections. If available, a tracefile begins with the
 432 .I testname
 433 which is stored in the following format:
 434
 435   TN:<test name>
 436
 437 For each source file referenced in the .da file, there is a section containing
 438 filename and coverage data:
 439
 440   SF:<absolute path to the source file>
 441
 442 Following is a list of line numbers for each function name found in the
 443 source file:
 444
 445   FN:<line number of function start>,<function name>
 446
 447 Next, there is a list of execution counts for each instrumented function:
 448
 449   FNDA:<execution count>,<function name>
 450
 451 This list is followed by two lines containing the number of functions found
 452 and hit:
 453
 454   FNF:<number of functions found>
 455   FNH:<number of function hit>
 456
 457 Branch coverage information is stored which one line per branch:
 458
 459   BRDA:<line number>,<block number>,<branch number>,<taken>
 460
 461 Block number and branch number are gcc internal IDs for the branch. Taken is
 462 either '-' if the basic block containing the branch was never executed or
 463 a number indicating how often that branch was taken.
 464
 465 Branch coverage summaries are stored in two lines:
 466
 467   BRF:<number of branches found>
 468   BRH:<number of branches hit>
 469
 470 Then there is a list of execution counts for each instrumented line
 471 (i.e. a line which resulted in executable code):
 472
 473   DA:<line number>,<execution count>[,<checksum>]
 474
 475 Note that there may be an optional checksum present for each instrumented
 476 line. The current
 477 .B geninfo
 478 implementation uses an MD5 hash as checksumming algorithm.
 479
 480 At the end of a section, there is a summary about how many lines
 481 were found and how many were actually instrumented:
 482
 483   LH:<number of lines with a non\-zero execution count>
 484   LF:<number of instrumented lines>
 485
 486 Each sections ends with:
 487
 488   end_of_record
 489
 490 In addition to the main source code file there are sections for all
 491 #included files which also contain executable code.
 492
 493 Note that the absolute path of a source file is generated by interpreting
 494 the contents of the respective .bb file (see
 495 .BR "gcov " (1)
 496 for more information on this file type). Relative filenames are prefixed
 497 with the directory in which the .bb file is found.
 498
 499 Note also that symbolic links to the .bb file will be resolved so that the
 500 actual file path is used instead of the path to a link. This approach is
 501 necessary for the mechanism to work with the /proc/gcov files.
 502
 503 .SH AUTHOR
 504 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
 505
 506 .SH SEE ALSO
 507 .BR lcov (1),
 508 .BR lcovrc (5),
 509 .BR genhtml (1),
 510 .BR genpng (1),
 511 .BR gendesc (1),
 512 .BR gcov (1)