1llvm-cov - emit coverage information 2==================================== 3 4SYNOPSIS 5-------- 6 7:program:`llvm-cov` *command* [*args...*] 8 9DESCRIPTION 10----------- 11 12The :program:`llvm-cov` tool shows code coverage information for 13programs that are instrumented to emit profile data. It can be used to 14work with ``gcov``\-style coverage or with ``clang``\'s instrumentation 15based profiling. 16 17If the program is invoked with a base name of ``gcov``, it will behave as if 18the :program:`llvm-cov gcov` command were called. Otherwise, a command should 19be provided. 20 21COMMANDS 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 33GCOV COMMAND 34------------ 35 36SYNOPSIS 37^^^^^^^^ 38 39:program:`llvm-cov gcov` [*options*] *SOURCEFILE* 40 41DESCRIPTION 42^^^^^^^^^^^ 43 44The :program:`llvm-cov gcov` tool reads code coverage data files and displays 45the 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 47later versions of ``gcov``. 48 49To use :program:`llvm-cov gcov`, you must first build an instrumented version 50of your application that collects coverage data as it runs. Compile with the 51``-fprofile-arcs`` and ``-ftest-coverage`` options to add the 52instrumentation. (Alternatively, you can use the ``--coverage`` option, which 53includes both of those other options.) You should compile with debugging 54information (``-g``) and without optimization (``-O0``); otherwise, the 55coverage data cannot be accurately mapped back to the source code. 56 57At the time you compile the instrumented code, a ``.gcno`` data file will be 58generated for each object file. These ``.gcno`` files contain half of the 59coverage data. The other half of the data comes from ``.gcda`` files that are 60generated when you run the instrumented program, with a separate ``.gcda`` 61file for each object file. Each time you run the program, the execution counts 62are summed into any existing ``.gcda`` files, so be sure to remove any old 63files if you do not want their contents to be included. 64 65By default, the ``.gcda`` files are written into the same directory as the 66object files, but you can override that by setting the ``GCOV_PREFIX`` and 67``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP`` 68variable specifies a number of directory components to be removed from the 69start of the absolute path to the object file directory. After stripping those 70directories, the prefix from the ``GCOV_PREFIX`` variable is added. These 71environment variables allow you to run the instrumented program on a machine 72where the original object file directories are not accessible, but you will 73then need to copy the ``.gcda`` files back to the object file directories 74where :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. This 78should be run from the same directory where you previously ran the 79compiler. The results for the specified source file are written to a file named 80by appending a ``.gcov`` suffix. A separate output file is also created for 81each 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 with 84an execution count and line number prepended to every line. The execution 85count is shown as ``-`` if a line does not contain any executable code. If 86a line contains code but that code was never executed, the count is displayed 87as ``#####``. 88 89OPTIONS 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 153EXIT STATUS 154^^^^^^^^^^^ 155 156:program:`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise, 157it exits with zero. 158 159 160.. program:: llvm-cov show 161 162.. _llvm-cov-show: 163 164SHOW COMMAND 165------------ 166 167SYNOPSIS 168^^^^^^^^ 169 170:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*] 171 172DESCRIPTION 173^^^^^^^^^^^ 174 175The :program:`llvm-cov show` command shows line by line coverage of the 176binaries *BIN*,... using the profile data *PROFILE*. It can optionally be 177filtered to only show the coverage for the files listed in *SOURCES*. 178 179To use :program:`llvm-cov show`, you need a program that is compiled with 180instrumentation to emit profile and coverage data. To build such a program with 181``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping`` 182flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate`` 183to the link stage to make sure the necessary runtime libraries are linked in. 184 185The coverage information is stored in the built executable or library itself, 186and this is what you should pass to :program:`llvm-cov show` as a *BIN* 187argument. The profile data is generated by running this instrumented program 188normally. When the program exits it will write out a raw profile file, 189typically called ``default.profraw``, which can be converted to a format that 190is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge` 191tool. 192 193OPTIONS 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 314REPORT COMMAND 315-------------- 316 317SYNOPSIS 318^^^^^^^^ 319 320:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*] 321 322DESCRIPTION 323^^^^^^^^^^^ 324 325The :program:`llvm-cov report` command displays a summary of the coverage of 326the binaries *BIN*,... using the profile data *PROFILE*. It can optionally be 327filtered to only show the coverage for the files listed in *SOURCES*. 328 329If no source files are provided, a summary line is printed for each file in the 330coverage data. If any files are provided, summaries can be shown for each 331function in the listed files if the ``-show-functions`` option is enabled. 332 333For information on compiling programs for coverage and generating profile data, 334see :ref:`llvm-cov-show`. 335 336OPTIONS 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 366EXPORT COMMAND 367-------------- 368 369SYNOPSIS 370^^^^^^^^ 371 372:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*] 373 374DESCRIPTION 375^^^^^^^^^^^ 376 377The :program:`llvm-cov export` command exports regions, functions, expansions, 378and summaries of the coverage of the binaries *BIN*,... using the profile data 379*PROFILE* as JSON. It can optionally be filtered to only export the coverage 380for the files listed in *SOURCES*. 381 382For information on compiling programs for coverage and generating profile data, 383see :ref:`llvm-cov-show`. 384 385OPTIONS 386^^^^^^^ 387 388.. option:: -arch=<name> 389 390 If the covered binary is a universal binary, select the architecture to use. 391 It is an error to specify an architecture that is not included in the 392 universal binary or to use an architecture that does not match a 393 non-universal binary. 394 395.. option:: -summary-only 396 397 Export only summary information for each file in the coverage data. This mode 398 will not export coverage information for smaller units such as individual 399 functions or regions. The result will be the same as produced by :program: 400 `llvm-cov report` command, but presented in JSON format rather than text. 401 402.. option:: -ignore-filename-regex=<PATTERN> 403 404 Skip source code files with file paths that match the given regular expression. 405