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

SHOW COMMAND

145   SYNOPSIS
146       llvm-cov show [options] -instr-profile PROFILE  BIN  [-object  BIN,...]
147       [[-object BIN]] [SOURCES]
148
149   DESCRIPTION
150       The  llvm-cov  show command shows line by line coverage of the binaries
151       BIN,...  using the profile data PROFILE. It can optionally be  filtered
152       to only show the coverage for the files listed in SOURCES.
153
154       BIN  may  be  an  executable,  object file, dynamic library, or archive
155       (thin or otherwise).
156
157       To use llvm-cov show, you need a program that is compiled with  instru‐
158       mentation  to  emit  profile and coverage data. To build such a program
159       with clang  use  the  -fprofile-instr-generate  and  -fcoverage-mapping
160       flags.  If linking with the clang driver, pass -fprofile-instr-generate
161       to the link stage to make sure  the  necessary  runtime  libraries  are
162       linked in.
163
164       The  coverage  information is stored in the built executable or library
165       itself, and this is what you should pass to llvm-cov show as a BIN  ar‐
166       gument. The profile data is generated by running this instrumented pro‐
167       gram normally. When the program exits it will write out a  raw  profile
168       file,  typically  called  default.profraw,  which can be converted to a
169       format that is suitable for the PROFILE argument using  the  llvm-prof‐
170       data merge tool.
171
172   OPTIONS
173       -show-line-counts
174              Show  the  execution counts for each line. Defaults to true, un‐
175              less another -show option is used.
176
177       -show-expansions
178              Expand inclusions, such as preprocessor macros or textual inclu‐
179              sions,  inline  in  the  display of the source file. Defaults to
180              false.
181
182       -show-instantiations
183              For source regions that are instantiated multiple times, such as
184              templates  in C++, show each instantiation separately as well as
185              the combined summary.  Defaults to true.
186
187       -show-regions
188              Show the execution counts for each region by displaying a  caret
189              that  points  to the character where the region starts. Defaults
190              to false.
191
192       -show-line-counts-or-regions
193              Show the execution counts for each line if there is only one re‐
194              gion  on  the line, but show the individual regions if there are
195              multiple on the line.  Defaults to false.
196
197       -use-color
198              Enable or disable color output. By default this is autodetected.
199
200       -arch=[*NAMES*]
201              Specify a list of architectures such that the Nth entry  in  the
202              list corresponds to the Nth specified binary. If the covered ob‐
203              ject is a universal binary, this specifies the  architecture  to
204              use.  It  is an error to specify an architecture that is not in‐
205              cluded in the universal binary or to use  an  architecture  that
206              does not match a non-universal binary.
207
208       -name=<NAME>
209              Show code coverage only for functions with the given name.
210
211       -name-whitelist=<FILE>
212              Show  code coverage only for functions listed in the given file.
213              Each line in the file should start with whitelist_fun:,  immedi‐
214              ately  followed by the name of the function to accept. This name
215              can be a wildcard expression.
216
217       -name-regex=<PATTERN>
218              Show code coverage only for functions that match the given regu‐
219              lar expression.
220
221       -ignore-filename-regex=<PATTERN>
222              Skip source code files with file paths that match the given reg‐
223              ular expression.
224
225       -format=<FORMAT>
226              Use the specified output  format.  The  supported  formats  are:
227              "text", "html".
228
229       -tab-size=<TABSIZE>
230              Replace  tabs with <TABSIZE> spaces when preparing reports. Cur‐
231              rently, this is only supported for the html format.
232
233       -output-dir=PATH
234              Specify a directory to write coverage reports into. If  the  di‐
235              rectory  does  not  exist,  it is created. When used in function
236              view mode (i.e when -name or -name-regex are used to select spe‐
237              cific functions), the report is written to PATH/functions.EXTEN‐
238              SION. When used in file view mode, a report  for  each  file  is
239              written to PATH/REL_PATH_TO_FILE.EXTENSION.
240
241       -Xdemangler=<TOOL>|<TOOL-OPTION>
242              Specify  a  symbol  demangler.  This can be used to make reports
243              more human-readable. This option can be specified multiple times
244              to  supply  arguments  to the demangler (e.g -Xdemangler c++filt
245              -Xdemangler -n for C++).  The demangler is expected  to  read  a
246              newline-separated  list  of  symbols from stdin and write a new‐
247              line-separated list of the same length to stdout.
248
249       -num-threads=N, -j=N
250              Use N threads to write file reports (only applicable when  -out‐
251              put-dir is specified). When N=0, llvm-cov auto-detects an appro‐
252              priate number of threads to use. This is the default.
253
254       -line-coverage-gt=<N>
255              Show code coverage only for functions with line coverage greater
256              than the given threshold.
257
258       -line-coverage-lt=<N>
259              Show  code  coverage  only for functions with line coverage less
260              than the given threshold.
261
262       -region-coverage-gt=<N>
263              Show code coverage  only  for  functions  with  region  coverage
264              greater than the given threshold.
265
266       -region-coverage-lt=<N>
267              Show  code coverage only for functions with region coverage less
268              than the given threshold.
269
270       -path-equivalence=<from>,<to>
271              Map the paths in the coverage data to local source  file  paths.
272              This  allows  you  to generate the coverage data on one machine,
273              and then use llvm-cov on a different machine where you have  the
274              same files on a different path.
275

REPORT COMMAND

277   SYNOPSIS
278       llvm-cov  report [options] -instr-profile PROFILE BIN [-object BIN,...]
279       [[-object BIN]] [SOURCES]
280
281   DESCRIPTION
282       The llvm-cov report command displays a summary of the coverage  of  the
283       binaries  BIN,...  using the profile data PROFILE. It can optionally be
284       filtered to only show the coverage for the files listed in SOURCES.
285
286       BIN may be an executable, object  file,  dynamic  library,  or  archive
287       (thin or otherwise).
288
289       If  no  source  files  are provided, a summary line is printed for each
290       file in the coverage data. If any files are provided, summaries can  be
291       shown  for each function in the listed files if the -show-functions op‐
292       tion is enabled.
293
294       For information on compiling programs for coverage and generating  pro‐
295       file data, see SHOW COMMAND.
296
297   OPTIONS
298       -use-color[=VALUE]
299              Enable or disable color output. By default this is autodetected.
300
301       -arch=<name>
302              If  the  covered binary is a universal binary, select the archi‐
303              tecture to use.  It is an error to specify an architecture  that
304              is  not  included in the universal binary or to use an architec‐
305              ture that does not match a non-universal binary.
306
307       -show-functions
308              Show coverage summaries for each function. Defaults to false.
309
310       -show-instantiation-summary
311              Show statistics for all  function  instantiations.  Defaults  to
312              false.
313
314       -ignore-filename-regex=<PATTERN>
315              Skip source code files with file paths that match the given reg‐
316              ular expression.
317

EXPORT COMMAND

319   SYNOPSIS
320       llvm-cov export [options] -instr-profile PROFILE BIN [-object  BIN,...]
321       [[-object BIN]] [SOURCES]
322
323   DESCRIPTION
324       The  llvm-cov  export  command  exports  coverage  data of the binaries
325       BIN,... using the profile data PROFILE in either  JSON  or  lcov  trace
326       file format.
327
328       When  exporting JSON, the regions, functions, expansions, and summaries
329       of the coverage data will be exported. When  exporting  an  lcov  trace
330       file, the line-based coverage and summaries will be exported.
331
332       The  exported data can optionally be filtered to only export the cover‐
333       age for the files listed in SOURCES.
334
335       For information on compiling programs for coverage and generating  pro‐
336       file data, see SHOW COMMAND.
337
338   OPTIONS
339       -arch=<name>
340              If  the  covered binary is a universal binary, select the archi‐
341              tecture to use.  It is an error to specify an architecture  that
342              is  not  included in the universal binary or to use an architec‐
343              ture that does not match a non-universal binary.
344
345       -format=<FORMAT>
346              Use the specified output  format.  The  supported  formats  are:
347              "text" (JSON), "lcov".
348
349       -summary-only
350              Export  only  summary  information for each file in the coverage
351              data. This mode will not export coverage information for smaller
352              units  such  as individual functions or regions. The result will
353              contain the same information as produced by the llvm-cov  report
354              command, but presented in JSON or lcov format rather than text.
355
356       -ignore-filename-regex=<PATTERN>
357              Skip source code files with file paths that match the given reg‐
358              ular expression.
359
360              -skip-expansions
361
362              Skip exporting macro expansion coverage data.
363
364              -skip-functions
365
366              Skip exporting per-function coverage data.
367
368              -num-threads=N, -j=N
369
370              Use N threads  to  export  coverage  data.  When  N=0,  llvm-cov
371              auto-detects  an  appropriate  number of threads to use. This is
372              the default.
373

AUTHOR

375       Maintained by the LLVM Team (https://llvm.org/).
376
378       2003-2023, LLVM Project
379
380
381
382
38311                                2023-07-20                       LLVM-COV(1)
Impressum