1 .\" Man page generated from reStructuredText.

     2 .

     3 .TH "LLVM-COV" "1" "2016-07-10" "3.8" "LLVM"

     4 .SH NAME

     5 llvm-cov \- emit coverage information

     6 .

     7 .nr rst2man-indent-level 0

     8 .

     9 .de1 rstReportMargin

    10 \\$1 \\n[an-margin]

    11 level \\n[rst2man-indent-level]

    12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

    13 -

    14 \\n[rst2man-indent0]

    15 \\n[rst2man-indent1]

    16 \\n[rst2man-indent2]

    17 ..

    18 .de1 INDENT

    19 .\" .rstReportMargin pre:

    20 . RS \\$1

    21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]

    22 . nr rst2man-indent-level +1

    23 .\" .rstReportMargin post:

    24 ..

    25 .de UNINDENT

    26 . RE

    27 .\" indent \\n[an-margin]

    28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]

    29 .nr rst2man-indent-level -1

    30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]

    31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u

    32 ..

    33 .SH SYNOPSIS

    34 .sp

    35 \fBllvm\-cov\fP \fIcommand\fP [\fIargs...\fP]

    36 .SH DESCRIPTION

    37 .sp

    38 The \fBllvm\-cov\fP tool shows code coverage information for

    39 programs that are instrumented to emit profile data. It can be used to

    40 work with \fBgcov\fP\-style coverage or with \fBclang\fP\(aqs instrumentation

    41 based profiling.

    42 .sp

    43 If the program is invoked with a base name of \fBgcov\fP, it will behave as if

    44 the \fBllvm\-cov gcov\fP command were called. Otherwise, a command should

    45 be provided.

    46 .SH COMMANDS

    47 .INDENT 0.0

    48 .IP \(bu 2

    49 \fI\%gcov\fP

    50 .IP \(bu 2

    51 \fI\%show\fP

    52 .IP \(bu 2

    53 \fI\%report\fP

    54 .UNINDENT

    55 .SH GCOV COMMAND

    56 .SS SYNOPSIS

    57 .sp

    58 \fBllvm\-cov gcov\fP [\fIoptions\fP] \fISOURCEFILE\fP

    59 .SS DESCRIPTION

    60 .sp

    61 The \fBllvm\-cov gcov\fP tool reads code coverage data files and displays

    62 the coverage information for a specified source file. It is compatible with the

    63 \fBgcov\fP tool from version 4.2 of \fBGCC\fP and may also be compatible with some

    64 later versions of \fBgcov\fP\&.

    65 .sp

    66 To use \fBllvm\-cov gcov\fP, you must first build an instrumented version

    67 of your application that collects coverage data as it runs. Compile with the

    68 \fB\-fprofile\-arcs\fP and \fB\-ftest\-coverage\fP options to add the

    69 instrumentation. (Alternatively, you can use the \fB\-\-coverage\fP option, which

    70 includes both of those other options.) You should compile with debugging

    71 information (\fB\-g\fP) and without optimization (\fB\-O0\fP); otherwise, the

    72 coverage data cannot be accurately mapped back to the source code.

    73 .sp

    74 At the time you compile the instrumented code, a \fB\&.gcno\fP data file will be

    75 generated for each object file. These \fB\&.gcno\fP files contain half of the

    76 coverage data. The other half of the data comes from \fB\&.gcda\fP files that are

    77 generated when you run the instrumented program, with a separate \fB\&.gcda\fP

    78 file for each object file. Each time you run the program, the execution counts

    79 are summed into any existing \fB\&.gcda\fP files, so be sure to remove any old

    80 files if you do not want their contents to be included.

    81 .sp

    82 By default, the \fB\&.gcda\fP files are written into the same directory as the

    83 object files, but you can override that by setting the \fBGCOV_PREFIX\fP and

    84 \fBGCOV_PREFIX_STRIP\fP environment variables. The \fBGCOV_PREFIX_STRIP\fP

    85 variable specifies a number of directory components to be removed from the

    86 start of the absolute path to the object file directory. After stripping those

    87 directories, the prefix from the \fBGCOV_PREFIX\fP variable is added. These

    88 environment variables allow you to run the instrumented program on a machine

    89 where the original object file directories are not accessible, but you will

    90 then need to copy the \fB\&.gcda\fP files back to the object file directories

    91 where \fBllvm\-cov gcov\fP expects to find them.

    92 .sp

    93 Once you have generated the coverage data files, run \fBllvm\-cov gcov\fP

    94 for each main source file where you want to examine the coverage results. This

    95 should be run from the same directory where you previously ran the

    96 compiler. The results for the specified source file are written to a file named

    97 by appending a \fB\&.gcov\fP suffix. A separate output file is also created for

    98 each file included by the main source file, also with a \fB\&.gcov\fP suffix added.

    99 .sp

   100 The basic content of an \fB\&.gcov\fP output file is a copy of the source file with

   101 an execution count and line number prepended to every line. The execution

   102 count is shown as \fB\-\fP if a line does not contain any executable code. If

   103 a line contains code but that code was never executed, the count is displayed

   104 as \fB#####\fP\&.

   105 .SS OPTIONS

   106 .INDENT 0.0

   107 .TP

   108 .B \-a, \-\-all\-blocks

   109 Display all basic blocks. If there are multiple blocks for a single line of

   110 source code, this option causes llvm\-cov to show the count for each block

   111 instead of just one count for the entire line.

   112 .UNINDENT

   113 .INDENT 0.0

   114 .TP

   115 .B \-b, \-\-branch\-probabilities

   116 Display conditional branch probabilities and a summary of branch information.

   117 .UNINDENT

   118 .INDENT 0.0

   119 .TP

   120 .B \-c, \-\-branch\-counts

   121 Display branch counts instead of probabilities (requires \-b).

   122 .UNINDENT

   123 .INDENT 0.0

   124 .TP

   125 .B \-f, \-\-function\-summaries

   126 Show a summary of coverage for each function instead of just one summary for

   127 an entire source file.

   128 .UNINDENT

   129 .INDENT 0.0

   130 .TP

   131 .B \-\-help

   132 Display available options (\-\-help\-hidden for more).

   133 .UNINDENT

   134 .INDENT 0.0

   135 .TP

   136 .B \-l, \-\-long\-file\-names

   137 For coverage output of files included from the main source file, add the

   138 main file name followed by \fB##\fP as a prefix to the output file names. This

   139 can be combined with the \-\-preserve\-paths option to use complete paths for

   140 both the main file and the included file.

   141 .UNINDENT

   142 .INDENT 0.0

   143 .TP

   144 .B \-n, \-\-no\-output

   145 Do not output any \fB\&.gcov\fP files. Summary information is still

   146 displayed.

   147 .UNINDENT

   148 .INDENT 0.0

   149 .TP

   150 .B \-o=<DIR|FILE>, \-\-object\-directory=<DIR>, \-\-object\-file=<FILE>

   151 Find objects in DIR or based on FILE\(aqs path. If you specify a particular

   152 object file, the coverage data files are expected to have the same base name

   153 with \fB\&.gcno\fP and \fB\&.gcda\fP extensions. If you specify a directory, the

   154 files are expected in that directory with the same base name as the source

   155 file.

   156 .UNINDENT

   157 .INDENT 0.0

   158 .TP

   159 .B \-p, \-\-preserve\-paths

   160 Preserve path components when naming the coverage output files. In addition

   161 to the source file name, include the directories from the path to that

   162 file. The directories are separate by \fB#\fP characters, with \fB\&.\fP directories

   163 removed and \fB\&..\fP directories replaced by \fB^\fP characters. When used with

   164 the \-\-long\-file\-names option, this applies to both the main file name and the

   165 included file name.

   166 .UNINDENT

   167 .INDENT 0.0

   168 .TP

   169 .B \-u, \-\-unconditional\-branches

   170 Include unconditional branches in the output for the \-\-branch\-probabilities

   171 option.

   172 .UNINDENT

   173 .INDENT 0.0

   174 .TP

   175 .B \-version

   176 Display the version of llvm\-cov.

   177 .UNINDENT

   178 .SS EXIT STATUS

   179 .sp

   180 \fBllvm\-cov gcov\fP returns 1 if it cannot read input files.  Otherwise,

   181 it exits with zero.

   182 .SH SHOW COMMAND

   183 .SS SYNOPSIS

   184 .sp

   185 \fBllvm\-cov show\fP [\fIoptions\fP] \-instr\-profile \fIPROFILE\fP \fIBIN\fP [\fISOURCES\fP]

   186 .SS DESCRIPTION

   187 .sp

   188 The \fBllvm\-cov show\fP command shows line by line coverage of a binary

   189 \fIBIN\fP using the profile data \fIPROFILE\fP\&. It can optionally be filtered to only

   190 show the coverage for the files listed in \fISOURCES\fP\&.

   191 .sp

   192 To use \fBllvm\-cov show\fP, you need a program that is compiled with

   193 instrumentation to emit profile and coverage data. To build such a program with

   194 \fBclang\fP use the \fB\-fprofile\-instr\-generate\fP and \fB\-fcoverage\-mapping\fP

   195 flags. If linking with the \fBclang\fP driver, pass \fB\-fprofile\-instr\-generate\fP

   196 to the link stage to make sure the necessary runtime libraries are linked in.

   197 .sp

   198 The coverage information is stored in the built executable or library itself,

   199 and this is what you should pass to \fBllvm\-cov show\fP as the \fIBIN\fP

   200 argument. The profile data is generated by running this instrumented program

   201 normally. When the program exits it will write out a raw profile file,

   202 typically called \fBdefault.profraw\fP, which can be converted to a format that

   203 is suitable for the \fIPROFILE\fP argument using the \fBllvm\-profdata merge\fP

   204 tool.

   205 .SS OPTIONS

   206 .INDENT 0.0

   207 .TP

   208 .B \-show\-line\-counts

   209 Show the execution counts for each line. This is enabled by default, unless

   210 another \fB\-show\fP option is used.

   211 .UNINDENT

   212 .INDENT 0.0

   213 .TP

   214 .B \-show\-expansions

   215 Expand inclusions, such as preprocessor macros or textual inclusions, inline

   216 in the display of the source file.

   217 .UNINDENT

   218 .INDENT 0.0

   219 .TP

   220 .B \-show\-instantiations

   221 For source regions that are instantiated multiple times, such as templates in

   222 \fBC++\fP, show each instantiation separately as well as the combined summary.

   223 .UNINDENT

   224 .INDENT 0.0

   225 .TP

   226 .B \-show\-regions

   227 Show the execution counts for each region by displaying a caret that points to

   228 the character where the region starts.

   229 .UNINDENT

   230 .INDENT 0.0

   231 .TP

   232 .B \-show\-line\-counts\-or\-regions

   233 Show the execution counts for each line if there is only one region on the

   234 line, but show the individual regions if there are multiple on the line.

   235 .UNINDENT

   236 .INDENT 0.0

   237 .TP

   238 .B \-use\-color[=VALUE]

   239 Enable or disable color output. By default this is autodetected.

   240 .UNINDENT

   241 .INDENT 0.0

   242 .TP

   243 .B \-arch=<name>

   244 If the covered binary is a universal binary, select the architecture to use.

   245 It is an error to specify an architecture that is not included in the

   246 universal binary or to use an architecture that does not match a

   247 non\-universal binary.

   248 .UNINDENT

   249 .INDENT 0.0

   250 .TP

   251 .B \-name=<NAME>

   252 Show code coverage only for functions with the given name.

   253 .UNINDENT

   254 .INDENT 0.0

   255 .TP

   256 .B \-name\-regex=<PATTERN>

   257 Show code coverage only for functions that match the given regular expression.

   258 .UNINDENT

   259 .INDENT 0.0

   260 .TP

   261 .B \-line\-coverage\-gt=<N>

   262 Show code coverage only for functions with line coverage greater than the

   263 given threshold.

   264 .UNINDENT

   265 .INDENT 0.0

   266 .TP

   267 .B \-line\-coverage\-lt=<N>

   268 Show code coverage only for functions with line coverage less than the given

   269 threshold.

   270 .UNINDENT

   271 .INDENT 0.0

   272 .TP

   273 .B \-region\-coverage\-gt=<N>

   274 Show code coverage only for functions with region coverage greater than the

   275 given threshold.

   276 .UNINDENT

   277 .INDENT 0.0

   278 .TP

   279 .B \-region\-coverage\-lt=<N>

   280 Show code coverage only for functions with region coverage less than the given

   281 threshold.

   282 .UNINDENT

   283 .SH REPORT COMMAND

   284 .SS SYNOPSIS

   285 .sp

   286 \fBllvm\-cov report\fP [\fIoptions\fP] \-instr\-profile \fIPROFILE\fP \fIBIN\fP [\fISOURCES\fP]

   287 .SS DESCRIPTION

   288 .sp

   289 The \fBllvm\-cov report\fP command displays a summary of the coverage of a

   290 binary \fIBIN\fP using the profile data \fIPROFILE\fP\&. It can optionally be filtered to

   291 only show the coverage for the files listed in \fISOURCES\fP\&.

   292 .sp

   293 If no source files are provided, a summary line is printed for each file in the

   294 coverage data. If any files are provided, summaries are shown for each function

   295 in the listed files instead.

   296 .sp

   297 For information on compiling programs for coverage and generating profile data,

   298 see \fI\%SHOW COMMAND\fP\&.

   299 .SS OPTIONS

   300 .INDENT 0.0

   301 .TP

   302 .B \-use\-color[=VALUE]

   303 Enable or disable color output. By default this is autodetected.

   304 .UNINDENT

   305 .INDENT 0.0

   306 .TP

   307 .B \-arch=<name>

   308 If the covered binary is a universal binary, select the architecture to use.

   309 It is an error to specify an architecture that is not included in the

   310 universal binary or to use an architecture that does not match a

   311 non\-universal binary.

   312 .UNINDENT

   313 .SH AUTHOR

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

   315 .SH COPYRIGHT

   316 2003-2016, LLVM Project

   317 .\" Generated by docutils manpage writer.

   318 .