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.  Defaults  to  true,
167              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.  Defaults  to
172              false.
173
174       -show-instantiations
175              For source regions that are instantiated multiple times, such as
176              templates in C++, show each instantiation separately as well  as
177              the combined summary.  Defaults to true.
178
179       -show-regions
180              Show  the execution counts for each region by displaying a caret
181              that points to the character where the region  starts.  Defaults
182              to false.
183
184       -show-line-counts-or-regions
185              Show  the  execution  counts  for each line if there is only one
186              region on the line, but show the individual regions if there are
187              multiple on the line.  Defaults to false.
188
189       -use-color
190              Enable or disable color output. By default this is autodetected.
191
192       -arch=[*NAMES*]
193              Specify  a  list of architectures such that the Nth entry in the
194              list corresponds to the Nth specified  binary.  If  the  covered
195              object is a universal binary, this specifies the architecture to
196              use. It is an error to  specify  an  architecture  that  is  not
197              included  in the universal binary or to use an architecture that
198              does not match a non-universal binary.
199
200       -name=<NAME>
201              Show code coverage only for functions with the given name.
202
203       -name-whitelist=<FILE>
204              Show code coverage only for functions listed in the given  file.
205              Each  line in the file should start with whitelist_fun:, immedi‐
206              ately followed by the name of the function to accept. This  name
207              can be a wildcard expression.
208
209       -name-regex=<PATTERN>
210              Show code coverage only for functions that match the given regu‐
211              lar expression.
212
213       -ignore-filename-regex=<PATTERN>
214              Skip source code files with file paths that match the given reg‐
215              ular expression.
216
217       -format=<FORMAT>
218              Use  the  specified  output  format.  The supported formats are:
219              "text", "html".
220
221       -tab-size=<TABSIZE>
222              Replace tabs with <TABSIZE> spaces when preparing reports.  Cur‐
223              rently, this is only supported for the html format.
224
225       -output-dir=PATH
226              Specify  a  directory  to  write  coverage  reports into. If the
227              directory does not exist, it is created. When used  in  function
228              view mode (i.e when -name or -name-regex are used to select spe‐
229              cific functions), the report is written to PATH/functions.EXTEN‐
230              SION.  When  used  in  file view mode, a report for each file is
231              written to PATH/REL_PATH_TO_FILE.EXTENSION.
232
233       -Xdemangler=<TOOL>|<TOOL-OPTION>
234              Specify a symbol demangler. This can be  used  to  make  reports
235              more human-readable. This option can be specified multiple times
236              to supply arguments to the demangler  (e.g  -Xdemangler  c++filt
237              -Xdemangler  -n  for  C++).  The demangler is expected to read a
238              newline-separated list of symbols from stdin and  write  a  new‐
239              line-separated list of the same length to stdout.
240
241       -num-threads=N, -j=N
242              Use  N threads to write file reports (only applicable when -out‐
243              put-dir is specified). When N=0, llvm-cov auto-detects an appro‐
244              priate number of threads to use. This is the default.
245
246       -line-coverage-gt=<N>
247              Show code coverage only for functions with line coverage greater
248              than the given threshold.
249
250       -line-coverage-lt=<N>
251              Show code coverage only for functions with  line  coverage  less
252              than the given threshold.
253
254       -region-coverage-gt=<N>
255              Show  code  coverage  only  for  functions  with region coverage
256              greater than the given threshold.
257
258       -region-coverage-lt=<N>
259              Show code coverage only for functions with region coverage  less
260              than the given threshold.
261
262       -path-equivalence=<from>,<to>
263              Map  the  paths in the coverage data to local source file paths.
264              This allows you to generate the coverage data  on  one  machine,
265              and  then use llvm-cov on a different machine where you have the
266              same files on a different path.
267

REPORT COMMAND

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

EXPORT COMMAND

308   SYNOPSIS
309       llvm-cov export [options] -instr-profile PROFILE BIN [-object  BIN,...]
310       [[-object BIN]] [SOURCES]
311
312   DESCRIPTION
313       The  llvm-cov  export  command  exports  coverage  data of the binaries
314       BIN,... using the profile data PROFILE in either  JSON  or  lcov  trace
315       file format.
316
317       When  exporting JSON, the regions, functions, expansions, and summaries
318       of the coverage data will be exported. When  exporting  an  lcov  trace
319       file, the line-based coverage and summaries will be exported.
320
321       The  exported data can optionally be filtered to only export the cover‐
322       age for the files listed in SOURCES.
323
324       For information on compiling programs for coverage and generating  pro‐
325       file data, see SHOW COMMAND.
326
327   OPTIONS
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       -format=<FORMAT>
335              Use the specified output  format.  The  supported  formats  are:
336              "text" (JSON), "lcov".
337
338       -summary-only
339              Export  only  summary  information for each file in the coverage
340              data. This mode will not export coverage information for smaller
341              units  such  as individual functions or regions. The result will
342              contain the same information as produced by the llvm-cov  report
343              command, but presented in JSON or lcov format rather than text.
344
345       -ignore-filename-regex=<PATTERN>
346              Skip source code files with file paths that match the given reg‐
347              ular expression.
348

AUTHOR

350       Maintained by the LLVM Team (https://llvm.org/).
351
353       2003-2019, LLVM Project
354
355
356
357
3588                                 2019-11-13                       LLVM-COV(1)
Impressum