docs/CommandGuide/llvm-cov.rst

   1 llvm-cov - emit coverage information
   2 ====================================
   3
   4 SYNOPSIS
   5 --------
   6
   7 :program:`llvm-cov` *command* [*args...*]
   8
   9 DESCRIPTION
  10 -----------
  11
  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
  29
  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
  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
  73 where :program:`llvm-cov gcov` expects to find them.
  74
  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.
  81
  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
  86 as ``#####``.
  87
  88 OPTIONS
  89 ^^^^^^^
  90
  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
  99  Display conditional branch probabilities and a summary of branch information.
 100
 101 .. option:: -c, --branch-counts
 102
 103  Display branch counts instead of probabilities (requires -b).
 104
 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
 111
 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.
 120
 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
 135
 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.
 142
 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.
 151
 152 EXIT STATUS
 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'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.
 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>
 225
 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.
 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
 260
 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  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.