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 * :ref:`export <llvm-cov-export>`
  28
  29 .. program:: llvm-cov gcov
  30
  31 .. _llvm-cov-gcov:
  32
  33 GCOV COMMAND
  34 ------------
  35
  36 SYNOPSIS
  37 ^^^^^^^^
  38
  39 :program:`llvm-cov gcov` [*options*] *SOURCEFILE*
  40
  41 DESCRIPTION
  42 ^^^^^^^^^^^
  43
  44 The :program:`llvm-cov gcov` tool reads code coverage data files and displays
  45 the coverage information for a specified source file. It is compatible with the
  46 ``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
  47 later versions of ``gcov``.
  48
  49 To use :program:`llvm-cov gcov`, you must first build an instrumented version
  50 of your application that collects coverage data as it runs. Compile with the
  51 ``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
  52 instrumentation. (Alternatively, you can use the ``--coverage`` option, which
  53 includes both of those other options.) You should compile with debugging
  54 information (``-g``) and without optimization (``-O0``); otherwise, the
  55 coverage data cannot be accurately mapped back to the source code.
  56
  57 At the time you compile the instrumented code, a ``.gcno`` data file will be
  58 generated for each object file. These ``.gcno`` files contain half of the
  59 coverage data. The other half of the data comes from ``.gcda`` files that are
  60 generated when you run the instrumented program, with a separate ``.gcda``
  61 file for each object file. Each time you run the program, the execution counts
  62 are summed into any existing ``.gcda`` files, so be sure to remove any old
  63 files if you do not want their contents to be included.
  64
  65 By default, the ``.gcda`` files are written into the same directory as the
  66 object files, but you can override that by setting the ``GCOV_PREFIX`` and
  67 ``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP``
  68 variable specifies a number of directory components to be removed from the
  69 start of the absolute path to the object file directory. After stripping those
  70 directories, the prefix from the ``GCOV_PREFIX`` variable is added. These
  71 environment variables allow you to run the instrumented program on a machine
  72 where the original object file directories are not accessible, but you will
  73 then need to copy the ``.gcda`` files back to the object file directories
  74 where :program:`llvm-cov gcov` expects to find them.
  75
  76 Once you have generated the coverage data files, run :program:`llvm-cov gcov`
  77 for each main source file where you want to examine the coverage results. This
  78 should be run from the same directory where you previously ran the
  79 compiler. The results for the specified source file are written to a file named
  80 by appending a ``.gcov`` suffix. A separate output file is also created for
  81 each file included by the main source file, also with a ``.gcov`` suffix added.
  82
  83 The basic content of an ``.gcov`` output file is a copy of the source file with
  84 an execution count and line number prepended to every line. The execution
  85 count is shown as ``-`` if a line does not contain any executable code. If
  86 a line contains code but that code was never executed, the count is displayed
  87 as ``#####``.
  88
  89 OPTIONS
  90 ^^^^^^^
  91
  92 .. option:: -a, --all-blocks
  93
  94  Display all basic blocks. If there are multiple blocks for a single line of
  95  source code, this option causes llvm-cov to show the count for each block
  96  instead of just one count for the entire line.
  97
  98 .. option:: -b, --branch-probabilities
  99
 100  Display conditional branch probabilities and a summary of branch information.
 101
 102 .. option:: -c, --branch-counts
 103
 104  Display branch counts instead of probabilities (requires -b).
 105
 106 .. option:: -f, --function-summaries
 107
 108  Show a summary of coverage for each function instead of just one summary for
 109  an entire source file.
 110
 111 .. option:: --help
 112
 113  Display available options (--help-hidden for more).
 114
 115 .. option:: -l, --long-file-names
 116
 117  For coverage output of files included from the main source file, add the
 118  main file name followed by ``##`` as a prefix to the output file names. This
 119  can be combined with the --preserve-paths option to use complete paths for
 120  both the main file and the included file.
 121
 122 .. option:: -n, --no-output
 123
 124  Do not output any ``.gcov`` files. Summary information is still
 125  displayed.
 126
 127 .. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
 128
 129  Find objects in DIR or based on FILE's path. If you specify a particular
 130  object file, the coverage data files are expected to have the same base name
 131  with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the
 132  files are expected in that directory with the same base name as the source
 133  file.
 134
 135 .. option:: -p, --preserve-paths
 136
 137  Preserve path components when naming the coverage output files. In addition
 138  to the source file name, include the directories from the path to that
 139  file. The directories are separate by ``#`` characters, with ``.`` directories
 140  removed and ``..`` directories replaced by ``^`` characters. When used with
 141  the --long-file-names option, this applies to both the main file name and the
 142  included file name.
 143
 144 .. option:: -u, --unconditional-branches
 145
 146  Include unconditional branches in the output for the --branch-probabilities
 147  option.
 148
 149 .. option:: -version
 150
 151  Display the version of llvm-cov.
 152
 153 EXIT STATUS
 154 ^^^^^^^^^^^
 155
 156 :program:`llvm-cov gcov` returns 1 if it cannot read input files.  Otherwise,
 157 it exits with zero.
 158
 159
 160 .. program:: llvm-cov show
 161
 162 .. _llvm-cov-show:
 163
 164 SHOW COMMAND
 165 ------------
 166
 167 SYNOPSIS
 168 ^^^^^^^^
 169
 170 :program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
 171
 172 DESCRIPTION
 173 ^^^^^^^^^^^
 174
 175 The :program:`llvm-cov show` command shows line by line coverage of the
 176 binaries *BIN*,...  using the profile data *PROFILE*. It can optionally be
 177 filtered to only show the coverage for the files listed in *SOURCES*.
 178
 179 To use :program:`llvm-cov show`, you need a program that is compiled with
 180 instrumentation to emit profile and coverage data. To build such a program with
 181 ``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
 182 flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
 183 to the link stage to make sure the necessary runtime libraries are linked in.
 184
 185 The coverage information is stored in the built executable or library itself,
 186 and this is what you should pass to :program:`llvm-cov show` as a *BIN*
 187 argument. The profile data is generated by running this instrumented program
 188 normally. When the program exits it will write out a raw profile file,
 189 typically called ``default.profraw``, which can be converted to a format that
 190 is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
 191 tool.
 192
 193 OPTIONS
 194 ^^^^^^^
 195
 196 .. option:: -show-line-counts
 197
 198  Show the execution counts for each line. This is enabled by default, unless
 199  another ``-show`` option is used.
 200
 201 .. option:: -show-expansions
 202
 203  Expand inclusions, such as preprocessor macros or textual inclusions, inline
 204  in the display of the source file.
 205
 206 .. option:: -show-instantiations
 207
 208  For source regions that are instantiated multiple times, such as templates in
 209  ``C++``, show each instantiation separately as well as the combined summary.
 210  This option is enabled by default.
 211
 212 .. option:: -show-regions
 213
 214  Show the execution counts for each region by displaying a caret that points to
 215  the character where the region starts.
 216
 217 .. option:: -show-line-counts-or-regions
 218
 219  Show the execution counts for each line if there is only one region on the
 220  line, but show the individual regions if there are multiple on the line.
 221
 222 .. option:: -use-color[=VALUE]
 223
 224  Enable or disable color output. By default this is autodetected.
 225
 226 .. option:: -arch=[*NAMES*]
 227
 228  Specify a list of architectures such that the Nth entry in the list
 229  corresponds to the Nth specified binary. If the covered object is a universal
 230  binary, this specifies the architecture to use. It is an error to specify an
 231  architecture that is not included in the universal binary or to use an
 232  architecture that does not match a non-universal binary.
 233
 234 .. option:: -name=<NAME>
 235
 236  Show code coverage only for functions with the given name.
 237
 238 .. option:: -name-regex=<PATTERN>
 239
 240  Show code coverage only for functions that match the given regular expression.
 241
 242 .. option:: -format=<FORMAT>
 243
 244  Use the specified output format. The supported formats are: "text", "html".
 245
 246 .. option:: -tab-size=<TABSIZE>
 247
 248  Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
 249  only supported for the html format.
 250
 251 .. option:: -output-dir=PATH
 252
 253  Specify a directory to write coverage reports into. If the directory does not
 254  exist, it is created. When used in function view mode (i.e when -name or
 255  -name-regex are used to select specific functions), the report is written to
 256  PATH/functions.EXTENSION. When used in file view mode, a report for each file
 257  is written to PATH/REL_PATH_TO_FILE.EXTENSION.
 258
 259 .. option:: -Xdemangler=<TOOL>|<TOOL-OPTION>
 260
 261  Specify a symbol demangler. This can be used to make reports more
 262  human-readable. This option can be specified multiple times to supply
 263  arguments to the demangler (e.g `-Xdemangler c++filt -Xdemangler -n` for C++).
 264  The demangler is expected to read a newline-separated list of symbols from
 265  stdin and write a newline-separated list of the same length to stdout.
 266
 267 .. option:: -num-threads=N, -j=N
 268
 269  Use N threads to write file reports (only applicable when -output-dir is
 270  specified). When N=0, llvm-cov auto-detects an appropriate number of threads to
 271  use. This is the default.
 272
 273 .. option:: -line-coverage-gt=<N>
 274
 275  Show code coverage only for functions with line coverage greater than the
 276  given threshold.
 277
 278 .. option:: -line-coverage-lt=<N>
 279
 280  Show code coverage only for functions with line coverage less than the given
 281  threshold.
 282
 283 .. option:: -region-coverage-gt=<N>
 284
 285  Show code coverage only for functions with region coverage greater than the
 286  given threshold.
 287
 288 .. option:: -region-coverage-lt=<N>
 289
 290  Show code coverage only for functions with region coverage less than the given
 291  threshold.
 292
 293 .. program:: llvm-cov report
 294
 295 .. _llvm-cov-report:
 296
 297 REPORT COMMAND
 298 --------------
 299
 300 SYNOPSIS
 301 ^^^^^^^^
 302
 303 :program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
 304
 305 DESCRIPTION
 306 ^^^^^^^^^^^
 307
 308 The :program:`llvm-cov report` command displays a summary of the coverage of
 309 the binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
 310 filtered to only show the coverage for the files listed in *SOURCES*.
 311
 312 If no source files are provided, a summary line is printed for each file in the
 313 coverage data. If any files are provided, summaries are shown for each function
 314 in the listed files instead.
 315
 316 For information on compiling programs for coverage and generating profile data,
 317 see :ref:`llvm-cov-show`.
 318
 319 OPTIONS
 320 ^^^^^^^
 321
 322 .. option:: -use-color[=VALUE]
 323
 324  Enable or disable color output. By default this is autodetected.
 325
 326 .. option:: -arch=<name>
 327
 328  If the covered binary is a universal binary, select the architecture to use.
 329  It is an error to specify an architecture that is not included in the
 330  universal binary or to use an architecture that does not match a
 331  non-universal binary.
 332
 333 .. option:: -show-functions
 334
 335  Show coverage summaries for each function.
 336
 337 .. program:: llvm-cov export
 338
 339 .. _llvm-cov-export:
 340
 341 EXPORT COMMAND
 342 --------------
 343
 344 SYNOPSIS
 345 ^^^^^^^^
 346
 347 :program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]]
 348
 349 DESCRIPTION
 350 ^^^^^^^^^^^
 351
 352 The :program:`llvm-cov export` command exports regions, functions, expansions,
 353 and summaries of the coverage of the binaries *BIN*,... using the profile data
 354 *PROFILE* as JSON.
 355
 356 For information on compiling programs for coverage and generating profile data,
 357 see :ref:`llvm-cov-show`.
 358
 359 OPTIONS
 360 ^^^^^^^
 361
 362 .. option:: -arch=<name>
 363
 364  If the covered binary is a universal binary, select the architecture to use.
 365  It is an error to specify an architecture that is not included in the
 366  universal binary or to use an architecture that does not match a
 367  non-universal binary.