third_party/lcov-1.9/man/geninfo.1

   1 .TH geninfo 1 "LCOV 1.9" 2010\-08\-06 "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 .RE
  36 .SH DESCRIPTION
  37 .B geninfo
  38 converts all GCOV coverage data files found in
  39 .I directory
  40 into tracefiles, which the
  41 .B genhtml
  42 tool can convert to HTML output.
  43
  44 Unless the \-\-output\-filename option is specified,
  45 .B geninfo
  46 writes its
  47 output to one file per .da file, the name of which is generated by simply
  48 appending ".info" to the respective .da file name.
  49
  50 Note that the current user needs write access to both
  51 .I directory
  52 as well as to the original source code location. This is necessary because
  53 some temporary files have to be created there during the conversion process.
  54
  55 Note also that
  56 .B geninfo
  57 is called from within
  58 .BR lcov ,
  59 so that there is usually no need to call it directly.
  60
  61 .B Exclusion markers
  62
  63 To exclude specific lines of code from a tracefile, you can add exclusion
  64 markers to the source code. Exclusion markers are keywords which can for
  65 example be added in the form of a comment.
  66
  67 The following markers are recognized by geninfo:
  68
  69 LCOV_EXCL_LINE
  70 .RS
  71 Lines containing this marker will be excluded.
  72 .br
  73 .RE
  74 LCOV_EXCL_START
  75 .RS
  76 Marks the beginning of an excluded section. The current line is part of this
  77 section.
  78 .br
  79 .RE
  80 LCOV_EXCL_STOP
  81 .RS
  82 Marks the end of an excluded section. The current line not part of this
  83 section.
  84 .RE
  85 .br
  86
  87 .SH OPTIONS
  88
  89 .B \-b
  90 .I directory
  91 .br
  92 .B \-\-base\-directory
  93 .I directory
  94 .br
  95 .RS
  96 .RI "Use " directory
  97 as base directory for relative paths.
  98
  99 Use this option to specify the base directory of a build\-environment
 100 when geninfo produces error messages like:
 101
 102 .RS
 103 ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c
 104 .RE
 105
 106 In this example, use /home/user/project as base directory.
 107
 108 This option is required when using geninfo on projects built with libtool or
 109 similar build environments that work with a base directory, i.e. environments,
 110 where the current working directory when invoking the compiler is not the same
 111 directory in which the source code file is located.
 112
 113 Note that this option will not work in environments where multiple base
 114 directories are used. In that case repeat the geninfo call for each base
 115 directory while using the \-\-ignore\-errors option to prevent geninfo from
 116 exiting when the first source code file could not be found. This way you can
 117 get partial coverage information for each base directory which can then be
 118 combined using the \-a option.
 119 .RE
 120
 121 .B \-\-checksum
 122 .br
 123 .B \-\-no\-checksum
 124 .br
 125 .RS
 126 Specify whether to generate checksum data when writing tracefiles.
 127
 128 Use \-\-checksum to enable checksum generation or \-\-no\-checksum to
 129 disable it. Checksum generation is
 130 .B disabled
 131 by default.
 132
 133 When checksum generation is enabled, a checksum will be generated for each
 134 source code line and stored along with the coverage data. This checksum will
 135 be used to prevent attempts to combine coverage data from different source
 136 code versions.
 137
 138 If you don't work with different source code versions, disable this option
 139 to speed up coverage data processing and to reduce the size of tracefiles.
 140 .RE
 141
 142 .B \-\-compat\-libtool
 143 .br
 144 .B \-\-no\-compat\-libtool
 145 .br
 146 .RS
 147 Specify whether to enable libtool compatibility mode.
 148
 149 Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-libtool
 150 to disable it. The libtool compatibility mode is
 151 .B enabled
 152 by default.
 153
 154 When libtool compatibility mode is enabled, geninfo will assume that the source
 155 code relating to a .da file located in a directory named ".libs" can be
 156 found in its parent directory.
 157
 158 If you have directories named ".libs" in your build environment but don't use
 159 libtool, disable this option to prevent problems when capturing coverage data.
 160 .RE
 161
 162 .B \-f
 163 .br
 164 .B \-\-follow
 165 .RS
 166 Follow links when searching .da files.
 167 .RE
 168
 169 .B \-\-gcov\-tool
 170 .I tool
 171 .br
 172 .RS
 173 Specify the location of the gcov tool.
 174 .RE
 175
 176 .B \-h
 177 .br
 178 .B \-\-help
 179 .RS
 180 Print a short help text, then exit.
 181 .RE
 182
 183 .B \-\-ignore\-errors
 184 .I errors
 185 .br
 186 .RS
 187 Specify a list of errors after which to continue processing.
 188
 189 Use this option to specify a list of one or more classes of errors after which
 190 geninfo should continue processing instead of aborting.
 191
 192 .I errors
 193 can be a comma\-separated list of the following keywords:
 194
 195 .B gcov:
 196 the gcov tool returned with a non\-zero return code.
 197
 198 .B source:
 199 the source code file for a data set could not be found.
 200 .RE
 201
 202 .B \-i
 203 .br
 204 .B \-\-initial
 205 .RS
 206 Capture initial zero coverage data.
 207
 208 Run geninfo with this option on the directories containing .bb, .bbg or .gcno
 209 files before running any test case. The result is a "baseline" coverage data
 210 file that contains zero coverage for every instrumented line and function.
 211 Combine this data file (using lcov \-a) with coverage data files captured
 212 after a test run to ensure that the percentage of total lines covered is
 213 correct even when not all object code files were loaded during the test.
 214
 215 Note: currently, the \-\-initial option does not generate branch coverage
 216 information.
 217 .RE
 218
 219 .B \-\-no\-recursion
 220 .br
 221 .RS
 222 Use this option if you want to get coverage data for the specified directory
 223 only without processing subdirectories.
 224 .RE
 225
 226 .BI "\-o " output\-filename
 227 .br
 228 .BI "\-\-output\-filename " output\-filename
 229 .RS
 230 Write all data to
 231 .IR output\-filename .
 232
 233 If you want to have all data written to a single file (for easier
 234 handling), use this option to specify the respective filename. By default,
 235 one tracefile will be created for each processed .da file.
 236 .RE
 237
 238 .B \-q
 239 .br
 240 .B \-\-quiet
 241 .RS
 242 Do not print progress messages.
 243
 244 Suppresses all informational progress output. When this switch is enabled,
 245 only error or warning messages are printed.
 246 .RE
 247
 248 .BI "\-t " testname
 249 .br
 250 .BI "\-\-test\-name " testname
 251 .RS
 252 Use test case name
 253 .I testname
 254 for resulting data. Valid test case names can consist of letters, decimal
 255 digits and the underscore character ('_').
 256
 257 This proves useful when data from several test cases is merged (i.e. by
 258 simply concatenating the respective tracefiles) in which case a test
 259 name can be used to differentiate between data from each test case.
 260 .RE
 261
 262 .B \-v
 263 .br
 264 .B \-\-version
 265 .RS
 266 Print version number, then exit.
 267 .RE
 268
 269
 270 .SH FILES
 271
 272 .I /etc/lcovrc
 273 .RS
 274 The system\-wide configuration file.
 275 .RE
 276
 277 .I ~/.lcovrc
 278 .RS
 279 The per\-user configuration file.
 280 .RE
 281
 282 Following is a quick description of the tracefile format as used by
 283 .BR genhtml ", " geninfo " and " lcov .
 284
 285 A tracefile is made up of several human\-readable lines of text,
 286 divided into sections. If available, a tracefile begins with the
 287 .I testname
 288 which is stored in the following format:
 289
 290   TN:<test name>
 291
 292 For each source file referenced in the .da file, there is a section containing
 293 filename and coverage data:
 294
 295   SF:<absolute path to the source file>
 296
 297 Following is a list of line numbers for each function name found in the
 298 source file:
 299
 300   FN:<line number of function start>,<function name>
 301
 302 Next, there is a list of execution counts for each instrumented function:
 303
 304   FNDA:<execution count>,<function name>
 305
 306 This list is followed by two lines containing the number of functions found
 307 and hit:
 308
 309   FNF:<number of functions found>
 310   FNH:<number of function hit>
 311
 312 Branch coverage information is stored which one line per branch:
 313
 314   BRDA:<line number>,<block number>,<branch number>,<taken>
 315
 316 Block number and branch number are gcc internal IDs for the branch. Taken is
 317 either '-' if the basic block containing the branch was never executed or
 318 a number indicating how often that branch was taken.
 319
 320 Branch coverage summaries are stored in two lines:
 321
 322   BRF:<number of branches found>
 323   BRH:<number of branches hit>
 324
 325 Then there is a list of execution counts for each instrumented line
 326 (i.e. a line which resulted in executable code):
 327
 328   DA:<line number>,<execution count>[,<checksum>]
 329
 330 Note that there may be an optional checksum present for each instrumented
 331 line. The current
 332 .B geninfo
 333 implementation uses an MD5 hash as checksumming algorithm.
 334
 335 At the end of a section, there is a summary about how many lines
 336 were found and how many were actually instrumented:
 337
 338   LH:<number of lines with a non\-zero execution count>
 339   LF:<number of instrumented lines>
 340
 341 Each sections ends with:
 342
 343   end_of_record
 344
 345 In addition to the main source code file there are sections for all
 346 #included files which also contain executable code.
 347
 348 Note that the absolute path of a source file is generated by interpreting
 349 the contents of the respective .bb file (see
 350 .BR "gcov " (1)
 351 for more information on this file type). Relative filenames are prefixed
 352 with the directory in which the .bb file is found.
 353
 354 Note also that symbolic links to the .bb file will be resolved so that the
 355 actual file path is used instead of the path to a link. This approach is
 356 necessary for the mechanism to work with the /proc/gcov files.
 357
 358 .SH AUTHOR
 359 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
 360
 361 .SH SEE ALSO
 362 .BR lcov (1),
 363 .BR genhtml (1),
 364 .BR genpng (1),
 365 .BR gendesc (1),
 366 .BR gcov (1)