llvm/docs/CommandGuide/llvm-cov.rst

   1 llvm-cov - emit coverage information
   2 ====================================
   3
   4 .. program:: llvm-cov
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-cov` *command* [*args...*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 The :program:`llvm-cov` tool shows code coverage information for
  15 programs that are instrumented to emit profile data. It can be used to
  16 work with ``gcov``\-style coverage or with ``clang``\'s instrumentation
  17 based profiling.
  18
  19 If the program is invoked with a base name of ``gcov``, it will behave as if
  20 the :program:`llvm-cov gcov` command were called. Otherwise, a command should
  21 be provided.
  22
  23 COMMANDS
  24 --------
  25
  26 * :ref:`gcov <llvm-cov-gcov>`
  27 * :ref:`show <llvm-cov-show>`
  28 * :ref:`report <llvm-cov-report>`
  29 * :ref:`export <llvm-cov-export>`
  30
  31 .. program:: llvm-cov gcov
  32
  33 .. _llvm-cov-gcov:
  34
  35 GCOV COMMAND
  36 ------------
  37
  38 SYNOPSIS
  39 ^^^^^^^^
  40
  41 :program:`llvm-cov gcov` [*options*] *SOURCEFILE*
  42
  43 DESCRIPTION
  44 ^^^^^^^^^^^
  45
  46 The :program:`llvm-cov gcov` tool reads code coverage data files and displays
  47 the coverage information for a specified source file. It is compatible with the
  48 ``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
  49 later versions of ``gcov``.
  50
  51 To use :program:`llvm-cov gcov`, you must first build an instrumented version
  52 of your application that collects coverage data as it runs. Compile with the
  53 ``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
  54 instrumentation. (Alternatively, you can use the ``--coverage`` option, which
  55 includes both of those other options.)
  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:: -m, --demangled-names
 107
 108  Demangle function names.
 109
 110 .. option:: -f, --function-summaries
 111
 112  Show a summary of coverage for each function instead of just one summary for
 113  an entire source file.
 114
 115 .. option:: --help
 116
 117  Display available options (--help-hidden for more).
 118
 119 .. option:: -l, --long-file-names
 120
 121  For coverage output of files included from the main source file, add the
 122  main file name followed by ``##`` as a prefix to the output file names. This
 123  can be combined with the --preserve-paths option to use complete paths for
 124  both the main file and the included file.
 125
 126 .. option:: -n, --no-output
 127
 128  Do not output any ``.gcov`` files. Summary information is still
 129  displayed.
 130
 131 .. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
 132
 133  Find objects in DIR or based on FILE's path. If you specify a particular
 134  object file, the coverage data files are expected to have the same base name
 135  with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the
 136  files are expected in that directory with the same base name as the source
 137  file.
 138
 139 .. option:: -p, --preserve-paths
 140
 141  Preserve path components when naming the coverage output files. In addition
 142  to the source file name, include the directories from the path to that
 143  file. The directories are separate by ``#`` characters, with ``.`` directories
 144  removed and ``..`` directories replaced by ``^`` characters. When used with
 145  the --long-file-names option, this applies to both the main file name and the
 146  included file name.
 147
 148 .. option:: -r
 149
 150  Only dump files with relative paths or absolute paths with the prefix specified
 151  by ``-s``.
 152
 153 .. option:: -s=<string>
 154
 155  Source prefix to elide.
 156
 157 .. option:: -t, --stdout
 158
 159  Print to stdout instead of producing ``.gcov`` files.
 160
 161 .. option:: -u, --unconditional-branches
 162
 163  Include unconditional branches in the output for the --branch-probabilities
 164  option.
 165
 166 .. option:: -version
 167
 168  Display the version of llvm-cov.
 169
 170 .. option:: -x, --hash-filenames
 171
 172  Use md5 hash of file name when naming the coverage output files. The source
 173  file name will be suffixed by ``##`` followed by MD5 hash calculated for it.
 174
 175 EXIT STATUS
 176 ^^^^^^^^^^^
 177
 178 :program:`llvm-cov gcov` returns 1 if it cannot read input files.  Otherwise,
 179 it exits with zero.
 180
 181 .. program:: llvm-cov show
 182
 183 .. _llvm-cov-show:
 184
 185 SHOW COMMAND
 186 ------------
 187
 188 SYNOPSIS
 189 ^^^^^^^^
 190
 191 :program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
 192
 193 DESCRIPTION
 194 ^^^^^^^^^^^
 195
 196 The :program:`llvm-cov show` command shows line by line coverage of the
 197 binaries *BIN*,...  using the profile data *PROFILE*. It can optionally be
 198 filtered to only show the coverage for the files listed in *SOURCES*.
 199
 200 *BIN* may be an executable, object file, dynamic library, or archive (thin or
 201 otherwise).
 202
 203 To use :program:`llvm-cov show`, you need a program that is compiled with
 204 instrumentation to emit profile and coverage data. To build such a program with
 205 ``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
 206 flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
 207 to the link stage to make sure the necessary runtime libraries are linked in.
 208
 209 The coverage information is stored in the built executable or library itself,
 210 and this is what you should pass to :program:`llvm-cov show` as a *BIN*
 211 argument. The profile data is generated by running this instrumented program
 212 normally. When the program exits it will write out a raw profile file,
 213 typically called ``default.profraw``, which can be converted to a format that
 214 is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
 215 tool.
 216
 217 OPTIONS
 218 ^^^^^^^
 219
 220 .. option:: -show-branches=<VIEW>
 221
 222  Show coverage for branch conditions in terms of either count or percentage.
 223  The supported views are: "count", "percent".
 224
 225 .. option:: -show-line-counts
 226
 227  Show the execution counts for each line. Defaults to true, unless another
 228  ``-show`` option is used.
 229
 230 .. option:: -show-expansions
 231
 232  Expand inclusions, such as preprocessor macros or textual inclusions, inline
 233  in the display of the source file. Defaults to false.
 234
 235 .. option:: -show-instantiations
 236
 237  For source regions that are instantiated multiple times, such as templates in
 238  ``C++``, show each instantiation separately as well as the combined summary.
 239  Defaults to true.
 240
 241 .. option:: -show-regions
 242
 243  Show the execution counts for each region by displaying a caret that points to
 244  the character where the region starts. Defaults to false.
 245
 246 .. option:: -show-line-counts-or-regions
 247
 248  Show the execution counts for each line if there is only one region on the
 249  line, but show the individual regions if there are multiple on the line.
 250  Defaults to false.
 251
 252 .. option:: -use-color
 253
 254  Enable or disable color output. By default this is autodetected.
 255
 256 .. option:: -arch=[*NAMES*]
 257
 258  Specify a list of architectures such that the Nth entry in the list
 259  corresponds to the Nth specified binary. If the covered object is a universal
 260  binary, this specifies the architecture to use. It is an error to specify an
 261  architecture that is not included in the universal binary or to use an
 262  architecture that does not match a non-universal binary.
 263
 264 .. option:: -name=<NAME>
 265
 266  Show code coverage only for functions with the given name.
 267
 268 .. option:: -name-whitelist=<FILE>
 269
 270  Show code coverage only for functions listed in the given file. Each line in
 271  the file should start with `whitelist_fun:`, immediately followed by the name
 272  of the function to accept. This name can be a wildcard expression.
 273
 274 .. option:: -name-regex=<PATTERN>
 275
 276  Show code coverage only for functions that match the given regular expression.
 277
 278 .. option:: -ignore-filename-regex=<PATTERN>
 279
 280  Skip source code files with file paths that match the given regular expression.
 281
 282 .. option:: -format=<FORMAT>
 283
 284  Use the specified output format. The supported formats are: "text", "html".
 285
 286 .. option:: -tab-size=<TABSIZE>
 287
 288  Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
 289  only supported for the html format.
 290
 291 .. option:: -output-dir=PATH
 292
 293  Specify a directory to write coverage reports into. If the directory does not
 294  exist, it is created. When used in function view mode (i.e when -name or
 295  -name-regex are used to select specific functions), the report is written to
 296  PATH/functions.EXTENSION. When used in file view mode, a report for each file
 297  is written to PATH/REL_PATH_TO_FILE.EXTENSION.
 298
 299 .. option:: -Xdemangler=<TOOL>|<TOOL-OPTION>
 300
 301  Specify a symbol demangler. This can be used to make reports more
 302  human-readable. This option can be specified multiple times to supply
 303  arguments to the demangler (e.g `-Xdemangler c++filt -Xdemangler -n` for C++).
 304  The demangler is expected to read a newline-separated list of symbols from
 305  stdin and write a newline-separated list of the same length to stdout.
 306
 307 .. option:: -num-threads=N, -j=N
 308
 309  Use N threads to write file reports (only applicable when -output-dir is
 310  specified). When N=0, llvm-cov auto-detects an appropriate number of threads to
 311  use. This is the default.
 312
 313 .. option:: -compilation-dir=<dir>
 314
 315  Directory used as a base for relative coverage mapping paths. Only applicable
 316  when binaries have been compiled with one of `-fcoverage-prefix-map`
 317  `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.
 318
 319 .. option:: -line-coverage-gt=<N>
 320
 321  Show code coverage only for functions with line coverage greater than the
 322  given threshold.
 323
 324 .. option:: -line-coverage-lt=<N>
 325
 326  Show code coverage only for functions with line coverage less than the given
 327  threshold.
 328
 329 .. option:: -region-coverage-gt=<N>
 330
 331  Show code coverage only for functions with region coverage greater than the
 332  given threshold.
 333
 334 .. option:: -region-coverage-lt=<N>
 335
 336  Show code coverage only for functions with region coverage less than the given
 337  threshold.
 338
 339 .. option:: -path-equivalence=<from>,<to>
 340
 341  Map the paths in the coverage data to local source file paths. This allows you
 342  to generate the coverage data on one machine, and then use llvm-cov on a
 343  different machine where you have the same files on a different path.
 344
 345 .. program:: llvm-cov report
 346
 347 .. _llvm-cov-report:
 348
 349 REPORT COMMAND
 350 --------------
 351
 352 SYNOPSIS
 353 ^^^^^^^^
 354
 355 :program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
 356
 357 DESCRIPTION
 358 ^^^^^^^^^^^
 359
 360 The :program:`llvm-cov report` command displays a summary of the coverage of
 361 the binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
 362 filtered to only show the coverage for the files listed in *SOURCES*.
 363
 364 *BIN* may be an executable, object file, dynamic library, or archive (thin or
 365 otherwise).
 366
 367 If no source files are provided, a summary line is printed for each file in the
 368 coverage data. If any files are provided, summaries can be shown for each
 369 function in the listed files if the ``-show-functions`` option is enabled.
 370
 371 For information on compiling programs for coverage and generating profile data,
 372 see :ref:`llvm-cov-show`.
 373
 374 OPTIONS
 375 ^^^^^^^
 376
 377 .. option:: -use-color[=VALUE]
 378
 379  Enable or disable color output. By default this is autodetected.
 380
 381 .. option:: -arch=<name>
 382
 383  If the covered binary is a universal binary, select the architecture to use.
 384  It is an error to specify an architecture that is not included in the
 385  universal binary or to use an architecture that does not match a
 386  non-universal binary.
 387
 388 .. option:: -show-region-summary
 389
 390  Show statistics for all regions. Defaults to true.
 391
 392 .. option:: -show-branch-summary
 393
 394  Show statistics for all branch conditions. Defaults to true.
 395
 396 .. option:: -show-functions
 397
 398  Show coverage summaries for each function. Defaults to false.
 399
 400 .. option:: -show-instantiation-summary
 401
 402  Show statistics for all function instantiations. Defaults to false.
 403
 404 .. option:: -ignore-filename-regex=<PATTERN>
 405
 406  Skip source code files with file paths that match the given regular expression.
 407
 408 .. option:: -compilation-dir=<dir>
 409
 410  Directory used as a base for relative coverage mapping paths. Only applicable
 411  when binaries have been compiled with one of `-fcoverage-prefix-map`
 412  `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.
 413
 414 .. program:: llvm-cov export
 415
 416 .. _llvm-cov-export:
 417
 418 EXPORT COMMAND
 419 --------------
 420
 421 SYNOPSIS
 422 ^^^^^^^^
 423
 424 :program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
 425
 426 DESCRIPTION
 427 ^^^^^^^^^^^
 428
 429 The :program:`llvm-cov export` command exports coverage data of the binaries
 430 *BIN*,... using the profile data *PROFILE* in either JSON or lcov trace file
 431 format.
 432
 433 When exporting JSON, the regions, functions, branches, expansions, and
 434 summaries of the coverage data will be exported. When exporting an lcov trace
 435 file, the line-based coverage, branch coverage, and summaries will be exported.
 436
 437 The exported data can optionally be filtered to only export the coverage
 438 for the files listed in *SOURCES*.
 439
 440 For information on compiling programs for coverage and generating profile data,
 441 see :ref:`llvm-cov-show`.
 442
 443 OPTIONS
 444 ^^^^^^^
 445
 446 .. option:: -arch=<name>
 447
 448  If the covered binary is a universal binary, select the architecture to use.
 449  It is an error to specify an architecture that is not included in the
 450  universal binary or to use an architecture that does not match a
 451  non-universal binary.
 452
 453 .. option:: -format=<FORMAT>
 454
 455  Use the specified output format. The supported formats are: "text" (JSON),
 456  "lcov".
 457
 458 .. option:: -summary-only
 459
 460  Export only summary information for each file in the coverage data. This mode
 461  will not export coverage information for smaller units such as individual
 462  functions or regions. The result will contain the same information as produced
 463  by the :program:`llvm-cov report` command, but presented in JSON or lcov
 464  format rather than text.
 465
 466 .. option:: -ignore-filename-regex=<PATTERN>
 467
 468  Skip source code files with file paths that match the given regular expression.
 469
 470  .. option:: -skip-expansions
 471
 472  Skip exporting macro expansion coverage data.
 473
 474  .. option:: -skip-functions
 475
 476  Skip exporting per-function coverage data.
 477
 478  .. option:: -num-threads=N, -j=N
 479
 480  Use N threads to export coverage data. When N=0, llvm-cov auto-detects an
 481  appropriate number of threads to use. This is the default.
 482
 483 .. option:: -compilation-dir=<dir>
 484
 485  Directory used as a base for relative coverage mapping paths. Only applicable
 486  when binaries have been compiled with one of `-fcoverage-prefix-map`
 487  `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.