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 regions, functions, expansions, 378 and 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 380 for the files listed in *SOURCES*. 381 382 For information on compiling programs for coverage and generating profile data, 383 see :ref:`llvm-cov-show`. 384 385 OPTIONS 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
