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
303       -coverage-watermark=<high>,<low>
304              Set high and low watermarks for coverage in html format  output.
305              This allows you to set the high and low watermark of coverage as
306              desired, green when coverage >= high, red when coverage  <  low,
307              and  yellow otherwise. Both high and low should be between 0-100
308              and high > low.
309

REPORT COMMAND

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

EXPORT COMMAND

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

AUTHOR

428       Maintained by the LLVM Team (https://llvm.org/).
429
431       2003-2023, LLVM Project
432
433
434
435
43615                                2023-07-20                       LLVM-COV(1)
Impressum