0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
1 llvm-cov - emit coverage information
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
2 ====================================
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
3
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
4 SYNOPSIS
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
5 --------
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
6
|
|
95
|
7 :program:`llvm-cov` *command* [*args...*]
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
8
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
9 DESCRIPTION
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
10 -----------
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
11
|
|
95
|
12 The :program:`llvm-cov` tool shows code coverage information for
|
|
|
13 programs that are instrumented to emit profile data. It can be used to
|
|
|
14 work with ``gcov``\-style coverage or with ``clang``\'s instrumentation
|
|
|
15 based profiling.
|
|
|
16
|
|
|
17 If the program is invoked with a base name of ``gcov``, it will behave as if
|
|
|
18 the :program:`llvm-cov gcov` command were called. Otherwise, a command should
|
|
|
19 be provided.
|
|
|
20
|
|
|
21 COMMANDS
|
|
|
22 --------
|
|
|
23
|
|
|
24 * :ref:`gcov <llvm-cov-gcov>`
|
|
|
25 * :ref:`show <llvm-cov-show>`
|
|
|
26 * :ref:`report <llvm-cov-report>`
|
|
|
27
|
|
|
28 .. program:: llvm-cov gcov
|
|
77
|
29
|
|
95
|
30 .. _llvm-cov-gcov:
|
|
|
31
|
|
|
32 GCOV COMMAND
|
|
|
33 ------------
|
|
|
34
|
|
|
35 SYNOPSIS
|
|
|
36 ^^^^^^^^
|
|
|
37
|
|
|
38 :program:`llvm-cov gcov` [*options*] *SOURCEFILE*
|
|
|
39
|
|
|
40 DESCRIPTION
|
|
|
41 ^^^^^^^^^^^
|
|
|
42
|
|
|
43 The :program:`llvm-cov gcov` tool reads code coverage data files and displays
|
|
|
44 the coverage information for a specified source file. It is compatible with the
|
|
|
45 ``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
|
|
|
46 later versions of ``gcov``.
|
|
|
47
|
|
|
48 To use :program:`llvm-cov gcov`, you must first build an instrumented version
|
|
|
49 of your application that collects coverage data as it runs. Compile with the
|
|
77
|
50 ``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
|
|
|
51 instrumentation. (Alternatively, you can use the ``--coverage`` option, which
|
|
|
52 includes both of those other options.) You should compile with debugging
|
|
|
53 information (``-g``) and without optimization (``-O0``); otherwise, the
|
|
|
54 coverage data cannot be accurately mapped back to the source code.
|
|
|
55
|
|
|
56 At the time you compile the instrumented code, a ``.gcno`` data file will be
|
|
|
57 generated for each object file. These ``.gcno`` files contain half of the
|
|
|
58 coverage data. The other half of the data comes from ``.gcda`` files that are
|
|
|
59 generated when you run the instrumented program, with a separate ``.gcda``
|
|
|
60 file for each object file. Each time you run the program, the execution counts
|
|
|
61 are summed into any existing ``.gcda`` files, so be sure to remove any old
|
|
|
62 files if you do not want their contents to be included.
|
|
|
63
|
|
|
64 By default, the ``.gcda`` files are written into the same directory as the
|
|
|
65 object files, but you can override that by setting the ``GCOV_PREFIX`` and
|
|
|
66 ``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP``
|
|
|
67 variable specifies a number of directory components to be removed from the
|
|
|
68 start of the absolute path to the object file directory. After stripping those
|
|
|
69 directories, the prefix from the ``GCOV_PREFIX`` variable is added. These
|
|
|
70 environment variables allow you to run the instrumented program on a machine
|
|
|
71 where the original object file directories are not accessible, but you will
|
|
|
72 then need to copy the ``.gcda`` files back to the object file directories
|
|
95
|
73 where :program:`llvm-cov gcov` expects to find them.
|
|
77
|
74
|
|
95
|
75 Once you have generated the coverage data files, run :program:`llvm-cov gcov`
|
|
|
76 for each main source file where you want to examine the coverage results. This
|
|
|
77 should be run from the same directory where you previously ran the
|
|
|
78 compiler. The results for the specified source file are written to a file named
|
|
|
79 by appending a ``.gcov`` suffix. A separate output file is also created for
|
|
|
80 each file included by the main source file, also with a ``.gcov`` suffix added.
|
|
77
|
81
|
|
95
|
82 The basic content of an ``.gcov`` output file is a copy of the source file with
|
|
77
|
83 an execution count and line number prepended to every line. The execution
|
|
|
84 count is shown as ``-`` if a line does not contain any executable code. If
|
|
|
85 a line contains code but that code was never executed, the count is displayed
|
|
|
86 as ``#####``.
|
|
|
87
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
88 OPTIONS
|
|
95
|
89 ^^^^^^^
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
90
|
|
77
|
91 .. option:: -a, --all-blocks
|
|
|
92
|
|
|
93 Display all basic blocks. If there are multiple blocks for a single line of
|
|
|
94 source code, this option causes llvm-cov to show the count for each block
|
|
|
95 instead of just one count for the entire line.
|
|
|
96
|
|
|
97 .. option:: -b, --branch-probabilities
|
|
|
98
|
|
95
|
99 Display conditional branch probabilities and a summary of branch information.
|
|
77
|
100
|
|
|
101 .. option:: -c, --branch-counts
|
|
|
102
|
|
|
103 Display branch counts instead of probabilities (requires -b).
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
104
|
|
77
|
105 .. option:: -f, --function-summaries
|
|
|
106
|
|
|
107 Show a summary of coverage for each function instead of just one summary for
|
|
|
108 an entire source file.
|
|
|
109
|
|
|
110 .. option:: --help
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
111
|
|
77
|
112 Display available options (--help-hidden for more).
|
|
|
113
|
|
|
114 .. option:: -l, --long-file-names
|
|
|
115
|
|
|
116 For coverage output of files included from the main source file, add the
|
|
|
117 main file name followed by ``##`` as a prefix to the output file names. This
|
|
|
118 can be combined with the --preserve-paths option to use complete paths for
|
|
|
119 both the main file and the included file.
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
120
|
|
77
|
121 .. option:: -n, --no-output
|
|
|
122
|
|
|
123 Do not output any ``.gcov`` files. Summary information is still
|
|
|
124 displayed.
|
|
|
125
|
|
|
126 .. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
|
|
|
127
|
|
|
128 Find objects in DIR or based on FILE's path. If you specify a particular
|
|
|
129 object file, the coverage data files are expected to have the same base name
|
|
|
130 with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the
|
|
|
131 files are expected in that directory with the same base name as the source
|
|
|
132 file.
|
|
|
133
|
|
|
134 .. option:: -p, --preserve-paths
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
135
|
|
77
|
136 Preserve path components when naming the coverage output files. In addition
|
|
|
137 to the source file name, include the directories from the path to that
|
|
|
138 file. The directories are separate by ``#`` characters, with ``.`` directories
|
|
|
139 removed and ``..`` directories replaced by ``^`` characters. When used with
|
|
|
140 the --long-file-names option, this applies to both the main file name and the
|
|
|
141 included file name.
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
142
|
|
77
|
143 .. option:: -u, --unconditional-branches
|
|
|
144
|
|
|
145 Include unconditional branches in the output for the --branch-probabilities
|
|
|
146 option.
|
|
|
147
|
|
|
148 .. option:: -version
|
|
|
149
|
|
|
150 Display the version of llvm-cov.
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
151
|
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
152 EXIT STATUS
|
|
95
|
153 ^^^^^^^^^^^
|
|
|
154
|
|
|
155 :program:`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise,
|
|
|
156 it exits with zero.
|
|
|
157
|
|
|
158
|
|
|
159 .. program:: llvm-cov show
|
|
|
160
|
|
|
161 .. _llvm-cov-show:
|
|
|
162
|
|
|
163 SHOW COMMAND
|
|
|
164 ------------
|
|
|
165
|
|
|
166 SYNOPSIS
|
|
|
167 ^^^^^^^^
|
|
|
168
|
|
|
169 :program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*]
|
|
|
170
|
|
|
171 DESCRIPTION
|
|
|
172 ^^^^^^^^^^^
|
|
|
173
|
|
|
174 The :program:`llvm-cov show` command shows line by line coverage of a binary
|
|
|
175 *BIN* using the profile data *PROFILE*. It can optionally be filtered to only
|
|
|
176 show the coverage for the files listed in *SOURCES*.
|
|
|
177
|
|
|
178 To use :program:`llvm-cov show`, you need a program that is compiled with
|
|
|
179 instrumentation to emit profile and coverage data. To build such a program with
|
|
|
180 ``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
|
|
|
181 flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
|
|
|
182 to the link stage to make sure the necessary runtime libraries are linked in.
|
|
|
183
|
|
|
184 The coverage information is stored in the built executable or library itself,
|
|
|
185 and this is what you should pass to :program:`llvm-cov show` as the *BIN*
|
|
|
186 argument. The profile data is generated by running this instrumented program
|
|
|
187 normally. When the program exits it will write out a raw profile file,
|
|
|
188 typically called ``default.profraw``, which can be converted to a format that
|
|
|
189 is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
|
|
|
190 tool.
|
|
|
191
|
|
|
192 OPTIONS
|
|
|
193 ^^^^^^^
|
|
|
194
|
|
|
195 .. option:: -show-line-counts
|
|
|
196
|
|
|
197 Show the execution counts for each line. This is enabled by default, unless
|
|
|
198 another ``-show`` option is used.
|
|
|
199
|
|
|
200 .. option:: -show-expansions
|
|
|
201
|
|
|
202 Expand inclusions, such as preprocessor macros or textual inclusions, inline
|
|
|
203 in the display of the source file.
|
|
|
204
|
|
|
205 .. option:: -show-instantiations
|
|
|
206
|
|
|
207 For source regions that are instantiated multiple times, such as templates in
|
|
|
208 ``C++``, show each instantiation separately as well as the combined summary.
|
|
|
209
|
|
|
210 .. option:: -show-regions
|
|
|
211
|
|
|
212 Show the execution counts for each region by displaying a caret that points to
|
|
|
213 the character where the region starts.
|
|
|
214
|
|
|
215 .. option:: -show-line-counts-or-regions
|
|
|
216
|
|
|
217 Show the execution counts for each line if there is only one region on the
|
|
|
218 line, but show the individual regions if there are multiple on the line.
|
|
|
219
|
|
|
220 .. option:: -use-color[=VALUE]
|
|
|
221
|
|
|
222 Enable or disable color output. By default this is autodetected.
|
|
|
223
|
|
|
224 .. option:: -arch=<name>
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
225
|
|
95
|
226 If the covered binary is a universal binary, select the architecture to use.
|
|
|
227 It is an error to specify an architecture that is not included in the
|
|
|
228 universal binary or to use an architecture that does not match a
|
|
|
229 non-universal binary.
|
|
|
230
|
|
|
231 .. option:: -name=<NAME>
|
|
|
232
|
|
|
233 Show code coverage only for functions with the given name.
|
|
|
234
|
|
|
235 .. option:: -name-regex=<PATTERN>
|
|
|
236
|
|
|
237 Show code coverage only for functions that match the given regular expression.
|
|
|
238
|
|
|
239 .. option:: -line-coverage-gt=<N>
|
|
|
240
|
|
|
241 Show code coverage only for functions with line coverage greater than the
|
|
|
242 given threshold.
|
|
|
243
|
|
|
244 .. option:: -line-coverage-lt=<N>
|
|
|
245
|
|
|
246 Show code coverage only for functions with line coverage less than the given
|
|
|
247 threshold.
|
|
|
248
|
|
|
249 .. option:: -region-coverage-gt=<N>
|
|
|
250
|
|
|
251 Show code coverage only for functions with region coverage greater than the
|
|
|
252 given threshold.
|
|
|
253
|
|
|
254 .. option:: -region-coverage-lt=<N>
|
|
|
255
|
|
|
256 Show code coverage only for functions with region coverage less than the given
|
|
|
257 threshold.
|
|
|
258
|
|
|
259 .. program:: llvm-cov report
|
0
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff
changeset
|
260
|
|
95
|
261 .. _llvm-cov-report:
|
|
|
262
|
|
|
263 REPORT COMMAND
|
|
|
264 --------------
|
|
|
265
|
|
|
266 SYNOPSIS
|
|
|
267 ^^^^^^^^
|
|
|
268
|
|
|
269 :program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*]
|
|
|
270
|
|
|
271 DESCRIPTION
|
|
|
272 ^^^^^^^^^^^
|
|
|
273
|
|
|
274 The :program:`llvm-cov report` command displays a summary of the coverage of a
|
|
|
275 binary *BIN* using the profile data *PROFILE*. It can optionally be filtered to
|
|
|
276 only show the coverage for the files listed in *SOURCES*.
|
|
|
277
|
|
|
278 If no source files are provided, a summary line is printed for each file in the
|
|
|
279 coverage data. If any files are provided, summaries are shown for each function
|
|
|
280 in the listed files instead.
|
|
|
281
|
|
|
282 For information on compiling programs for coverage and generating profile data,
|
|
|
283 see :ref:`llvm-cov-show`.
|
|
|
284
|
|
|
285 OPTIONS
|
|
|
286 ^^^^^^^
|
|
|
287
|
|
|
288 .. option:: -use-color[=VALUE]
|
|
|
289
|
|
|
290 Enable or disable color output. By default this is autodetected.
|
|
|
291
|
|
|
292 .. option:: -arch=<name>
|
|
|
293
|
|
|
294 If the covered binary is a universal binary, select the architecture to use.
|
|
|
295 It is an error to specify an architecture that is not included in the
|
|
|
296 universal binary or to use an architecture that does not match a
|
|
|
297 non-universal binary.
|
