Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(8)

Side by Side Diff: third_party/lcov-1.9/man/lcov.1

Issue 23189008: Upgrades lcov to 1.10, removes lcov-1.9 (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Re-adds UNKNOWN suppression Created 7 years, 4 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « third_party/lcov-1.9/man/genpng.1 ('k') | third_party/lcov-1.9/man/lcovrc.5 » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(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)
OLDNEW
« no previous file with comments | « third_party/lcov-1.9/man/genpng.1 ('k') | third_party/lcov-1.9/man/lcovrc.5 » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698