OLD | NEW |
| (Empty) |
1 .TH lcov 1 "LCOV 1.9" 2010\-08\-06 "User Manuals" | |
2 .SH NAME | |
3 lcov \- a graphical GCOV front\-end | |
4 .SH SYNOPSIS | |
5 .B lcov | |
6 .BR \-c | \-\-capture | |
7 .RS 5 | |
8 .br | |
9 .RB [ \-d | \-\-directory | |
10 .IR directory ] | |
11 .RB [ \-k | \-\-kernel\-directory | |
12 .IR directory ] | |
13 .br | |
14 .RB [ \-o | \-\-output\-file | |
15 .IR tracefile ] | |
16 .RB [ \-t | \-\-test\-name | |
17 .IR testname ] | |
18 .br | |
19 .RB [ \-b | \-\-base\-directory | |
20 .IR directory ] | |
21 .RB [ \-i | \-\-initial ] | |
22 .RB [ \-\-gcov\-tool | |
23 .IR tool ] | |
24 .br | |
25 .RB [ \-\-checksum ] | |
26 .RB [ \-\-no\-checksum ] | |
27 .RB [ \-\-no\-recursion ] | |
28 .RB [ \-f | \-\-follow ] | |
29 .br | |
30 .RB [ \-\-compat\-libtool ] | |
31 .RB [ \-\-no\-compat\-libtool ] | |
32 .RB [ \-\-ignore\-errors | |
33 .IR errors ] | |
34 .br | |
35 .RB [ \-\-to\-package | |
36 .IR package ] | |
37 .RB [ \-\-from\-package | |
38 .IR package ] | |
39 .RB [ \-q | \-\-quiet ] | |
40 .br | |
41 .RB [ \-\-no\-markers ] | |
42 .br | |
43 .RE | |
44 | |
45 .B lcov | |
46 .BR \-z | \-\-zerocounters | |
47 .RS 5 | |
48 .br | |
49 .RB [ \-d | \-\-directory | |
50 .IR directory ] | |
51 .RB [ \-\-no\-recursion ] | |
52 .RB [ \-f | \-\-follow ] | |
53 .br | |
54 .RB [ \-q | \-\-quiet ] | |
55 .br | |
56 .RE | |
57 | |
58 .B lcov | |
59 .BR \-l | \-\-list | |
60 .I tracefile | |
61 .RS 5 | |
62 .br | |
63 .RB [ \-q | \-\-quiet ] | |
64 .RB [ \-\-list\-full\-path ] | |
65 .RB [ \-\-no\-list\-full\-path ] | |
66 .br | |
67 .RE | |
68 | |
69 .B lcov | |
70 .BR \-a | \-\-add\-tracefile | |
71 .I tracefile | |
72 .RS 5 | |
73 .br | |
74 .RB [ \-o | \-\-output\-file | |
75 .IR tracefile ] | |
76 .RB [ \-\-checksum ] | |
77 .RB [ \-\-no\-checksum ] | |
78 .br | |
79 .RB [ \-q | \-\-quiet ] | |
80 .br | |
81 .RE | |
82 | |
83 .B lcov | |
84 .BR \-e | \-\-extract | |
85 .I tracefile pattern | |
86 .RS 5 | |
87 .br | |
88 .RB [ \-o | \-\-output\-file | |
89 .IR tracefile ] | |
90 .RB [ \-\-checksum ] | |
91 .RB [ \-\-no\-checksum ] | |
92 .br | |
93 .RB [ \-q | \-\-quiet ] | |
94 .RE | |
95 | |
96 .B lcov | |
97 .BR \-r | \-\-remove | |
98 .I tracefile pattern | |
99 .RS 5 | |
100 .br | |
101 .RB [ \-o | \-\-output\-file | |
102 .IR tracefile ] | |
103 .RB [ \-\-checksum ] | |
104 .RB [ \-\-no\-checksum ] | |
105 .br | |
106 .RB [ \-q | \-\-quiet ] | |
107 .br | |
108 .RE | |
109 | |
110 .B lcov | |
111 .BR \-\-diff | |
112 .IR "tracefile diff" | |
113 .RS 5 | |
114 .br | |
115 .RB [ \-o | \-\-output\-file | |
116 .IR tracefile ] | |
117 .RB [ \-\-checksum ] | |
118 .RB [ \-\-no\-checksum ] | |
119 .br | |
120 .RB [ \-\-convert\-filenames ] | |
121 .RB [ \-\-strip | |
122 .IR depth ] | |
123 .RB [ \-\-path | |
124 .IR path ] | |
125 .RB [ \-q | \-\-quiet ] | |
126 .br | |
127 .RE | |
128 | |
129 .B lcov | |
130 .RB [ \-h | \-\-help ] | |
131 .RB [ \-v | \-\-version ] | |
132 .RS 5 | |
133 .br | |
134 .RE | |
135 | |
136 .SH DESCRIPTION | |
137 .B lcov | |
138 is a graphical front\-end for GCC's coverage testing tool gcov. It collects | |
139 line, function and branch coverage data for multiple source files and creates | |
140 HTML pages containing the source code annotated with coverage information. | |
141 It also adds overview pages for easy navigation within the file structure. | |
142 | |
143 Use | |
144 .B lcov | |
145 to collect coverage data and | |
146 .B genhtml | |
147 to create HTML pages. Coverage data can either be collected from the | |
148 currently running Linux kernel or from a user space application. To do this, | |
149 you have to complete the following preparation steps: | |
150 | |
151 For Linux kernel coverage: | |
152 .RS | |
153 Follow the setup instructions for the gcov\-kernel infrastructure: | |
154 .I http://ltp.sourceforge.net/coverage/gcov.php | |
155 .br | |
156 | |
157 | |
158 .RE | |
159 For user space application coverage: | |
160 .RS | |
161 Compile the application with GCC using the options | |
162 "\-fprofile\-arcs" and "\-ftest\-coverage". | |
163 .RE | |
164 | |
165 Please note that this man page refers to the output format of | |
166 .B lcov | |
167 as ".info file" or "tracefile" and that the output of GCOV | |
168 is called ".da file". | |
169 .SH OPTIONS | |
170 | |
171 | |
172 .B \-a | |
173 .I tracefile | |
174 .br | |
175 .B \-\-add\-tracefile | |
176 .I tracefile | |
177 .br | |
178 .RS | |
179 Add contents of | |
180 .IR tracefile . | |
181 | |
182 Specify several tracefiles using the \-a switch to combine the coverage data | |
183 contained in these files by adding up execution counts for matching test and | |
184 filename combinations. | |
185 | |
186 The result of the add operation will be written to stdout or the tracefile | |
187 specified with \-o. | |
188 | |
189 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified | |
190 at a time. | |
191 | |
192 .RE | |
193 | |
194 .B \-b | |
195 .I directory | |
196 .br | |
197 .B \-\-base\-directory | |
198 .I directory | |
199 .br | |
200 .RS | |
201 .RI "Use " directory | |
202 as base directory for relative paths. | |
203 | |
204 Use this option to specify the base directory of a build\-environment | |
205 when lcov produces error messages like: | |
206 | |
207 .RS | |
208 ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/sub
dir2/file.c | |
209 .RE | |
210 | |
211 In this example, use /home/user/project as base directory. | |
212 | |
213 This option is required when using lcov on projects built with libtool or | |
214 similar build environments that work with a base directory, i.e. environments, | |
215 where the current working directory when invoking the compiler is not the same | |
216 directory in which the source code file is located. | |
217 | |
218 Note that this option will not work in environments where multiple base | |
219 directories are used. In that case repeat the lcov call for each base directory | |
220 while using the \-\-ignore\-errors option to prevent lcov from exiting when the | |
221 first source code file could not be found. This way you can get partial coverage | |
222 information for each base directory which can then be combined using the \-a | |
223 option. | |
224 .RE | |
225 | |
226 .B \-c | |
227 .br | |
228 .B \-\-capture | |
229 .br | |
230 .RS | |
231 Capture coverage data. | |
232 | |
233 By default captures the current kernel execution counts and writes the | |
234 resulting coverage data to the standard output. Use the \-\-directory | |
235 option to capture counts for a user space program. | |
236 | |
237 The result of the capture operation will be written to stdout or the tracefile | |
238 specified with \-o. | |
239 | |
240 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified | |
241 at a time. | |
242 .RE | |
243 | |
244 .B \-\-checksum | |
245 .br | |
246 .B \-\-no\-checksum | |
247 .br | |
248 .RS | |
249 Specify whether to generate checksum data when writing tracefiles. | |
250 | |
251 Use \-\-checksum to enable checksum generation or \-\-no\-checksum to | |
252 disable it. Checksum generation is | |
253 .B disabled | |
254 by default. | |
255 | |
256 When checksum generation is enabled, a checksum will be generated for each | |
257 source code line and stored along with the coverage data. This checksum will | |
258 be used to prevent attempts to combine coverage data from different source | |
259 code versions. | |
260 | |
261 If you don't work with different source code versions, disable this option | |
262 to speed up coverage data processing and to reduce the size of tracefiles. | |
263 .RE | |
264 | |
265 .B \-\-compat\-libtool | |
266 .br | |
267 .B \-\-no\-compat\-libtool | |
268 .br | |
269 .RS | |
270 Specify whether to enable libtool compatibility mode. | |
271 | |
272 Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-
libtool | |
273 to disable it. The libtool compatibility mode is | |
274 .B enabled | |
275 by default. | |
276 | |
277 When libtool compatibility mode is enabled, lcov will assume that the source | |
278 code relating to a .da file located in a directory named ".libs" can be | |
279 found in its parent directory. | |
280 | |
281 If you have directories named ".libs" in your build environment but don't use | |
282 libtool, disable this option to prevent problems when capturing coverage data. | |
283 .RE | |
284 | |
285 .B \-\-convert\-filenames | |
286 .br | |
287 .RS | |
288 Convert filenames when applying diff. | |
289 | |
290 Use this option together with \-\-diff to rename the file names of processed | |
291 data sets according to the data provided by the diff. | |
292 .RE | |
293 | |
294 .B \-\-diff | |
295 .I tracefile | |
296 .I difffile | |
297 .br | |
298 .RS | |
299 Convert coverage data in | |
300 .I tracefile | |
301 using source code diff file | |
302 .IR difffile . | |
303 | |
304 Use this option if you want to merge coverage data from different source code | |
305 levels of a program, e.g. when you have data taken from an older version | |
306 and want to combine it with data from a more current version. | |
307 .B lcov | |
308 will try to map source code lines between those versions and adjust the coverage | |
309 data respectively. | |
310 .I difffile | |
311 needs to be in unified format, i.e. it has to be created using the "\-u" option | |
312 of the | |
313 .B diff | |
314 tool. | |
315 | |
316 Note that lines which are not present in the old version will not be counted | |
317 as instrumented, therefore tracefiles resulting from this operation should | |
318 not be interpreted individually but together with other tracefiles taken | |
319 from the newer version. Also keep in mind that converted coverage data should | |
320 only be used for overview purposes as the process itself introduces a loss | |
321 of accuracy. | |
322 | |
323 The result of the diff operation will be written to stdout or the tracefile | |
324 specified with \-o. | |
325 | |
326 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified | |
327 at a time. | |
328 .RE | |
329 | |
330 .B \-d | |
331 .I directory | |
332 .br | |
333 .B \-\-directory | |
334 .I directory | |
335 .br | |
336 .RS | |
337 Use .da files in | |
338 .I directory | |
339 instead of kernel. | |
340 | |
341 If you want to work on coverage data for a user space program, use this | |
342 option to specify the location where the program was compiled (that's | |
343 where the counter files ending with .da will be stored). | |
344 | |
345 Note that you may specify this option more than once. | |
346 .RE | |
347 | |
348 .B \-e | |
349 .I tracefile | |
350 .I pattern | |
351 .br | |
352 .B \-\-extract | |
353 .I tracefile | |
354 .I pattern | |
355 .br | |
356 .RS | |
357 Extract data from | |
358 .IR tracefile . | |
359 | |
360 Use this switch if you want to extract coverage data for only a particular | |
361 set of files from a tracefile. Additional command line parameters will be | |
362 interpreted as shell wildcard patterns (note that they may need to be | |
363 escaped accordingly to prevent the shell from expanding them first). | |
364 Every file entry in | |
365 .I tracefile | |
366 which matches at least one of those patterns will be extracted. | |
367 | |
368 The result of the extract operation will be written to stdout or the tracefile | |
369 specified with \-o. | |
370 | |
371 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified | |
372 at a time. | |
373 .RE | |
374 | |
375 .B \-f | |
376 .br | |
377 .B \-\-follow | |
378 .br | |
379 .RS | |
380 Follow links when searching for .da files. | |
381 .RE | |
382 | |
383 .B \-\-from\-package | |
384 .I package | |
385 .br | |
386 .RS | |
387 Use .da files in | |
388 .I package | |
389 instead of kernel or directory. | |
390 | |
391 Use this option if you have separate machines for build and test and | |
392 want to perform the .info file creation on the build machine. See | |
393 \-\-to\-package for more information. | |
394 .RE | |
395 | |
396 .B \-\-gcov\-tool | |
397 .I tool | |
398 .br | |
399 .RS | |
400 Specify the location of the gcov tool. | |
401 .RE | |
402 | |
403 .B \-h | |
404 .br | |
405 .B \-\-help | |
406 .br | |
407 .RS | |
408 Print a short help text, then exit. | |
409 .RE | |
410 | |
411 .B \-\-ignore\-errors | |
412 .I errors | |
413 .br | |
414 .RS | |
415 Specify a list of errors after which to continue processing. | |
416 | |
417 Use this option to specify a list of one or more classes of errors after which | |
418 lcov should continue processing instead of aborting. | |
419 | |
420 .I errors | |
421 can be a comma\-separated list of the following keywords: | |
422 | |
423 .B gcov: | |
424 the gcov tool returned with a non\-zero return code. | |
425 | |
426 .B source: | |
427 the source code file for a data set could not be found. | |
428 .RE | |
429 | |
430 .B \-i | |
431 .br | |
432 .B \-\-initial | |
433 .RS | |
434 Capture initial zero coverage data. | |
435 | |
436 Run lcov with \-c and this option on the directories containing .bb, .bbg | |
437 or .gcno files before running any test case. The result is a "baseline" | |
438 coverage data file that contains zero coverage for every instrumented line. | |
439 Combine this data file (using lcov \-a) with coverage data files captured | |
440 after a test run to ensure that the percentage of total lines covered is | |
441 correct even when not all source code files were loaded during the test. | |
442 | |
443 Recommended procedure when capturing data for a test case: | |
444 | |
445 1. create baseline coverage data file | |
446 .RS | |
447 # lcov \-c \-i \-d appdir \-o app_base.info | |
448 .br | |
449 | |
450 .RE | |
451 2. perform test | |
452 .RS | |
453 # appdir/test | |
454 .br | |
455 | |
456 .RE | |
457 3. create test coverage data file | |
458 .RS | |
459 # lcov \-c \-d appdir \-o app_test.info | |
460 .br | |
461 | |
462 .RE | |
463 4. combine baseline and test coverage data | |
464 .RS | |
465 # lcov \-a app_base.info \-a app_test.info \-o app_total.info | |
466 .br | |
467 | |
468 .RE | |
469 .RE | |
470 | |
471 .B \-k | |
472 .I subdirectory | |
473 .br | |
474 .B \-\-kernel\-directory | |
475 .I subdirectory | |
476 .br | |
477 .RS | |
478 Capture kernel coverage data only from | |
479 .IR subdirectory . | |
480 | |
481 Use this option if you don't want to get coverage data for all of the | |
482 kernel, but only for specific subdirectories. This option may be specified | |
483 more than once. | |
484 | |
485 Note that you may need to specify the full path to the kernel subdirectory | |
486 depending on the version of the kernel gcov support. | |
487 .RE | |
488 | |
489 .B \-l | |
490 .I tracefile | |
491 .br | |
492 .B \-\-list | |
493 .I tracefile | |
494 .br | |
495 .RS | |
496 List the contents of the | |
497 .IR tracefile . | |
498 | |
499 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified | |
500 at a time. | |
501 .RE | |
502 | |
503 .B \-\-list\-full\-path | |
504 .br | |
505 .B \-\-no\-list\-full\-path | |
506 .br | |
507 .RS | |
508 Specify whether to show full paths during list operation. | |
509 | |
510 Use \-\-list\-full\-path to show full paths during list operation | |
511 or \-\-no\-list\-full\-path to show shortened paths. Paths are | |
512 .B shortened | |
513 by default. | |
514 .RE | |
515 | |
516 .B \-\-no\-markers | |
517 .br | |
518 .RS | |
519 Use this option if you want to get coverage data without regard to exclusion | |
520 markers in the source code file. See | |
521 .BR "geninfo " (1) | |
522 for details on exclusion markers. | |
523 .RE | |
524 | |
525 .B \-\-no\-recursion | |
526 .br | |
527 .RS | |
528 Use this option if you want to get coverage data for the specified directory | |
529 only without processing subdirectories. | |
530 .RE | |
531 | |
532 .B \-o | |
533 .I tracefile | |
534 .br | |
535 .B \-\-output\-file | |
536 .I tracefile | |
537 .br | |
538 .RS | |
539 Write data to | |
540 .I tracefile | |
541 instead of stdout. | |
542 | |
543 Specify "\-" as a filename to use the standard output. | |
544 | |
545 By convention, lcov\-generated coverage data files are called "tracefiles" and | |
546 should have the filename extension ".info". | |
547 .RE | |
548 | |
549 .B \-\-path | |
550 .I path | |
551 .br | |
552 .RS | |
553 Strip path from filenames when applying diff. | |
554 | |
555 Use this option together with \-\-diff to tell lcov to disregard the specified | |
556 initial path component when matching between tracefile and diff filenames. | |
557 .RE | |
558 | |
559 .B \-q | |
560 .br | |
561 .B \-\-quiet | |
562 .br | |
563 .RS | |
564 Do not print progress messages. | |
565 | |
566 This option is implied when no output filename is specified to prevent | |
567 progress messages to mess with coverage data which is also printed to | |
568 the standard output. | |
569 .RE | |
570 | |
571 .B \-r | |
572 .I tracefile | |
573 .I pattern | |
574 .br | |
575 .B \-\-remove | |
576 .I tracefile | |
577 .I pattern | |
578 .br | |
579 .RS | |
580 Remove data from | |
581 .IR tracefile . | |
582 | |
583 Use this switch if you want to remove coverage data for a particular | |
584 set of files from a tracefile. Additional command line parameters will be | |
585 interpreted as shell wildcard patterns (note that they may need to be | |
586 escaped accordingly to prevent the shell from expanding them first). | |
587 Every file entry in | |
588 .I tracefile | |
589 which matches at least one of those patterns will be removed. | |
590 | |
591 The result of the remove operation will be written to stdout or the tracefile | |
592 specified with \-o. | |
593 | |
594 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified | |
595 at a time. | |
596 .RE | |
597 | |
598 .B \-\-strip | |
599 .I depth | |
600 .br | |
601 .RS | |
602 Strip path components when applying diff. | |
603 | |
604 Use this option together with \-\-diff to tell lcov to disregard the specified | |
605 number of initial directories when matching tracefile and diff filenames. | |
606 .RE | |
607 | |
608 .B \-t | |
609 .I testname | |
610 .br | |
611 .B \-\-test\-name | |
612 .I testname | |
613 .br | |
614 .RS | |
615 Specify test name to be stored in the tracefile. | |
616 | |
617 This name identifies a coverage data set when more than one data set is merged | |
618 into a combined tracefile (see option \-a). | |
619 | |
620 Valid test names can consist of letters, decimal digits and the underscore | |
621 character ("_"). | |
622 .RE | |
623 | |
624 .B \-\-to\-package | |
625 .I package | |
626 .br | |
627 .RS | |
628 Store .da files for later processing. | |
629 | |
630 Use this option if you have separate machines for build and test and | |
631 want to perform the .info file creation on the build machine. To do this, | |
632 follow these steps: | |
633 | |
634 On the test machine: | |
635 .RS | |
636 .br | |
637 \- run the test | |
638 .br | |
639 \- run lcov \-c [\-d directory] \-\-to-package | |
640 .I file | |
641 .br | |
642 \- copy | |
643 .I file | |
644 to the build machine | |
645 .RE | |
646 .br | |
647 | |
648 On the build machine: | |
649 .RS | |
650 .br | |
651 \- run lcov \-c \-\-from-package | |
652 .I file | |
653 [\-o and other options] | |
654 .RE | |
655 .br | |
656 | |
657 This works for both kernel and user space coverage data. Note that you might | |
658 have to specify the path to the build directory using \-b with | |
659 either \-\-to\-package or \-\-from-package. Note also that the package data | |
660 must be converted to a .info file before recompiling the program or it will | |
661 become invalid. | |
662 .RE | |
663 | |
664 .B \-v | |
665 .br | |
666 .B \-\-version | |
667 .br | |
668 .RS | |
669 Print version number, then exit. | |
670 .RE | |
671 | |
672 .B \-z | |
673 .br | |
674 .B \-\-zerocounters | |
675 .br | |
676 .RS | |
677 Reset all execution counts to zero. | |
678 | |
679 By default tries to reset kernel execution counts. Use the \-\-directory | |
680 option to reset all counters of a user space program. | |
681 | |
682 Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified | |
683 at a time. | |
684 .RE | |
685 | |
686 .SH FILES | |
687 | |
688 .I /etc/lcovrc | |
689 .RS | |
690 The system\-wide configuration file. | |
691 .RE | |
692 | |
693 .I ~/.lcovrc | |
694 .RS | |
695 The per\-user configuration file. | |
696 .RE | |
697 | |
698 .SH AUTHOR | |
699 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> | |
700 | |
701 .SH SEE ALSO | |
702 .BR lcovrc (5), | |
703 .BR genhtml (1), | |
704 .BR geninfo (1), | |
705 .BR genpng (1), | |
706 .BR gendesc (1), | |
707 .BR gcov (1) | |
OLD | NEW |