1 llvm-cov - emit coverage information
2 ====================================
7 :program:`llvm-cov` *command* [*args...*]
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
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
24 * :ref:`gcov <llvm-cov-gcov>`
25 * :ref:`show <llvm-cov-show>`
26 * :ref:`report <llvm-cov-report>`
28 .. program:: llvm-cov gcov
38 :program:`llvm-cov gcov` [*options*] *SOURCEFILE*
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``.
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
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.
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.
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
73 where :program:`llvm-cov gcov` expects to find them.
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.
82 The basic content of an ``.gcov`` output file is a copy of the source file with
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
91 .. option:: -a, --all-blocks
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.
97 .. option:: -b, --branch-probabilities
99 Display conditional branch probabilities and a summary of branch information.
101 .. option:: -c, --branch-counts
103 Display branch counts instead of probabilities (requires -b).
105 .. option:: -f, --function-summaries
107 Show a summary of coverage for each function instead of just one summary for
108 an entire source file.
112 Display available options (--help-hidden for more).
114 .. option:: -l, --long-file-names
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.
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>
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
134 .. option:: -p, --preserve-paths
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
143 .. option:: -u, --unconditional-branches
145 Include unconditional branches in the output for the --branch-probabilities
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
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
175 *BIN* using the profile data *PROFILE*. It can optionally be filtered to only
176 show the coverage for the files listed in *SOURCES*.
178 To use :program:`llvm-cov show`, you need a program that's 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.
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`
195 .. option:: -show-line-counts
197 Show the execution counts for each line. This is enabled by default, unless
198 another ``-show`` option is used.
200 .. option:: -show-expansions
202 Expand inclusions, such as preprocessor macros or textual inclusions, inline
203 in the display of the source file.
205 .. option:: -show-instantiations
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.
210 .. option:: -show-regions
212 Show the execution counts for each region by displaying a caret that points to
213 the character where the region starts.
215 .. option:: -show-line-counts-or-regions
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.
220 .. option:: -use-color[=VALUE]
222 Enable or disable color output. By default this is autodetected.
224 .. option:: -arch=<name>
226 If the covered binary is a universal binary, select the architecture to use
227 when looking up the coverage map. Errors out if the supplied architecture is
228 not found in the universal binary, or if used on a non-universal binary of
229 a different architecture.
231 .. option:: -name=<NAME>
233 Show code coverage only for functions with the given name.
235 .. option:: -name-regex=<PATTERN>
237 Show code coverage only for functions that match the given regular expression.
239 .. option:: -line-coverage-gt=<N>
241 Show code coverage only for functions with line coverage greater than the
244 .. option:: -line-coverage-lt=<N>
246 Show code coverage only for functions with line coverage less than the given
249 .. option:: -region-coverage-gt=<N>
251 Show code coverage only for functions with region coverage greater than the
254 .. option:: -region-coverage-lt=<N>
256 Show code coverage only for functions with region coverage less than the given
259 .. program:: llvm-cov report
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
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*.
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.
282 For information on compiling programs for coverage and generating profile data,
283 see :ref:`llvm-cov-show`.
288 .. option:: -use-color[=VALUE]
290 Enable or disable color output. By default this is autodetected.
292 .. option:: -arch=<name>
294 If the covered binary is a universal binary, select the architecture to use
295 when looking up the coverage map. Errors out if the supplied architecture is
296 not found in the universal binary, or if used on a non-universal binary of
297 a different architecture.