1lcov(1) User Manuals lcov(1)
2
6 lcov - GCOV coverage tool extension
7
9 lcov [-h|--help] [-v|--version] [-q|--quiet]
10 [-z|--zerocounters] [-c|--capture]
11 [-a|--add-tracefile tracefile]
12 [-e|--extract tracefile]
13 [-r|--remove tracefile]
14 [-l|--list tracefile]
15 [--diff tracefile diff]
16 [-i|--initial] [-t|--test-name testname]
17 [-o|--output-file filename]
18 [-d|--directory directory]
19 [-f|--follow]
20 [-k|--kernel-directory directory]
21 [-b|--base-directory directory]
22 [--convert-filenames] [--strip depth] [--path path]
23 [--checksum] [--no-checksum]
24 [--compat-libtool] [--no-compat-libtool]
25 [--gcov-tool tool] [--ignore-errors errors]
26
28 lcov is an extension of GCOV, a GNU tool which provides information
29 about what parts of a program are actually executed (i.e. "covered")
30 during a particular test case. The extension consists of a set of PERL
31 scripts which build on the textual GCOV output to implement HTML output
32 and support for large projects.
33 Use lcov to collect coverage data from either the currently running
35 Linux kernel or from a user space application. To do this, you have to
36 complete the following preparation steps:
37 For Linux kernel coverage:
39 Download and install the "gcov-kernel" package from
40 http://sourceforge.net/projects/ltp
41 The resulting kernel module has to be installed either in the
43 system wide kernel modules directory or in the same directory as
44 the LCOV tool. Note that you will need root privileges to
45 access kernel coverage data.
46 For user space application coverage:
48 Compile the application with GCC using the options "-fpro‐
49 file-arcs" and "-ftest-coverage".
50 Please note that this man page refers to the output format of lcov as
52 ".info file" or "tracefile" and that the output of GCOV is called ".da
53 file".
54
56 -a tracefile
57 --add-tracefile tracefile
58 Add contents of tracefile.
59 Specify several tracefiles using the -a switch to combine the
61 coverage data contained in these files by adding up execution
62 counts for matching test and filename combinations.
63 The result of the add operation will be written to stdout or the
65 tracefile specified with -o.
66 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
68 at a time.
69 -b directory
72 --base-directory directory
73 Use directory as base directory for relative paths.
74 Use this option to specify the base directory of a build-envi‐
76 ronment when lcov produces error messages like:
77 ERROR: could not read source file /home/user/project/sub‐
79 dir1/subdir2/subdir1/subdir2/file.c
80 In this example, use /home/user/project as base directory.
82 This option is required when using lcov on projects built with
84 libtool or similar build environments that work with a base
85 directory, i.e. environments, where the current working direc‐
86 tory when invoking the compiler is not the same directory in
87 which the source code file is located.
88 Note that this option will not work in environments where multi‐
90 ple base directories are used. In that case repeat the lcov call
91 for each base directory while using the --ignore-errors option
92 to prevent lcov from exiting when the first source code file
93 could not be found. This way you can get partial coverage infor‐
94 mation for each base directory which can then be combined using
95 the -a option.
96 -c
98 --capture
99 Capture coverage data.
100 By default captures the current kernel execution counts and
102 writes the resulting coverage data to the standard output. Use
103 the --directory option to capture counts for a user space pro‐
104 gram.
105 The result of the capture operation will be written to stdout or
107 the tracefile specified with -o.
108 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
110 at a time.
111 --checksum
113 --no-checksum
114 Specify whether to generate checksum data when writing trace‐
115 files.
116 Use --checksum to enable checksum generation or --no-checksum to
118 disable it. Checksum generation is disabled by default.
119 When checksum generation is enabled, a checksum will be gener‐
121 ated for each source code line and stored along with the cover‐
122 age data. This checksum will be used to prevent attempts to com‐
123 bine coverage data from different source code versions.
124 If you don't work with different source code versions, disable
126 this option to speed up coverage data processing and to reduce
127 the size of tracefiles.
128 --compat-libtool
130 --no-compat-libtool
131 Specify whether to enable libtool compatibility mode.
132 Use --compat-libtool to enable libtool compatibility mode or
134 --no-compat-libtool to disable it. The libtool compatibility
135 mode is enabled by default.
136 When libtool compatibility mode is enabled, lcov will assume
138 that the source code relating to a .da file located in a direc‐
139 tory named ".libs" can be found in its parent directory.
140 If you have directories named ".libs" in your build environment
142 but don't use libtool, disable this option to prevent problems
143 when capturing coverage data.
144 --convert-filenames
146 Convert filenames when applying diff.
147 Use this option together with --diff to rename the file names of
149 processed data sets according to the data provided by the diff.
150 --diff tracefile difffile
152 Convert coverage data in tracefile using source code diff file
153 difffile.
154 Use this option if you want to merge coverage data from differ‐
156 ent source code levels of a program, e.g. when you have data
157 taken from an older version and want to combine it with data
158 from a more current version. lcov will try to map source code
159 lines between those versions and adjust the coverage data
160 respectively. difffile needs to be in unified format, i.e. it
161 has to be created using the "-u" option of the diff tool.
162 Note that lines which are not present in the old version will
164 not be counted as instrumented, therefore tracefiles resulting
165 from this operation should not be interpreted individually but
166 together with other tracefiles taken from the newer version.
167 Also keep in mind that converted coverage data should only be
168 used for overview purposes as the process itself introduces a
169 loss of accuracy.
170 The result of the diff operation will be written to stdout or
172 the tracefile specified with -o.
173 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
175 at a time.
176 -d directory
178 --directory directory
179 Use .da files in directory instead of kernel.
180 If you want to work on coverage data for a user space program,
182 use this option to specify the location where the program was
183 compiled (that's where the counter files ending with .da will be
184 stored).
185 Note that you may specify this option more than once.
187 -e tracefile pattern
189 --extract tracefile pattern
190 Extract data from tracefile.
191 Use this switch if you want to extract coverage data for only a
193 particular set of files from a tracefile. Additional command
194 line parameters will be interpreted as shell wildcard patterns
195 (note that they may need to be escaped accordingly to prevent
196 the shell from expanding them first). Every file entry in
197 tracefile which matches at least one of those patterns will be
198 extracted.
199 The result of the extract operation will be written to stdout or
201 the tracefile specified with -o.
202 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
204 at a time.
205 -f
207 --follow
208 Follow links when searching for .da files.
209 --gcov-tool tool
211 Specify the location of the gcov tool.
212 -h
214 --help
215 Print a short help text, then exit.
216 --ignore-errors errors
218 Specify a list of errors after which to continue processing.
219 Use this option to specify a list of one or more classes of
221 errors after which lcov should continue processing instead of
222 aborting.
223 errors can be a comma-separated list of the following keywords:
225 gcov: the gcov tool returned with a non-zero return code.
227 source: the source code file for a data set could not be found.
229 -i
231 --initial
232 Capture initial zero coverage data.
233 Run lcov with -c and this option on the directories containing
235 .bb, .bbg or .gcno files before running any test case. The
236 result is a "baseline" coverage data file that contains zero
237 coverage for every instrumented line. Combine this data file
238 (using lcov -a) with coverage data files captured after a test
239 run to ensure that the percentage of total lines covered is cor‐
240 rect even when not all source code files were loaded during the
241 test.
242 Recommended procedure when capturing data for a test case:
244 1. create baseline coverage data file
246 # lcov -c -i -d appdir -o app_base.info
247 2. perform test
249 # appdir/test
250 3. create test coverage data file
252 # lcov -c -d appdir -o app_test.info
253 4. combine baseline and test coverage data
255 # lcov -a app_base.info -a app_test.info -o
256 app_total.info
257 -k subdirectory
260 --kernel-directory subdirectory
261 Capture kernel coverage data only from subdirectory.
262 Use this option if you don't want to get coverage data for all
264 of the kernel, but only for specific subdirectories.
265 Note that you may specify this option more than once.
267 -l tracefile
269 --list tracefile
270 List the contents of the tracefile.
271 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
273 at a time.
274 -o tracefile
276 --output-file tracefile
277 Write data to tracefile instead of stdout.
278 Specify "-" as a filename to use the standard output.
280 By convention, lcov-generated coverage data files are called
282 "tracefiles" and should have the filename extension ".info".
283 --path path
285 Strip path from filenames when applying diff.
286 Use this option together with --diff to tell lcov to disregard
288 the specified initial path component when matching between
289 tracefile and diff filenames.
290 -q
292 --quiet
293 Do not print progress messages.
294 This option is implied when no output filename is specified to
296 prevent progress messages to mess with coverage data which is
297 also printed to the standard output.
298 -r tracefile pattern
300 --remove tracefile pattern
301 Remove data from tracefile.
302 Use this switch if you want to remove coverage data for a par‐
304 ticular set of files from a tracefile. Additional command line
305 parameters will be interpreted as shell wildcard patterns (note
306 that they may need to be escaped accordingly to prevent the
307 shell from expanding them first). Every file entry in tracefile
308 which matches at least one of those patterns will be removed.
309 The result of the remove operation will be written to stdout or
311 the tracefile specified with -o.
312 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
314 at a time.
315 --strip depth
317 Strip path components when applying diff.
318 Use this option together with --diff to tell lcov to disregard
320 the specified number of initial directories when matching trace‐
321 file and diff filenames.
322 -t testname
324 --test-name testname
325 Specify test name to be stored in the tracefile.
326 This name identifies a coverage data set when more than one data
328 set is merged into a combined tracefile (see option -a).
329 Valid test names can consist of letters, decimal digits and the
331 underscore character ("_").
332 -v
334 --version
335 Print version number, then exit.
336 -z
338 --zerocounters
339 Reset all execution counts to zero.
340 By default tries to reset kernel execution counts. Use the
342 --directory option to reset all counters of a user space pro‐
343 gram.
344 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
346 at a time.
347
350 /etc/lcovrc
351 The system-wide configuration file.
352 ~/.lcovrc
354 The per-user configuration file.
355
358 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
359
362 lcovrc(5), genhtml(1), geninfo(1), genpng(1), gendesc(1), gcov(1)
3632003-12-19 lcov 1.6 lcov(1)