320 lines
11 KiB
Groff
320 lines
11 KiB
Groff
.\" $FreeBSD$
|
|
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "LLVM-COV" "1" "2016-03-03" "3.8" "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 \fIcommand\fP [\fIargs...\fP]
|
|
.SH DESCRIPTION
|
|
.sp
|
|
The \fBllvm\-cov\fP tool shows code coverage information for
|
|
programs that are instrumented to emit profile data. It can be used to
|
|
work with \fBgcov\fP\-style coverage or with \fBclang\fP\(aqs instrumentation
|
|
based profiling.
|
|
.sp
|
|
If the program is invoked with a base name of \fBgcov\fP, it will behave as if
|
|
the \fBllvm\-cov gcov\fP command were called. Otherwise, a command should
|
|
be provided.
|
|
.SH COMMANDS
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fI\%gcov\fP
|
|
.IP \(bu 2
|
|
\fI\%show\fP
|
|
.IP \(bu 2
|
|
\fI\%report\fP
|
|
.UNINDENT
|
|
.SH GCOV COMMAND
|
|
.SS SYNOPSIS
|
|
.sp
|
|
\fBllvm\-cov gcov\fP [\fIoptions\fP] \fISOURCEFILE\fP
|
|
.SS DESCRIPTION
|
|
.sp
|
|
The \fBllvm\-cov gcov\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 \fBllvm\-cov gcov\fP, 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 \fBllvm\-cov gcov\fP expects to find them.
|
|
.sp
|
|
Once you have generated the coverage data files, run \fBllvm\-cov gcov\fP
|
|
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 \fB\&.gcov\fP 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\&.
|
|
.SS 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
|
|
.SS EXIT STATUS
|
|
.sp
|
|
\fBllvm\-cov gcov\fP returns 1 if it cannot read input files. Otherwise,
|
|
it exits with zero.
|
|
.SH SHOW COMMAND
|
|
.SS SYNOPSIS
|
|
.sp
|
|
\fBllvm\-cov show\fP [\fIoptions\fP] \-instr\-profile \fIPROFILE\fP \fIBIN\fP [\fISOURCES\fP]
|
|
.SS DESCRIPTION
|
|
.sp
|
|
The \fBllvm\-cov show\fP command shows line by line coverage of a binary
|
|
\fIBIN\fP using the profile data \fIPROFILE\fP\&. It can optionally be filtered to only
|
|
show the coverage for the files listed in \fISOURCES\fP\&.
|
|
.sp
|
|
To use \fBllvm\-cov show\fP, you need a program that is compiled with
|
|
instrumentation to emit profile and coverage data. To build such a program with
|
|
\fBclang\fP use the \fB\-fprofile\-instr\-generate\fP and \fB\-fcoverage\-mapping\fP
|
|
flags. If linking with the \fBclang\fP driver, pass \fB\-fprofile\-instr\-generate\fP
|
|
to the link stage to make sure the necessary runtime libraries are linked in.
|
|
.sp
|
|
The coverage information is stored in the built executable or library itself,
|
|
and this is what you should pass to \fBllvm\-cov show\fP as the \fIBIN\fP
|
|
argument. The profile data is generated by running this instrumented program
|
|
normally. When the program exits it will write out a raw profile file,
|
|
typically called \fBdefault.profraw\fP, which can be converted to a format that
|
|
is suitable for the \fIPROFILE\fP argument using the \fBllvm\-profdata merge\fP
|
|
tool.
|
|
.SS OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-show\-line\-counts
|
|
Show the execution counts for each line. This is enabled by default, unless
|
|
another \fB\-show\fP option is used.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-show\-expansions
|
|
Expand inclusions, such as preprocessor macros or textual inclusions, inline
|
|
in the display of the source file.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-show\-instantiations
|
|
For source regions that are instantiated multiple times, such as templates in
|
|
\fBC++\fP, show each instantiation separately as well as the combined summary.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-show\-regions
|
|
Show the execution counts for each region by displaying a caret that points to
|
|
the character where the region starts.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-use\-color[=VALUE]
|
|
Enable or disable color output. By default this is autodetected.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-arch=<name>
|
|
If the covered binary is a universal binary, select the architecture to use.
|
|
It is an error to specify an architecture that is not included in the
|
|
universal binary or to use an architecture that does not match a
|
|
non\-universal binary.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-name=<NAME>
|
|
Show code coverage only for functions with the given name.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-name\-regex=<PATTERN>
|
|
Show code coverage only for functions that match the given regular expression.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-line\-coverage\-gt=<N>
|
|
Show code coverage only for functions with line coverage greater than the
|
|
given threshold.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-line\-coverage\-lt=<N>
|
|
Show code coverage only for functions with line coverage less than the given
|
|
threshold.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-region\-coverage\-gt=<N>
|
|
Show code coverage only for functions with region coverage greater than the
|
|
given threshold.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-region\-coverage\-lt=<N>
|
|
Show code coverage only for functions with region coverage less than the given
|
|
threshold.
|
|
.UNINDENT
|
|
.SH REPORT COMMAND
|
|
.SS SYNOPSIS
|
|
.sp
|
|
\fBllvm\-cov report\fP [\fIoptions\fP] \-instr\-profile \fIPROFILE\fP \fIBIN\fP [\fISOURCES\fP]
|
|
.SS DESCRIPTION
|
|
.sp
|
|
The \fBllvm\-cov report\fP command displays a summary of the coverage of a
|
|
binary \fIBIN\fP using the profile data \fIPROFILE\fP\&. It can optionally be filtered to
|
|
only show the coverage for the files listed in \fISOURCES\fP\&.
|
|
.sp
|
|
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.
|
|
.sp
|
|
For information on compiling programs for coverage and generating profile data,
|
|
see \fI\%SHOW COMMAND\fP\&.
|
|
.SS OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-use\-color[=VALUE]
|
|
Enable or disable color output. By default this is autodetected.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-arch=<name>
|
|
If the covered binary is a universal binary, select the architecture to use.
|
|
It is an error to specify an architecture that is not included in the
|
|
universal binary or to use an architecture that does not match a
|
|
non\-universal binary.
|
|
.UNINDENT
|
|
.SH AUTHOR
|
|
Maintained by The LLVM Team (http://llvm.org/).
|
|
.SH COPYRIGHT
|
|
2003-2016, LLVM Project
|
|
.\" Generated by docutils manpage writer.
|
|
.
|