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