www/compatibility.html

   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>Language Compatibility</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 <h1>Language Compatibility</h1>
  20 <!-- ======================================================================= -->
  21
  22 <p>Clang strives to both conform to current language standards (C99,
  23   C++98) and also to implement many widely-used extensions available
  24   in other compilers, so that most correct code will "just work" when
  25   compiler with Clang. However, Clang is more strict than other
  26   popular compilers, and may reject incorrect code that other
  27   compilers allow. This page documents common compatibility and
  28   portability issues with Clang to help you understand and fix the
  29   problem in your code when Clang emits an error message.</p>
  30
  31 <ul>
  32   <li><a href="#c">C compatibility</a>
  33     <ul>
  34       <li><a href="#inline">C99 inline functions</a></li>
  35       <li><a href="#vector_builtins">"missing" vector __builtin functions</a></li>
  36       <li><a href="#lvalue-cast">Lvalue casts</a></li>
  37       <li><a href="#blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</a></li>
  38       <li><a href="#block-variable-initialization">Non-initialization of <tt>__block</tt> variables</a></li>
  39       <li><a href="#inline-asm">Inline assembly</a></li>
  40     </ul>
  41   </li>
  42   <li><a href="#objective-c">Objective-C compatibility</a>
  43     <ul>
  44       <li><a href="#super-cast">Cast of super</a></li>
  45       <li><a href="#sizeof-interface">Size of interfaces</a></li>
  46       <li><a href="#objc_objs-cast">Internal Objective-C types</a></li>
  47       <li><a href="#c_variables-class">C variables in @class or @protocol</a></li>
  48     </ul>
  49   </li>
  50   <li><a href="#c++">C++ compatibility</a>
  51     <ul>
  52       <li><a href="#vla">Variable-length arrays</a></li>
  53       <li><a href="#dep_lookup">Unqualified lookup in templates</a></li>
  54       <li><a href="#dep_lookup_bases">Unqualified lookup into dependent bases of class templates</a></li>
  55       <li><a href="#undep_incomplete">Incomplete types in templates</a></li>
  56       <li><a href="#bad_templates">Templates with no valid instantiations</a></li>
  57       <li><a href="#default_init_const">Default initialization of const
  58       variable of a class type requires user-defined default
  59       constructor</a></li>
  60       <li><a href="#param_name_lookup">Parameter name lookup</a></li>
  61     </ul>
  62   </li>
  63   <li><a href="#objective-c++">Objective-C++ compatibility</a>
  64     <ul>
  65       <li><a href="#implicit-downcasts">Implicit downcasts</a></li>
  66     </ul>
  67     <ul>
  68       <li><a href="#class-as-property-name">Using <code>class</code> as a property name</a></li>
  69     </ul>
  70   </li>
  71 </ul>
  72
  73 <!-- ======================================================================= -->
  74 <h2 id="c">C compatibility</h3>
  75 <!-- ======================================================================= -->
  76
  77 <!-- ======================================================================= -->
  78 <h3 id="inline">C99 inline functions</h3>
  79 <!-- ======================================================================= -->
  80 <p>By default, Clang builds C code according to the C99 standard,
  81 which provides different semantics for the <code>inline</code> keyword
  82 than GCC's default behavior. For example, consider the following
  83 code:</p>
  84 <pre>
  85 inline int add(int i, int j) { return i + j; }
  86
  87 int main() {
  88   int i = add(4, 5);
  89   return i;
  90 }
  91 </pre>
  92
  93 <p>In C99, <code>inline</code> means that a function's definition is
  94 provided only for inlining, and that there is another definition
  95 (without <code>inline</code>) somewhere else in the program.  That
  96 means that this program is incomplete, because if <code>add</code>
  97 isn't inlined (for example, when compiling without optimization), then
  98 <code>main</code> will have an unresolved reference to that other
  99 definition.  Therefore we'll get a (correct) link-time error like this:</p>
 100
 101 <pre>
 102 Undefined symbols:
 103   "_add", referenced from:
 104       _main in cc-y1jXIr.o
 105 </pre>
 106
 107 <p>By contrast, GCC's default behavior follows the GNU89 dialect,
 108 which is the C89 standard plus a lot of extensions.  C89 doesn't have
 109 an <code>inline</code> keyword, but GCC recognizes it as an extension
 110 and just treats it as a hint to the optimizer.</p>
 111
 112 <p>There are several ways to fix this problem:</p>
 113
 114 <ul>
 115   <li>Change <code>add</code> to a <code>static inline</code>
 116   function.  This is usually the right solution if only one
 117   translation unit needs to use the function.  <code>static
 118   inline</code> functions are always resolved within the translation
 119   unit, so you won't have to add a non-<code>inline</code> definition
 120   of the function elsewhere in your program.</li>
 121
 122   <li>Remove the <code>inline</code> keyword from this definition of
 123   <code>add</code>.  The <code>inline</code> keyword is not required
 124   for a function to be inlined, nor does it guarantee that it will be.
 125   Some compilers ignore it completely.  Clang treats it as a mild
 126   suggestion from the programmer.</li>
 127
 128   <li>Provide an external (non-<code>inline</code>) definition
 129   of <code>add</code> somewhere else in your program.  The two
 130   definitions must be equivalent!</li>
 131
 132   <li>Compile with the GNU89 dialect by adding
 133   <code>-std=gnu89</code> to the set of Clang options. This option is
 134   only recommended if the program source cannot be changed or if the
 135   program also relies on additional C89-specific behavior that cannot
 136   be changed.</li>
 137 </ul>
 138
 139 <p>All of this only applies to C code; the meaning of <code>inline</code>
 140 in C++ is very different from its meaning in either GNU89 or C99.</p>
 141
 142 <!-- ======================================================================= -->
 143 <h3 id="vector_builtins">"missing" vector __builtin functions</h3>
 144 <!-- ======================================================================= -->
 145
 146 <p>The Intel and AMD manuals document a number "<tt>&lt;*mmintrin.h&gt;</tt>"
 147 header files, which define a standardized API for accessing vector operations
 148 on X86 CPUs.  These functions have names like <tt>_mm_xor_ps</tt> and
 149 <tt>_mm256_addsub_pd</tt>.  Compilers have leeway to implement these functions
 150 however they want.  Since Clang supports an excellent set of <a
 151 href="../docs/LanguageExtensions.html#vectors">native vector operations</a>,
 152 the Clang headers implement these interfaces in terms of the native vector
 153 operations.
 154 </p>
 155
 156 <p>In contrast, GCC implements these functions mostly as a 1-to-1 mapping to
 157 builtin function calls, like <tt>__builtin_ia32_paddw128</tt>.  These builtin
 158 functions are an internal implementation detail of GCC, and are not portable to
 159 the Intel compiler, the Microsoft compiler, or Clang.  If you get build errors
 160 mentioning these, the fix is simple: switch to the *mmintrin.h functions.</p>
 161
 162 <p>The same issue occurs for NEON and Altivec for the ARM and PowerPC
 163 architectures respectively.  For these, make sure to use the &lt;arm_neon.h&gt;
 164 and &lt;altivec.h&gt; headers.</p>
 165
 166 <p>For x86 architectures this <a href="builtins.py">script</a> should help with
 167 the manual migration process.  It will rewrite your source files in place to
 168 use the APIs instead of builtin function calls. Just call it like this:</p>
 169
 170 <pre>
 171   builtins.py *.c *.h
 172 </pre>
 173
 174 <p>and it will rewrite all of the .c and .h files in the current directory to
 175 use the API calls instead of calls like <tt>__builtin_ia32_paddw128</tt>.</p>
 176
 177 <!-- ======================================================================= -->
 178 <h3 id="lvalue-cast">Lvalue casts</h3>
 179 <!-- ======================================================================= -->
 180
 181 <p>Old versions of GCC permit casting the left-hand side of an assignment to a
 182 different type. Clang produces an error on similar code, e.g.,</p>
 183
 184 <pre>
 185 lvalue.c:2:3: error: assignment to cast is illegal, lvalue casts are not
 186       supported
 187   (int*)addr = val;
 188   ^~~~~~~~~~ ~
 189 </pre>
 190
 191 <p>To fix this problem, move the cast to the right-hand side. In this
 192 example, one could use:</p>
 193
 194 <pre>
 195   addr = (float *)val;
 196 </pre>
 197
 198 <!-- ======================================================================= -->
 199 <h3 id="blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</h3>
 200 <!-- ======================================================================= -->
 201
 202 <p>Clang disallows jumps into the scope of a <tt>__block</tt>
 203 variable.  Variables marked with <tt>__block</tt> require special
 204 runtime initialization. A jump into the scope of a <tt>__block</tt>
 205 variable bypasses this initialization, leaving the variable's metadata
 206 in an invalid state.  Consider the following code fragment:</p>
 207
 208 <pre>
 209 int fetch_object_state(struct MyObject *c) {
 210   if (!c->active) goto error;
 211
 212   __block int result;
 213   run_specially_somehow(^{ result = c->state; });
 214   return result;
 215
 216  error:
 217   fprintf(stderr, "error while fetching object state");
 218   return -1;
 219 }
 220 </pre>
 221
 222 <p>GCC accepts this code, but it produces code that will usually crash
 223 when <code>result</code> goes out of scope if the jump is taken.  (It's
 224 possible for this bug to go undetected because it often won't crash if
 225 the stack is fresh, i.e. still zeroed.)  Therefore, Clang rejects this
 226 code with a hard error:</p>
 227
 228 <pre>
 229 t.c:3:5: error: goto into protected scope
 230     goto error;
 231     ^
 232 t.c:5:15: note: jump bypasses setup of __block variable
 233   __block int result;
 234               ^
 235 </pre>
 236
 237 <p>The fix is to rewrite the code to not require jumping into a
 238 <tt>__block</tt> variable's scope, e.g. by limiting that scope:</p>
 239
 240 <pre>
 241   {
 242     __block int result;
 243     run_specially_somehow(^{ result = c->state; });
 244     return result;
 245   }
 246 </pre>
 247
 248 <!-- ======================================================================= -->
 249 <h3 id="block-variable-initialization">Non-initialization of <tt>__block</tt>
 250 variables</h3>
 251 <!-- ======================================================================= -->
 252
 253 <p>In the following example code, the <tt>x</tt> variable is used before it is
 254 defined:</p>
 255 <pre>
 256 int f0() {
 257   __block int x;
 258   return ^(){ return x; }();
 259 }
 260 </pre>
 261
 262 <p>By an accident of implementation, GCC and llvm-gcc unintentionally always
 263 zero initialized <tt>__block</tt> variables. However, any program which depends
 264 on this behavior is relying on unspecified compiler behavior. Programs must
 265 explicitly initialize all local block variables before they are used, as with
 266 other local variables.</p>
 267
 268 <p>Clang does not zero initialize local block variables, and programs which rely
 269 on such behavior will most likely break when built with Clang.</p>
 270
 271
 272 <!-- ======================================================================= -->
 273 <h3 id="inline-asm">Inline assembly</h3>
 274 <!-- ======================================================================= -->
 275
 276 <p>In general, Clang is highly compatible with the GCC inline assembly
 277 extensions, allowing the same set of constraints, modifiers and operands as GCC
 278 inline assembly.</p>
 279
 280 <p>On targets that use the integrated assembler (such as most X86 targets),
 281 inline assembly is run through the integrated assembler instead of your system
 282 assembler (which is most commonly "gas", the GNU assembler).  The LLVM
 283 integrated assembler is extremely compatible with GAS, but there are a couple of
 284 minor places where it is more picky, particularly due to outright GAS bugs.</p>
 285
 286 <p>One specific example is that the assembler rejects ambiguous X86 instructions
 287 that don't have suffixes.  For example:</p>
 288
 289 <pre>
 290   asm("add %al, (%rax)");
 291   asm("addw $4, (%rax)");
 292   asm("add $4, (%rax)");
 293 </pre>
 294
 295 <p>Both clang and GAS accept the first instruction: because the first
 296 instruction uses the 8-bit <tt>%al</tt> register as an operand, it is clear that
 297 it is an 8-bit add.  The second instruction is accepted by both because the "w"
 298 suffix indicates that it is a 16-bit add.  The last instruction is accepted by
 299 GAS even though there is nothing that specifies the size of the instruction (and
 300 the assembler randomly picks a 32-bit add).  Because it is ambiguous, Clang
 301 rejects the instruction with this error message:
 302 </p>
 303
 304 <pre>
 305 &lt;inline asm&gt;:3:1: error: ambiguous instructions require an explicit suffix (could be 'addb', 'addw', 'addl', or 'addq')
 306 add $4, (%rax)
 307 ^
 308 1 error generated.
 309 </pre>
 310
 311 <p>To fix this compatibility issue, add an explicit suffix to the instruction:
 312 this makes your code more clear and is compatible with both GCC and Clang.</p>
 313
 314 <!-- ======================================================================= -->
 315 <h2 id="objective-c">Objective-C compatibility</h3>
 316 <!-- ======================================================================= -->
 317
 318 <!-- ======================================================================= -->
 319 <h3 id="super-cast">Cast of super</h3>
 320 <!-- ======================================================================= -->
 321
 322 <p>GCC treats the <code>super</code> identifier as an expression that
 323 can, among other things, be cast to a different type. Clang treats
 324 <code>super</code> as a context-sensitive keyword, and will reject a
 325 type-cast of <code>super</code>:</p>
 326
 327 <pre>
 328 super.m:11:12: error: cannot cast 'super' (it isn't an expression)
 329   [(Super*)super add:4];
 330    ~~~~~~~~^
 331 </pre>
 332
 333 <p>To fix this problem, remove the type cast, e.g.</p>
 334 <pre>
 335   [super add:4];
 336 </pre>
 337
 338 <!-- ======================================================================= -->
 339 <h3 id="sizeof-interface">Size of interfaces</h3>
 340 <!-- ======================================================================= -->
 341
 342 <p>When using the "non-fragile" Objective-C ABI in use, the size of an
 343 Objective-C class may change over time as instance variables are added
 344 (or removed). For this reason, Clang rejects the application of the
 345 <code>sizeof</code> operator to an Objective-C class when using this
 346 ABI:</p>
 347
 348 <pre>
 349 sizeof.m:4:14: error: invalid application of 'sizeof' to interface 'NSArray' in
 350       non-fragile ABI
 351   int size = sizeof(NSArray);
 352              ^     ~~~~~~~~~
 353 </pre>
 354
 355 <p>Code that relies on the size of an Objective-C class is likely to
 356 be broken anyway, since that size is not actually constant. To address
 357 this problem, use the Objective-C runtime API function
 358 <code>class_getInstanceSize()</code>:</p>
 359
 360 <pre>
 361   class_getInstanceSize([NSArray class])
 362 </pre>
 363
 364 <!-- ======================================================================= -->
 365 <h3 id="objc_objs-cast">Internal Objective-C types</h3>
 366 <!-- ======================================================================= -->
 367
 368 <p>GCC allows using pointers to internal Objective-C objects, <tt>struct objc_object*</tt>,
 369 <tt>struct objc_selector*</tt>, and <tt>struct objc_class*</tt> in place of the types
 370 <tt>id</tt>, <tt>SEL</tt>, and <tt>Class</tt> respectively. Clang treats the
 371 internal Objective-C structures as implementation detail and won't do implicit conversions:
 372
 373 <pre>
 374 t.mm:11:2: error: no matching function for call to 'f'
 375         f((struct objc_object *)p);
 376         ^
 377 t.mm:5:6: note: candidate function not viable: no known conversion from 'struct objc_object *' to 'id' for 1st argument
 378 void f(id x);
 379      ^
 380 </pre>
 381
 382 <p>Code should use types <tt>id</tt>, <tt>SEL</tt>, and <tt>Class</tt>
 383 instead of the internal types.</p>
 384
 385 <!-- ======================================================================= -->
 386 <h3 id="c_variables-class">C variables in @interface or @protocol</h3>
 387 <!-- ======================================================================= -->
 388
 389 <p>GCC allows the declaration of C variables in
 390 an <code>@interface</code> or <code>@protocol</code>
 391 declaration. Clang does not allow variable declarations to appear
 392 within these declarations unless they are marked <code>extern</code>.</p>
 393
 394 <p>Variables may still be declared in an @implementation.</p>
 395
 396 <pre>
 397 @interface XX
 398 int a;         // not allowed in clang
 399 int b = 1;     // not allowed in clang
 400 extern int c;  // allowed
 401 @end
 402
 403 </pre>
 404
 405 <!-- ======================================================================= -->
 406 <h2 id="c++">C++ compatibility</h3>
 407 <!-- ======================================================================= -->
 408
 409 <!-- ======================================================================= -->
 410 <h3 id="vla">Variable-length arrays</h3>
 411 <!-- ======================================================================= -->
 412
 413 <p>GCC and C99 allow an array's size to be determined at run
 414 time. This extension is not permitted in standard C++. However, Clang
 415 supports such variable length arrays in very limited circumstances for
 416 compatibility with GNU C and C99 programs:</p>
 417
 418 <ul>
 419   <li>The element type of a variable length array must be a POD
 420   ("plain old data") type, which means that it cannot have any
 421   user-declared constructors or destructors, any base classes, or any
 422   members of non-POD type. All C types are POD types.</li>
 423
 424   <li>Variable length arrays cannot be used as the type of a non-type
 425 template parameter.</li> </ul>
 426
 427 <p>If your code uses variable length arrays in a manner that Clang doesn't support, there are several ways to fix your code:
 428
 429 <ol>
 430 <li>replace the variable length array with a fixed-size array if you can
 431     determine a reasonable upper bound at compile time; sometimes this is as
 432     simple as changing <tt>int size = ...;</tt> to <tt>const int size
 433     = ...;</tt> (if the initializer is a compile-time constant);</li>
 434 <li>use <tt>std::vector</tt> or some other suitable container type;
 435     or</li>
 436 <li>allocate the array on the heap instead using <tt>new Type[]</tt> -
 437     just remember to <tt>delete[]</tt> it.</li>
 438 </ol>
 439
 440 <!-- ======================================================================= -->
 441 <h3 id="dep_lookup">Unqualified lookup in templates</h3>
 442 <!-- ======================================================================= -->
 443
 444 <p>Some versions of GCC accept the following invalid code:
 445
 446 <pre>
 447 template &lt;typename T&gt; T Squared(T x) {
 448   return Multiply(x, x);
 449 }
 450
 451 int Multiply(int x, int y) {
 452   return x * y;
 453 }
 454
 455 int main() {
 456   Squared(5);
 457 }
 458 </pre>
 459
 460 <p>Clang complains:
 461
 462 <pre>  <b>my_file.cpp:2:10: <span class="error">error:</span> use of undeclared identifier 'Multiply'</b>
 463     return Multiply(x, x);
 464   <span class="caret">         ^</span>
 465
 466   <b>my_file.cpp:10:3: <span class="note">note:</span> in instantiation of function template specialization 'Squared&lt;int&gt;' requested here</b>
 467     Squared(5);
 468   <span class="caret">  ^</span>
 469 </pre>
 470
 471 <p>The C++ standard says that unqualified names like <q>Multiply</q>
 472 are looked up in two ways.
 473
 474 <p>First, the compiler does <i>unqualified lookup</i> in the scope
 475 where the name was written.  For a template, this means the lookup is
 476 done at the point where the template is defined, not where it's
 477 instantiated.  Since <tt>Multiply</tt> hasn't been declared yet at
 478 this point, unqualified lookup won't find it.
 479
 480 <p>Second, if the name is called like a function, then the compiler
 481 also does <i>argument-dependent lookup</i> (ADL).  (Sometimes
 482 unqualified lookup can suppress ADL; see [basic.lookup.argdep]p3 for
 483 more information.)  In ADL, the compiler looks at the types of all the
 484 arguments to the call.  When it finds a class type, it looks up the
 485 name in that class's namespace; the result is all the declarations it
 486 finds in those namespaces, plus the declarations from unqualified
 487 lookup.  However, the compiler doesn't do ADL until it knows all the
 488 argument types.
 489
 490 <p>In our example, <tt>Multiply</tt> is called with dependent
 491 arguments, so ADL isn't done until the template is instantiated.  At
 492 that point, the arguments both have type <tt>int</tt>, which doesn't
 493 contain any class types, and so ADL doesn't look in any namespaces.
 494 Since neither form of lookup found the declaration
 495 of <tt>Multiply</tt>, the code doesn't compile.
 496
 497 <p>Here's another example, this time using overloaded operators,
 498 which obey very similar rules.
 499
 500 <pre>#include &lt;iostream&gt;
 501
 502 template&lt;typename T&gt;
 503 void Dump(const T&amp; value) {
 504   std::cout &lt;&lt; value &lt;&lt; "\n";
 505 }
 506
 507 namespace ns {
 508   struct Data {};
 509 }
 510
 511 std::ostream&amp; operator&lt;&lt;(std::ostream&amp; out, ns::Data data) {
 512   return out &lt;&lt; "Some data";
 513 }
 514
 515 void Use() {
 516   Dump(ns::Data());
 517 }</pre>
 518
 519 <p>Again, Clang complains about not finding a matching function:</p>
 520
 521 <pre>
 522 <b>my_file.cpp:5:13: <span class="error">error:</span> invalid operands to binary expression ('ostream' (aka 'basic_ostream&lt;char&gt;') and 'ns::Data const')</b>
 523   std::cout &lt;&lt; value &lt;&lt; "\n";
 524   <span class="caret">~~~~~~~~~ ^  ~~~~~</span>
 525 <b>my_file.cpp:17:3: <span class="note">note:</span> in instantiation of function template specialization 'Dump&lt;ns::Data&gt;' requested here</b>
 526   Dump(ns::Data());
 527   <span class="caret">^</span>
 528 </pre>
 529
 530 <p>Just like before, unqualified lookup didn't find any declarations
 531 with the name <tt>operator&lt;&lt;</tt>.  Unlike before, the argument
 532 types both contain class types: one of them is an instance of the
 533 class template type <tt>std::basic_ostream</tt>, and the other is the
 534 type <tt>ns::Data</tt> that we declared above.  Therefore, ADL will
 535 look in the namespaces <tt>std</tt> and <tt>ns</tt> for
 536 an <tt>operator&lt;&lt;</tt>.  Since one of the argument types was
 537 still dependent during the template definition, ADL isn't done until
 538 the template is instantiated during <tt>Use</tt>, which means that
 539 the <tt>operator&lt;&lt;</tt> we want it to find has already been
 540 declared.  Unfortunately, it was declared in the global namespace, not
 541 in either of the namespaces that ADL will look in!
 542
 543 <p>There are two ways to fix this problem:</p>
 544 <ol><li>Make sure the function you want to call is declared before the
 545 template that might call it.  This is the only option if none of its
 546 argument types contain classes.  You can do this either by moving the
 547 template definition, or by moving the function definition, or by
 548 adding a forward declaration of the function before the template.</li>
 549 <li>Move the function into the same namespace as one of its arguments
 550 so that ADL applies.</li></ol>
 551
 552 <p>For more information about argument-dependent lookup, see
 553 [basic.lookup.argdep].  For more information about the ordering of
 554 lookup in templates, see [temp.dep.candidate].
 555
 556 <!-- ======================================================================= -->
 557 <h3 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h3>
 558 <!-- ======================================================================= -->
 559
 560 Some versions of GCC accept the following invalid code:
 561
 562 <pre>
 563 template &lt;typename T&gt; struct Base {
 564   void DoThis(T x) {}
 565   static void DoThat(T x) {}
 566 };
 567
 568 template &lt;typename T&gt; struct Derived : public Base&lt;T&gt; {
 569   void Work(T x) {
 570     DoThis(x);  // Invalid!
 571     DoThat(x);  // Invalid!
 572   }
 573 };
 574 </pre>
 575
 576 Clang correctly rejects it with the following errors
 577 (when <tt>Derived</tt> is eventually instantiated):
 578
 579 <pre>
 580 my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
 581     DoThis(x);
 582     ^
 583     this-&gt;
 584 my_file.cpp:2:8: note: must qualify identifier to find this declaration in dependent base class
 585   void DoThis(T x) {}
 586        ^
 587 my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
 588     DoThat(x);
 589     ^
 590     this-&gt;
 591 my_file.cpp:3:15: note: must qualify identifier to find this declaration in dependent base class
 592   static void DoThat(T x) {}
 593 </pre>
 594
 595 Like we said <a href="#dep_lookup">above</a>, unqualified names like
 596 <tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
 597 <tt>Derived</tt> is defined, not when it's instantiated.  When we look
 598 up a name used in a class, we usually look into the base classes.
 599 However, we can't look into the base class <tt>Base&lt;T&gt;</tt>
 600 because its type depends on the template argument <tt>T</tt>, so the
 601 standard says we should just ignore it.  See [temp.dep]p3 for details.
 602
 603 <p>The fix, as Clang tells you, is to tell the compiler that we want a
 604 class member by prefixing the calls with <tt>this-&gt;</tt>:
 605
 606 <pre>
 607   void Work(T x) {
 608     <b>this-&gt;</b>DoThis(x);
 609     <b>this-&gt;</b>DoThat(x);
 610   }
 611 </pre>
 612
 613 Alternatively, you can tell the compiler exactly where to look:
 614
 615 <pre>
 616   void Work(T x) {
 617     <b>Base&lt;T&gt;</b>::DoThis(x);
 618     <b>Base&lt;T&gt;</b>::DoThat(x);
 619   }
 620 </pre>
 621
 622 This works whether the methods are static or not, but be careful:
 623 if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
 624 dispatch!
 625
 626 <!-- ======================================================================= -->
 627 <h3 id="undep_incomplete">Incomplete types in templates</h3>
 628 <!-- ======================================================================= -->
 629
 630 The following code is invalid, but compilers are allowed to accept it:
 631
 632 <pre>
 633   class IOOptions;
 634   template &lt;class T&gt; bool read(T &amp;value) {
 635     IOOptions opts;
 636     return read(opts, value);
 637   }
 638
 639   class IOOptions { bool ForceReads; };
 640   bool read(const IOOptions &amp;opts, int &amp;x);
 641   template bool read&lt;&gt;(int &amp;);
 642 </pre>
 643
 644 The standard says that types which don't depend on template parameters
 645 must be complete when a template is defined if they affect the
 646 program's behavior.  However, the standard also says that compilers
 647 are free to not enforce this rule.  Most compilers enforce it to some
 648 extent; for example, it would be an error in GCC to
 649 write <tt>opts.ForceReads</tt> in the code above.  In Clang, we feel
 650 that enforcing the rule consistently lets us provide a better
 651 experience, but unfortunately it also means we reject some code that
 652 other compilers accept.
 653
 654 <p>We've explained the rule here in very imprecise terms; see
 655 [temp.res]p8 for details.
 656
 657 <!-- ======================================================================= -->
 658 <h3 id="bad_templates">Templates with no valid instantiations</h3>
 659 <!-- ======================================================================= -->
 660
 661 The following code contains a typo: the programmer
 662 meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
 663
 664 <pre>
 665   template &lt;class T&gt; class Processor {
 666     ...
 667     void init();
 668     ...
 669   };
 670   ...
 671   template &lt;class T&gt; void process() {
 672     Processor&lt;T&gt; processor;
 673     processor.innit();       // <-- should be 'init()'
 674     ...
 675   }
 676 </pre>
 677
 678 Unfortunately, we can't flag this mistake as soon as we see it: inside
 679 a template, we're not allowed to make assumptions about "dependent
 680 types" like <tt>Processor&lt;T&gt;</tt>.  Suppose that later on in
 681 this file the programmer adds an explicit specialization
 682 of <tt>Processor</tt>, like so:
 683
 684 <pre>
 685   template &lt;&gt; class Processor&lt;char*&gt; {
 686     void innit();
 687   };
 688 </pre>
 689
 690 Now the program will work &mdash; as long as the programmer only ever
 691 instantiates <tt>process()</tt> with <tt>T = char*</tt>!  This is why
 692 it's hard, and sometimes impossible, to diagnose mistakes in a
 693 template definition before it's instantiated.
 694
 695 <p>The standard says that a template with no valid instantiations is
 696 ill-formed.  Clang tries to do as much checking as possible at
 697 definition-time instead of instantiation-time: not only does this
 698 produce clearer diagnostics, but it also substantially improves
 699 compile times when using pre-compiled headers.  The downside to this
 700 philosophy is that Clang sometimes fails to process files because they
 701 contain broken templates that are no longer used.  The solution is
 702 simple: since the code is unused, just remove it.
 703
 704 <!-- ======================================================================= -->
 705 <h3 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h3>
 706 <!-- ======================================================================= -->
 707
 708 If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
 709 constructor, C++ doesn't allow you to default construct a <tt>const</tt>
 710 instance of it like this ([dcl.init], p9):
 711
 712 <pre>
 713 class Foo {
 714  public:
 715   // The compiler-supplied default constructor works fine, so we
 716   // don't bother with defining one.
 717   ...
 718 };
 719
 720 void Bar() {
 721   const Foo foo;  // Error!
 722   ...
 723 }
 724 </pre>
 725
 726 To fix this, you can define a default constructor for the class:
 727
 728 <pre>
 729 class Foo {
 730  public:
 731   Foo() {}
 732   ...
 733 };
 734
 735 void Bar() {
 736   const Foo foo;  // Now the compiler is happy.
 737   ...
 738 }
 739 </pre>
 740
 741 <!-- ======================================================================= -->
 742 <h3 id="param_name_lookup">Parameter name lookup</h3>
 743 <!-- ======================================================================= -->
 744
 745 <p>Due to a bug in its implementation, GCC allows the redeclaration of function parameter names within a function prototype in C++ code, e.g.</p>
 746 <blockquote>
 747 <pre>
 748 void f(int a, int a);
 749 </pre>
 750 </blockquote>
 751 <p>Clang diagnoses this error (where the parameter name has been redeclared). To fix this problem, rename one of the parameters.</p>
 752
 753 <!-- ======================================================================= -->
 754 <h2 id="objective-c++">Objective-C++ compatibility</h3>
 755 <!-- ======================================================================= -->
 756
 757 <!-- ======================================================================= -->
 758 <h3 id="implicit-downcasts">Implicit downcasts</h3>
 759 <!-- ======================================================================= -->
 760
 761 <p>Due to a bug in its implementation, GCC allows implicit downcasts
 762 of Objective-C pointers (from a base class to a derived class) when
 763 calling functions. Such code is inherently unsafe, since the object
 764 might not actually be an instance of the derived class, and is
 765 rejected by Clang. For example, given this code:</p>
 766
 767 <pre>
 768 @interface Base @end
 769 @interface Derived : Base @end
 770
 771 void f(Derived *p);
 772 void g(Base *p) {
 773   f(p);
 774 }
 775 </pre>
 776
 777 <p>Clang produces the following error:</p>
 778
 779 <pre>
 780 downcast.mm:6:3: error: no matching function for call to 'f'
 781   f(p);
 782   ^
 783 downcast.mm:4:6: note: candidate function not viable: cannot convert from
 784       superclass 'Base *' to subclass 'Derived *' for 1st argument
 785 void f(Derived *p);
 786      ^
 787 </pre>
 788
 789 <p>If the downcast is actually correct (e.g., because the code has
 790 already checked that the object has the appropriate type), add an
 791 explicit cast:</p>
 792
 793 <pre>
 794   f((Derived *)base);
 795 </pre>
 796
 797 <!-- ======================================================================= -->
 798 <h3 id="class-as-property-name">Using <code>class</code> as a property name</h3>
 799 <!-- ======================================================================= -->
 800
 801 <p>In C and Objective-C, <code>class</code> is a normal identifier and
 802 can be used to name fields, ivars, methods, and so on.  In
 803 C++, <code>class</code> is a keyword.  For compatibility with existing
 804 code, Clang permits <code>class</code> to be used as part of a method
 805 selector in Objective-C++, but this does not extend to any other part
 806 of the language.  In particular, it is impossible to use property dot
 807 syntax in Objective-C++ with the property name <code>class</code>, so
 808 the following code will fail to parse:</p>
 809
 810 <pre>
 811 @interface I {
 812 int cls;
 813 }
 814 + (int)class;
 815 @end
 816
 817 @implementation  I
 818 - (int) Meth { return I.class; }
 819 @end
 820 <pre>
 821
 822 <p>Use explicit message-send syntax instead, i.e. <code>[I class]</code>.</p>
 823
 824 </div>
 825 </body>
 826 </html>