fe2efc8c43
defined. These help with processing coverage and profile data.
166 lines
6.1 KiB
Groff
166 lines
6.1 KiB
Groff
.\" $FreeBSD$
|
|
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "LLVM-COV" "1" "2015-04-01" "3.6" "LLVM"
|
|
.SH NAME
|
|
llvm-cov \- emit coverage information
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fBllvm\-cov\fP [options] SOURCEFILE
|
|
.SH DESCRIPTION
|
|
.sp
|
|
The \fBllvm\-cov\fP tool reads code coverage data files and displays the
|
|
coverage information for a specified source file. It is compatible with the
|
|
\fBgcov\fP tool from version 4.2 of \fBGCC\fP and may also be compatible with
|
|
some later versions of \fBgcov\fP\&.
|
|
.sp
|
|
To use llvm\-cov, you must first build an instrumented version of your
|
|
application that collects coverage data as it runs. Compile with the
|
|
\fB\-fprofile\-arcs\fP and \fB\-ftest\-coverage\fP options to add the
|
|
instrumentation. (Alternatively, you can use the \fB\-\-coverage\fP option, which
|
|
includes both of those other options.) You should compile with debugging
|
|
information (\fB\-g\fP) and without optimization (\fB\-O0\fP); otherwise, the
|
|
coverage data cannot be accurately mapped back to the source code.
|
|
.sp
|
|
At the time you compile the instrumented code, a \fB\&.gcno\fP data file will be
|
|
generated for each object file. These \fB\&.gcno\fP files contain half of the
|
|
coverage data. The other half of the data comes from \fB\&.gcda\fP files that are
|
|
generated when you run the instrumented program, with a separate \fB\&.gcda\fP
|
|
file for each object file. Each time you run the program, the execution counts
|
|
are summed into any existing \fB\&.gcda\fP files, so be sure to remove any old
|
|
files if you do not want their contents to be included.
|
|
.sp
|
|
By default, the \fB\&.gcda\fP files are written into the same directory as the
|
|
object files, but you can override that by setting the \fBGCOV_PREFIX\fP and
|
|
\fBGCOV_PREFIX_STRIP\fP environment variables. The \fBGCOV_PREFIX_STRIP\fP
|
|
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 \fBGCOV_PREFIX\fP 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 \fB\&.gcda\fP files back to the object file directories
|
|
where llvm\-cov expects to find them.
|
|
.sp
|
|
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 \fB\&.gcov\fP
|
|
suffix. A separate output file is also created for each file included by the
|
|
main source file, also with a \fB\&.gcov\fP suffix added.
|
|
.sp
|
|
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 \fB\-\fP 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 \fB#####\fP\&.
|
|
.SH OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-b, \-\-branch\-probabilities
|
|
Display conditional branch probabilities and a summary of branch information.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-c, \-\-branch\-counts
|
|
Display branch counts instead of probabilities (requires \-b).
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-f, \-\-function\-summaries
|
|
Show a summary of coverage for each function instead of just one summary for
|
|
an entire source file.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-help
|
|
Display available options (\-\-help\-hidden for more).
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-l, \-\-long\-file\-names
|
|
For coverage output of files included from the main source file, add the
|
|
main file name followed by \fB##\fP 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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-n, \-\-no\-output
|
|
Do not output any \fB\&.gcov\fP files. Summary information is still
|
|
displayed.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-o=<DIR|FILE>, \-\-object\-directory=<DIR>, \-\-object\-file=<FILE>
|
|
Find objects in DIR or based on FILE\(aqs path. If you specify a particular
|
|
object file, the coverage data files are expected to have the same base name
|
|
with \fB\&.gcno\fP and \fB\&.gcda\fP extensions. If you specify a directory, the
|
|
files are expected in that directory with the same base name as the source
|
|
file.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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 \fB#\fP characters, with \fB\&.\fP directories
|
|
removed and \fB\&..\fP directories replaced by \fB^\fP characters. When used with
|
|
the \-\-long\-file\-names option, this applies to both the main file name and the
|
|
included file name.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-u, \-\-unconditional\-branches
|
|
Include unconditional branches in the output for the \-\-branch\-probabilities
|
|
option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-version
|
|
Display the version of llvm\-cov.
|
|
.UNINDENT
|
|
.SH EXIT STATUS
|
|
.sp
|
|
\fBllvm\-cov\fP returns 1 if it cannot read input files. Otherwise, it
|
|
exits with zero.
|
|
.SH AUTHOR
|
|
Maintained by The LLVM Team (http://llvm.org/).
|
|
.SH COPYRIGHT
|
|
2003-2014, LLVM Project
|
|
.\" Generated by docutils manpage writer.
|
|
.
|