xenial (1) llvm-cov-3.6.1.gz

Provided by: llvm-3.6_3.6.2-3ubuntu2_amd64 bug

NAME

       llvm-cov - emit coverage information

SYNOPSIS

       llvm-cov [options] SOURCEFILE

DESCRIPTION

       The  llvm-cov  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, 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 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 separate .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 accessible, 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
       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 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
       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 (--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 displayed.

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

       2003-2014, LLVM Project