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. Defaults to true, unless another
 199  ``-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. Defaults to false.
 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  Defaults to true.
 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. Defaults to false.
 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  Defaults to false.
 222
 223 .. option:: -use-color
 224
 225  Enable or disable color output. By default this is autodetected.
 226
 227 .. option:: -arch=[*NAMES*]
 228
 229  Specify a list of architectures such that the Nth entry in the list
 230  corresponds to the Nth specified binary. If the covered object is a universal
 231  binary, this specifies the architecture to use. It is an error to specify an
 232  architecture that is not included in the universal binary or to use an
 233  architecture that does not match a non-universal binary.
 234
 235 .. option:: -name=<NAME>
 236
 237  Show code coverage only for functions with the given name.
 238
 239 .. option:: -name-whitelist=<FILE>
 240
 241  Show code coverage only for functions listed in the given file. Each line in
 242  the file should start with `whitelist_fun:`, immediately followed by the name
 243  of the function to accept. This name can be a wildcard expression.
 244
 245 .. option:: -name-regex=<PATTERN>
 246
 247  Show code coverage only for functions that match the given regular expression.
 248
 249 .. option:: -ignore-filename-regex=<PATTERN>
 250
 251  Skip source code files with file paths that match the given regular expression.
 252
 253 .. option:: -format=<FORMAT>
 254
 255  Use the specified output format. The supported formats are: "text", "html".
 256
 257 .. option:: -tab-size=<TABSIZE>
 258
 259  Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
 260  only supported for the html format.
 261
 262 .. option:: -output-dir=PATH
 263
 264  Specify a directory to write coverage reports into. If the directory does not
 265  exist, it is created. When used in function view mode (i.e when -name or
 266  -name-regex are used to select specific functions), the report is written to
 267  PATH/functions.EXTENSION. When used in file view mode, a report for each file
 268  is written to PATH/REL_PATH_TO_FILE.EXTENSION.
 269
 270 .. option:: -Xdemangler=<TOOL>|<TOOL-OPTION>
 271
 272  Specify a symbol demangler. This can be used to make reports more
 273  human-readable. This option can be specified multiple times to supply
 274  arguments to the demangler (e.g `-Xdemangler c++filt -Xdemangler -n` for C++).
 275  The demangler is expected to read a newline-separated list of symbols from
 276  stdin and write a newline-separated list of the same length to stdout.
 277
 278 .. option:: -num-threads=N, -j=N
 279
 280  Use N threads to write file reports (only applicable when -output-dir is
 281  specified). When N=0, llvm-cov auto-detects an appropriate number of threads to
 282  use. This is the default.
 283
 284 .. option:: -line-coverage-gt=<N>
 285
 286  Show code coverage only for functions with line coverage greater than the
 287  given threshold.
 288
 289 .. option:: -line-coverage-lt=<N>
 290
 291  Show code coverage only for functions with line coverage less than the given
 292  threshold.
 293
 294 .. option:: -region-coverage-gt=<N>
 295
 296  Show code coverage only for functions with region coverage greater than the
 297  given threshold.
 298
 299 .. option:: -region-coverage-lt=<N>
 300
 301  Show code coverage only for functions with region coverage less than the given
 302  threshold.
 303
 304 .. option:: -path-equivalence=<from>,<to>
 305
 306  Map the paths in the coverage data to local source file paths. This allows you
 307  to generate the coverage data on one machine, and then use llvm-cov on a
 308  different machine where you have the same files on a different path.
 309
 310 .. program:: llvm-cov report
 311
 312 .. _llvm-cov-report:
 313
 314 REPORT COMMAND
 315 --------------
 316
 317 SYNOPSIS
 318 ^^^^^^^^
 319
 320 :program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
 321
 322 DESCRIPTION
 323 ^^^^^^^^^^^
 324
 325 The :program:`llvm-cov report` command displays a summary of the coverage of
 326 the binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
 327 filtered to only show the coverage for the files listed in *SOURCES*.
 328
 329 If no source files are provided, a summary line is printed for each file in the
 330 coverage data. If any files are provided, summaries can be shown for each
 331 function in the listed files if the ``-show-functions`` option is enabled.
 332
 333 For information on compiling programs for coverage and generating profile data,
 334 see :ref:`llvm-cov-show`.
 335
 336 OPTIONS
 337 ^^^^^^^
 338
 339 .. option:: -use-color[=VALUE]
 340
 341  Enable or disable color output. By default this is autodetected.
 342
 343 .. option:: -arch=<name>
 344
 345  If the covered binary is a universal binary, select the architecture to use.
 346  It is an error to specify an architecture that is not included in the
 347  universal binary or to use an architecture that does not match a
 348  non-universal binary.
 349
 350 .. option:: -show-functions
 351
 352  Show coverage summaries for each function. Defaults to false.
 353
 354 .. option:: -show-instantiation-summary
 355
 356  Show statistics for all function instantiations. Defaults to false.
 357
 358 .. option:: -ignore-filename-regex=<PATTERN>
 359
 360  Skip source code files with file paths that match the given regular expression.
 361
 362 .. program:: llvm-cov export
 363
 364 .. _llvm-cov-export:
 365
 366 EXPORT COMMAND
 367 --------------
 368
 369 SYNOPSIS
 370 ^^^^^^^^
 371
 372 :program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
 373
 374 DESCRIPTION
 375 ^^^^^^^^^^^
 376
 377 The :program:`llvm-cov export` command exports coverage data of the binaries
 378 *BIN*,... using the profile data *PROFILE* in either JSON or lcov trace file
 379 format.
 380
 381 When exporting JSON, the regions, functions, expansions, and summaries of the
 382 coverage data will be exported. When exporting an lcov trace file, the
 383 line-based coverage and summaries will be exported.
 384
 385 The exported data can optionally be filtered to only export the coverage
 386 for the files listed in *SOURCES*.
 387
 388 For information on compiling programs for coverage and generating profile data,
 389 see :ref:`llvm-cov-show`.
 390
 391 OPTIONS
 392 ^^^^^^^
 393
 394 .. option:: -arch=<name>
 395
 396  If the covered binary is a universal binary, select the architecture to use.
 397  It is an error to specify an architecture that is not included in the
 398  universal binary or to use an architecture that does not match a
 399  non-universal binary.
 400
 401 .. option:: -format=<FORMAT>
 402
 403  Use the specified output format. The supported formats are: "text" (JSON),
 404  "lcov".
 405
 406 .. option:: -summary-only
 407
 408  Export only summary information for each file in the coverage data. This mode
 409  will not export coverage information for smaller units such as individual
 410  functions or regions. The result will contain the same information as produced
 411  by the :program:`llvm-cov report` command, but presented in JSON or lcov
 412  format rather than text.
 413
 414 .. option:: -ignore-filename-regex=<PATTERN>
 415
 416  Skip source code files with file paths that match the given regular expression.