blob: 08123e8cb788aab2f10d9092fe1311c9d89c9148 [file] [log] [blame]
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +00001llvm-cov - emit coverage information
2====================================
3
James Hendersona0566842019-06-27 13:24:46 +00004.. program:: llvm-cov
5
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +00006SYNOPSIS
7--------
8
Justin Bogner92f47392015-03-12 04:18:21 +00009:program:`llvm-cov` *command* [*args...*]
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +000010
11DESCRIPTION
12-----------
13
Justin Bogner92f47392015-03-12 04:18:21 +000014The :program:`llvm-cov` tool shows code coverage information for
15programs that are instrumented to emit profile data. It can be used to
16work with ``gcov``\-style coverage or with ``clang``\'s instrumentation
17based profiling.
Bob Wilsonc16b7042014-05-06 15:58:06 +000018
Justin Bogner92f47392015-03-12 04:18:21 +000019If the program is invoked with a base name of ``gcov``, it will behave as if
20the :program:`llvm-cov gcov` command were called. Otherwise, a command should
21be provided.
22
23COMMANDS
24--------
25
26* :ref:`gcov <llvm-cov-gcov>`
27* :ref:`show <llvm-cov-show>`
28* :ref:`report <llvm-cov-report>`
Vedant Kumar7101d732016-07-26 22:50:58 +000029* :ref:`export <llvm-cov-export>`
Justin Bogner92f47392015-03-12 04:18:21 +000030
31.. program:: llvm-cov gcov
32
33.. _llvm-cov-gcov:
34
35GCOV COMMAND
36------------
37
38SYNOPSIS
39^^^^^^^^
40
41:program:`llvm-cov gcov` [*options*] *SOURCEFILE*
42
43DESCRIPTION
44^^^^^^^^^^^
45
46The :program:`llvm-cov gcov` tool reads code coverage data files and displays
47the coverage information for a specified source file. It is compatible with the
48``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
49later versions of ``gcov``.
50
51To use :program:`llvm-cov gcov`, you must first build an instrumented version
52of your application that collects coverage data as it runs. Compile with the
Bob Wilsonc16b7042014-05-06 15:58:06 +000053``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
54instrumentation. (Alternatively, you can use the ``--coverage`` option, which
55includes both of those other options.) You should compile with debugging
56information (``-g``) and without optimization (``-O0``); otherwise, the
57coverage data cannot be accurately mapped back to the source code.
58
59At the time you compile the instrumented code, a ``.gcno`` data file will be
60generated for each object file. These ``.gcno`` files contain half of the
61coverage data. The other half of the data comes from ``.gcda`` files that are
62generated when you run the instrumented program, with a separate ``.gcda``
63file for each object file. Each time you run the program, the execution counts
64are summed into any existing ``.gcda`` files, so be sure to remove any old
65files if you do not want their contents to be included.
66
67By default, the ``.gcda`` files are written into the same directory as the
68object files, but you can override that by setting the ``GCOV_PREFIX`` and
69``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP``
70variable specifies a number of directory components to be removed from the
71start of the absolute path to the object file directory. After stripping those
72directories, the prefix from the ``GCOV_PREFIX`` variable is added. These
73environment variables allow you to run the instrumented program on a machine
74where the original object file directories are not accessible, but you will
75then need to copy the ``.gcda`` files back to the object file directories
Justin Bogner92f47392015-03-12 04:18:21 +000076where :program:`llvm-cov gcov` expects to find them.
Bob Wilsonc16b7042014-05-06 15:58:06 +000077
Justin Bogner92f47392015-03-12 04:18:21 +000078Once you have generated the coverage data files, run :program:`llvm-cov gcov`
79for each main source file where you want to examine the coverage results. This
80should be run from the same directory where you previously ran the
81compiler. The results for the specified source file are written to a file named
82by appending a ``.gcov`` suffix. A separate output file is also created for
83each file included by the main source file, also with a ``.gcov`` suffix added.
Bob Wilsonc16b7042014-05-06 15:58:06 +000084
Justin Bogner92f47392015-03-12 04:18:21 +000085The basic content of an ``.gcov`` output file is a copy of the source file with
Bob Wilsonc16b7042014-05-06 15:58:06 +000086an execution count and line number prepended to every line. The execution
87count is shown as ``-`` if a line does not contain any executable code. If
88a line contains code but that code was never executed, the count is displayed
89as ``#####``.
90
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +000091OPTIONS
Justin Bogner92f47392015-03-12 04:18:21 +000092^^^^^^^
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +000093
Bob Wilsonc16b7042014-05-06 15:58:06 +000094.. option:: -a, --all-blocks
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +000095
Bob Wilsonc16b7042014-05-06 15:58:06 +000096 Display all basic blocks. If there are multiple blocks for a single line of
97 source code, this option causes llvm-cov to show the count for each block
98 instead of just one count for the entire line.
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +000099
Bob Wilsonc16b7042014-05-06 15:58:06 +0000100.. option:: -b, --branch-probabilities
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +0000101
Justin Bogner92f47392015-03-12 04:18:21 +0000102 Display conditional branch probabilities and a summary of branch information.
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +0000103
Bob Wilsonc16b7042014-05-06 15:58:06 +0000104.. option:: -c, --branch-counts
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +0000105
Bob Wilsonc16b7042014-05-06 15:58:06 +0000106 Display branch counts instead of probabilities (requires -b).
107
108.. option:: -f, --function-summaries
109
110 Show a summary of coverage for each function instead of just one summary for
111 an entire source file.
112
113.. option:: --help
114
115 Display available options (--help-hidden for more).
116
117.. option:: -l, --long-file-names
118
119 For coverage output of files included from the main source file, add the
120 main file name followed by ``##`` as a prefix to the output file names. This
121 can be combined with the --preserve-paths option to use complete paths for
122 both the main file and the included file.
123
Justin Bognerd9687172014-05-07 02:33:58 +0000124.. option:: -n, --no-output
125
126 Do not output any ``.gcov`` files. Summary information is still
127 displayed.
128
Bob Wilsonc16b7042014-05-06 15:58:06 +0000129.. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
130
131 Find objects in DIR or based on FILE's path. If you specify a particular
132 object file, the coverage data files are expected to have the same base name
133 with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the
134 files are expected in that directory with the same base name as the source
135 file.
136
137.. option:: -p, --preserve-paths
138
139 Preserve path components when naming the coverage output files. In addition
140 to the source file name, include the directories from the path to that
141 file. The directories are separate by ``#`` characters, with ``.`` directories
142 removed and ``..`` directories replaced by ``^`` characters. When used with
143 the --long-file-names option, this applies to both the main file name and the
144 included file name.
145
146.. option:: -u, --unconditional-branches
147
148 Include unconditional branches in the output for the --branch-probabilities
149 option.
150
151.. option:: -version
152
153 Display the version of llvm-cov.
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +0000154
Vedant Kumara0b97252019-02-19 20:45:00 +0000155.. option:: -x, --hash-filenames
156
157 Use md5 hash of file name when naming the coverage output files. The source
158 file name will be suffixed by ``##`` followed by MD5 hash calculated for it.
159
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +0000160EXIT STATUS
Justin Bogner92f47392015-03-12 04:18:21 +0000161^^^^^^^^^^^
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +0000162
Justin Bogner92f47392015-03-12 04:18:21 +0000163:program:`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise,
164it exits with zero.
Daniel Dunbar8f4a8a62012-05-08 16:50:35 +0000165
Justin Bogner92f47392015-03-12 04:18:21 +0000166.. program:: llvm-cov show
167
168.. _llvm-cov-show:
169
170SHOW COMMAND
171------------
172
173SYNOPSIS
174^^^^^^^^
175
Vedant Kumara3661ef2016-10-25 17:40:55 +0000176:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
Justin Bogner92f47392015-03-12 04:18:21 +0000177
178DESCRIPTION
179^^^^^^^^^^^
180
Vedant Kumara3661ef2016-10-25 17:40:55 +0000181The :program:`llvm-cov show` command shows line by line coverage of the
182binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
183filtered to only show the coverage for the files listed in *SOURCES*.
Justin Bogner92f47392015-03-12 04:18:21 +0000184
Vedant Kumar901d04f2019-06-13 20:48:57 +0000185*BIN* may be an executable, object file, dynamic library, or archive (thin or
186otherwise).
187
Bob Wilson98105882015-04-21 16:32:02 +0000188To use :program:`llvm-cov show`, you need a program that is compiled with
Justin Bogner92f47392015-03-12 04:18:21 +0000189instrumentation to emit profile and coverage data. To build such a program with
190``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
191flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
192to the link stage to make sure the necessary runtime libraries are linked in.
193
194The coverage information is stored in the built executable or library itself,
Vedant Kumara3661ef2016-10-25 17:40:55 +0000195and this is what you should pass to :program:`llvm-cov show` as a *BIN*
Justin Bogner92f47392015-03-12 04:18:21 +0000196argument. The profile data is generated by running this instrumented program
197normally. When the program exits it will write out a raw profile file,
198typically called ``default.profraw``, which can be converted to a format that
199is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
200tool.
201
202OPTIONS
203^^^^^^^
204
205.. option:: -show-line-counts
206
Vedant Kumar305e1b52017-09-25 23:10:04 +0000207 Show the execution counts for each line. Defaults to true, unless another
208 ``-show`` option is used.
Justin Bogner92f47392015-03-12 04:18:21 +0000209
210.. option:: -show-expansions
211
212 Expand inclusions, such as preprocessor macros or textual inclusions, inline
Vedant Kumar305e1b52017-09-25 23:10:04 +0000213 in the display of the source file. Defaults to false.
Justin Bogner92f47392015-03-12 04:18:21 +0000214
215.. option:: -show-instantiations
216
217 For source regions that are instantiated multiple times, such as templates in
218 ``C++``, show each instantiation separately as well as the combined summary.
Vedant Kumar305e1b52017-09-25 23:10:04 +0000219 Defaults to true.
Justin Bogner92f47392015-03-12 04:18:21 +0000220
221.. option:: -show-regions
222
223 Show the execution counts for each region by displaying a caret that points to
Vedant Kumar305e1b52017-09-25 23:10:04 +0000224 the character where the region starts. Defaults to false.
Justin Bogner92f47392015-03-12 04:18:21 +0000225
226.. option:: -show-line-counts-or-regions
227
228 Show the execution counts for each line if there is only one region on the
229 line, but show the individual regions if there are multiple on the line.
Vedant Kumar305e1b52017-09-25 23:10:04 +0000230 Defaults to false.
Justin Bogner92f47392015-03-12 04:18:21 +0000231
Vedant Kumar305e1b52017-09-25 23:10:04 +0000232.. option:: -use-color
Justin Bogner92f47392015-03-12 04:18:21 +0000233
Justin Bogner7bf61d32015-03-19 18:22:46 +0000234 Enable or disable color output. By default this is autodetected.
Justin Bogner92f47392015-03-12 04:18:21 +0000235
Vedant Kumar4b102c32017-08-01 21:23:26 +0000236.. option:: -arch=[*NAMES*]
Justin Bogner92f47392015-03-12 04:18:21 +0000237
Vedant Kumar4b102c32017-08-01 21:23:26 +0000238 Specify a list of architectures such that the Nth entry in the list
239 corresponds to the Nth specified binary. If the covered object is a universal
240 binary, this specifies the architecture to use. It is an error to specify an
241 architecture that is not included in the universal binary or to use an
242 architecture that does not match a non-universal binary.
Justin Bogner92f47392015-03-12 04:18:21 +0000243
244.. option:: -name=<NAME>
245
246 Show code coverage only for functions with the given name.
247
Sean Evesone15300e2017-08-31 09:11:31 +0000248.. option:: -name-whitelist=<FILE>
249
250 Show code coverage only for functions listed in the given file. Each line in
251 the file should start with `whitelist_fun:`, immediately followed by the name
252 of the function to accept. This name can be a wildcard expression.
253
Justin Bogner92f47392015-03-12 04:18:21 +0000254.. option:: -name-regex=<PATTERN>
255
256 Show code coverage only for functions that match the given regular expression.
257
Max Moroz4220f892018-04-09 15:20:35 +0000258.. option:: -ignore-filename-regex=<PATTERN>
259
260 Skip source code files with file paths that match the given regular expression.
261
Vedant Kumar635c83c2016-06-28 00:15:54 +0000262.. option:: -format=<FORMAT>
263
Vedant Kumar4c010922016-07-06 21:44:05 +0000264 Use the specified output format. The supported formats are: "text", "html".
Vedant Kumar635c83c2016-06-28 00:15:54 +0000265
Vedant Kumarad547d32016-08-04 18:00:42 +0000266.. option:: -tab-size=<TABSIZE>
267
268 Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
269 only supported for the html format.
270
Vedant Kumar7937ef32016-06-28 02:09:39 +0000271.. option:: -output-dir=PATH
272
273 Specify a directory to write coverage reports into. If the directory does not
274 exist, it is created. When used in function view mode (i.e when -name or
275 -name-regex are used to select specific functions), the report is written to
276 PATH/functions.EXTENSION. When used in file view mode, a report for each file
277 is written to PATH/REL_PATH_TO_FILE.EXTENSION.
278
Vedant Kumar424f51b2016-07-15 22:44:57 +0000279.. option:: -Xdemangler=<TOOL>|<TOOL-OPTION>
280
281 Specify a symbol demangler. This can be used to make reports more
282 human-readable. This option can be specified multiple times to supply
283 arguments to the demangler (e.g `-Xdemangler c++filt -Xdemangler -n` for C++).
284 The demangler is expected to read a newline-separated list of symbols from
285 stdin and write a newline-separated list of the same length to stdout.
286
Vedant Kumar7fa75102017-07-11 01:23:29 +0000287.. option:: -num-threads=N, -j=N
288
289 Use N threads to write file reports (only applicable when -output-dir is
290 specified). When N=0, llvm-cov auto-detects an appropriate number of threads to
291 use. This is the default.
292
Justin Bogner92f47392015-03-12 04:18:21 +0000293.. option:: -line-coverage-gt=<N>
294
295 Show code coverage only for functions with line coverage greater than the
296 given threshold.
297
298.. option:: -line-coverage-lt=<N>
299
300 Show code coverage only for functions with line coverage less than the given
301 threshold.
302
303.. option:: -region-coverage-gt=<N>
304
305 Show code coverage only for functions with region coverage greater than the
306 given threshold.
307
308.. option:: -region-coverage-lt=<N>
309
310 Show code coverage only for functions with region coverage less than the given
311 threshold.
312
Sean Eveson9edfeac2017-08-14 10:20:12 +0000313.. option:: -path-equivalence=<from>,<to>
314
315 Map the paths in the coverage data to local source file paths. This allows you
316 to generate the coverage data on one machine, and then use llvm-cov on a
317 different machine where you have the same files on a different path.
318
Justin Bogner92f47392015-03-12 04:18:21 +0000319.. program:: llvm-cov report
320
321.. _llvm-cov-report:
322
323REPORT COMMAND
324--------------
325
326SYNOPSIS
327^^^^^^^^
328
Vedant Kumara3661ef2016-10-25 17:40:55 +0000329:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
Justin Bogner92f47392015-03-12 04:18:21 +0000330
331DESCRIPTION
332^^^^^^^^^^^
333
Vedant Kumara3661ef2016-10-25 17:40:55 +0000334The :program:`llvm-cov report` command displays a summary of the coverage of
335the binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
336filtered to only show the coverage for the files listed in *SOURCES*.
Justin Bogner92f47392015-03-12 04:18:21 +0000337
Vedant Kumar901d04f2019-06-13 20:48:57 +0000338*BIN* may be an executable, object file, dynamic library, or archive (thin or
339otherwise).
340
Justin Bogner92f47392015-03-12 04:18:21 +0000341If no source files are provided, a summary line is printed for each file in the
Vedant Kumar899692e2018-07-13 22:39:31 +0000342coverage data. If any files are provided, summaries can be shown for each
343function in the listed files if the ``-show-functions`` option is enabled.
Justin Bogner92f47392015-03-12 04:18:21 +0000344
345For information on compiling programs for coverage and generating profile data,
Justin Bogner0ea61e92015-03-12 04:43:01 +0000346see :ref:`llvm-cov-show`.
Justin Bogner92f47392015-03-12 04:18:21 +0000347
348OPTIONS
349^^^^^^^
350
Justin Bogner7bf61d32015-03-19 18:22:46 +0000351.. option:: -use-color[=VALUE]
Justin Bogner92f47392015-03-12 04:18:21 +0000352
Justin Bogner7bf61d32015-03-19 18:22:46 +0000353 Enable or disable color output. By default this is autodetected.
Justin Bogner92f47392015-03-12 04:18:21 +0000354
355.. option:: -arch=<name>
356
Bob Wilson98105882015-04-21 16:32:02 +0000357 If the covered binary is a universal binary, select the architecture to use.
358 It is an error to specify an architecture that is not included in the
359 universal binary or to use an architecture that does not match a
360 non-universal binary.
Vedant Kumar7101d732016-07-26 22:50:58 +0000361
Vedant Kumar62eb0fd2017-02-05 20:11:08 +0000362.. option:: -show-functions
363
Vedant Kumar305e1b52017-09-25 23:10:04 +0000364 Show coverage summaries for each function. Defaults to false.
Vedant Kumar62eb0fd2017-02-05 20:11:08 +0000365
Vedant Kumar305e1b52017-09-25 23:10:04 +0000366.. option:: -show-instantiation-summary
Vedant Kumar047cbee2017-09-20 21:52:09 +0000367
368 Show statistics for all function instantiations. Defaults to false.
369
Max Moroz4220f892018-04-09 15:20:35 +0000370.. option:: -ignore-filename-regex=<PATTERN>
371
372 Skip source code files with file paths that match the given regular expression.
373
Vedant Kumar90f1b822016-07-26 23:09:57 +0000374.. program:: llvm-cov export
375
376.. _llvm-cov-export:
377
Vedant Kumar7101d732016-07-26 22:50:58 +0000378EXPORT COMMAND
379--------------
380
381SYNOPSIS
382^^^^^^^^
383
Max Moroz1ef3a772018-01-04 19:33:29 +0000384:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
Vedant Kumar7101d732016-07-26 22:50:58 +0000385
386DESCRIPTION
387^^^^^^^^^^^
388
Max Morozb2091c92018-11-09 16:10:44 +0000389The :program:`llvm-cov export` command exports coverage data of the binaries
390*BIN*,... using the profile data *PROFILE* in either JSON or lcov trace file
391format.
392
393When exporting JSON, the regions, functions, expansions, and summaries of the
394coverage data will be exported. When exporting an lcov trace file, the
395line-based coverage and summaries will be exported.
396
397The exported data can optionally be filtered to only export the coverage
Max Moroz1ef3a772018-01-04 19:33:29 +0000398for the files listed in *SOURCES*.
Vedant Kumar7101d732016-07-26 22:50:58 +0000399
400For information on compiling programs for coverage and generating profile data,
401see :ref:`llvm-cov-show`.
402
403OPTIONS
404^^^^^^^
405
406.. option:: -arch=<name>
407
408 If the covered binary is a universal binary, select the architecture to use.
409 It is an error to specify an architecture that is not included in the
410 universal binary or to use an architecture that does not match a
411 non-universal binary.
Max Morozfe4d9042017-12-11 23:17:46 +0000412
Max Morozb2091c92018-11-09 16:10:44 +0000413.. option:: -format=<FORMAT>
414
415 Use the specified output format. The supported formats are: "text" (JSON),
416 "lcov".
417
Max Morozfe4d9042017-12-11 23:17:46 +0000418.. option:: -summary-only
419
420 Export only summary information for each file in the coverage data. This mode
421 will not export coverage information for smaller units such as individual
Max Morozb2091c92018-11-09 16:10:44 +0000422 functions or regions. The result will contain the same information as produced
423 by the :program:`llvm-cov report` command, but presented in JSON or lcov
424 format rather than text.
Max Moroz4220f892018-04-09 15:20:35 +0000425
426.. option:: -ignore-filename-regex=<PATTERN>
427
428 Skip source code files with file paths that match the given regular expression.
Max Moroza80d9ce2019-03-14 17:49:27 +0000429
430 .. option:: -skip-expansions
431
432 Skip exporting macro expansion coverage data.
433
434 .. option:: -skip-functions
435
436 Skip exporting per-function coverage data.
437
438 .. option:: -num-threads=N, -j=N
439
440 Use N threads to export coverage data. When N=0, llvm-cov auto-detects an
441 appropriate number of threads to use. This is the default.