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