1 llvm-cov - emit coverage information
5 --------
7 :program:`llvm-cov` *command* [*args...*]
10 -----------
12 The :program:`llvm-cov` tool shows code coverage information for
14 work with ``gcov``\-style coverage or with ``clang``\'s instrumentation
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
22 --------
24 * :ref:`gcov <llvm-cov-gcov>`
25 * :ref:`show <llvm-cov-show>`
26 * :ref:`report <llvm-cov-report>`
28 .. program:: llvm-cov gcov
30 .. _llvm-cov-gcov:
32 GCOV COMMAND
33 ------------
38 :program:`llvm-cov gcov` [*options*] *SOURCEFILE*
43 The :program:`llvm-cov gcov` tool reads code coverage data files and displays
45 ``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
46 later versions of ``gcov``.
48 To use :program:`llvm-cov gcov`, you must first build an instrumented version
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
73 where :program:`llvm-cov gcov` expects to find them.
75 Once you have generated the coverage data files, run :program:`llvm-cov gcov`
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.
82 The basic content of an ``.gcov`` output file is a copy of the source file with
84 count is shown as ``-`` if a line does not contain any executable code. If
88 OPTIONS  section in GCOV COMMAND
91 .. option:: -a, --all-blocks
94  source code, this option causes llvm-cov to show the count for each block
97 .. option:: -b, --branch-probabilities
101 .. option:: -c, --branch-counts
103  Display branch counts instead of probabilities (requires -b).
105 .. option:: -f, --function-summaries
110 .. option:: --help
112  Display available options (--help-hidden for more).
114 .. option:: -l, --long-file-names
118  can be combined with the --preserve-paths option to use complete paths for
121 .. option:: -n, --no-output
123  Do not output any ``.gcov`` files. Summary information is still
126 .. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
134 .. option:: -p, --preserve-paths
140  the --long-file-names option, this applies to both the main file name and the
143 .. option:: -u, --unconditional-branches
145  Include unconditional branches in the output for the --branch-probabilities
148 .. option:: -version
150  Display the version of llvm-cov.
155 :program:`llvm-cov gcov` returns 1 if it cannot read input files.  Otherwise,
159 .. program:: llvm-cov show
161 .. _llvm-cov-show:
164 ------------
169 :program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*]
174 The :program:`llvm-cov show` command shows line by line coverage of a binary
178 To use :program:`llvm-cov show`, you need a program that is compiled with
180 ``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
181 flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
185 and this is what you should pass to :program:`llvm-cov show` as the *BIN*
189 is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
192 OPTIONS  section in SHOW COMMAND
195 .. option:: -show-line-counts
198  another ``-show`` option is used.
200 .. option:: -show-expansions
205 .. option:: -show-instantiations
210 .. option:: -show-regions
215 .. option:: -show-line-counts-or-regions
220 .. option:: -use-color[=VALUE]
224 .. option:: -arch=<name>
229  non-universal binary.
231 .. option:: -name=<NAME>
235 .. option:: -name-regex=<PATTERN>
239 .. option:: -line-coverage-gt=<N>
244 .. option:: -line-coverage-lt=<N>
249 .. option:: -region-coverage-gt=<N>
254 .. option:: -region-coverage-lt=<N>
259 .. program:: llvm-cov report
261 .. _llvm-cov-report:
264 --------------
269 :program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*]
274 The :program:`llvm-cov report` command displays a summary of the coverage of a
283 see :ref:`llvm-cov-show`.
285 OPTIONS  section in REPORT COMMAND
288 .. option:: -use-color[=VALUE]
292 .. option:: -arch=<name>
297  non-universal binary.