manpagez: man pages & more
man llvm-cov(1)
Home | html | info | man
llvm-cov(1)                          LLVM                          llvm-cov(1)




NAME

       llvm-cov - emit coverage information


SYNOPSIS

       llvm-cov command [args^<i>a|]


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 clangas 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
       object 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
              entire 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 (ahelp-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 apreserve-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 FILEas 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
              replaced by ^ characters. When used  with  the  along-file-names
              option, this applies to both the main file name and the included
              file name.

       -u, --unconditional-branches
              Include  unconditional  branches   in   the   output   for   the
              abranch-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,^<i>a|]
       [[-object BIN]] [SOURCES]

   DESCRIPTION
       The  llvm-cov  show command shows line by line coverage of the binaries
       BIN,a|  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
       argument. The profile data is generated by  running  this  instrumented
       program  normally.  When the program exits it will write out a raw pro-
       file 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.  This  is  enabled  by
              default, unless 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.

       -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.

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

       -show-line-counts-or-regions
              Show  the  execution  counts  for each line if there is only one
              region on the line, but show the individual regions if there are
              multiple on the line.

       -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.

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

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

       -format=<FORMAT>
              Use the specified output  format.  The  supported  formats  are:
              atexta, ahtmla.

       -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
              directory  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.

       -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.


REPORT COMMAND

   SYNOPSIS
       llvm-cov report [options] -instr-profile PROFILE BIN  [-object  BIN,^<i>a|]
       [[-object BIN]] [SOURCES]

   DESCRIPTION
       The  llvm-cov  report command displays a summary of the coverage of the
       binaries BIN,a| using the profile data PROFILE. It  can  optionally  be
       filtered 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  are
       shown for each function in the listed files instead.

       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.


EXPORT COMMAND

   SYNOPSIS
       llvm-cov export [options] -instr-profile PROFILE BIN  [-object  BIN,^<i>a|]
       [[-object BIN]]

   DESCRIPTION
       The llvm-cov export command exports regions, functions, expansions, and
       summaries of the coverage of the binaries BIN,a| using the profile data
       PROFILE as JSON.

       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.


AUTHOR

       Maintained by The LLVM Team (http://llvm.org/).


COPYRIGHT

       2003-2017, LLVM Project



Apple LLVM 9.0.0                  2017-09-19                       llvm-cov(1)

Mac OS X 10.12.6 - Generated Sun Oct 29 07:43:49 CDT 2017
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.