1LLVM-COV(1)                          LLVM                          LLVM-COV(1)
2
3
4

NAME

6       llvm-cov - emit coverage information
7

SYNOPSIS

9       llvm-cov command [args...]
10

DESCRIPTION

12       The llvm-cov tool shows code coverage information for programs that are
13       instrumented to emit  profile  data.  It  can  be  used  to  work  with
14       gcov-style coverage or with clang's instrumentation based profiling.
15
16       If  the  program is invoked with a base name of gcov, it will behave as
17       if the llvm-cov gcov command were called. Otherwise, a  command  should
18       be provided.
19

COMMANDS

21gcov
22
23show
24
25report
26
27export
28

GCOV COMMAND

30   SYNOPSIS
31       llvm-cov gcov [options] SOURCEFILE
32
33   DESCRIPTION
34       The  llvm-cov gcov tool reads code coverage data files and displays the
35       coverage information for a specified source file. It is compatible with
36       the  gcov  tool from version 4.2 of GCC and may also be compatible with
37       some later versions of gcov.
38
39       To use llvm-cov gcov, you must first build an instrumented  version  of
40       your  application  that collects coverage data as it runs. Compile with
41       the -fprofile-arcs and -ftest-coverage options to add the  instrumenta‐
42       tion. (Alternatively, you can use the --coverage option, which includes
43       both of those other options.)
44
45       At the time you compile the instrumented code, a .gcno data  file  will
46       be  generated  for  each object file. These .gcno files contain half of
47       the coverage data. The other half of the data comes  from  .gcda  files
48       that  are generated when you run the instrumented program, with a sepa‐
49       rate .gcda file for each object file. Each time you  run  the  program,
50       the  execution  counts  are summed into any existing .gcda files, so be
51       sure to remove any old files if you do not want their  contents  to  be
52       included.
53
54       By  default, the .gcda files are written into the same directory as the
55       object files, but you can override that by setting the GCOV_PREFIX  and
56       GCOV_PREFIX_STRIP environment variables. The GCOV_PREFIX_STRIP variable
57       specifies a number of directory components to be removed from the start
58       of  the  absolute  path  to  the object file directory. After stripping
59       those directories, the prefix from the GCOV_PREFIX variable  is  added.
60       These  environment  variables allow you to run the instrumented program
61       on a machine where the original object file directories are not  acces‐
62       sible,  but  you will then need to copy the .gcda files back to the ob‐
63       ject file directories where llvm-cov gcov expects to find them.
64
65       Once you have generated the coverage data files, run llvm-cov gcov  for
66       each  main  source file where you want to examine the coverage results.
67       This should be run from the same directory where you previously ran the
68       compiler.  The  results  for the specified source file are written to a
69       file named by appending a .gcov suffix. A separate output file is  also
70       created  for  each  file  included by the main source file, also with a
71       .gcov suffix added.
72
73       The basic content of an .gcov output file is a copy of the source  file
74       with  an  execution  count and line number prepended to every line. The
75       execution count is shown as - if a line does not contain any executable
76       code.  If  a  line  contains code but that code was never executed, the
77       count is displayed as #####.
78
79   OPTIONS
80       -a, --all-blocks
81              Display all basic blocks. If there are  multiple  blocks  for  a
82              single  line of source code, this option causes llvm-cov to show
83              the count for each block instead of just one count for  the  en‐
84              tire line.
85
86       -b, --branch-probabilities
87              Display conditional branch probabilities and a summary of branch
88              information.
89
90       -c, --branch-counts
91              Display branch counts instead of probabilities (requires -b).
92
93       -m, --demangled-names
94              Demangle function names.
95
96       -f, --function-summaries
97              Show a summary of coverage for each function instead of just one
98              summary for an entire source file.
99
100       --help Display available options (--help-hidden for more).
101
102       -l, --long-file-names
103              For coverage output of files included from the main source file,
104              add the main file name followed by ## as a prefix to the  output
105              file  names.  This can be combined with the --preserve-paths op‐
106              tion to use complete paths for both the main file  and  the  in‐
107              cluded file.
108
109       -n, --no-output
110              Do not output any .gcov files. Summary information is still dis‐
111              played.
112
113       -o <DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
114              Find objects in DIR or based on FILE's path. If  you  specify  a
115              particular  object file, the coverage data files are expected to
116              have the same base name with .gcno and .gcda extensions. If  you
117              specify  a  directory,  the files are expected in that directory
118              with the same base name as the source file.
119
120       -p, --preserve-paths
121              Preserve path components when naming the coverage output  files.
122              In  addition  to  the  source file name, include the directories
123              from the path to that file. The directories are  separate  by  #
124              characters,  with  .  directories removed and .. directories re‐
125              placed by ^ characters. When used with the --long-file-names op‐
126              tion,  this  applies to both the main file name and the included
127              file name.
128
129       -r     Only dump files with relative paths or absolute paths  with  the
130              prefix specified by -s.
131
132       -s <string>
133              Source prefix to elide.
134
135       -t, --stdout
136              Print to stdout instead of producing .gcov files.
137
138       -u, --unconditional-branches
139              Include   unconditional   branches   in   the   output  for  the
140              --branch-probabilities option.
141
142       -version
143              Display the version of llvm-cov.
144
145       -x, --hash-filenames
146              Use md5 hash of file name when naming the coverage output files.
147              The source file name will be suffixed by ## followed by MD5 hash
148              calculated for it.
149
150   EXIT STATUS
151       llvm-cov gcov returns 1 if it cannot read input files.   Otherwise,  it
152       exits with zero.
153

SHOW COMMAND

155   SYNOPSIS
156       llvm-cov  show  [options] -instr-profile PROFILE [BIN] [-object BIN]...
157       [-sources] [SOURCE]...
158
159   DESCRIPTION
160       The llvm-cov show command shows line by line coverage of  the  binaries
161       BIN...   using  the profile data PROFILE. It can optionally be filtered
162       to only show the coverage for the files listed in SOURCE....
163
164       BIN may be an executable, object  file,  dynamic  library,  or  archive
165       (thin or otherwise).
166
167       To  use llvm-cov show, you need a program that is compiled with instru‐
168       mentation to emit profile and coverage data. To build  such  a  program
169       with  clang  use  the  -fprofile-instr-generate  and -fcoverage-mapping
170       flags. If linking with the clang driver, pass  -fprofile-instr-generate
171       to  the  link  stage  to  make sure the necessary runtime libraries are
172       linked in.
173
174       The coverage information is stored in the built executable  or  library
175       itself,  and this is what you should pass to llvm-cov show as a BIN ar‐
176       gument. The profile data is generated by running this instrumented pro‐
177       gram  normally.  When the program exits it will write out a raw profile
178       file, typically called default.profraw, which can  be  converted  to  a
179       format  that  is suitable for the PROFILE argument using the llvm-prof‐
180       data merge tool.
181
182   OPTIONS
183       -show-branches=<VIEW>
184              Show coverage for branch conditions in terms of either count  or
185              percentage.  The supported views are: "count", "percent".
186
187       -show-line-counts
188              Show  the  execution counts for each line. Defaults to true, un‐
189              less another -show option is used.
190
191       -show-expansions
192              Expand inclusions, such as preprocessor macros or textual inclu‐
193              sions,  inline  in  the  display of the source file. Defaults to
194              false.
195
196       -show-instantiations
197              For source regions that are instantiated multiple times, such as
198              templates  in C++, show each instantiation separately as well as
199              the combined summary.  Defaults to true.
200
201       -show-regions
202              Show the execution counts for each region by displaying a  caret
203              that  points  to the character where the region starts. Defaults
204              to false.
205
206       -show-line-counts-or-regions
207              Show the execution counts for each line if there is only one re‐
208              gion  on  the line, but show the individual regions if there are
209              multiple on the line.  Defaults to false.
210
211       -use-color
212              Enable or disable color output. By default this is autodetected.
213
214       -arch=[*NAMES*]
215              Specify a list of architectures such that the Nth entry  in  the
216              list corresponds to the Nth specified binary. If the covered ob‐
217              ject is a universal binary, this specifies the  architecture  to
218              use.  It  is an error to specify an architecture that is not in‐
219              cluded in the universal binary or to use  an  architecture  that
220              does not match a non-universal binary.
221
222       -name=<NAME>
223              Show code coverage only for functions with the given name.
224
225       -name-allowlist=<FILE>
226              Show  code coverage only for functions listed in the given file.
227              Each line in the file should start with allowlist_fun:,  immedi‐
228              ately  followed by the name of the function to accept. This name
229              can be a wildcard expression.
230
231       -name-regex=<PATTERN>
232              Show code coverage only for functions that match the given regu‐
233              lar expression.
234
235       -ignore-filename-regex=<PATTERN>
236              Skip source code files with file paths that match the given reg‐
237              ular expression.
238
239       -format=<FORMAT>
240              Use the specified output  format.  The  supported  formats  are:
241              "text", "html".
242
243       -tab-size=<TABSIZE>
244              Replace  tabs with <TABSIZE> spaces when preparing reports. Cur‐
245              rently, this is only supported for the html format.
246
247       -output-dir=PATH
248              Specify a directory to write coverage reports into. If  the  di‐
249              rectory  does  not  exist,  it is created. When used in function
250              view mode (i.e when -name or -name-regex are used to select spe‐
251              cific functions), the report is written to PATH/functions.EXTEN‐
252              SION. When used in file view mode, a report  for  each  file  is
253              written to PATH/REL_PATH_TO_FILE.EXTENSION.
254
255       -Xdemangler=<TOOL>|<TOOL-OPTION>
256              Specify  a  symbol  demangler.  This can be used to make reports
257              more human-readable. This option can be specified multiple times
258              to  supply  arguments  to the demangler (e.g -Xdemangler c++filt
259              -Xdemangler -n for C++).  The demangler is expected  to  read  a
260              newline-separated  list  of  symbols from stdin and write a new‐
261              line-separated list of the same length to stdout.
262
263       -num-threads=N, -j=N
264              Use N threads to write file reports (only applicable when  -out‐
265              put-dir is specified). When N=0, llvm-cov auto-detects an appro‐
266              priate number of threads to use. This is the default.
267
268       -compilation-dir=<dir>
269              Directory used as a base for relative  coverage  mapping  paths.
270              Only  applicable  when  binaries  have been compiled with one of
271              -fcoverage-prefix-map -fcoverage-compilation-dir, or -ffile-com‐
272              pilation-dir.
273
274       -line-coverage-gt=<N>
275              Show code coverage only for functions with line coverage greater
276              than the given threshold.
277
278       -line-coverage-lt=<N>
279              Show code coverage only for functions with  line  coverage  less
280              than the given threshold.
281
282       -region-coverage-gt=<N>
283              Show  code  coverage  only  for  functions  with region coverage
284              greater than the given threshold.
285
286       -region-coverage-lt=<N>
287              Show code coverage only for functions with region coverage  less
288              than the given threshold.
289
290       -path-equivalence=<from>,<to>
291              Map  the  paths in the coverage data to local source file paths.
292              This allows you to generate the coverage data  on  one  machine,
293              and  then use llvm-cov on a different machine where you have the
294              same files on a different path.
295
296       -coverage-watermark=<high>,<low>
297              Set high and low watermarks for coverage in html format  output.
298              This allows you to set the high and low watermark of coverage as
299              desired, green when coverage >= high, red when coverage  <  low,
300              and  yellow otherwise. Both high and low should be between 0-100
301              and high > low.
302
303       -debuginfod
304              Use debuginfod to  look  up  coverage  mapping  for  binary  IDs
305              present  in  the profile but not in any object given on the com‐
306              mand line. Defaults to true if debuginfod  is  compiled  in  and
307              configured via the DEBUGINFOD_URLS environment variable.
308
309       -debug-file-directory=<dir>
310              Provides  local  directories to search for objects corresponding
311              to binary IDs in the profile (as with debuginfod).  Defaults  to
312              system build ID directories.
313
314       -check-binary-ids
315              Fail  if  an object file cannot be found for a binary ID present
316              in the profile, neither on the command line nor  via  binary  ID
317              lookup.
318

REPORT COMMAND

320   SYNOPSIS
321       llvm-cov report [options] -instr-profile PROFILE [BIN] [-object BIN]...
322       [-sources] [SOURCE]...
323
324   DESCRIPTION
325       The llvm-cov report command displays a summary of the coverage  of  the
326       binaries  BIN...  using  the profile data PROFILE. It can optionally be
327       filtered to only show the coverage for the files listed in SOURCE....
328
329       BIN may be an executable, object  file,  dynamic  library,  or  archive
330       (thin or otherwise).
331
332       If  no  source  files  are provided, a summary line is printed for each
333       file in the coverage data. If any files are provided, summaries can  be
334       shown  for each function in the listed files if the -show-functions op‐
335       tion is enabled.
336
337       For information on compiling programs for coverage and generating  pro‐
338       file data, see SHOW COMMAND.
339
340   OPTIONS
341       -use-color[=VALUE]
342              Enable or disable color output. By default this is autodetected.
343
344       -arch=<name>
345              If  the  covered binary is a universal binary, select the archi‐
346              tecture to use.  It is an error to specify an architecture  that
347              is  not  included in the universal binary or to use an architec‐
348              ture that does not match a non-universal binary.
349
350       -show-region-summary
351              Show statistics for all regions. Defaults to true.
352
353       -show-branch-summary
354              Show statistics for all branch conditions. Defaults to true.
355
356       -show-functions
357              Show coverage summaries for each function. Defaults to false.
358
359       -show-instantiation-summary
360              Show statistics for all  function  instantiations.  Defaults  to
361              false.
362
363       -ignore-filename-regex=<PATTERN>
364              Skip source code files with file paths that match the given reg‐
365              ular expression.
366
367       -compilation-dir=<dir>
368              Directory used as a base for relative  coverage  mapping  paths.
369              Only  applicable  when  binaries  have been compiled with one of
370              -fcoverage-prefix-map -fcoverage-compilation-dir, or -ffile-com‐
371              pilation-dir.
372
373       -debuginfod
374              Attempt  to look up coverage mapping from objects using debugin‐
375              fod. This is attempted by default for binary IDs present in  the
376              profile  but not provided on the command line, so long as debug‐
377              infod is compiled in and configured via DEBUGINFOD_URLS.
378
379       -debug-file-directory=<dir>
380              Provides a directory to search for objects corresponding to  bi‐
381              nary IDs in the profile.
382
383       -check-binary-ids
384              Fail  if  an object file cannot be found for a binary ID present
385              in the profile, neither on the command line nor  via  binary  ID
386              lookup.
387

EXPORT COMMAND

389   SYNOPSIS
390       llvm-cov export [options] -instr-profile PROFILE [BIN] [-object BIN]...
391       [-sources] [SOURCE]...
392
393   DESCRIPTION
394       The llvm-cov export command  exports  coverage  data  of  the  binaries
395       BIN... using the profile data PROFILE in either JSON or lcov trace file
396       format.
397
398       When exporting JSON, the regions, functions, branches, expansions,  and
399       summaries of the coverage data will be exported. When exporting an lcov
400       trace file, the line-based coverage,  branch  coverage,  and  summaries
401       will be exported.
402
403       The  exported data can optionally be filtered to only export the cover‐
404       age for the files listed in SOURCE....
405
406       For information on compiling programs for coverage and generating  pro‐
407       file data, see SHOW COMMAND.
408
409   OPTIONS
410       -arch=<name>
411              If  the  covered binary is a universal binary, select the archi‐
412              tecture to use.  It is an error to specify an architecture  that
413              is  not  included in the universal binary or to use an architec‐
414              ture that does not match a non-universal binary.
415
416       -format=<FORMAT>
417              Use the specified output  format.  The  supported  formats  are:
418              "text" (JSON), "lcov".
419
420       -summary-only
421              Export  only  summary  information for each file in the coverage
422              data. This mode will not export coverage information for smaller
423              units  such  as individual functions or regions. The result will
424              contain the same information as produced by the llvm-cov  report
425              command, but presented in JSON or lcov format rather than text.
426
427       -ignore-filename-regex=<PATTERN>
428              Skip source code files with file paths that match the given reg‐
429              ular expression.
430
431              -skip-expansions
432
433              Skip exporting macro expansion coverage data.
434
435              -skip-functions
436
437              Skip exporting per-function coverage data.
438
439              -num-threads=N, -j=N
440
441              Use N threads  to  export  coverage  data.  When  N=0,  llvm-cov
442              auto-detects  an  appropriate  number of threads to use. This is
443              the default.
444
445       -compilation-dir=<dir>
446              Directory used as a base for relative  coverage  mapping  paths.
447              Only  applicable  when  binaries  have been compiled with one of
448              -fcoverage-prefix-map -fcoverage-compilation-dir, or -ffile-com‐
449              pilation-dir.
450
451       -debuginfod
452              Attempt  to look up coverage mapping from objects using debugin‐
453              fod. This is attempted by default for binary IDs present in  the
454              profile  but not provided on the command line, so long as debug‐
455              infod is compiled in and configured via DEBUGINFOD_URLS.
456
457       -debug-file-directory=<dir>
458              Provides a directory to search for objects corresponding to  bi‐
459              nary IDs in the profile.
460
461       -check-binary-ids
462              Fail  if  an object file cannot be found for a binary ID present
463              in the profile, neither on the command line nor  via  binary  ID
464              lookup.
465

AUTHOR

467       Maintained by the LLVM Team (https://llvm.org/).
468
470       2003-2023, LLVM Project
471
472
473
474
47517                                2023-11-28                       LLVM-COV(1)
Impressum