llvm-cov-3.5(1)



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

NAME
       llvm-cov - emit coverage information

SYNOPSIS
       llvm-cov [options] SOURCEFILE

DESCRIPTION
       The  llvm-cov tool reads code coverage data files and displays the cov-
       erage 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, 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  instrumentation.
       (Alternatively,  you can use the --coverage option, which includes both
       of those other options.) You should compile with debugging  information
       (-g)  and without optimization (-O0); otherwise, the coverage data can-
       not 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 expects to find them.

       Once you have generated the coverage data files, run llvm-cov 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 com-
       piler.  The results for the specified source file are written to a file
       named by appending a .gcov suffix. A separate output file is also  cre-
       ated  for each file included by the main source file, also with a .gcov
       suffix added.

       The basic content of an llvm-cov 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  exe-
       cutable 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 (--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
              replaced by ^ characters. When used with  the  --long-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
              --branch-probabilities option.

       -version
              Display the version of llvm-cov.

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

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

COPYRIGHT
       2003-2016, LLVM Project

3.5                               2016-10-07                       LLVM-COV(1)

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