128 lines
5.0 KiB
ReStructuredText
128 lines
5.0 KiB
ReStructuredText
llvm-cov - emit coverage information
|
|
====================================
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
:program:`llvm-cov` [options] SOURCEFILE
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The :program:`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
|
|
-------
|
|
|
|
.. option:: -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.
|
|
|
|
.. option:: -b, --branch-probabilities
|
|
|
|
Display conditional branch probabilities and a summary of branch information.
|
|
|
|
.. option:: -c, --branch-counts
|
|
|
|
Display branch counts instead of probabilities (requires -b).
|
|
|
|
.. option:: -f, --function-summaries
|
|
|
|
Show a summary of coverage for each function instead of just one summary for
|
|
an entire source file.
|
|
|
|
.. option:: --help
|
|
|
|
Display available options (--help-hidden for more).
|
|
|
|
.. option:: -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.
|
|
|
|
.. option:: -n, --no-output
|
|
|
|
Do not output any ``.gcov`` files. Summary information is still
|
|
displayed.
|
|
|
|
.. option:: -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.
|
|
|
|
.. option:: -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.
|
|
|
|
.. option:: -u, --unconditional-branches
|
|
|
|
Include unconditional branches in the output for the --branch-probabilities
|
|
option.
|
|
|
|
.. option:: -version
|
|
|
|
Display the version of llvm-cov.
|
|
|
|
EXIT STATUS
|
|
-----------
|
|
|
|
:program:`llvm-cov` returns 1 if it cannot read input files. Otherwise, it
|
|
exits with zero.
|
|
|