1lcov(1) User Manuals lcov(1)
2
3
4
6 lcov - a graphical GCOV front-end
7
9 lcov -c|--capture
10 [-d|--directory directory] [-k|--kernel-directory directory]
11 [-o|--output-file tracefile] [-t|--test-name testname]
12 [-b|--base-directory directory] [-i|--initial] [--gcov-tool tool]
13 [--checksum] [--no-checksum] [--no-recursion] [-f|--follow]
14 [--compat-libtool] [--no-compat-libtool] [--ignore-errors errors]
15 [--to-package package] [--from-package package] [-q|--quiet]
16 [--no-markers] [--external] [--no-external]
17 [--config-file config-file] [--rc keyword=value]
18 [--compat mode=on|off|auto]
19 [--include pattern] [--exclude pattern]
20
21 lcov -z|--zerocounters
22 [-d|--directory directory] [--no-recursion] [-f|--follow]
23 [-q|--quiet]
24
25 lcov -l|--list tracefile
26 [-q|--quiet] [--list-full-path] [--no-list-full-path]
27 [--config-file config-file] [--rc keyword=value]
28
29 lcov -a|--add-tracefile tracefile
30 [-o|--output-file tracefile] [--checksum] [--no-checksum]
31 [-q|--quiet] [--config-file config-file] [--rc keyword=value]
32
33 lcov -e|--extract tracefile pattern
34 [-o|--output-file tracefile] [--checksum] [--no-checksum]
35 [-q|--quiet] [--config-file config-file] [--rc keyword=value]
36
37 lcov -r|--remove tracefile pattern
38 [-o|--output-file tracefile] [--checksum] [--no-checksum]
39 [-q|--quiet] [--config-file config-file] [--rc keyword=value]
40
41 lcov --diff tracefile diff
42 [-o|--output-file tracefile] [--checksum] [--no-checksum]
43 [--convert-filenames] [--strip depth] [--path path] [-q|--quiet]
44 [--config-file config-file] [--rc keyword=value]
45
46 lcov --summary tracefile
47 [-q|--quiet]
48
49 lcov [-h|--help] [-v|--version]
50
51
53 lcov is a graphical front-end for GCC's coverage testing tool gcov. It
54 collects line, function and branch coverage data for multiple source
55 files and creates HTML pages containing the source code annotated with
56 coverage information. It also adds overview pages for easy navigation
57 within the file structure.
58
59 Use lcov to collect coverage data and genhtml to create HTML pages.
60 Coverage data can either be collected from the currently running Linux
61 kernel or from a user space application. To do this, you have to com‐
62 plete the following preparation steps:
63
64 For Linux kernel coverage:
65 Follow the setup instructions for the gcov-kernel infrastruc‐
66 ture: http://ltp.sourceforge.net/coverage/gcov.php
67
68
69 For user space application coverage:
70 Compile the application with GCC using the options "-fpro‐
71 file-arcs" and "-ftest-coverage".
72
73 Please note that this man page refers to the output format of lcov as
74 ".info file" or "tracefile" and that the output of GCOV is called ".da
75 file".
76
77 Also note that when printing percentages, 0% and 100% are only printed
78 when the values are exactly 0% and 100% respectively. Other values
79 which would conventionally be rounded to 0% or 100% are instead printed
80 as nearest non-boundary value. This behavior is in accordance with that
81 of the gcov(1) tool.
82
83
85 -a tracefile
86 --add-tracefile tracefile
87 Add contents of tracefile.
88
89 Specify several tracefiles using the -a switch to combine the
90 coverage data contained in these files by adding up execution
91 counts for matching test and filename combinations.
92
93 The result of the add operation will be written to stdout or the
94 tracefile specified with -o.
95
96 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
97 specified at a time.
98
99
100 -b directory
101 --base-directory directory
102 Use directory as base directory for relative paths.
103
104 Use this option to specify the base directory of a build-envi‐
105 ronment when lcov produces error messages like:
106
107 ERROR: could not read source file /home/user/project/sub‐
108 dir1/subdir2/subdir1/subdir2/file.c
109
110 In this example, use /home/user/project as base directory.
111
112 This option is required when using lcov on projects built with
113 libtool or similar build environments that work with a base
114 directory, i.e. environments, where the current working direc‐
115 tory when invoking the compiler is not the same directory in
116 which the source code file is located.
117
118 Note that this option will not work in environments where multi‐
119 ple base directories are used. In that case use configuration
120 file setting geninfo_auto_base=1 (see lcovrc(5)).
121
122 -c
123 --capture
124 Capture coverage data.
125
126 By default captures the current kernel execution counts and
127 writes the resulting coverage data to the standard output. Use
128 the --directory option to capture counts for a user space pro‐
129 gram.
130
131 The result of the capture operation will be written to stdout or
132 the tracefile specified with -o.
133
134 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
135 specified at a time.
136
137 --checksum
138 --no-checksum
139 Specify whether to generate checksum data when writing trace‐
140 files.
141
142 Use --checksum to enable checksum generation or --no-checksum to
143 disable it. Checksum generation is disabled by default.
144
145 When checksum generation is enabled, a checksum will be gener‐
146 ated for each source code line and stored along with the cover‐
147 age data. This checksum will be used to prevent attempts to com‐
148 bine coverage data from different source code versions.
149
150 If you don't work with different source code versions, disable
151 this option to speed up coverage data processing and to reduce
152 the size of tracefiles.
153
154 --compat mode=value[,mode=value,...]
155 Set compatibility mode.
156
157 Use --compat to specify that lcov should enable one or more com‐
158 patibility modes when capturing coverage data. You can provide a
159 comma-separated list of mode=value pairs to specify the values
160 for multiple modes.
161
162 Valid values are:
163
164 on
165 Enable compatibility mode.
166 off
167 Disable compatibility mode.
168 auto
169 Apply auto-detection to determine if compatibility mode
170 is required. Note that auto-detection is not available
171 for all compatibility modes.
172
173 If no value is specified, 'on' is assumed as default value.
174
175 Valid modes are:
176
177 libtool
178 Enable this mode if you are capturing coverage data for a
179 project that was built using the libtool mechanism. See
180 also --compat-libtool.
181
182 The default value for this setting is 'on'.
183
184 hammer
185 Enable this mode if you are capturing coverage data for a
186 project that was built using a version of GCC 3.3 that
187 contains a modification (hammer patch) of later GCC ver‐
188 sions. You can identify a modified GCC 3.3 by checking
189 the build directory of your project for files ending in
190 the extension '.bbg'. Unmodified versions of GCC 3.3 name
191 these files '.bb'.
192
193 The default value for this setting is 'auto'.
194
195 split_crc
196 Enable this mode if you are capturing coverage data for a
197 project that was built using a version of GCC 4.6 that
198 contains a modification (split function checksums) of
199 later GCC versions. Typical error messages when running
200 lcov on coverage data produced by such GCC versions are
201 ´out of memory' and 'reached unexpected end of file'.
202
203 The default value for this setting is 'auto'
204
205
206 --compat-libtool
207 --no-compat-libtool
208 Specify whether to enable libtool compatibility mode.
209
210 Use --compat-libtool to enable libtool compatibility mode or
211 --no-compat-libtool to disable it. The libtool compatibility
212 mode is enabled by default.
213
214 When libtool compatibility mode is enabled, lcov will assume
215 that the source code relating to a .da file located in a direc‐
216 tory named ".libs" can be found in its parent directory.
217
218 If you have directories named ".libs" in your build environment
219 but don't use libtool, disable this option to prevent problems
220 when capturing coverage data.
221
222 --config-file config-file
223 Specify a configuration file to use.
224
225 When this option is specified, neither the system-wide configu‐
226 ration file /etc/lcovrc, nor the per-user configuration file
227 ~/.lcovrc is read.
228
229 This option may be useful when there is a need to run several
230 instances of lcov with different configuration file options in
231 parallel.
232
233 --convert-filenames
234 Convert filenames when applying diff.
235
236 Use this option together with --diff to rename the file names of
237 processed data sets according to the data provided by the diff.
238
239 --diff tracefile difffile
240 Convert coverage data in tracefile using source code diff file
241 difffile.
242
243 Use this option if you want to merge coverage data from differ‐
244 ent source code levels of a program, e.g. when you have data
245 taken from an older version and want to combine it with data
246 from a more current version. lcov will try to map source code
247 lines between those versions and adjust the coverage data
248 respectively. difffile needs to be in unified format, i.e. it
249 has to be created using the "-u" option of the diff tool.
250
251 Note that lines which are not present in the old version will
252 not be counted as instrumented, therefore tracefiles resulting
253 from this operation should not be interpreted individually but
254 together with other tracefiles taken from the newer version.
255 Also keep in mind that converted coverage data should only be
256 used for overview purposes as the process itself introduces a
257 loss of accuracy.
258
259 The result of the diff operation will be written to stdout or
260 the tracefile specified with -o.
261
262 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
263 specified at a time.
264
265 -d directory
266 --directory directory
267 Use .da files in directory instead of kernel.
268
269 If you want to work on coverage data for a user space program,
270 use this option to specify the location where the program was
271 compiled (that's where the counter files ending with .da will be
272 stored).
273
274 Note that you may specify this option more than once.
275
276 --exclude pattern
277 Exclude source files matching pattern.
278
279 Use this switch if you want to exclude coverage data for a par‐
280 ticular set of source files matching any of the given patterns.
281 Multiple patterns can be specified by using multiple --exclude
282 command line switches. The patterns will be interpreted as shell
283 wildcard patterns (note that they may need to be escaped accord‐
284 ingly to prevent the shell from expanding them first).
285
286 Can be combined with the --include command line switch. If a
287 given file matches both the include pattern and the exclude pat‐
288 tern, the exclude pattern will take precedence.
289
290 --external
291 --no-external
292 Specify whether to capture coverage data for external source
293 files.
294
295 External source files are files which are not located in one of
296 the directories specified by --directory or --base-directory.
297 Use --external to include external source files while capturing
298 coverage data or --no-external to ignore this data.
299
300 Data for external source files is included by default.
301
302 -e tracefile pattern
303 --extract tracefile pattern
304 Extract data from tracefile.
305
306 Use this switch if you want to extract coverage data for only a
307 particular set of files from a tracefile. Additional command
308 line parameters will be interpreted as shell wildcard patterns
309 (note that they may need to be escaped accordingly to prevent
310 the shell from expanding them first). Every file entry in
311 tracefile which matches at least one of those patterns will be
312 extracted.
313
314 The result of the extract operation will be written to stdout or
315 the tracefile specified with -o.
316
317 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
318 specified at a time.
319
320 -f
321 --follow
322 Follow links when searching for .da files.
323
324 --from-package package
325 Use .da files in package instead of kernel or directory.
326
327 Use this option if you have separate machines for build and test
328 and want to perform the .info file creation on the build
329 machine. See --to-package for more information.
330
331 --gcov-tool tool
332 Specify the location of the gcov tool.
333
334 -h
335 --help
336 Print a short help text, then exit.
337
338 --include pattern
339 Include source files matching pattern.
340
341 Use this switch if you want to include coverage data for only a
342 particular set of source files matching any of the given pat‐
343 terns. Multiple patterns can be specified by using multiple
344 --include command line switches. The patterns will be inter‐
345 preted as shell wildcard patterns (note that they may need to be
346 escaped accordingly to prevent the shell from expanding them
347 first).
348
349 --ignore-errors errors
350 Specify a list of errors after which to continue processing.
351
352 Use this option to specify a list of one or more classes of
353 errors after which lcov should continue processing instead of
354 aborting.
355
356 errors can be a comma-separated list of the following keywords:
357
358 gcov: the gcov tool returned with a non-zero return code.
359
360 source: the source code file for a data set could not be found.
361
362 graph: the graph file could not be found or is corrupted.
363
364 -i
365 --initial
366 Capture initial zero coverage data.
367
368 Run lcov with -c and this option on the directories containing
369 .bb, .bbg or .gcno files before running any test case. The
370 result is a "baseline" coverage data file that contains zero
371 coverage for every instrumented line. Combine this data file
372 (using lcov -a) with coverage data files captured after a test
373 run to ensure that the percentage of total lines covered is cor‐
374 rect even when not all source code files were loaded during the
375 test.
376
377 Recommended procedure when capturing data for a test case:
378
379 1. create baseline coverage data file
380 # lcov -c -i -d appdir -o app_base.info
381
382 2. perform test
383 # appdir/test
384
385 3. create test coverage data file
386 # lcov -c -d appdir -o app_test.info
387
388 4. combine baseline and test coverage data
389 # lcov -a app_base.info -a app_test.info -o
390 app_total.info
391
392
393 -k subdirectory
394 --kernel-directory subdirectory
395 Capture kernel coverage data only from subdirectory.
396
397 Use this option if you don't want to get coverage data for all
398 of the kernel, but only for specific subdirectories. This option
399 may be specified more than once.
400
401 Note that you may need to specify the full path to the kernel
402 subdirectory depending on the version of the kernel gcov sup‐
403 port.
404
405 -l tracefile
406 --list tracefile
407 List the contents of the tracefile.
408
409 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
410 specified at a time.
411
412 --list-full-path
413 --no-list-full-path
414 Specify whether to show full paths during list operation.
415
416 Use --list-full-path to show full paths during list operation or
417 --no-list-full-path to show shortened paths. Paths are shortened
418 by default.
419
420 --no-markers
421 Use this option if you want to get coverage data without regard
422 to exclusion markers in the source code file. See geninfo [22m(1)
423 for details on exclusion markers.
424
425 --no-recursion
426 Use this option if you want to get coverage data for the speci‐
427 fied directory only without processing subdirectories.
428
429 -o tracefile
430 --output-file tracefile
431 Write data to tracefile instead of stdout.
432
433 Specify "-" as a filename to use the standard output.
434
435 By convention, lcov-generated coverage data files are called
436 "tracefiles" and should have the filename extension ".info".
437
438 --path path
439 Strip path from filenames when applying diff.
440
441 Use this option together with --diff to tell lcov to disregard
442 the specified initial path component when matching between
443 tracefile and diff filenames.
444
445 -q
446 --quiet
447 Do not print progress messages.
448
449 This option is implied when no output filename is specified to
450 prevent progress messages to mess with coverage data which is
451 also printed to the standard output.
452
453 --rc keyword=value
454 Override a configuration directive.
455
456 Use this option to specify a keyword=value statement which over‐
457 rides the corresponding configuration statement in the lcovrc
458 configuration file. You can specify this option more than once
459 to override multiple configuration statements. See lcovrc(5)
460 for a list of available keywords and their meaning.
461
462 -r tracefile pattern
463 --remove tracefile pattern
464 Remove data from tracefile.
465
466 Use this switch if you want to remove coverage data for a par‐
467 ticular set of files from a tracefile. Additional command line
468 parameters will be interpreted as shell wildcard patterns (note
469 that they may need to be escaped accordingly to prevent the
470 shell from expanding them first). Every file entry in tracefile
471 which matches at least one of those patterns will be removed.
472
473 The result of the remove operation will be written to stdout or
474 the tracefile specified with -o.
475
476 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
477 specified at a time.
478
479 --strip depth
480 Strip path components when applying diff.
481
482 Use this option together with --diff to tell lcov to disregard
483 the specified number of initial directories when matching trace‐
484 file and diff filenames.
485
486 --summary tracefile
487 Show summary coverage information for the specified tracefile.
488
489 Note that you may specify this option more than once.
490
491 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
492 specified at a time.
493
494 -t testname
495 --test-name testname
496 Specify test name to be stored in the tracefile.
497
498 This name identifies a coverage data set when more than one data
499 set is merged into a combined tracefile (see option -a).
500
501 Valid test names can consist of letters, decimal digits and the
502 underscore character ("_").
503
504 --to-package package
505 Store .da files for later processing.
506
507 Use this option if you have separate machines for build and test
508 and want to perform the .info file creation on the build
509 machine. To do this, follow these steps:
510
511 On the test machine:
512 - run the test
513 - run lcov -c [-d directory] --to-package file
514 - copy file to the build machine
515
516 On the build machine:
517 - run lcov -c --from-package file [-o and other options]
518
519 This works for both kernel and user space coverage data. Note
520 that you might have to specify the path to the build directory
521 using -b with either --to-package or --from-package. Note also
522 that the package data must be converted to a .info file before
523 recompiling the program or it will become invalid.
524
525 -v
526 --version
527 Print version number, then exit.
528
529 -z
530 --zerocounters
531 Reset all execution counts to zero.
532
533 By default tries to reset kernel execution counts. Use the
534 --directory option to reset all counters of a user space pro‐
535 gram.
536
537 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
538 specified at a time.
539
540
542 /etc/lcovrc
543 The system-wide configuration file.
544
545 ~/.lcovrc
546 The per-user configuration file.
547
548
550 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
551
552
554 lcovrc(5), genhtml(1), geninfo(1), genpng(1), gendesc(1), gcov(1)
555
556
557
5582020-07-28 LCOV 1.14 lcov(1)