1lcov(1) User Manuals lcov(1)
2
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 lcov -z|--zerocounters
22 [-d|--directory directory] [--no-recursion] [-f|--follow]
23 [-q|--quiet]
24 lcov -l|--list tracefile
26 [-q|--quiet] [--list-full-path] [--no-list-full-path]
27 [--config-file config-file] [--rc keyword=value]
28 lcov -a|--add-tracefile tracefile
30 [-o|--output-file tracefile] [--checksum] [--no-checksum]
31 [-q|--quiet] [--config-file config-file] [--rc keyword=value]
32 lcov -e|--extract tracefile pattern
34 [-o|--output-file tracefile] [--checksum] [--no-checksum]
35 [-q|--quiet] [--config-file config-file] [--rc keyword=value]
36 lcov -r|--remove tracefile pattern
38 [-o|--output-file tracefile] [--checksum] [--no-checksum]
39 [-q|--quiet] [--config-file config-file] [--rc keyword=value]
40 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 lcov --summary tracefile
47 [-q|--quiet]
48 lcov [-h|--help] [-v|--version]
50
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 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 For Linux kernel coverage:
65 Follow the setup instructions for the gcov-kernel infrastruc‐
66 ture: http://ltp.sourceforge.net/coverage/gcov.php
67 For user space application coverage:
70 Compile the application with GCC using the options "-fpro‐
71 file-arcs" and "-ftest-coverage".
72 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 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
85 -a tracefile
86 --add-tracefile tracefile
87 Add contents of tracefile.
88 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 The result of the add operation will be written to stdout or the
94 tracefile specified with -o.
95 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
97 specified at a time.
98 -b directory
101 --base-directory directory
102 Use directory as base directory for relative paths.
103 Use this option to specify the base directory of a build-envi‐
105 ronment when lcov produces error messages like:
106 ERROR: could not read source file /home/user/project/sub‐
108 dir1/subdir2/subdir1/subdir2/file.c
109 In this example, use /home/user/project as base directory.
111 This option is required when using lcov on projects built with
113 libtool or similar build environments that work with a base di‐
114 rectory, i.e. environments, where the current working directory
115 when invoking the compiler is not the same directory in which
116 the source code file is located.
117 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 -c
123 --capture
124 Capture coverage data.
125 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 The result of the capture operation will be written to stdout or
132 the tracefile specified with -o.
133 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
135 specified at a time.
136 --checksum
138 --no-checksum
139 Specify whether to generate checksum data when writing trace‐
140 files.
141 Use --checksum to enable checksum generation or --no-checksum to
143 disable it. Checksum generation is disabled by default.
144 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 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 --compat mode=value[,mode=value,...]
155 Set compatibility mode.
156 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 Valid values are:
163 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 If no value is specified, 'on' is assumed as default value.
174 Valid modes are:
176 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 The default value for this setting is 'on'.
183 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 The default value for this setting is 'auto'.
194 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 The default value for this setting is 'auto'
204 --compat-libtool
207 --no-compat-libtool
208 Specify whether to enable libtool compatibility mode.
209 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 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 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 --config-file config-file
223 Specify a configuration file to use.
224 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 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 --convert-filenames
234 Convert filenames when applying diff.
235 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 --diff tracefile difffile
240 Convert coverage data in tracefile using source code diff file
241 difffile.
242 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 re‐
248 spectively. difffile needs to be in unified format, i.e. it has
249 to be created using the "-u" option of the diff tool.
250 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 The result of the diff operation will be written to stdout or
260 the tracefile specified with -o.
261 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
263 specified at a time.
264 -d directory
266 --directory directory
267 Use .da files in directory instead of kernel.
268 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 Note that you may specify this option more than once.
275 --exclude pattern
277 Exclude source files matching pattern.
278 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 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 --external
291 --no-external
292 Specify whether to capture coverage data for external source
293 files.
294 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 Data for external source files is included by default.
301 -e tracefile pattern
303 --extract tracefile pattern
304 Extract data from tracefile.
305 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 The result of the extract operation will be written to stdout or
315 the tracefile specified with -o.
316 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
318 specified at a time.
319 -f
321 --follow
322 Follow links when searching for .da files.
323 --from-package package
325 Use .da files in package instead of kernel or directory.
326 Use this option if you have separate machines for build and test
328 and want to perform the .info file creation on the build ma‐
329 chine. See --to-package for more information.
330 --gcov-tool tool
332 Specify the location of the gcov tool.
333 -h
335 --help
336 Print a short help text, then exit.
337 --include pattern
339 Include source files matching pattern.
340 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 --ignore-errors errors
350 Specify a list of errors after which to continue processing.
351 Use this option to specify a list of one or more classes of er‐
353 rors after which lcov should continue processing instead of
354 aborting.
355 errors can be a comma-separated list of the following keywords:
357 gcov: the gcov tool returned with a non-zero return code.
359 source: the source code file for a data set could not be found.
361 graph: the graph file could not be found or is corrupted.
363 -i
365 --initial
366 Capture initial zero coverage data.
367 Run lcov with -c and this option on the directories containing
369 .bb, .bbg or .gcno files before running any test case. The re‐
370 sult is a "baseline" coverage data file that contains zero cov‐
371 erage for every instrumented line. Combine this data file (us‐
372 ing lcov -a) with coverage data files captured after a test run
373 to ensure that the percentage of total lines covered is correct
374 even when not all source code files were loaded during the test.
375 Recommended procedure when capturing data for a test case:
377 1. create baseline coverage data file
379 # lcov -c -i -d appdir -o app_base.info
380 2. perform test
382 # appdir/test
383 3. create test coverage data file
385 # lcov -c -d appdir -o app_test.info
386 4. combine baseline and test coverage data
388 # lcov -a app_base.info -a app_test.info -o app_to‐
389 tal.info
390 -k subdirectory
393 --kernel-directory subdirectory
394 Capture kernel coverage data only from subdirectory.
395 Use this option if you don't want to get coverage data for all
397 of the kernel, but only for specific subdirectories. This option
398 may be specified more than once.
399 Note that you may need to specify the full path to the kernel
401 subdirectory depending on the version of the kernel gcov sup‐
402 port.
403 -l tracefile
405 --list tracefile
406 List the contents of the tracefile.
407 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
409 specified at a time.
410 --list-full-path
412 --no-list-full-path
413 Specify whether to show full paths during list operation.
414 Use --list-full-path to show full paths during list operation or
416 --no-list-full-path to show shortened paths. Paths are shortened
417 by default.
418 --no-markers
420 Use this option if you want to get coverage data without regard
421 to exclusion markers in the source code file. See geninfo (1)
422 for details on exclusion markers.
423 --no-recursion
425 Use this option if you want to get coverage data for the speci‐
426 fied directory only without processing subdirectories.
427 -o tracefile
429 --output-file tracefile
430 Write data to tracefile instead of stdout.
431 Specify "-" as a filename to use the standard output.
433 By convention, lcov-generated coverage data files are called
435 "tracefiles" and should have the filename extension ".info".
436 --path path
438 Strip path from filenames when applying diff.
439 Use this option together with --diff to tell lcov to disregard
441 the specified initial path component when matching between
442 tracefile and diff filenames.
443 -q
445 --quiet
446 Do not print progress messages.
447 This option is implied when no output filename is specified to
449 prevent progress messages to mess with coverage data which is
450 also printed to the standard output.
451 --rc keyword=value
453 Override a configuration directive.
454 Use this option to specify a keyword=value statement which over‐
456 rides the corresponding configuration statement in the lcovrc
457 configuration file. You can specify this option more than once
458 to override multiple configuration statements. See lcovrc(5)
459 for a list of available keywords and their meaning.
460 -r tracefile pattern
462 --remove tracefile pattern
463 Remove data from tracefile.
464 Use this switch if you want to remove coverage data for a par‐
466 ticular set of files from a tracefile. Additional command line
467 parameters will be interpreted as shell wildcard patterns (note
468 that they may need to be escaped accordingly to prevent the
469 shell from expanding them first). Every file entry in tracefile
470 which matches at least one of those patterns will be removed.
471 The result of the remove operation will be written to stdout or
473 the tracefile specified with -o.
474 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
476 specified at a time.
477 --strip depth
479 Strip path components when applying diff.
480 Use this option together with --diff to tell lcov to disregard
482 the specified number of initial directories when matching trace‐
483 file and diff filenames.
484 --summary tracefile
486 Show summary coverage information for the specified tracefile.
487 Note that you may specify this option more than once.
489 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
491 specified at a time.
492 -t testname
494 --test-name testname
495 Specify test name to be stored in the tracefile.
496 This name identifies a coverage data set when more than one data
498 set is merged into a combined tracefile (see option -a).
499 Valid test names can consist of letters, decimal digits and the
501 underscore character ("_").
502 --to-package package
504 Store .da files for later processing.
505 Use this option if you have separate machines for build and test
507 and want to perform the .info file creation on the build ma‐
508 chine. To do this, follow these steps:
509 On the test machine:
511 - run the test
512 - run lcov -c [-d directory] --to-package file
513 - copy file to the build machine
514 On the build machine:
516 - run lcov -c --from-package file [-o and other options]
517 This works for both kernel and user space coverage data. Note
519 that you might have to specify the path to the build directory
520 using -b with either --to-package or --from-package. Note also
521 that the package data must be converted to a .info file before
522 recompiling the program or it will become invalid.
523 -v
525 --version
526 Print version number, then exit.
527 -z
529 --zerocounters
530 Reset all execution counts to zero.
531 By default tries to reset kernel execution counts. Use the --di‐
533 rectory option to reset all counters of a user space program.
534 Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be
536 specified at a time.
537
540 /etc/lcovrc
541 The system-wide configuration file.
542 ~/.lcovrc
544 The per-user configuration file.
545
548 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
549
552 lcovrc(5), genhtml(1), geninfo(1), genpng(1), gendesc(1), gcov(1)
5532023-01-19 LCOV 1.14 lcov(1)