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