LLVM-COV(1)



LLVM-COV(1)                          LLVM                          LLVM-COV(1)

NAME
       llvm-cov - emit coverage information

SYNOPSIS
       llvm-cov command [args]

DESCRIPTION
       The llvm-cov tool shows code coverage information for programs that are
       instrumented to emit  profile  data.  It  can  be  used  to  work  with
       gcov-style coverage or with clang's instrumentation based profiling.

       If  the  program is invoked with a base name of gcov, it will behave as
       if the llvm-cov gcov command were called. Otherwise, a  command  should
       be provided.

COMMANDS
       o gcov

       o show

       o report

       o export

GCOV COMMAND
   SYNOPSIS
       llvm-cov gcov [options] SOURCEFILE

   DESCRIPTION
       The  llvm-cov gcov tool reads code coverage data files and displays the
       coverage information for a specified source file. It is compatible with
       the  gcov  tool from version 4.2 of GCC and may also be compatible with
       some later versions of gcov.

       To use llvm-cov gcov, you must first build an instrumented  version  of
       your  application  that collects coverage data as it runs. Compile with
       the -fprofile-arcs and -ftest-coverage options to add the  instrumenta-
       tion. (Alternatively, you can use the --coverage option, which includes
       both of those other options.) You should compile with debugging  infor-
       mation  (-g)  and  without  optimization (-O0); otherwise, the coverage
       data cannot be accurately mapped back to the source code.

       At the time you compile the instrumented code, a .gcno data  file  will
       be  generated  for  each object file. These .gcno files contain half of
       the coverage data. The other half of the data comes  from  .gcda  files
       that  are generated when you run the instrumented program, with a sepa-
       rate .gcda file for each object file. Each time you  run  the  program,
       the  execution  counts  are summed into any existing .gcda files, so be
       sure to remove any old files if you do not want their  contents  to  be
       included.

       By  default, the .gcda files are written into the same directory as the
       object files, but you can override that by setting the GCOV_PREFIX  and
       GCOV_PREFIX_STRIP environment variables. The GCOV_PREFIX_STRIP variable
       specifies a number of directory components to be removed from the start
       of  the  absolute  path  to  the object file directory. After stripping
       those directories, the prefix from the GCOV_PREFIX variable  is  added.
       These  environment  variables allow you to run the instrumented program
       on a machine where the original object file directories are not  acces-
       sible,  but  you will then need to copy the .gcda files back to the ob-
       ject file directories where llvm-cov gcov expects to find them.

       Once you have generated the coverage data files, run llvm-cov gcov  for
       each  main  source file where you want to examine the coverage results.
       This should be run from the same directory where you previously ran the
       compiler.  The  results  for the specified source file are written to a
       file named by appending a .gcov suffix. A separate output file is  also
       created  for  each  file  included by the main source file, also with a
       .gcov suffix added.

       The basic content of an .gcov output file is a copy of the source  file
       with  an  execution  count and line number prepended to every line. The
       execution count is shown as - if a line does not contain any executable
       code.  If  a  line  contains code but that code was never executed, the
       count is displayed as #####.

   OPTIONS
       -a, --all-blocks
              Display all basic blocks. If there are  multiple  blocks  for  a
              single  line of source code, this option causes llvm-cov to show
              the count for each block instead of just one count for  the  en-
              tire line.

       -b, --branch-probabilities
              Display conditional branch probabilities and a summary of branch
              information.

       -c, --branch-counts
              Display branch counts instead of probabilities (requires -b).

       -f, --function-summaries
              Show a summary of coverage for each function instead of just one
              summary for an entire source file.

       --help Display available options (-help-hidden for more).

       -l, --long-file-names
              For coverage output of files included from the main source file,
              add the main file name followed by ## as a prefix to the  output
              file names. This can be combined with the -preserve-paths option
              to use complete paths for both the main file  and  the  included
              file.

       -n, --no-output
              Do not output any .gcov files. Summary information is still dis-
              played.

       -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
              Find objects in DIR or based on FILE's path. If  you  specify  a
              particular  object file, the coverage data files are expected to
              have the same base name with .gcno and .gcda extensions. If  you
              specify  a  directory,  the files are expected in that directory
              with the same base name as the source file.

       -p, --preserve-paths
              Preserve path components when naming the coverage output  files.
              In  addition  to  the  source file name, include the directories
              from the path to that file. The directories are  separate  by  #
              characters,  with  .  directories removed and .. directories re-
              placed by ^ characters. When used with the -long-file-names  op-
              tion,  this  applies to both the main file name and the included
              file name.

       -u, --unconditional-branches
              Include  unconditional  branches   in   the   output   for   the
              -branch-probabilities option.

       -version
              Display the version of llvm-cov.

   EXIT STATUS
       llvm-cov  gcov  returns 1 if it cannot read input files.  Otherwise, it
       exits with zero.

SHOW COMMAND
   SYNOPSIS
       llvm-cov show  [options]  -instr-profile  PROFILE  BIN  [-object  BIN,]
       [[-object BIN]] [SOURCES]

   DESCRIPTION
       The  llvm-cov  show command shows line by line coverage of the binaries
       BIN,  using the profile data PROFILE. It can optionally be filtered  to
       only show the coverage for the files listed in SOURCES.

       To  use llvm-cov show, you need a program that is compiled with instru-
       mentation to emit profile and coverage data. To build  such  a  program
       with  clang  use  the  -fprofile-instr-generate  and -fcoverage-mapping
       flags. If linking with the clang driver, pass  -fprofile-instr-generate
       to  the  link  stage  to  make sure the necessary runtime libraries are
       linked in.

       The coverage information is stored in the built executable  or  library
       itself,  and this is what you should pass to llvm-cov show as a BIN ar-
       gument. The profile data is generated by running this instrumented pro-
       gram  normally.  When the program exits it will write out a raw profile
       file, typically called default.profraw, which can  be  converted  to  a
       format  that  is suitable for the PROFILE argument using the llvm-prof-
       data merge tool.

   OPTIONS
       -show-line-counts
              Show the execution counts for each line. Defaults to  true,  un-
              less another -show option is used.

       -show-expansions
              Expand inclusions, such as preprocessor macros or textual inclu-
              sions, inline in the display of the  source  file.  Defaults  to
              false.

       -show-instantiations
              For source regions that are instantiated multiple times, such as
              templates in C++, show each instantiation separately as well  as
              the combined summary.  Defaults to true.

       -show-regions
              Show  the execution counts for each region by displaying a caret
              that points to the character where the region  starts.  Defaults
              to false.

       -show-line-counts-or-regions
              Show the execution counts for each line if there is only one re-
              gion on the line, but show the individual regions if  there  are
              multiple on the line.  Defaults to false.

       -use-color
              Enable or disable color output. By default this is autodetected.

       -arch=[*NAMES*]
              Specify  a  list of architectures such that the Nth entry in the
              list corresponds to the Nth specified binary. If the covered ob-
              ject  is  a universal binary, this specifies the architecture to
              use. It is an error to specify an architecture that is  not  in-
              cluded  in  the  universal binary or to use an architecture that
              does not match a non-universal binary.

       -name=<NAME>
              Show code coverage only for functions with the given name.

       -name-whitelist=<FILE>
              Show code coverage only for functions listed in the given  file.
              Each  line in the file should start with whitelist_fun:, immedi-
              ately followed by the name of the function to accept. This  name
              can be a wildcard expression.

       -name-regex=<PATTERN>
              Show code coverage only for functions that match the given regu-
              lar expression.

       -ignore-filename-regex=<PATTERN>
              Skip source code files with file paths that match the given reg-
              ular expression.

       -format=<FORMAT>
              Use  the  specified  output  format.  The supported formats are:
              "text", "html".

       -tab-size=<TABSIZE>
              Replace tabs with <TABSIZE> spaces when preparing reports.  Cur-
              rently, this is only supported for the html format.

       -output-dir=PATH
              Specify  a  directory to write coverage reports into. If the di-
              rectory does not exist, it is created.  When  used  in  function
              view mode (i.e when -name or -name-regex are used to select spe-
              cific functions), the report is written to PATH/functions.EXTEN-
              SION.  When  used  in  file view mode, a report for each file is
              written to PATH/REL_PATH_TO_FILE.EXTENSION.

       -Xdemangler=<TOOL>|<TOOL-OPTION>
              Specify a symbol demangler. This can be  used  to  make  reports
              more human-readable. This option can be specified multiple times
              to supply arguments to the demangler  (e.g  -Xdemangler  c++filt
              -Xdemangler  -n  for  C++).  The demangler is expected to read a
              newline-separated list of symbols from stdin and  write  a  new-
              line-separated list of the same length to stdout.

       -num-threads=N, -j=N
              Use  N threads to write file reports (only applicable when -out-
              put-dir is specified). When N=0, llvm-cov auto-detects an appro-
              priate number of threads to use. This is the default.

       -line-coverage-gt=<N>
              Show code coverage only for functions with line coverage greater
              than the given threshold.

       -line-coverage-lt=<N>
              Show code coverage only for functions with  line  coverage  less
              than the given threshold.

       -region-coverage-gt=<N>
              Show  code  coverage  only  for  functions  with region coverage
              greater than the given threshold.

       -region-coverage-lt=<N>
              Show code coverage only for functions with region coverage  less
              than the given threshold.

       -path-equivalence=<from>,<to>
              Map  the  paths in the coverage data to local source file paths.
              This allows you to generate the coverage data  on  one  machine,
              and  then use llvm-cov on a different machine where you have the
              same files on a different path.

REPORT COMMAND
   SYNOPSIS
       llvm-cov report [options] -instr-profile  PROFILE  BIN  [-object  BIN,]
       [[-object BIN]] [SOURCES]

   DESCRIPTION
       The  llvm-cov  report command displays a summary of the coverage of the
       binaries BIN, using the profile data PROFILE. It can optionally be fil-
       tered to only show the coverage for the files listed in SOURCES.

       If  no  source  files  are provided, a summary line is printed for each
       file in the coverage data. If any files are provided, summaries can  be
       shown  for each function in the listed files if the -show-functions op-
       tion is enabled.

       For information on compiling programs for coverage and generating  pro-
       file data, see SHOW COMMAND.

   OPTIONS
       -use-color[=VALUE]
              Enable or disable color output. By default this is autodetected.

       -arch=<name>
              If  the  covered binary is a universal binary, select the archi-
              tecture to use.  It is an error to specify an architecture  that
              is  not  included in the universal binary or to use an architec-
              ture that does not match a non-universal binary.

       -show-functions
              Show coverage summaries for each function. Defaults to false.

       -show-instantiation-summary
              Show statistics for all  function  instantiations.  Defaults  to
              false.

       -ignore-filename-regex=<PATTERN>
              Skip source code files with file paths that match the given reg-
              ular expression.

EXPORT COMMAND
   SYNOPSIS
       llvm-cov export [options] -instr-profile  PROFILE  BIN  [-object  BIN,]
       [[-object BIN]] [SOURCES]

   DESCRIPTION
       The  llvm-cov export command exports coverage data of the binaries BIN,
       using the profile data PROFILE in either JSON or lcov trace  file  for-
       mat.

       When  exporting JSON, the regions, functions, expansions, and summaries
       of the coverage data will be exported. When  exporting  an  lcov  trace
       file, the line-based coverage and summaries will be exported.

       The  exported data can optionally be filtered to only export the cover-
       age for the files listed in SOURCES.

       For information on compiling programs for coverage and generating  pro-
       file data, see SHOW COMMAND.

   OPTIONS
       -arch=<name>
              If  the  covered binary is a universal binary, select the archi-
              tecture to use.  It is an error to specify an architecture  that
              is  not  included in the universal binary or to use an architec-
              ture that does not match a non-universal binary.

       -format=<FORMAT>
              Use the specified output  format.  The  supported  formats  are:
              "text" (JSON), "lcov".

       -summary-only
              Export  only  summary  information for each file in the coverage
              data. This mode will not export coverage information for smaller
              units  such  as individual functions or regions. The result will
              contain the same information as produced by the llvm-cov  report
              command, but presented in JSON or lcov format rather than text.

       -ignore-filename-regex=<PATTERN>
              Skip source code files with file paths that match the given reg-
              ular expression.

AUTHOR
       Maintained by the LLVM Team (https://llvm.org/).

COPYRIGHT
       2003-2020, LLVM Project

8                                 2020-03-19                       LLVM-COV(1)

Man(1) output converted with man2html
list of all man pages