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 |