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       [[-object BIN]] [SOURCES]
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 SOURCES.
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-whitelist=<FILE>
232              Show code coverage only for functions listed in the given  file.
233              Each  line in the file should start with whitelist_fun:, immedi‐
234              ately followed by the name of the function to accept. This  name
235              can be a wildcard expression. This option will be deprecated for
236              -name-allowlist=<FILE> in future releases.
237
238       -name-regex=<PATTERN>
239              Show code coverage only for functions that match the given regu‐
240              lar expression.
241
242       -ignore-filename-regex=<PATTERN>
243              Skip source code files with file paths that match the given reg‐
244              ular expression.
245
246       -format=<FORMAT>
247              Use the specified output  format.  The  supported  formats  are:
248              "text", "html".
249
250       -tab-size=<TABSIZE>
251              Replace  tabs with <TABSIZE> spaces when preparing reports. Cur‐
252              rently, this is only supported for the html format.
253
254       -output-dir=PATH
255              Specify a directory to write coverage reports into. If  the  di‐
256              rectory  does  not  exist,  it is created. When used in function
257              view mode (i.e when -name or -name-regex are used to select spe‐
258              cific functions), the report is written to PATH/functions.EXTEN‐
259              SION. When used in file view mode, a report  for  each  file  is
260              written to PATH/REL_PATH_TO_FILE.EXTENSION.
261
262       -Xdemangler=<TOOL>|<TOOL-OPTION>
263              Specify  a  symbol  demangler.  This can be used to make reports
264              more human-readable. This option can be specified multiple times
265              to  supply  arguments  to the demangler (e.g -Xdemangler c++filt
266              -Xdemangler -n for C++).  The demangler is expected  to  read  a
267              newline-separated  list  of  symbols from stdin and write a new‐
268              line-separated list of the same length to stdout.
269
270       -num-threads=N, -j=N
271              Use N threads to write file reports (only applicable when  -out‐
272              put-dir is specified). When N=0, llvm-cov auto-detects an appro‐
273              priate number of threads to use. This is the default.
274
275       -compilation-dir=<dir>
276              Directory used as a base for relative  coverage  mapping  paths.
277              Only  applicable  when  binaries  have been compiled with one of
278              -fcoverage-prefix-map -fcoverage-compilation-dir, or -ffile-com‐
279              pilation-dir.
280
281       -line-coverage-gt=<N>
282              Show code coverage only for functions with line coverage greater
283              than the given threshold.
284
285       -line-coverage-lt=<N>
286              Show code coverage only for functions with  line  coverage  less
287              than the given threshold.
288
289       -region-coverage-gt=<N>
290              Show  code  coverage  only  for  functions  with region coverage
291              greater than the given threshold.
292
293       -region-coverage-lt=<N>
294              Show code coverage only for functions with region coverage  less
295              than the given threshold.
296
297       -path-equivalence=<from>,<to>
298              Map  the  paths in the coverage data to local source file paths.
299              This allows you to generate the coverage data  on  one  machine,
300              and  then use llvm-cov on a different machine where you have the
301              same files on a different path.
302

REPORT COMMAND

304   SYNOPSIS
305       llvm-cov report [options] -instr-profile PROFILE BIN [-object  BIN,...]
306       [[-object BIN]] [SOURCES]
307
308   DESCRIPTION
309       The  llvm-cov  report command displays a summary of the coverage of the
310       binaries BIN,... using the profile data PROFILE. It can  optionally  be
311       filtered to only show the coverage for the files listed in SOURCES.
312
313       BIN  may  be  an  executable,  object file, dynamic library, or archive
314       (thin or otherwise).
315
316       If no source files are provided, a summary line  is  printed  for  each
317       file  in the coverage data. If any files are provided, summaries can be
318       shown for each function in the listed files if the -show-functions  op‐
319       tion is enabled.
320
321       For  information on compiling programs for coverage and generating pro‐
322       file data, see SHOW COMMAND.
323
324   OPTIONS
325       -use-color[=VALUE]
326              Enable or disable color output. By default this is autodetected.
327
328       -arch=<name>
329              If the covered binary is a universal binary, select  the  archi‐
330              tecture  to use.  It is an error to specify an architecture that
331              is not included in the universal binary or to use  an  architec‐
332              ture that does not match a non-universal binary.
333
334       -show-region-summary
335              Show statistics for all regions. Defaults to true.
336
337       -show-branch-summary
338              Show statistics for all branch conditions. Defaults to true.
339
340       -show-functions
341              Show coverage summaries for each function. Defaults to false.
342
343       -show-instantiation-summary
344              Show  statistics  for  all  function instantiations. Defaults to
345              false.
346
347       -ignore-filename-regex=<PATTERN>
348              Skip source code files with file paths that match the given reg‐
349              ular expression.
350
351       -compilation-dir=<dir>
352              Directory  used  as  a base for relative coverage mapping paths.
353              Only applicable when binaries have been  compiled  with  one  of
354              -fcoverage-prefix-map -fcoverage-compilation-dir, or -ffile-com‐
355              pilation-dir.
356

EXPORT COMMAND

358   SYNOPSIS
359       llvm-cov export [options] -instr-profile PROFILE BIN [-object  BIN,...]
360       [[-object BIN]] [SOURCES]
361
362   DESCRIPTION
363       The  llvm-cov  export  command  exports  coverage  data of the binaries
364       BIN,... using the profile data PROFILE in either  JSON  or  lcov  trace
365       file format.
366
367       When  exporting JSON, the regions, functions, branches, expansions, and
368       summaries of the coverage data will be exported. When exporting an lcov
369       trace  file,  the  line-based  coverage, branch coverage, and summaries
370       will be exported.
371
372       The exported data can optionally be filtered to only export the  cover‐
373       age for the files listed in SOURCES.
374
375       For  information on compiling programs for coverage and generating pro‐
376       file data, see SHOW COMMAND.
377
378   OPTIONS
379       -arch=<name>
380              If the covered binary is a universal binary, select  the  archi‐
381              tecture  to use.  It is an error to specify an architecture that
382              is not included in the universal binary or to use  an  architec‐
383              ture that does not match a non-universal binary.
384
385       -format=<FORMAT>
386              Use  the  specified  output  format.  The supported formats are:
387              "text" (JSON), "lcov".
388
389       -summary-only
390              Export only summary information for each file  in  the  coverage
391              data. This mode will not export coverage information for smaller
392              units such as individual functions or regions. The  result  will
393              contain  the same information as produced by the llvm-cov report
394              command, but presented in JSON or lcov format rather than text.
395
396       -ignore-filename-regex=<PATTERN>
397              Skip source code files with file paths that match the given reg‐
398              ular expression.
399
400              -skip-expansions
401
402              Skip exporting macro expansion coverage data.
403
404              -skip-functions
405
406              Skip exporting per-function coverage data.
407
408              -num-threads=N, -j=N
409
410              Use  N  threads  to  export  coverage  data.  When N=0, llvm-cov
411              auto-detects an appropriate number of threads to  use.  This  is
412              the default.
413
414       -compilation-dir=<dir>
415              Directory  used  as  a base for relative coverage mapping paths.
416              Only applicable when binaries have been  compiled  with  one  of
417              -fcoverage-prefix-map -fcoverage-compilation-dir, or -ffile-com‐
418              pilation-dir.
419

AUTHOR

421       Maintained by the LLVM Team (https://llvm.org/).
422
424       2003-2023, LLVM Project
425
426
427
428
42914                                2023-01-19                       LLVM-COV(1)
Impressum