diff options
Diffstat (limited to 'www/diagnostics.html')
| -rw-r--r-- | www/diagnostics.html | 152 |
1 files changed, 78 insertions, 74 deletions
diff --git a/www/diagnostics.html b/www/diagnostics.html index b3b168b..45f6907 100644 --- a/www/diagnostics.html +++ b/www/diagnostics.html @@ -4,10 +4,14 @@ <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" /> + <link type="text/css" rel="stylesheet" href="menu.css"> + <link type="text/css" rel="stylesheet" href="content.css"> <style type="text/css"> -</style> + .warn { color:magenta; } + .err { color:red; } + .snip { color:darkgreen; } + .point { color:blue; } + </style> </head> <body> @@ -35,14 +39,14 @@ that embed Clang and extract equivalent information through internal APIs.--> <p>First, all diagnostics produced by clang include full column number information. The clang command-line compiler driver uses this information -to print "caret diagnostics". +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 caret (the blue "^" character) exactly shows where the problem is, even +<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> @@ -51,9 +55,9 @@ revisit this more in following examples.)</p> $ <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: <font color="magenta">warning:</font> '.*' specified field precision is missing a matching 'int' argument - <font color="darkgreen"> printf("%.*d");</font> - <font color="blue"> ^</font> + 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> @@ -63,7 +67,7 @@ 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 -caret, you know exactly <em>which</em> plus it is complaining about. The range +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 @@ -73,9 +77,9 @@ cases involving precedence issues and many other cases.</p> $ <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: <font color="red">error:</font> invalid operands to binary expression ('int' and 'struct A') - <font color="darkgreen"> return y + func(y ? ((SomeA.X + 40) + SomeA) / 42 + SomeA.X : SomeA.X);</font> - <font color="blue"> ~~~~~~~~~~~~~~ ^ ~~~~~</font> + 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> @@ -84,7 +88,7 @@ cases involving precedence issues and many other cases.</p> 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 -caret (e.g., that this is a "binary +").</p> +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 @@ -96,9 +100,9 @@ quickly.</p> $ <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: <font color="red">error:</font> indirection requires pointer operand ('int' invalid) - <font color="darkgreen"> int y = *SomeA.X;</font> - <font color="blue"> ^~~~~~~~</font> + 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> @@ -111,9 +115,9 @@ it tries to do this. In this example P and Q have type "int*":</p> $ <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: <font color="red">error:</font> called object type 'int' is not a function or function pointer - <font color="darkgreen"> (P-Q)();</font> - <font color="blue"> ~~~~~^</font> + 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 @@ -136,9 +140,9 @@ it tries to do this. In this example P and Q have type "int*":</p> 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: <font color="red">error:</font> invalid operands to binary expression ('int' and 'foo') - <font color="darkgreen"> return P->bar() + *P;</font> - <font color="blue"> ~~~~~~~~ ^ ~~</font> + 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> @@ -160,9 +164,9 @@ message would be ugly just because it was long and hard to read.</p> $ <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: <font color="red">error:</font> can't convert between vector values of different size ('__m128' and 'int const *') - <font color="darkgreen"> myvec[1]/P;</font> - <font color="blue"> ~~~~~~~~^~</font> + 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 @@ -173,9 +177,9 @@ system "pid_t" typedef is defined, Clang helpfully displays it with "aka".</p> $ <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: <font color="red">error:</font> member reference base type 'pid_t' (aka 'int') is not a structure or union - <font color="darkgreen"> myvar = myvar.x;</font> - <font color="blue"> ~~~~~ ^</font> + 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: @@ -204,9 +208,9 @@ void addHTTPService(servers::Server const &server, ::services::WebService co $ <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: <font color="red">error:</font> invalid operands to binary expression ('servers::Server const' and '::services::WebService const *') - <font color="darkgreen">server += http;</font> - <font color="blue">~~~~~~ ^ ~~~~</font> + 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> @@ -215,9 +219,9 @@ void addHTTPService(servers::Server const &server, ::services::WebService co $ <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: <font color="red">error:</font> incompatible type assigning 'vector<Real>', expected 'std::string' (aka 'class std::basic_string<char>') - <font color="darkgreen">str = vec</font>; - <font color="blue">^ ~~~</font> + 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> @@ -230,18 +234,18 @@ 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 -caret line (".x =" or ".y =", respectively).</p> +point line (".x =" or ".y =", respectively).</p> <pre> $ <b>clang t.c</b> - t.c:5:28: <font color="magenta">warning:</font> use of GNU old-style field designator extension - <font color="darkgreen">struct point origin = { x: 0.0, y: 0.0 };</font> - <font color="red">~~</font> <font color="blue">^</font> - <font color="darkgreen">.x = </font> - t.c:5:36: <font color="magenta">warning:</font> use of GNU old-style field designator extension - <font color="darkgreen">struct point origin = { x: 0.0, y: 0.0 };</font> - <font color="red">~~</font> <font color="blue">^</font> - <font color="darkgreen">.y = </font> + 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 @@ -253,10 +257,10 @@ diagnostic.<p> <pre> $ <b>clang t.cpp</b> - t.cpp:9:3: <font color="red">error:</font> template specialization requires 'template<>' + t.cpp:9:3: <span class="err">error:</span> template specialization requires 'template<>' struct iterator_traits<file_iterator> { - <font color="blue">^</font> - <font color="darkgreen">template<> </font> + <span class="point">^</span> + <span class="snip">template<> </span> </pre> <h2>Automatic Macro Expansion</h2> @@ -273,12 +277,12 @@ and also shows how some of the other pieces work in a bigger example.</p> 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: <font color="red">error:</font> invalid operands to binary expression ('typeof(P)' (aka 'struct mystruct') and 'typeof(F)' (aka 'float')) - <font color="darkgreen"> X = MYMAX(P, F);</font> - <font color="blue"> ^~~~~~~~~~~</font> + 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: - <font color="darkgreen">#define MYMAX(A,B) __extension__ ({ __typeof__(A) __a = (A); __typeof__(B) __b = (B); __a < __b ? __b : __a; })</font> - <font color="blue"> ~~~ ^ ~~~</font> + <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 @@ -286,15 +290,15 @@ implements the "wwopen" class of APIs):</p> <pre> $ <b>clang -fsyntax-only t.c</b> - t.c:22:2: <font color="magenta">warning:</font> type specifier missing, defaults to 'int' - <font color="darkgreen"> ILPAD();</font> - <font color="blue"> ^</font> + 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: - <font color="darkgreen">#define ILPAD() PAD((NROW - tt.tt_row) * 10) /* 1 ms per char */</font> - <font color="blue"> ^</font> + <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: - <font color="darkgreen"> register i; \</font> - <font color="blue"> ^</font> + <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 @@ -308,7 +312,7 @@ 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 caret diagnostics, because otherwise you don't get the important context. +and point diagnostics, because otherwise you don't get the important context. </p> <pre> @@ -316,10 +320,10 @@ and caret diagnostics, because otherwise you don't get the important context. t.c: In function 'foo': t.c:5: error: expected ';' before '}' token $ <b>clang t.c</b> - t.c:4:8: <font color="red">error:</font> expected ';' after expression - <font color="darkgreen"> bar()</font> - <font color="blue"> ^</font> - <font color="blue"> ;</font> + 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 @@ -330,9 +334,9 @@ and produces a much more useful diagnosis of the problem.</p> $ <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: <font color="red">error:</font> unknown type name 'foo_t' - <font color="darkgreen">foo_t *P = 0;</font> - <font color="blue">^</font> + 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 @@ -352,14 +356,14 @@ forgetting a ; after a struct definition much better than GCC.</p> 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: <font color="red">error:</font> expected ';' after class - <font color="darkgreen">class a {}</font> - <font color="blue"> ^</font> - <font color="blue"> ;</font> - t.cc:6:2: <font color="red">error:</font> expected ';' after struct - <font color="darkgreen">}</font> - <font color="blue"> ^</font> - <font color="blue"> ;</font> + 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 |
