llvm.org GIT mirror llvm / 88a84e3
docs: Document the llvm-cov show and report commands Add a basic synopsis of how to work with instrprof based coverage using the llvm-cov tools. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@232007 91177308-0d34-0410-b5e6-96231b3b80d8 Justin Bogner 5 years ago
1 changed file(s) with 196 addition(s) and 26 deletion(s). Raw diff Collapse all Expand all
33 SYNOPSIS
44 --------
55
6 :program:`llvm-cov` [options] SOURCEFILE
6 :program:`llvm-cov` *command* [*args...*]
77
88 DESCRIPTION
99 -----------
1010
11 The :program:`llvm-cov` tool reads code coverage data files and displays the
12 coverage information for a specified source file. It is compatible with the
13 ``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with
14 some later versions of ``gcov``.
15
16 To use llvm-cov, you must first build an instrumented version of your
17 application that collects coverage data as it runs. Compile with the
11 The :program:`llvm-cov` tool shows code coverage information for
12 programs that are instrumented to emit profile data. It can be used to
13 work with ``gcov``\-style coverage or with ``clang``\'s instrumentation
14 based profiling.
15
16 If the program is invoked with a base name of ``gcov``, it will behave as if
17 the :program:`llvm-cov gcov` command were called. Otherwise, a command should
18 be provided.
19
20 COMMANDS
21 --------
22
23 * :ref:`gcov `
24 * :ref:`show `
25 * :ref:`report `
26
27 .. program:: llvm-cov gcov
28
29 .. _llvm-cov-gcov:
30
31 GCOV COMMAND
32 ------------
33
34 SYNOPSIS
35 ^^^^^^^^
36
37 :program:`llvm-cov gcov` [*options*] *SOURCEFILE*
38
39 DESCRIPTION
40 ^^^^^^^^^^^
41
42 The :program:`llvm-cov gcov` tool reads code coverage data files and displays
43 the coverage information for a specified source file. It is compatible with the
44 ``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
45 later versions of ``gcov``.
46
47 To use :program:`llvm-cov gcov`, you must first build an instrumented version
48 of your application that collects coverage data as it runs. Compile with the
1849 ``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
1950 instrumentation. (Alternatively, you can use the ``--coverage`` option, which
2051 includes both of those other options.) You should compile with debugging
3869 environment variables allow you to run the instrumented program on a machine
3970 where the original object file directories are not accessible, but you will
4071 then need to copy the ``.gcda`` files back to the object file directories
41 where llvm-cov expects to find them.
42
43 Once you have generated the coverage data files, run llvm-cov for each main
44 source file where you want to examine the coverage results. This should be run
45 from the same directory where you previously ran the compiler. The results for
46 the specified source file are written to a file named by appending a ``.gcov``
47 suffix. A separate output file is also created for each file included by the
48 main source file, also with a ``.gcov`` suffix added.
49
50 The basic content of an llvm-cov output file is a copy of the source file with
72 where :program:`llvm-cov gcov` expects to find them.
73
74 Once you have generated the coverage data files, run :program:`llvm-cov gcov`
75 for each main source file where you want to examine the coverage results. This
76 should be run from the same directory where you previously ran the
77 compiler. The results for the specified source file are written to a file named
78 by appending a ``.gcov`` suffix. A separate output file is also created for
79 each file included by the main source file, also with a ``.gcov`` suffix added.
80
81 The basic content of an ``.gcov`` output file is a copy of the source file with
5182 an execution count and line number prepended to every line. The execution
5283 count is shown as ``-`` if a line does not contain any executable code. If
5384 a line contains code but that code was never executed, the count is displayed
5485 as ``#####``.
5586
56
5787 OPTIONS
58 -------
88 ^^^^^^^
5989
6090 .. option:: -a, --all-blocks
6191
6595
6696 .. option:: -b, --branch-probabilities
6797
68 Display conditional branch probabilities and a summary of branch information.
98 Display conditional branch probabilities and a summary of branch information.
6999
70100 .. option:: -c, --branch-counts
71101
119149 Display the version of llvm-cov.
120150
121151 EXIT STATUS
122 -----------
123
124 :program:`llvm-cov` returns 1 if it cannot read input files. Otherwise, it
125 exits with zero.
126
152 ^^^^^^^^^^^
153
154 :program:`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise,
155 it exits with zero.
156
157
158 .. program:: llvm-cov show
159
160 .. _llvm-cov-show:
161
162 SHOW COMMAND
163 ------------
164
165 SYNOPSIS
166 ^^^^^^^^
167
168 :program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*]
169
170 DESCRIPTION
171 ^^^^^^^^^^^
172
173 The :program:`llvm-cov show` command shows line by line coverage of a binary
174 *BIN* using the profile data *PROFILE*. It can optionally be filtered to only
175 show the coverage for the files listed in *SOURCES*.
176
177 To use :program:`llvm-cov show`, you need a program that's compiled with
178 instrumentation to emit profile and coverage data. To build such a program with
179 ``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
180 flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
181 to the link stage to make sure the necessary runtime libraries are linked in.
182
183 The coverage information is stored in the built executable or library itself,
184 and this is what you should pass to :program:`llvm-cov show` as the *BIN*
185 argument. The profile data is generated by running this instrumented program
186 normally. When the program exits it will write out a raw profile file,
187 typically called ``default.profraw``, which can be converted to a format that
188 is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
189 tool.
190
191 OPTIONS
192 ^^^^^^^
193
194 .. option:: -show-line-counts
195
196 Show the execution counts for each line. This is enabled by default, unless
197 another ``-show`` option is used.
198
199 .. option:: -show-expansions
200
201 Expand inclusions, such as preprocessor macros or textual inclusions, inline
202 in the display of the source file.
203
204 .. option:: -show-instantiations
205
206 For source regions that are instantiated multiple times, such as templates in
207 ``C++``, show each instantiation separately as well as the combined summary.
208
209 .. option:: -show-regions
210
211 Show the execution counts for each region by displaying a caret that points to
212 the character where the region starts.
213
214 .. option:: -show-line-counts-or-regions
215
216 Show the execution counts for each line if there is only one region on the
217 line, but show the individual regions if there are multiple on the line.
218
219 .. option:: -no-colors
220
221 Disable colorized output.
222
223 .. option:: -arch=
224
225 If the covered binary is a universal binary, select the architecture to use
226 when looking up the coverage map. Errors out if the supplied architecture is
227 not found in the universal binary, or if used on a non-universal binary of
228 a different architecture.
229
230 .. option:: -name=
231
232 Show code coverage only for functions with the given name.
233
234 .. option:: -name-regex=
235
236 Show code coverage only for functions that match the given regular expression.
237
238 .. option:: -line-coverage-gt=
239
240 Show code coverage only for functions with line coverage greater than the
241 given threshold.
242
243 .. option:: -line-coverage-lt=
244
245 Show code coverage only for functions with line coverage less than the given
246 threshold.
247
248 .. option:: -region-coverage-gt=
249
250 Show code coverage only for functions with region coverage greater than the
251 given threshold.
252
253 .. option:: -region-coverage-lt=
254
255 Show code coverage only for functions with region coverage less than the given
256 threshold.
257
258 .. program:: llvm-cov report
259
260 .. _llvm-cov-report:
261
262 REPORT COMMAND
263 --------------
264
265 SYNOPSIS
266 ^^^^^^^^
267
268 :program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*]
269
270 DESCRIPTION
271 ^^^^^^^^^^^
272
273 The :program:`llvm-cov report` command displays a summary of the coverage of a
274 binary *BIN* using the profile data *PROFILE*. It can optionally be filtered to
275 only show the coverage for the files listed in *SOURCES*.
276
277 If no source files are provided, a summary line is printed for each file in the
278 coverage data. If any files are provided, summaries are shown for each function
279 in the listed files instead.
280
281 For information on compiling programs for coverage and generating profile data,
282 see :ref:`report `.
283
284 OPTIONS
285 ^^^^^^^
286
287 .. option:: -no-colors
288
289 Disable colorized output.
290
291 .. option:: -arch=
292
293 If the covered binary is a universal binary, select the architecture to use
294 when looking up the coverage map. Errors out if the supplied architecture is
295 not found in the universal binary, or if used on a non-universal binary of
296 a different architecture.