| OLD | NEW |
|---|
| (Empty) |
| 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/sub
dir2/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) | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 23189008:
Upgrades lcov to 1.10, removes lcov-1.9 (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master