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

21       · gcov
22
23       · show
24
25       · report
26
27       · export
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
65       object 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
86              entire 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
105              option to use complete paths for both  the  main  file  and  the
106              included 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
124              replaced by ^ characters. When used with  the  --long-file-names
125              option, 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   EXIT STATUS
136       llvm-cov  gcov  returns 1 if it cannot read input files.  Otherwise, it
137       exits with zero.
138

SHOW COMMAND

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

REPORT COMMAND

249   SYNOPSIS
250       llvm-cov  report [options] -instr-profile PROFILE BIN [-object BIN,...]
251       [[-object BIN]] [SOURCES]
252
253   DESCRIPTION
254       The llvm-cov report command displays a summary of the coverage  of  the
255       binaries  BIN,...  using the profile data PROFILE. It can optionally be
256       filtered to only show the coverage for the files listed in SOURCES.
257
258       If no source files are provided, a summary line  is  printed  for  each
259       file  in  the  coverage  data. If any files are provided, summaries are
260       shown for each function in the listed files instead.
261
262       For information on compiling programs for coverage and generating  pro‐
263       file data, see SHOW COMMAND.
264
265   OPTIONS
266       -use-color[=VALUE]
267              Enable or disable color output. By default this is autodetected.
268
269       -arch=<name>
270              If  the  covered binary is a universal binary, select the archi‐
271              tecture to use.  It is an error to specify an architecture  that
272              is  not  included in the universal binary or to use an architec‐
273              ture that does not match a non-universal binary.
274
275       -show-functions
276              Show coverage summaries for each function.
277

EXPORT COMMAND

279   SYNOPSIS
280       llvm-cov export [options] -instr-profile PROFILE BIN [-object  BIN,...]
281       [[-object BIN]]
282
283   DESCRIPTION
284       The llvm-cov export command exports regions, functions, expansions, and
285       summaries of the coverage of the binaries  BIN,...  using  the  profile
286       data PROFILE as JSON.
287
288       For  information on compiling programs for coverage and generating pro‐
289       file data, see SHOW COMMAND.
290
291   OPTIONS
292       -arch=<name>
293              If the covered binary is a universal binary, select  the  archi‐
294              tecture  to use.  It is an error to specify an architecture that
295              is not included in the universal binary or to use  an  architec‐
296              ture that does not match a non-universal binary.
297

AUTHOR

299       Maintained by The LLVM Team (http://llvm.org/).
300
302       2003-2020, LLVM Project
303
304
305
306
3075                                 2020-01-29                       LLVM-COV(1)
Impressum