OLD | NEW |
1 .TH geninfo 1 "LCOV 1.7" 2008\-11\-17 "User Manuals" | 1 .TH geninfo 1 "LCOV 1.10" 2012\-10\-10 "User Manuals" |
2 .SH NAME | 2 .SH NAME |
3 geninfo \- Generate tracefiles from .da files | 3 geninfo \- Generate tracefiles from .da files |
4 .SH SYNOPSIS | 4 .SH SYNOPSIS |
5 .B geninfo | 5 .B geninfo |
6 .RB [ \-h | \-\-help ] | 6 .RB [ \-h | \-\-help ] |
7 .RB [ \-v | \-\-version ] | 7 .RB [ \-v | \-\-version ] |
8 .RB [ \-q | \-\-quiet ] | 8 .RB [ \-q | \-\-quiet ] |
9 .br | 9 .br |
10 .RS 8 | 10 .RS 8 |
11 .RB [ \-i | \-\-initial ] | 11 .RB [ \-i | \-\-initial ] |
(...skipping 13 matching lines...) Expand all Loading... |
25 .RB [ \-\-compat\-libtool ] | 25 .RB [ \-\-compat\-libtool ] |
26 .RB [ \-\-no\-compat\-libtool ] | 26 .RB [ \-\-no\-compat\-libtool ] |
27 .br | 27 .br |
28 .RB [ \-\-gcov\-tool | 28 .RB [ \-\-gcov\-tool |
29 .IR tool ] | 29 .IR tool ] |
30 .RB [ \-\-ignore\-errors | 30 .RB [ \-\-ignore\-errors |
31 .IR errors ] | 31 .IR errors ] |
32 .br | 32 .br |
33 .RB [ \-\-no\-recursion ] | 33 .RB [ \-\-no\-recursion ] |
34 .I directory | 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 ] |
35 .RE | 48 .RE |
36 .SH DESCRIPTION | 49 .SH DESCRIPTION |
37 .B geninfo | 50 .B geninfo |
38 converts all GCOV coverage data files found in | 51 converts all GCOV coverage data files found in |
39 .I directory | 52 .I directory |
40 into tracefiles, which the | 53 into tracefiles, which the |
41 .B genhtml | 54 .B genhtml |
42 tool can convert to HTML output. | 55 tool can convert to HTML output. |
43 | 56 |
44 Unless the \-\-output\-filename option is specified, | 57 Unless the \-\-output\-filename option is specified, |
45 .B geninfo | 58 .B geninfo |
46 writes its | 59 writes its |
47 output to one file per .da file, the name of which is generated by simply | 60 output to one file per .da file, the name of which is generated by simply |
48 appending ".info" to the respective .da file name. | 61 appending ".info" to the respective .da file name. |
49 | 62 |
50 Note that the current user needs write access to both | 63 Note that the current user needs write access to both |
51 .I directory | 64 .I directory |
52 as well as to the original source code location. This is necessary because | 65 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. | 66 some temporary files have to be created there during the conversion process. |
54 | 67 |
55 Note also that | 68 Note also that |
56 .B geninfo | 69 .B geninfo |
57 is called from within | 70 is called from within |
58 .BR lcov , | 71 .BR lcov , |
59 so that there is usually no need to call it directly. | 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 |
60 .SH OPTIONS | 100 .SH OPTIONS |
61 | 101 |
62 .B \-b | 102 .B \-b |
63 .I directory | 103 .I directory |
64 .br | 104 .br |
65 .B \-\-base\-directory | 105 .B \-\-base\-directory |
66 .I directory | 106 .I directory |
67 .br | 107 .br |
68 .RS | 108 .RS |
69 .RI "Use " directory | 109 .RI "Use " directory |
70 as base directory for relative paths. | 110 as base directory for relative paths. |
71 | 111 |
72 Use this option to specify the base directory of a build\-environment | 112 Use this option to specify the base directory of a build\-environment |
73 when geninfo produces error messages like: | 113 when geninfo produces error messages like: |
74 | 114 |
75 .RS | 115 .RS |
76 ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/sub
dir2/file.c | 116 ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/sub
dir2/file.c |
77 .RE | 117 .RE |
78 | 118 |
79 In this example, use /home/user/project as base directory. | 119 In this example, use /home/user/project as base directory. |
80 | 120 |
81 This option is required when using geninfo on projects built with libtool or | 121 This option is required when using geninfo on projects built with libtool or |
82 similar build environments that work with a base directory, i.e. environments, | 122 similar build environments that work with a base directory, i.e. environments, |
83 where the current working directory when invoking the compiler is not the same | 123 where the current working directory when invoking the compiler is not the same |
84 directory in which the source code file is located. | 124 directory in which the source code file is located. |
85 | 125 |
86 Note that this option will not work in environments where multiple base | 126 Note that this option will not work in environments where multiple base |
87 directories are used. In that case repeat the geninfo call for each base | 127 directories are used. In that case use configuration file setting |
88 directory while using the \-\-ignore\-errors option to prevent geninfo from | 128 .B geninfo_auto_base=1 |
89 exiting when the first source code file could not be found. This way you can | 129 (see |
90 get partial coverage information for each base directory which can then be | 130 .BR lcovrc (5)). |
91 combined using the \-a option. | |
92 .RE | 131 .RE |
93 | 132 |
94 .B \-\-checksum | 133 .B \-\-checksum |
95 .br | 134 .br |
96 .B \-\-no\-checksum | 135 .B \-\-no\-checksum |
97 .br | 136 .br |
98 .RS | 137 .RS |
99 Specify whether to generate checksum data when writing tracefiles. | 138 Specify whether to generate checksum data when writing tracefiles. |
100 | 139 |
101 Use \-\-checksum to enable checksum generation or \-\-no\-checksum to | 140 Use \-\-checksum to enable checksum generation or \-\-no\-checksum to |
102 disable it. Checksum generation is | 141 disable it. Checksum generation is |
103 .B disabled | 142 .B disabled |
104 by default. | 143 by default. |
105 | 144 |
106 When checksum generation is enabled, a checksum will be generated for each | 145 When checksum generation is enabled, a checksum will be generated for each |
107 source code line and stored along with the coverage data. This checksum will | 146 source code line and stored along with the coverage data. This checksum will |
108 be used to prevent attempts to combine coverage data from different source | 147 be used to prevent attempts to combine coverage data from different source |
109 code versions. | 148 code versions. |
110 | 149 |
111 If you don't work with different source code versions, disable this option | 150 If you don't work with different source code versions, disable this option |
112 to speed up coverage data processing and to reduce the size of tracefiles. | 151 to speed up coverage data processing and to reduce the size of tracefiles. |
113 .RE | 152 .RE |
114 | 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 |
115 .B \-\-compat\-libtool | 221 .B \-\-compat\-libtool |
116 .br | 222 .br |
117 .B \-\-no\-compat\-libtool | 223 .B \-\-no\-compat\-libtool |
118 .br | 224 .br |
119 .RS | 225 .RS |
120 Specify whether to enable libtool compatibility mode. | 226 Specify whether to enable libtool compatibility mode. |
121 | 227 |
122 Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-
libtool | 228 Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-
libtool |
123 to disable it. The libtool compatibility mode is | 229 to disable it. The libtool compatibility mode is |
124 .B enabled | 230 .B enabled |
125 by default. | 231 by default. |
126 | 232 |
127 When libtool compatibility mode is enabled, geninfo will assume that the source | 233 When libtool compatibility mode is enabled, geninfo will assume that the source |
128 code relating to a .da file located in a directory named ".libs" can be | 234 code relating to a .da file located in a directory named ".libs" can be |
129 found in its parent directory. | 235 found in its parent directory. |
130 | 236 |
131 If you have directories named ".libs" in your build environment but don't use | 237 If you have directories named ".libs" in your build environment but don't use |
132 libtool, disable this option to prevent problems when capturing coverage data. | 238 libtool, disable this option to prevent problems when capturing coverage data. |
133 .RE | 239 .RE |
134 | 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 |
135 .B \-f | 284 .B \-f |
136 .br | 285 .br |
137 .B \-\-follow | 286 .B \-\-follow |
138 .RS | 287 .RS |
139 Follow links when searching .da files. | 288 Follow links when searching .da files. |
140 .RE | 289 .RE |
141 | 290 |
142 .B \-\-gcov\-tool | 291 .B \-\-gcov\-tool |
143 .I tool | 292 .I tool |
144 .br | 293 .br |
(...skipping 28 matching lines...) Expand all Loading... |
173 .RE | 322 .RE |
174 | 323 |
175 .B \-i | 324 .B \-i |
176 .br | 325 .br |
177 .B \-\-initial | 326 .B \-\-initial |
178 .RS | 327 .RS |
179 Capture initial zero coverage data. | 328 Capture initial zero coverage data. |
180 | 329 |
181 Run geninfo with this option on the directories containing .bb, .bbg or .gcno | 330 Run geninfo with this option on the directories containing .bb, .bbg or .gcno |
182 files before running any test case. The result is a "baseline" coverage data | 331 files before running any test case. The result is a "baseline" coverage data |
183 file that contains zero coverage for every instrumented line. Combine this | 332 file that contains zero coverage for every instrumented line and function. |
184 data file (using lcov \-a) with coverage data files captured after a test | 333 Combine this data file (using lcov \-a) with coverage data files captured |
185 run to ensure that the percentage of total lines covered is correct even | 334 after a test run to ensure that the percentage of total lines covered is |
186 when not all source code files were loaded during the test. | 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. |
187 .RE | 346 .RE |
188 | 347 |
189 .B \-\-no\-recursion | 348 .B \-\-no\-recursion |
190 .br | 349 .br |
191 .RS | 350 .RS |
192 Use this option if you want to get coverage data for the specified directory | 351 Use this option if you want to get coverage data for the specified directory |
193 only without processing subdirectories. | 352 only without processing subdirectories. |
194 .RE | 353 .RE |
195 | 354 |
196 .BI "\-o " output\-filename | 355 .BI "\-o " output\-filename |
(...skipping 11 matching lines...) Expand all Loading... |
208 .B \-q | 367 .B \-q |
209 .br | 368 .br |
210 .B \-\-quiet | 369 .B \-\-quiet |
211 .RS | 370 .RS |
212 Do not print progress messages. | 371 Do not print progress messages. |
213 | 372 |
214 Suppresses all informational progress output. When this switch is enabled, | 373 Suppresses all informational progress output. When this switch is enabled, |
215 only error or warning messages are printed. | 374 only error or warning messages are printed. |
216 .RE | 375 .RE |
217 | 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 |
218 .BI "\-t " testname | 393 .BI "\-t " testname |
219 .br | 394 .br |
220 .BI "\-\-test\-name " testname | 395 .BI "\-\-test\-name " testname |
221 .RS | 396 .RS |
222 Use test case name | 397 Use test case name |
223 .I testname | 398 .I testname |
224 for resulting data. Valid test case names can consist of letters, decimal | 399 for resulting data. Valid test case names can consist of letters, decimal |
225 digits and the underscore character ('_'). | 400 digits and the underscore character ('_'). |
226 | 401 |
227 This proves useful when data from several test cases is merged (i.e. by | 402 This proves useful when data from several test cases is merged (i.e. by |
(...skipping 44 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
272 Next, there is a list of execution counts for each instrumented function: | 447 Next, there is a list of execution counts for each instrumented function: |
273 | 448 |
274 FNDA:<execution count>,<function name> | 449 FNDA:<execution count>,<function name> |
275 | 450 |
276 This list is followed by two lines containing the number of functions found | 451 This list is followed by two lines containing the number of functions found |
277 and hit: | 452 and hit: |
278 | 453 |
279 FNF:<number of functions found> | 454 FNF:<number of functions found> |
280 FNH:<number of function hit> | 455 FNH:<number of function hit> |
281 | 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 |
282 Then there is a list of execution counts for each instrumented line | 470 Then there is a list of execution counts for each instrumented line |
283 (i.e. a line which resulted in executable code): | 471 (i.e. a line which resulted in executable code): |
284 | 472 |
285 DA:<line number>,<execution count>[,<checksum>] | 473 DA:<line number>,<execution count>[,<checksum>] |
286 | 474 |
287 Note that there may be an optional checksum present for each instrumented | 475 Note that there may be an optional checksum present for each instrumented |
288 line. The current | 476 line. The current |
289 .B geninfo | 477 .B geninfo |
290 implementation uses an MD5 hash as checksumming algorithm. | 478 implementation uses an MD5 hash as checksumming algorithm. |
291 | 479 |
(...skipping 18 matching lines...) Expand all Loading... |
310 | 498 |
311 Note also that symbolic links to the .bb file will be resolved so that the | 499 Note also that symbolic links to the .bb file will be resolved so that the |
312 actual file path is used instead of the path to a link. This approach is | 500 actual file path is used instead of the path to a link. This approach is |
313 necessary for the mechanism to work with the /proc/gcov files. | 501 necessary for the mechanism to work with the /proc/gcov files. |
314 | 502 |
315 .SH AUTHOR | 503 .SH AUTHOR |
316 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> | 504 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> |
317 | 505 |
318 .SH SEE ALSO | 506 .SH SEE ALSO |
319 .BR lcov (1), | 507 .BR lcov (1), |
| 508 .BR lcovrc (5), |
320 .BR genhtml (1), | 509 .BR genhtml (1), |
321 .BR genpng (1), | 510 .BR genpng (1), |
322 .BR gendesc (1), | 511 .BR gendesc (1), |
323 .BR gcov (1) | 512 .BR gcov (1) |
OLD | NEW |