1lcov(1) User Manuals lcov(1)
2
6 lcov - a graphical GCOV front-end
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 [--no-recursion]
27
29 lcov is a graphical front-end for GCC's coverage testing tool gcov. It
30 collects gcov data for multiple source files and creates HTML pages
31 containing the source code annotated with coverage information. It also
32 adds overview pages for easy navigation within the file structure.
33 Use lcov to collect coverage data and genhtml to create HTML pages.
35 Coverage data can either be collected from the currently running Linux
36 kernel or from a user space application. To do this, you have to com‐
37 plete the following preparation steps:
38 For Linux kernel coverage:
40 Follow the installation instructions for the gcov-kernel patch:
41 http://ltp.sourceforge.net/coverage/gcov.php
42 For user space application coverage:
44 Compile the application with GCC using the options "-fpro‐
45 file-arcs" and "-ftest-coverage".
46 Please note that this man page refers to the output format of lcov as
48 ".info file" or "tracefile" and that the output of GCOV is called ".da
49 file".
50
52 -a tracefile
53 --add-tracefile tracefile
54 Add contents of tracefile.
55 Specify several tracefiles using the -a switch to combine the
57 coverage data contained in these files by adding up execution
58 counts for matching test and filename combinations.
59 The result of the add operation will be written to stdout or the
61 tracefile specified with -o.
62 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
64 at a time.
65 -b directory
68 --base-directory directory
69 Use directory as base directory for relative paths.
70 Use this option to specify the base directory of a build-envi‐
72 ronment when lcov produces error messages like:
73 ERROR: could not read source file /home/user/project/sub‐
75 dir1/subdir2/subdir1/subdir2/file.c
76 In this example, use /home/user/project as base directory.
78 This option is required when using lcov on projects built with
80 libtool or similar build environments that work with a base
81 directory, i.e. environments, where the current working direc‐
82 tory when invoking the compiler is not the same directory in
83 which the source code file is located.
84 Note that this option will not work in environments where multi‐
86 ple base directories are used. In that case repeat the lcov call
87 for each base directory while using the --ignore-errors option
88 to prevent lcov from exiting when the first source code file
89 could not be found. This way you can get partial coverage infor‐
90 mation for each base directory which can then be combined using
91 the -a option.
92 -c
94 --capture
95 Capture coverage data.
96 By default captures the current kernel execution counts and
98 writes the resulting coverage data to the standard output. Use
99 the --directory option to capture counts for a user space pro‐
100 gram.
101 The result of the capture operation will be written to stdout or
103 the tracefile specified with -o.
104 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
106 at a time.
107 --checksum
109 --no-checksum
110 Specify whether to generate checksum data when writing trace‐
111 files.
112 Use --checksum to enable checksum generation or --no-checksum to
114 disable it. Checksum generation is disabled by default.
115 When checksum generation is enabled, a checksum will be gener‐
117 ated for each source code line and stored along with the cover‐
118 age data. This checksum will be used to prevent attempts to com‐
119 bine coverage data from different source code versions.
120 If you don't work with different source code versions, disable
122 this option to speed up coverage data processing and to reduce
123 the size of tracefiles.
124 --compat-libtool
126 --no-compat-libtool
127 Specify whether to enable libtool compatibility mode.
128 Use --compat-libtool to enable libtool compatibility mode or
130 --no-compat-libtool to disable it. The libtool compatibility
131 mode is enabled by default.
132 When libtool compatibility mode is enabled, lcov will assume
134 that the source code relating to a .da file located in a direc‐
135 tory named ".libs" can be found in its parent directory.
136 If you have directories named ".libs" in your build environment
138 but don't use libtool, disable this option to prevent problems
139 when capturing coverage data.
140 --convert-filenames
142 Convert filenames when applying diff.
143 Use this option together with --diff to rename the file names of
145 processed data sets according to the data provided by the diff.
146 --diff tracefile difffile
148 Convert coverage data in tracefile using source code diff file
149 difffile.
150 Use this option if you want to merge coverage data from differ‐
152 ent source code levels of a program, e.g. when you have data
153 taken from an older version and want to combine it with data
154 from a more current version. lcov will try to map source code
155 lines between those versions and adjust the coverage data
156 respectively. difffile needs to be in unified format, i.e. it
157 has to be created using the "-u" option of the diff tool.
158 Note that lines which are not present in the old version will
160 not be counted as instrumented, therefore tracefiles resulting
161 from this operation should not be interpreted individually but
162 together with other tracefiles taken from the newer version.
163 Also keep in mind that converted coverage data should only be
164 used for overview purposes as the process itself introduces a
165 loss of accuracy.
166 The result of the diff operation will be written to stdout or
168 the tracefile specified with -o.
169 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
171 at a time.
172 -d directory
174 --directory directory
175 Use .da files in directory instead of kernel.
176 If you want to work on coverage data for a user space program,
178 use this option to specify the location where the program was
179 compiled (that's where the counter files ending with .da will be
180 stored).
181 Note that you may specify this option more than once.
183 -e tracefile pattern
185 --extract tracefile pattern
186 Extract data from tracefile.
187 Use this switch if you want to extract coverage data for only a
189 particular set of files from a tracefile. Additional command
190 line parameters will be interpreted as shell wildcard patterns
191 (note that they may need to be escaped accordingly to prevent
192 the shell from expanding them first). Every file entry in
193 tracefile which matches at least one of those patterns will be
194 extracted.
195 The result of the extract operation will be written to stdout or
197 the tracefile specified with -o.
198 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
200 at a time.
201 -f
203 --follow
204 Follow links when searching for .da files.
205 --gcov-tool tool
207 Specify the location of the gcov tool.
208 -h
210 --help
211 Print a short help text, then exit.
212 --ignore-errors errors
214 Specify a list of errors after which to continue processing.
215 Use this option to specify a list of one or more classes of
217 errors after which lcov should continue processing instead of
218 aborting.
219 errors can be a comma-separated list of the following keywords:
221 gcov: the gcov tool returned with a non-zero return code.
223 source: the source code file for a data set could not be found.
225 -i
227 --initial
228 Capture initial zero coverage data.
229 Run lcov with -c and this option on the directories containing
231 .bb, .bbg or .gcno files before running any test case. The
232 result is a "baseline" coverage data file that contains zero
233 coverage for every instrumented line. Combine this data file
234 (using lcov -a) with coverage data files captured after a test
235 run to ensure that the percentage of total lines covered is cor‐
236 rect even when not all source code files were loaded during the
237 test.
238 Recommended procedure when capturing data for a test case:
240 1. create baseline coverage data file
242 # lcov -c -i -d appdir -o app_base.info
243 2. perform test
245 # appdir/test
246 3. create test coverage data file
248 # lcov -c -d appdir -o app_test.info
249 4. combine baseline and test coverage data
251 # lcov -a app_base.info -a app_test.info -o
252 app_total.info
253 -k subdirectory
256 --kernel-directory subdirectory
257 Capture kernel coverage data only from subdirectory.
258 Use this option if you don't want to get coverage data for all
260 of the kernel, but only for specific subdirectories.
261 Note that you may specify this option more than once.
263 -l tracefile
265 --list tracefile
266 List the contents of the tracefile.
267 Only one of -z, -c, -a, -e, -r, -l and --diff may be specified
269 at a time.
270 --no-recursion
272 Use this option if you want to get coverage data for the speci‐
273 fied directory only without processing subdirectories.
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)
3632008-11-17 LCOV 1.7 lcov(1)