601 lines · plain
1llvm-cov - emit coverage information2====================================3 4.. program:: llvm-cov5 6SYNOPSIS7--------8 9:program:`llvm-cov` *command* [*args...*]10 11DESCRIPTION12-----------13 14The :program:`llvm-cov` tool shows code coverage information for15programs that are instrumented to emit profile data. It can be used to16work with ``gcov``\-style coverage or with ``clang``\'s instrumentation17based profiling.18 19If the program is invoked with a base name of ``gcov``, it will behave as if20the :program:`llvm-cov gcov` command were called. Otherwise, a command should21be provided.22 23COMMANDS24--------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 gcov32 33.. _llvm-cov-gcov:34 35GCOV COMMAND36------------37 38SYNOPSIS39^^^^^^^^40 41:program:`llvm-cov gcov` [*options*] *SOURCEFILE*42 43DESCRIPTION44^^^^^^^^^^^45 46The :program:`llvm-cov gcov` tool reads code coverage data files and displays47the coverage information for a specified source file. It is compatible with the48``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some49later versions of ``gcov``.50 51To use :program:`llvm-cov gcov`, you must first build an instrumented version52of your application that collects coverage data as it runs. Compile with the53``-fprofile-arcs`` and ``-ftest-coverage`` options to add the54instrumentation. (Alternatively, you can use the ``--coverage`` option, which55includes both of those other options.)56 57At the time you compile the instrumented code, a ``.gcno`` data file will be58generated for each object file. These ``.gcno`` files contain half of the59coverage data. The other half of the data comes from ``.gcda`` files that are60generated when you run the instrumented program, with a separate ``.gcda``61file for each object file. Each time you run the program, the execution counts62are summed into any existing ``.gcda`` files, so be sure to remove any old63files if you do not want their contents to be included.64 65By default, the ``.gcda`` files are written into the same directory as the66object files, but you can override that by setting the ``GCOV_PREFIX`` and67``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP``68variable specifies a number of directory components to be removed from the69start of the absolute path to the object file directory. After stripping those70directories, the prefix from the ``GCOV_PREFIX`` variable is added. These71environment variables allow you to run the instrumented program on a machine72where the original object file directories are not accessible, but you will73then need to copy the ``.gcda`` files back to the object file directories74where :program:`llvm-cov gcov` expects to find them.75 76Once you have generated the coverage data files, run :program:`llvm-cov gcov`77for each main source file where you want to examine the coverage results. This78should be run from the same directory where you previously ran the79compiler. The results for the specified source file are written to a file named80by appending a ``.gcov`` suffix. A separate output file is also created for81each file included by the main source file, also with a ``.gcov`` suffix added.82 83The basic content of an ``.gcov`` output file is a copy of the source file with84an execution count and line number prepended to every line. The execution85count is shown as ``-`` if a line does not contain any executable code. If86a line contains code but that code was never executed, the count is displayed87as ``#####``.88 89OPTIONS90^^^^^^^91 92.. option:: -a, --all-blocks93 94 Display all basic blocks. If there are multiple blocks for a single line of95 source code, this option causes llvm-cov to show the count for each block96 instead of just one count for the entire line.97 98.. option:: -b, --branch-probabilities99 100 Display conditional branch probabilities and a summary of branch information.101 102.. option:: -c, --branch-counts103 104 Display branch counts instead of probabilities (requires -b).105 106.. option:: -m, --demangled-names107 108 Demangle function names.109 110.. option:: -f, --function-summaries111 112 Show a summary of coverage for each function instead of just one summary for113 an entire source file.114 115.. option:: --help116 117 Display available options (--help-hidden for more).118 119.. option:: -l, --long-file-names120 121 For coverage output of files included from the main source file, add the122 main file name followed by ``##`` as a prefix to the output file names. This123 can be combined with the --preserve-paths option to use complete paths for124 both the main file and the included file.125 126.. option:: -n, --no-output127 128 Do not output any ``.gcov`` files. Summary information is still129 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 particular134 object file, the coverage data files are expected to have the same base name135 with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the136 files are expected in that directory with the same base name as the source137 file.138 139.. option:: -p, --preserve-paths140 141 Preserve path components when naming the coverage output files. In addition142 to the source file name, include the directories from the path to that143 file. The directories are separate by ``#`` characters, with ``.`` directories144 removed and ``..`` directories replaced by ``^`` characters. When used with145 the --long-file-names option, this applies to both the main file name and the146 included file name.147 148.. option:: -r149 150 Only dump files with relative paths or absolute paths with the prefix specified151 by ``-s``.152 153.. option:: -s <string>154 155 Source prefix to elide.156 157.. option:: -t, --stdout158 159 Print to stdout instead of producing ``.gcov`` files.160 161.. option:: -u, --unconditional-branches162 163 Include unconditional branches in the output for the --branch-probabilities164 option.165 166.. option:: -version167 168 Display the version of llvm-cov.169 170.. option:: -x, --hash-filenames171 172 Use md5 hash of file name when naming the coverage output files. The source173 file name will be suffixed by ``##`` followed by MD5 hash calculated for it.174 175EXIT STATUS176^^^^^^^^^^^177 178:program:`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise,179it exits with zero.180 181.. program:: llvm-cov show182 183.. _llvm-cov-show:184 185SHOW COMMAND186------------187 188SYNOPSIS189^^^^^^^^190 191:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...192 193DESCRIPTION194^^^^^^^^^^^195 196The :program:`llvm-cov show` command shows line by line coverage of the197binaries *BIN*... using the profile data *PROFILE*. It can optionally be198filtered to only show the coverage for the files listed in *SOURCE*....199 200*BIN* may be an executable, object file, dynamic library, or archive (thin or201otherwise).202 203To use :program:`llvm-cov show`, you need a program that is compiled with204instrumentation to emit profile and coverage data. To build such a program with205``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``206flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``207to the link stage to make sure the necessary runtime libraries are linked in.208 209The coverage information is stored in the built executable or library itself,210and this is what you should pass to :program:`llvm-cov show` as a *BIN*211argument. The profile data is generated by running this instrumented program212normally. When the program exits it will write out a raw profile file,213typically called ``default.profraw``, which can be converted to a format that214is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`215tool.216 217OPTIONS218^^^^^^^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-mcdc226 227 Show modified condition/decision coverage (MC/DC) for each applicable boolean228 expression.229 230.. option:: -show-line-counts231 232 Show the execution counts for each line. Defaults to true, unless another233 ``-show`` option is used.234 235.. option:: -show-expansions236 237 Expand inclusions, such as preprocessor macros or textual inclusions, inline238 in the display of the source file. Defaults to false.239 240.. option:: -show-instantiations241 242 For source regions that are instantiated multiple times, such as templates in243 ``C++``, show each instantiation separately as well as the combined summary.244 Defaults to true.245 246.. option:: -show-regions247 248 Show the execution counts for each region by displaying a caret that points to249 the character where the region starts. Defaults to false.250 251.. option:: -show-line-counts-or-regions252 253 Show the execution counts for each line if there is only one region on the254 line, but show the individual regions if there are multiple on the line.255 Defaults to false.256 257.. option:: -show-directory-coverage258 259 Generate an index file in each directory that contains at least one source260 file with a top level index showing aggregates. Defaults to false.261 262.. option:: -use-color263 264 Enable or disable color output. By default this is autodetected.265 266.. option:: -arch=[*NAMES*]267 268 Specify a list of architectures such that the Nth entry in the list269 corresponds to the Nth specified binary. If the covered object is a universal270 binary, this specifies the architecture to use. It is an error to specify an271 architecture that is not included in the universal binary or to use an272 architecture that does not match a non-universal binary.273 274.. option:: -name=<NAME>275 276 Show code coverage only for functions with the given name.277 278.. option:: -name-allowlist=<FILE>279 280 Show code coverage only for functions listed in the given file. Each line in281 the file should start with `allowlist_fun:`, immediately followed by the name282 of the function to accept. This name can be a wildcard expression.283 284.. option:: -name-regex=<PATTERN>285 286 Show code coverage only for functions that match the given regular expression.287 288.. option:: -ignore-filename-regex=<PATTERN>289 290 Skip source code files with file paths that match the given regular expression.291 292.. option:: -format=<FORMAT>293 294 Use the specified output format. The supported formats are: "text", "html".295 296.. option:: -tab-size=<TABSIZE>297 298 Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is299 only supported for the html format.300 301.. option:: -output-dir=PATH302 303 Specify a directory to write coverage reports into. If the directory does not304 exist, it is created. When used in function view mode (i.e when -name or305 -name-regex are used to select specific functions), the report is written to306 PATH/functions.EXTENSION. When used in file view mode, a report for each file307 is written to PATH/REL_PATH_TO_FILE.EXTENSION.308 309.. option:: -Xdemangler=<TOOL>|<TOOL-OPTION>310 311 Specify a symbol demangler. This can be used to make reports more312 human-readable. This option can be specified multiple times to supply313 arguments to the demangler (e.g `-Xdemangler c++filt -Xdemangler -n` for C++).314 The demangler is expected to read a newline-separated list of symbols from315 stdin and write a newline-separated list of the same length to stdout.316 317.. option:: -num-threads=N, -j=N318 319 Use N threads to write file reports (only applicable when -output-dir is320 specified). When N=0, llvm-cov auto-detects an appropriate number of threads to321 use. This is the default.322 323.. option:: -compilation-dir=<dir>324 325 Directory used as a base for relative coverage mapping paths. Only applicable326 when binaries have been compiled with one of `-fcoverage-prefix-map`327 `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.328 329.. option:: -line-coverage-gt=<N>330 331 Show code coverage only for functions with line coverage greater than the332 given threshold.333 334.. option:: -line-coverage-lt=<N>335 336 Show code coverage only for functions with line coverage less than the given337 threshold.338 339.. option:: -region-coverage-gt=<N>340 341 Show code coverage only for functions with region coverage greater than the342 given threshold.343 344.. option:: -region-coverage-lt=<N>345 346 Show code coverage only for functions with region coverage less than the given347 threshold.348 349.. option:: -path-equivalence=<from>,<to>350 351 Map the paths in the coverage data to local source file paths. This allows you352 to generate the coverage data on one machine, and then use llvm-cov on a353 different machine where you have the same files on a different path. Multiple354 `-path-equivalence` arguments can be passed to specify different mappings. Each355 argument consists of a source path `<from>` and its corresponding local path `<to>`.356 The mappings are applied in the order they are specified. If multiple mappings can357 be applied to a single path, the first mapping encountered is used.358 359.. option:: -coverage-watermark=<high>,<low>360 361 Set high and low watermarks for coverage in html format output. This allows you362 to set the high and low watermark of coverage as desired, green when363 coverage >= high, red when coverage < low, and yellow otherwise. Both high and364 low should be between 0-100 and high > low.365 366.. option:: -debuginfod367 368 Use debuginfod to look up coverage mapping for binary IDs present in the369 profile but not in any object given on the command line. Defaults to true if370 debuginfod is compiled in and configured via the DEBUGINFOD_URLS environment371 variable.372 373.. option:: -debug-file-directory=<dir>374 375 Provides local directories to search for objects corresponding to binary IDs in376 the profile (as with debuginfod). Defaults to system build ID directories.377 378.. option:: -check-binary-ids379 380 Fail if an object file cannot be found for a binary ID present in the profile,381 neither on the command line nor via binary ID lookup.382 383.. option:: -empty-profile384 385 Display the baseline coverage of the binaries with all zero execution counts.386 Mutually exclusive with -instr-profile.387 388.. program:: llvm-cov report389 390.. _llvm-cov-report:391 392REPORT COMMAND393--------------394 395SYNOPSIS396^^^^^^^^397 398:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...399 400DESCRIPTION401^^^^^^^^^^^402 403The :program:`llvm-cov report` command displays a summary of the coverage of404the binaries *BIN*... using the profile data *PROFILE*. It can optionally be405filtered to only show the coverage for the files listed in *SOURCE*....406 407*BIN* may be an executable, object file, dynamic library, or archive (thin or408otherwise).409 410If no source files are provided, a summary line is printed for each file in the411coverage data. If any files are provided, summaries can be shown for each412function in the listed files if the ``-show-functions`` option is enabled.413 414For information on compiling programs for coverage and generating profile data,415see :ref:`llvm-cov-show`.416 417OPTIONS418^^^^^^^419 420.. option:: -use-color[=VALUE]421 422 Enable or disable color output. By default this is autodetected.423 424.. option:: -arch=<name>425 426 If the covered binary is a universal binary, select the architecture to use.427 It is an error to specify an architecture that is not included in the428 universal binary or to use an architecture that does not match a429 non-universal binary.430 431.. option:: -show-region-summary432 433 Show statistics for all regions. Defaults to true.434 435.. option:: -show-branch-summary436 437 Show statistics for all branch conditions. Defaults to true.438 439.. option:: -show-mcdc-summary440 441 Show MC/DC statistics. Defaults to false.442 443.. option:: -show-functions444 445 Show coverage summaries for each function. Defaults to false.446 447.. option:: -show-instantiation-summary448 449 Show statistics for all function instantiations. Defaults to false.450 451.. option:: -ignore-filename-regex=<PATTERN>452 453 Skip source code files with file paths that match the given regular expression.454 455.. option:: -compilation-dir=<dir>456 457 Directory used as a base for relative coverage mapping paths. Only applicable458 when binaries have been compiled with one of `-fcoverage-prefix-map`459 `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.460 461.. option:: -debuginfod462 463 Attempt to look up coverage mapping from objects using debuginfod. This is464 attempted by default for binary IDs present in the profile but not provided on465 the command line, so long as debuginfod is compiled in and configured via466 DEBUGINFOD_URLS.467 468.. option:: -debug-file-directory=<dir>469 470 Provides a directory to search for objects corresponding to binary IDs in the471 profile.472 473.. option:: -check-binary-ids474 475 Fail if an object file cannot be found for a binary ID present in the profile,476 neither on the command line nor via binary ID lookup.477 478.. option:: -empty-profile479 480 Display the baseline coverage of the binaries with all zero execution counts.481 Mutually exclusive with -instr-profile.482 483.. program:: llvm-cov export484 485.. _llvm-cov-export:486 487EXPORT COMMAND488--------------489 490SYNOPSIS491^^^^^^^^492 493:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...494 495DESCRIPTION496^^^^^^^^^^^497 498The :program:`llvm-cov export` command exports coverage data of the binaries499*BIN*... using the profile data *PROFILE* in either JSON or lcov trace file500format.501 502When exporting JSON, the regions, functions, branches, expansions, and503summaries of the coverage data will be exported. When exporting an lcov trace504file, the line-based coverage, branch coverage, and summaries will be exported.505 506The exported data can optionally be filtered to only export the coverage507for the files listed in *SOURCE*....508 509For information on compiling programs for coverage and generating profile data,510see :ref:`llvm-cov-show`.511 512OPTIONS513^^^^^^^514 515.. option:: -arch=<name>516 517 If the covered binary is a universal binary, select the architecture to use.518 It is an error to specify an architecture that is not included in the519 universal binary or to use an architecture that does not match a520 non-universal binary.521 522.. option:: -format=<FORMAT>523 524 Use the specified output format. The supported formats are: "text" (JSON),525 "lcov".526 527.. option:: -summary-only528 529 Export only summary information for each file in the coverage data. This mode530 will not export coverage information for smaller units such as individual531 functions or regions. The result will contain the same information as produced532 by the :program:`llvm-cov report` command, but presented in JSON or lcov533 format rather than text.534 535.. option:: -ignore-filename-regex=<PATTERN>536 537 Skip source code files with file paths that match the given regular expression.538 539.. option:: -skip-expansions540 541 Skip exporting macro expansion coverage data.542 543.. option:: -skip-functions544 545 Skip exporting per-function coverage data.546 547.. option:: -num-threads=N, -j=N548 549 Use N threads to export coverage data. When N=0, llvm-cov auto-detects an550 appropriate number of threads to use. This is the default.551 552.. option:: -compilation-dir=<dir>553 554 Directory used as a base for relative coverage mapping paths. Only applicable555 when binaries have been compiled with one of `-fcoverage-prefix-map`556 `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.557 558.. option:: -debuginfod559 560 Attempt to look up coverage mapping from objects using debuginfod. This is561 attempted by default for binary IDs present in the profile but not provided on562 the command line, so long as debuginfod is compiled in and configured via563 DEBUGINFOD_URLS.564 565.. option:: -debug-file-directory=<dir>566 567 Provides a directory to search for objects corresponding to binary IDs in the568 profile.569 570.. option:: -check-binary-ids571 572 Fail if an object file cannot be found for a binary ID present in the profile,573 neither on the command line nor via binary ID lookup.574 575.. option:: -empty-profile576 577 Export the baseline coverage of the binaries with all zero execution counts.578 Mutually exclusive with -instr-profile.579 580CONVERT-FOR-TESTING COMMAND581---------------------------582 583.. warning::584 This command is for the LLVM developers who are working on ``llvm-cov`` only.585 586SYNOPSIS587^^^^^^^^588 589:program:`llvm-cov convert-for-testing` *BIN* -o *OUT*590 591DESCRIPTION592^^^^^^^^^^^593 594The :program:`llvm-cov convert-for-testing` command serves the purpose of595testing `llvm-cov` itself. It can extract all code coverage data from the596binary *BIN* to the file *OUT*, thereby reducing the size of test files. The597output file typically bears the :program:`.covmapping` extension.598 599The :program:`.covmapping` files can be read back by ``llvm-cov`` just as600ordinary binary files.601