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

REPORT COMMAND

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

EXPORT COMMAND

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

AUTHOR

414       Maintained by the LLVM Team (https://llvm.org/).
415
417       2003-2023, LLVM Project
418
419
420
421
42213                                2023-07-20                       LLVM-COV(1)
Impressum