forked from llvm-mirror/clang
-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathdiagnostics.html
407 lines (346 loc) · 17.5 KB
/
diagnostics.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<title>Clang - Expressive Diagnostics</title>
<link type="text/css" rel="stylesheet" href="menu.css">
<link type="text/css" rel="stylesheet" href="content.css">
<style type="text/css">
.warn { color:magenta; }
.err { color:red; }
.snip { color:darkgreen; }
.point { color:blue; }
</style>
</head>
<body>
<!--#include virtual="menu.html.incl"-->
<div id="content">
<!--=======================================================================-->
<h1>Expressive Diagnostics</h1>
<!--=======================================================================-->
<p>In addition to being fast and functional, we aim to make Clang extremely user
friendly. As far as a command-line compiler goes, this basically boils down to
making the diagnostics (error and warning messages) generated by the compiler
be as useful as possible. There are several ways that we do this. This section
talks about the experience provided by the command line compiler, contrasting
Clang output to GCC 4.2's output in several examples.
<!--
Other clients
that embed Clang and extract equivalent information through internal APIs.-->
</p>
<h2>Column Numbers and Caret Diagnostics</h2>
<p>First, all diagnostics produced by clang include full column number
information. The clang command-line compiler driver uses this information
to print "point diagnostics".
(IDEs can use the information to display in-line error markup.)
Precise error location in the source is a feature provided by many commercial
compilers, but is generally missing from open source
compilers. This is nice because it makes it very easy to understand exactly
what is wrong in a particular piece of code</p>
<p>The point (the blue "^" character) exactly shows where the problem is, even
inside of a string. This makes it really easy to jump to the problem and
helps when multiple instances of the same character occur on a line. (We'll
revisit this more in following examples.)</p>
<pre>
$ <b>gcc-4.2 -fsyntax-only -Wformat format-strings.c</b>
format-strings.c:91: warning: too few arguments for format
$ <b>clang -fsyntax-only format-strings.c</b>
format-strings.c:91:13: <span class="warn">warning:</span> '.*' specified field precision is missing a matching 'int' argument
<span class="snip"> printf("%.*d");</span>
<span class="point"> ^</span>
</pre>
<h2>Range Highlighting for Related Text</h2>
<p>Clang captures and accurately tracks range information for expressions,
statements, and other constructs in your program and uses this to make
diagnostics highlight related information. In the following somewhat
nonsensical example you can see that you don't even need to see the original source code to
understand what is wrong based on the Clang error. Because clang prints a
point, you know exactly <em>which</em> plus it is complaining about. The range
information highlights the left and right side of the plus which makes it
immediately obvious what the compiler is talking about.
Range information is very useful for
cases involving precedence issues and many other cases.</p>
<pre>
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c:7: error: invalid operands to binary + (have 'int' and 'struct A')
$ <b>clang -fsyntax-only t.c</b>
t.c:7:39: <span class="err">error:</span> invalid operands to binary expression ('int' and 'struct A')
<span class="snip"> return y + func(y ? ((SomeA.X + 40) + SomeA) / 42 + SomeA.X : SomeA.X);</span>
<span class="point"> ~~~~~~~~~~~~~~ ^ ~~~~~</span>
</pre>
<h2>Precision in Wording</h2>
<p>A detail is that we have tried really hard to make the diagnostics that come
out of clang contain exactly the pertinent information about what is wrong and
why. In the example above, we tell you what the inferred types are for
the left and right hand sides, and we don't repeat what is obvious from the
point (e.g., that this is a "binary +").</p>
<p>Many other examples abound. In the following example, not only do we tell you that there is a problem with the *
and point to it, we say exactly why and tell you what the type is (in case it is
a complicated subexpression, such as a call to an overloaded function). This
sort of attention to detail makes it much easier to understand and fix problems
quickly.</p>
<pre>
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c:5: error: invalid type argument of 'unary *'
$ <b>clang -fsyntax-only t.c</b>
t.c:5:11: <span class="err">error:</span> indirection requires pointer operand ('int' invalid)
<span class="snip"> int y = *SomeA.X;</span>
<span class="point"> ^~~~~~~~</span>
</pre>
<h2>No Pretty Printing of Expressions in Diagnostics</h2>
<p>Since Clang has range highlighting, it never needs to pretty print your code
back out to you. GCC can produce inscrutible error messages in some cases when
it tries to do this. In this example P and Q have type "int*":</p>
<pre>
$ <b>gcc-4.2 -fsyntax-only t.c</b>
#'exact_div_expr' not supported by pp_c_expression#'t.c:12: error: called object is not a function
$ <b>clang -fsyntax-only t.c</b>
t.c:12:8: <span class="err">error:</span> called object type 'int' is not a function or function pointer
<span class="snip"> (P-Q)();</span>
<span class="point"> ~~~~~^</span>
</pre>
<p>This can be particularly bad in G++, which often emits errors
containing lowered vtable references. For example:</p>
<pre>
$ <b>cat t.cc</b>
struct a {
virtual int bar();
};
struct foo : public virtual a {
};
void test(foo *P) {
return P->bar() + *P;
}
$ <b>gcc-4.2 t.cc</b>
t.cc: In function 'void test(foo*)':
t.cc:9: error: no match for 'operator+' in '(((a*)P) + (*(long int*)(P->foo::<anonymous>.a::_vptr$a + -0x00000000000000020)))->a::bar() + * P'
t.cc:9: error: return-statement with a value, in function returning 'void'
$ <b>clang t.cc</b>
t.cc:9:18: <span class="err">error:</span> invalid operands to binary expression ('int' and 'foo')
<span class="snip"> return P->bar() + *P;</span>
<span class="point"> ~~~~~~~~ ^ ~~</span>
</pre>
<h2>Typedef Preservation and Selective Unwrapping</h2>
<p>Many programmers use high-level user defined types, typedefs, and other
syntactic sugar to refer to types in their program. This is useful because they
can abbreviate otherwise very long types and it is useful to preserve the
typename in diagnostics. However, sometimes very simple typedefs can wrap
trivial types and it is important to strip off the typedef to understand what
is going on. Clang aims to handle both cases well.<p>
<p>The following example shows where it is important to preserve
a typedef in C. Here the type printed by GCC isn't even valid, but if the error
were about a very long and complicated type (as often happens in C++) the error
message would be ugly just because it was long and hard to read.</p>
<pre>
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c:15: error: invalid operands to binary / (have 'float __vector__' and 'const int *')
$ <b>clang -fsyntax-only t.c</b>
t.c:15:11: <span class="err">error:</span> can't convert between vector values of different size ('__m128' and 'int const *')
<span class="snip"> myvec[1]/P;</span>
<span class="point"> ~~~~~~~~^~</span>
</pre>
<p>The following example shows where it is useful for the compiler to expose
underlying details of a typedef. If the user was somehow confused about how the
system "pid_t" typedef is defined, Clang helpfully displays it with "aka".</p>
<pre>
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c:13: error: request for member 'x' in something not a structure or union
$ <b>clang -fsyntax-only t.c</b>
t.c:13:9: <span class="err">error:</span> member reference base type 'pid_t' (aka 'int') is not a structure or union
<span class="snip"> myvar = myvar.x;</span>
<span class="point"> ~~~~~ ^</span>
</pre>
<p>In C++, type preservation includes retaining any qualification written into type names. For example, if we take a small snippet of code such as:
<blockquote>
<pre>
namespace services {
struct WebService { };
}
namespace myapp {
namespace servers {
struct Server { };
}
}
using namespace myapp;
void addHTTPService(servers::Server const &server, ::services::WebService const *http) {
server += http;
}
</pre>
</blockquote>
<p>and then compile it, we see that Clang is both providing more accurate information and is retaining the types as written by the user (e.g., "servers::Server", "::services::WebService"):
<pre>
$ <b>g++-4.2 -fsyntax-only t.cpp</b>
t.cpp:9: error: no match for 'operator+=' in 'server += http'
$ <b>clang -fsyntax-only t.cpp</b>
t.cpp:9:10: <span class="err">error:</span> invalid operands to binary expression ('servers::Server const' and '::services::WebService const *')
<span class="snip">server += http;</span>
<span class="point">~~~~~~ ^ ~~~~</span>
</pre>
<p>Naturally, type preservation extends to uses of templates, and Clang retains information about how a particular template specialization (like <code>std::vector<Real></code>) was spelled within the source code. For example:</p>
<pre>
$ <b>g++-4.2 -fsyntax-only t.cpp</b>
t.cpp:12: error: no match for 'operator=' in 'str = vec'
$ <b>clang -fsyntax-only t.cpp</b>
t.cpp:12:7: <span class="err">error:</span> incompatible type assigning 'vector<Real>', expected 'std::string' (aka 'class std::basic_string<char>')
<span class="snip">str = vec</span>;
<span class="point">^ ~~~</span>
</pre>
<h2>Fix-it Hints</h2>
<p>"Fix-it" hints provide advice for fixing small, localized problems
in source code. When Clang produces a diagnostic about a particular
problem that it can work around (e.g., non-standard or redundant
syntax, missing keywords, common mistakes, etc.), it may also provide
specific guidance in the form of a code transformation to correct the
problem. In the following example, Clang warns about the use of a GCC
extension that has been considered obsolete since 1993. The underlined
code should be removed, then replaced with the code below the
point line (".x =" or ".y =", respectively).</p>
<pre>
$ <b>clang t.c</b>
t.c:5:28: <span class="warn">warning:</span> use of GNU old-style field designator extension
<span class="snip">struct point origin = { x: 0.0, y: 0.0 };</span>
<span class="err">~~</span> <span class="point">^</span>
<span class="snip">.x = </span>
t.c:5:36: <span class="warn">warning:</span> use of GNU old-style field designator extension
<span class="snip">struct point origin = { x: 0.0, y: 0.0 };</span>
<span class="err">~~</span> <span class="point">^</span>
<span class="snip">.y = </span>
</pre>
<p>"Fix-it" hints are most useful for
working around common user errors and misconceptions. For example, C++ users
commonly forget the syntax for explicit specialization of class templates,
as in the error in the following example. Again, after describing the problem,
Clang provides the fix--add <code>template<></code>--as part of the
diagnostic.<p>
<pre>
$ <b>clang t.cpp</b>
t.cpp:9:3: <span class="err">error:</span> template specialization requires 'template<>'
struct iterator_traits<file_iterator> {
<span class="point">^</span>
<span class="snip">template<> </span>
</pre>
<h2>Template Type Diffing</h2>
<p>Templates types can be long and difficult to read. Moreso when part of an
error message. Instead of just printing out the type name, Clang has enough
information to remove the common elements and highlight the differences. To
show the template structure more clearly, the templated type can also be
printed as an indented text tree.</p>
Default: template diff with type elision
<pre>
t.cc:4:5: <span class="note">note:</span> candidate function not viable: no known conversion from 'vector<map<[...], <span class="template-highlight">float</span>>>' to 'vector<map<[...], <span class="template-highlight">double</span>>>' for 1st argument;
</pre>
-fno-elide-type: template diff without elision
<pre>
t.cc:4:5: <span class="note">note:</span> candidate function not viable: no known conversion from 'vector<map<int, <span class="template-highlight">float</span>>>' to 'vector<map<int, <span class="template-highlight">double</span>>>' for 1st argument;
</pre>
-fdiagnostics-show-template-tree: template tree printing with elision
<pre>
t.cc:4:5: <span class="note">note:</span> candidate function not viable: no known conversion for 1st argument;
vector<
map<
[...],
[<span class="template-highlight">float</span> != <span class="template-highlight">double</span>]>>
</pre>
-fdiagnostics-show-template-tree -fno-elide-type: template tree printing with no elision
<pre>
t.cc:4:5: <span class="note">note:M</span> candidate function not viable: no known conversion for 1st argument;
vector<
map<
int,
[<span class="template-highlight">float</span> != <span class="template-highlight">double</span>]>>
</pre>
<h2>Automatic Macro Expansion</h2>
<p>Many errors happen in macros that are sometimes deeply nested. With
traditional compilers, you need to dig deep into the definition of the macro to
understand how you got into trouble. The following simple example shows how
Clang helps you out by automatically printing instantiation information and
nested range information for diagnostics as they are instantiated through macros
and also shows how some of the other pieces work in a bigger example.</p>
<pre>
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c: In function 'test':
t.c:80: error: invalid operands to binary < (have 'struct mystruct' and 'float')
$ <b>clang -fsyntax-only t.c</b>
t.c:80:3: <span class="err">error:</span> invalid operands to binary expression ('typeof(P)' (aka 'struct mystruct') and 'typeof(F)' (aka 'float'))
<span class="snip"> X = MYMAX(P, F);</span>
<span class="point"> ^~~~~~~~~~~</span>
t.c:76:94: note: instantiated from:
<span class="snip">#define MYMAX(A,B) __extension__ ({ __typeof__(A) __a = (A); __typeof__(B) __b = (B); __a < __b ? __b : __a; })</span>
<span class="point"> ~~~ ^ ~~~</span>
</pre>
<p>Here's another real world warning that occurs in the "window" Unix package (which
implements the "wwopen" class of APIs):</p>
<pre>
$ <b>clang -fsyntax-only t.c</b>
t.c:22:2: <span class="warn">warning:</span> type specifier missing, defaults to 'int'
<span class="snip"> ILPAD();</span>
<span class="point"> ^</span>
t.c:17:17: note: instantiated from:
<span class="snip">#define ILPAD() PAD((NROW - tt.tt_row) * 10) /* 1 ms per char */</span>
<span class="point"> ^</span>
t.c:14:2: note: instantiated from:
<span class="snip"> register i; \</span>
<span class="point"> ^</span>
</pre>
<p>In practice, we've found that Clang's treatment of macros is actually more useful in multiply nested
macros that in simple ones.</p>
<h2>Quality of Implementation and Attention to Detail</h2>
<p>Finally, we have put a lot of work polishing the little things, because
little things add up over time and contribute to a great user experience.</p>
<p>The following example shows a trivial little tweak, where we tell you to put the semicolon at
the end of the line that is missing it (line 4) instead of at the beginning of
the following line (line 5). This is particularly important with fixit hints
and point diagnostics, because otherwise you don't get the important context.
</p>
<pre>
$ <b>gcc-4.2 t.c</b>
t.c: In function 'foo':
t.c:5: error: expected ';' before '}' token
$ <b>clang t.c</b>
t.c:4:8: <span class="err">error:</span> expected ';' after expression
<span class="snip"> bar()</span>
<span class="point"> ^</span>
<span class="point"> ;</span>
</pre>
<p>The following example shows much better error recovery than GCC. The message coming out
of GCC is completely useless for diagnosing the problem. Clang tries much harder
and produces a much more useful diagnosis of the problem.</p>
<pre>
$ <b>gcc-4.2 t.c</b>
t.c:3: error: expected '=', ',', ';', 'asm' or '__attribute__' before '*' token
$ <b>clang t.c</b>
t.c:3:1: <span class="err">error:</span> unknown type name 'foo_t'
<span class="snip">foo_t *P = 0;</span>
<span class="point">^</span>
</pre>
<p>The following example shows that we recover from the simple case of
forgetting a ; after a struct definition much better than GCC.</p>
<pre>
$ <b>cat t.cc</b>
template<class T>
class a {}
class temp {};
a<temp> b;
struct b {
}
$ <b>gcc-4.2 t.cc</b>
t.cc:3: error: multiple types in one declaration
t.cc:4: error: non-template type 'a' used as a template
t.cc:4: error: invalid type in declaration before ';' token
t.cc:6: error: expected unqualified-id at end of input
$ <b>clang t.cc</b>
t.cc:2:11: <span class="err">error:</span> expected ';' after class
<span class="snip">class a {}</span>
<span class="point"> ^</span>
<span class="point"> ;</span>
t.cc:6:2: <span class="err">error:</span> expected ';' after struct
<span class="snip">}</span>
<span class="point"> ^</span>
<span class="point"> ;</span>
</pre>
<p>While each of these details is minor, we feel that they all add up to provide
a much more polished experience.</p>
</div>
</body>
</html>