1LLVM-COV(1) LLVM LLVM-COV(1)
2
6 llvm-cov - emit coverage information
7
9 llvm-cov command [args...]
10
12 The llvm-cov tool shows code coverage information for programs that are
13 instrumented to emit profile data. It can be used to work with
14 gcov-style coverage or with clang's instrumentation based profiling.
15 If the program is invoked with a base name of gcov, it will behave as
17 if the llvm-cov gcov command were called. Otherwise, a command should
18 be provided.
19
21 · gcov
22 · show
24 · report
26
28 SYNOPSIS
29 llvm-cov gcov [options] SOURCEFILE
30 DESCRIPTION
32 The llvm-cov gcov tool reads code coverage data files and displays the
33 coverage information for a specified source file. It is compatible with
34 the gcov tool from version 4.2 of GCC and may also be compatible with
35 some later versions of gcov.
36 To use llvm-cov gcov, you must first build an instrumented version of
38 your application that collects coverage data as it runs. Compile with
39 the -fprofile-arcs and -ftest-coverage options to add the instrumenta‐
40 tion. (Alternatively, you can use the --coverage option, which includes
41 both of those other options.) You should compile with debugging infor‐
42 mation (-g) and without optimization (-O0); otherwise, the coverage
43 data cannot be accurately mapped back to the source code.
44 At the time you compile the instrumented code, a .gcno data file will
46 be generated for each object file. These .gcno files contain half of
47 the coverage data. The other half of the data comes from .gcda files
48 that are generated when you run the instrumented program, with a sepa‐
49 rate .gcda file for each object file. Each time you run the program,
50 the execution counts are summed into any existing .gcda files, so be
51 sure to remove any old files if you do not want their contents to be
52 included.
53 By default, the .gcda files are written into the same directory as the
55 object files, but you can override that by setting the GCOV_PREFIX and
56 GCOV_PREFIX_STRIP environment variables. The GCOV_PREFIX_STRIP variable
57 specifies a number of directory components to be removed from the start
58 of the absolute path to the object file directory. After stripping
59 those directories, the prefix from the GCOV_PREFIX variable is added.
60 These environment variables allow you to run the instrumented program
61 on a machine where the original object file directories are not acces‐
62 sible, but you will then need to copy the .gcda files back to the
63 object file directories where llvm-cov gcov expects to find them.
64 Once you have generated the coverage data files, run llvm-cov gcov for
66 each main source file where you want to examine the coverage results.
67 This should be run from the same directory where you previously ran the
68 compiler. The results for the specified source file are written to a
69 file named by appending a .gcov suffix. A separate output file is also
70 created for each file included by the main source file, also with a
71 .gcov suffix added.
72 The basic content of an .gcov output file is a copy of the source file
74 with an execution count and line number prepended to every line. The
75 execution count is shown as - if a line does not contain any executable
76 code. If a line contains code but that code was never executed, the
77 count is displayed as #####.
78 OPTIONS
80 -a, --all-blocks
81 Display all basic blocks. If there are multiple blocks for a
82 single line of source code, this option causes llvm-cov to show
83 the count for each block instead of just one count for the
84 entire line.
85 -b, --branch-probabilities
87 Display conditional branch probabilities and a summary of branch
88 information.
89 -c, --branch-counts
91 Display branch counts instead of probabilities (requires -b).
92 -f, --function-summaries
94 Show a summary of coverage for each function instead of just one
95 summary for an entire source file.
96 --help Display available options (--help-hidden for more).
98 -l, --long-file-names
100 For coverage output of files included from the main source file,
101 add the main file name followed by ## as a prefix to the output
102 file names. This can be combined with the --preserve-paths
103 option to use complete paths for both the main file and the
104 included file.
105 -n, --no-output
107 Do not output any .gcov files. Summary information is still dis‐
108 played.
109 -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
111 Find objects in DIR or based on FILE's path. If you specify a
112 particular object file, the coverage data files are expected to
113 have the same base name with .gcno and .gcda extensions. If you
114 specify a directory, the files are expected in that directory
115 with the same base name as the source file.
116 -p, --preserve-paths
118 Preserve path components when naming the coverage output files.
119 In addition to the source file name, include the directories
120 from the path to that file. The directories are separate by #
121 characters, with . directories removed and .. directories
122 replaced by ^ characters. When used with the --long-file-names
123 option, this applies to both the main file name and the included
124 file name.
125 -u, --unconditional-branches
127 Include unconditional branches in the output for the
128 --branch-probabilities option.
129 -version
131 Display the version of llvm-cov.
132 EXIT STATUS
134 llvm-cov gcov returns 1 if it cannot read input files. Otherwise, it
135 exits with zero.
136
138 SYNOPSIS
139 llvm-cov show [options] -instr-profile PROFILE BIN [SOURCES]
140 DESCRIPTION
142 The llvm-cov show command shows line by line coverage of a binary BIN
143 using the profile data PROFILE. It can optionally be filtered to only
144 show the coverage for the files listed in SOURCES.
145 To use llvm-cov show, you need a program that is compiled with instru‐
147 mentation to emit profile and coverage data. To build such a program
148 with clang use the -fprofile-instr-generate and -fcoverage-mapping
149 flags. If linking with the clang driver, pass -fprofile-instr-generate
150 to the link stage to make sure the necessary runtime libraries are
151 linked in.
152 The coverage information is stored in the built executable or library
154 itself, and this is what you should pass to llvm-cov show as the BIN
155 argument. The profile data is generated by running this instrumented
156 program normally. When the program exits it will write out a raw pro‐
157 file file, typically called default.profraw, which can be converted to
158 a format that is suitable for the PROFILE argument using the llvm-prof‐
159 data merge tool.
160 OPTIONS
162 -show-line-counts
163 Show the execution counts for each line. This is enabled by
164 default, unless another -show option is used.
165 -show-expansions
167 Expand inclusions, such as preprocessor macros or textual inclu‐
168 sions, inline in the display of the source file.
169 -show-instantiations
171 For source regions that are instantiated multiple times, such as
172 templates in C++, show each instantiation separately as well as
173 the combined summary.
174 -show-regions
176 Show the execution counts for each region by displaying a caret
177 that points to the character where the region starts.
178 -show-line-counts-or-regions
180 Show the execution counts for each line if there is only one
181 region on the line, but show the individual regions if there are
182 multiple on the line.
183 -use-color[=VALUE]
185 Enable or disable color output. By default this is autodetected.
186 -arch=<name>
188 If the covered binary is a universal binary, select the archi‐
189 tecture to use. It is an error to specify an architecture that
190 is not included in the universal binary or to use an architec‐
191 ture that does not match a non-universal binary.
192 -name=<NAME>
194 Show code coverage only for functions with the given name.
195 -name-regex=<PATTERN>
197 Show code coverage only for functions that match the given regu‐
198 lar expression.
199 -format=<FORMAT>
201 Use the specified output format. The supported formats are:
202 "text", "html".
203 -output-dir=PATH
205 Specify a directory to write coverage reports into. If the
206 directory does not exist, it is created. When used in function
207 view mode (i.e when -name or -name-regex are used to select spe‐
208 cific functions), the report is written to PATH/functions.EXTEN‐
209 SION. When used in file view mode, a report for each file is
210 written to PATH/REL_PATH_TO_FILE.EXTENSION.
211 -Xdemangler=<TOOL>|<TOOL-OPTION>
213 Specify a symbol demangler. This can be used to make reports
214 more human-readable. This option can be specified multiple times
215 to supply arguments to the demangler (e.g -Xdemangler c++filt
216 -Xdemangler -n for C++). The demangler is expected to read a
217 newline-separated list of symbols from stdin and write a new‐
218 line-separated list of the same length to stdout.
219 -line-coverage-gt=<N>
221 Show code coverage only for functions with line coverage greater
222 than the given threshold.
223 -line-coverage-lt=<N>
225 Show code coverage only for functions with line coverage less
226 than the given threshold.
227 -region-coverage-gt=<N>
229 Show code coverage only for functions with region coverage
230 greater than the given threshold.
231 -region-coverage-lt=<N>
233 Show code coverage only for functions with region coverage less
234 than the given threshold.
235
237 SYNOPSIS
238 llvm-cov report [options] -instr-profile PROFILE BIN [SOURCES]
239 DESCRIPTION
241 The llvm-cov report command displays a summary of the coverage of a
242 binary BIN using the profile data PROFILE. It can optionally be fil‐
243 tered to only show the coverage for the files listed in SOURCES.
244 If no source files are provided, a summary line is printed for each
246 file in the coverage data. If any files are provided, summaries are
247 shown for each function in the listed files instead.
248 For information on compiling programs for coverage and generating pro‐
250 file data, see SHOW COMMAND.
251 OPTIONS
253 -use-color[=VALUE]
254 Enable or disable color output. By default this is autodetected.
255 -arch=<name>
257 If the covered binary is a universal binary, select the archi‐
258 tecture to use. It is an error to specify an architecture that
259 is not included in the universal binary or to use an architec‐
260 ture that does not match a non-universal binary.
261
263 Maintained by The LLVM Team (http://llvm.org/).
264
266 2003-2019, LLVM Project
2673.9 2019-02-01 LLVM-COV(1)