Blame - www/compatibility.html - platform/external/clang

blob: ca1553150b091bad59de87299a5b827267cf16fb [file] [log] [blame]

Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +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>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>
Chris Lattner	a02d183	2010-09-16 18:17:55 +0000	[diff] [blame]	35	<li><a href="#vector_builtins">"missing" vector __builtin functions</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	36	<li><a href="#lvalue-cast">Lvalue casts</a></li>
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	37	<li><a href="#blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</a></li>
Daniel Dunbar	15952c9	2010-11-09 22:45:16 +0000	[diff] [blame]	38	<li><a href="#block-variable-initialization">Non-initialization of <tt>__block</tt> variables</a></li>
Chris Lattner	9b743f4	2010-11-10 23:51:50 +0000	[diff] [blame]	39	<li><a href="#inline-asm">Inline assembly</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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>
Argyrios Kyrtzidis	3b5b92a	2010-09-13 17:48:07 +0000	[diff] [blame]	46	<li><a href="#objc_objs-cast">Internal Objective-C types</a></li>
Fariborz Jahanian	ddfa6c3	2010-10-22 22:35:51 +0000	[diff] [blame]	47	<li><a href="#c_variables-class">C variables in @class or @protocol</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	48	</ul>
				49	</li>
				50	<li><a href="#c++">C++ compatibility</a>
				51	<ul>
				52	<li><a href="#vla">Variable-length arrays</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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>
Douglas Gregor	a66d3bb	2010-11-10 20:24:21 +0000	[diff] [blame]	60	<li><a href="#param_name_lookup">Parameter name lookup</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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>
Fariborz Jahanian	36e738a	2010-08-11 18:57:26 +0000	[diff] [blame]	67	<ul>
				68	<li><a href="#Use of class as method name">Use of class as method name</a></li>
				69	</ul>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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,
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	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>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	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>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	100
				101	<pre>
				102	Undefined symbols:
				103	"_add", referenced from:
				104	_main in cc-y1jXIr.o
				105	</pre>
				106
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	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
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	112	<p>There are several ways to fix this problem:</p>
				113
				114	<ul>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	115	<li>Change <code>add</code> to a <code>static inline</code>
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	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
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	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>
Chris Lattner	a02d183	2010-09-16 18:17:55 +0000	[diff] [blame]	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><*mmintrin.h></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 <arm_neon.h>
				164	and <altivec.h> headers.</p>
				165
Eric Christopher	a473c95	2010-10-25 21:17:59 +0000	[diff] [blame]	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>
Chris Lattner	a02d183	2010-09-16 18:17:55 +0000	[diff] [blame]	176
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	177	<!-- ======================================================================= -->
				178	<h3 id="lvalue-cast">Lvalue casts</h3>
				179	<!-- ======================================================================= -->
				180
Douglas Gregor	6f1adba	2010-06-30 22:38:37 +0000	[diff] [blame]	181	<p>Old versions of GCC permit casting the left-hand side of an assignment to a
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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	<!-- ======================================================================= -->
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	199	<h3 id="blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</h3>
				200	<!-- ======================================================================= -->
				201
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	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>
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	207
				208	<pre>
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	209	int fetch_object_state(struct MyObject *c) {
				210	if (!c->active) goto error;
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	211
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	212	__block int result;
				213	run_specially_somehow(^{ result = c->state; });
				214	return result;
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	215
				216	error:
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	217	fprintf(stderr, "error while fetching object state");
				218	return -1;
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	219	}
				220	</pre>
				221
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	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>
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	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
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	233	__block int result;
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	234	^
				235	</pre>
				236
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	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>
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	247
				248	<!-- ======================================================================= -->
Daniel Dunbar	15952c9	2010-11-09 22:45:16 +0000	[diff] [blame]	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
Chris Lattner	9b743f4	2010-11-10 23:51:50 +0000	[diff] [blame]	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	<inline asm>: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
Daniel Dunbar	15952c9	2010-11-09 22:45:16 +0000	[diff] [blame]	314	<!-- ======================================================================= -->
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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
Benjamin Kramer	e661750	2010-06-30 22:29:56 +0000	[diff] [blame]	358	<code>class_getInstanceSize()</code>:</p>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	359
				360	<pre>
				361	class_getInstanceSize([NSArray class])
				362	</pre>
				363
				364	<!-- ======================================================================= -->
Argyrios Kyrtzidis	3b5b92a	2010-09-13 17:48:07 +0000	[diff] [blame]	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	<!-- ======================================================================= -->
John McCall	3cdbe44	2011-02-03 11:05:04 +0000	[diff] [blame^]	386	<h3 id="c_variables-class">C variables in @interface or @protocol</h3>
Fariborz Jahanian	ddfa6c3	2010-10-22 22:35:51 +0000	[diff] [blame]	387	<!-- ======================================================================= -->
				388
John McCall	3cdbe44	2011-02-03 11:05:04 +0000	[diff] [blame^]	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>
Fariborz Jahanian	ddfa6c3	2010-10-22 22:35:51 +0000	[diff] [blame]	395
				396	<pre>
				397	@interface XX
John McCall	3cdbe44	2011-02-03 11:05:04 +0000	[diff] [blame^]	398	int a; // not allowed in clang
				399	int b = 1; // not allowed in clang
				400	extern int c; // allowed
Fariborz Jahanian	ddfa6c3	2010-10-22 22:35:51 +0000	[diff] [blame]	401	@end
				402
				403	</pre>
				404
				405	<!-- ======================================================================= -->
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	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, base classes, or any
				422	members if 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
				432	reasonable upper bound at compile time; sometimes this is as
				433	simple as changing <tt>int size = ...;</tt> to <tt>const int size
				434	= ...;</tt> (if the definition of <tt>size</tt> is a compile-time
				435	integral constant);</li>
John McCall	3cdbe44	2011-02-03 11:05:04 +0000	[diff] [blame^]	436	<li>use <tt>std::string</tt> instead of a <tt>char []</tt>;</li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	437	<li>use <tt>std::vector</tt> or some other suitable container type;
				438	or</li>
				439	<li>allocate the array on the heap instead using <tt>new Type[]</tt> -
				440	just remember to <tt>delete[]</tt> it.</li>
				441	</ol>
				442
				443	<!-- ======================================================================= -->
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	444	<h3 id="dep_lookup">Unqualified lookup in templates</h3>
				445	<!-- ======================================================================= -->
				446
				447	<p>Some versions of GCC accept the following invalid code:
				448
				449	<pre>
				450	template <typename T> T Squared(T x) {
				451	return Multiply(x, x);
				452	}
				453
				454	int Multiply(int x, int y) {
				455	return x * y;
				456	}
				457
				458	int main() {
				459	Squared(5);
				460	}
				461	</pre>
				462
				463	<p>Clang complains:
				464
				465	<pre> <b>my_file.cpp:2:10: <span class="error">error:</span> use of undeclared identifier 'Multiply'</b>
				466	return Multiply(x, x);
				467	<span class="caret"> ^</span>
				468
				469	<b>my_file.cpp:10:3: <span class="note">note:</span> in instantiation of function template specialization 'Squared<int>' requested here</b>
				470	Squared(5);
				471	<span class="caret"> ^</span>
				472	</pre>
				473
				474	<p>The C++ standard says that unqualified names like <q>Multiply</q>
				475	are looked up in two ways.
				476
				477	<p>First, the compiler does <i>unqualified lookup</i> in the scope
				478	where the name was written. For a template, this means the lookup is
				479	done at the point where the template is defined, not where it's
				480	instantiated. Since <tt>Multiply</tt> hasn't been declared yet at
				481	this point, unqualified lookup won't find it.
				482
				483	<p>Second, if the name is called like a function, then the compiler
				484	also does <i>argument-dependent lookup</i> (ADL). (Sometimes
				485	unqualified lookup can suppress ADL; see [basic.lookup.argdep]p3 for
				486	more information.) In ADL, the compiler looks at the types of all the
				487	arguments to the call. When it finds a class type, it looks up the
				488	name in that class's namespace; the result is all the declarations it
				489	finds in those namespaces, plus the declarations from unqualified
				490	lookup. However, the compiler doesn't do ADL until it knows all the
				491	argument types.
				492
				493	<p>In our example, <tt>Multiply</tt> is called with dependent
				494	arguments, so ADL isn't done until the template is instantiated. At
				495	that point, the arguments both have type <tt>int</tt>, which doesn't
				496	contain any class types, and so ADL doesn't look in any namespaces.
				497	Since neither form of lookup found the declaration
				498	of <tt>Multiply</tt>, the code doesn't compile.
				499
				500	<p>Here's another example, this time using overloaded operators,
				501	which obey very similar rules.
				502
				503	<pre>#include <iostream>
				504
				505	template<typename T>
				506	void Dump(const T& value) {
				507	std::cout << value << "\n";
				508	}
				509
				510	namespace ns {
				511	struct Data {};
				512	}
				513
				514	std::ostream& operator<<(std::ostream& out, ns::Data data) {
				515	return out << "Some data";
				516	}
				517
				518	void Use() {
				519	Dump(ns::Data());
				520	}</pre>
				521
				522	<p>Again, Clang complains about not finding a matching function:</p>
				523
				524	<pre>
				525	<b>my_file.cpp:5:13: <span class="error">error:</span> invalid operands to binary expression ('ostream' (aka 'basic_ostream<char>') and 'ns::Data const')</b>
				526	std::cout << value << "\n";
				527	<span class="caret">~~~~~~~~~ ^ ~~~~~</span>
				528	<b>my_file.cpp:17:3: <span class="note">note:</span> in instantiation of function template specialization 'Dump<ns::Data>' requested here</b>
				529	Dump(ns::Data());
				530	<span class="caret">^</span>
				531	</pre>
				532
				533	<p>Just like before, unqualified lookup didn't find any declarations
				534	with the name <tt>operator<<</tt>. Unlike before, the argument
				535	types both contain class types: one of them is an instance of the
				536	class template type <tt>std::basic_ostream</tt>, and the other is the
				537	type <tt>ns::Data</tt> that we declared above. Therefore, ADL will
				538	look in the namespaces <tt>std</tt> and <tt>ns</tt> for
				539	an <tt>operator<<</tt>. Since one of the argument types was
				540	still dependent during the template definition, ADL isn't done until
				541	the template is instantiated during <tt>Use</tt>, which means that
				542	the <tt>operator<<</tt> we want it to find has already been
				543	declared. Unfortunately, it was declared in the global namespace, not
				544	in either of the namespaces that ADL will look in!
				545
				546	<p>There are two ways to fix this problem:</p>
				547	<ol><li>Make sure the function you want to call is declared before the
				548	template that might call it. This is the only option if none of its
				549	argument types contain classes. You can do this either by moving the
				550	template definition, or by moving the function definition, or by
				551	adding a forward declaration of the function before the template.</li>
				552	<li>Move the function into the same namespace as one of its arguments
				553	so that ADL applies.</li></ol>
				554
				555	<p>For more information about argument-dependent lookup, see
				556	[basic.lookup.argdep]. For more information about the ordering of
				557	lookup in templates, see [temp.dep.candidate].
				558
				559	<!-- ======================================================================= -->
				560	<h3 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h3>
				561	<!-- ======================================================================= -->
				562
				563	Some versions of GCC accept the following invalid code:
				564
				565	<pre>
				566	template <typename T> struct Base {
				567	void DoThis(T x) {}
				568	static void DoThat(T x) {}
				569	};
				570
				571	template <typename T> struct Derived : public Base<T> {
				572	void Work(T x) {
				573	DoThis(x); // Invalid!
				574	DoThat(x); // Invalid!
				575	}
				576	};
				577	</pre>
				578
				579	Clang correctly rejects it with the following errors
				580	(when <tt>Derived</tt> is eventually instantiated):
				581
				582	<pre>
				583	my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
				584	DoThis(x);
				585	^
				586	this->
				587	my_file.cpp:2:8: note: must qualify identifier to find this declaration in dependent base class
				588	void DoThis(T x) {}
				589	^
				590	my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
				591	DoThat(x);
				592	^
				593	this->
				594	my_file.cpp:3:15: note: must qualify identifier to find this declaration in dependent base class
				595	static void DoThat(T x) {}
				596	</pre>
				597
				598	Like we said <a href="#dep_lookup">above</a>, unqualified names like
				599	<tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
				600	<tt>Derived</tt> is defined, not when it's instantiated. When we look
				601	up a name used in a class, we usually look into the base classes.
				602	However, we can't look into the base class <tt>Base<T></tt>
				603	because its type depends on the template argument <tt>T</tt>, so the
				604	standard says we should just ignore it. See [temp.dep]p3 for details.
				605
				606	<p>The fix, as Clang tells you, is to tell the compiler that we want a
				607	class member by prefixing the calls with <tt>this-></tt>:
				608
				609	<pre>
				610	void Work(T x) {
				611	<b>this-></b>DoThis(x);
				612	<b>this-></b>DoThat(x);
				613	}
				614	</pre>
				615
				616	Alternatively, you can tell the compiler exactly where to look:
				617
				618	<pre>
				619	void Work(T x) {
				620	<b>Base<T></b>::DoThis(x);
				621	<b>Base<T></b>::DoThat(x);
				622	}
				623	</pre>
				624
				625	This works whether the methods are static or not, but be careful:
				626	if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
				627	dispatch!
				628
				629	<!-- ======================================================================= -->
				630	<h3 id="undep_incomplete">Incomplete types in templates</h3>
				631	<!-- ======================================================================= -->
				632
				633	The following code is invalid, but compilers are allowed to accept it:
				634
				635	<pre>
				636	class IOOptions;
				637	template <class T> bool read(T &value) {
				638	IOOptions opts;
				639	return read(opts, value);
				640	}
				641
				642	class IOOptions { bool ForceReads; };
				643	bool read(const IOOptions &opts, int &x);
				644	template bool read<>(int &);
				645	</pre>
				646
				647	The standard says that types which don't depend on template parameters
				648	must be complete when a template is defined if they affect the
				649	program's behavior. However, the standard also says that compilers
				650	are free to not enforce this rule. Most compilers enforce it to some
				651	extent; for example, it would be an error in GCC to
				652	write <tt>opts.ForceReads</tt> in the code above. In Clang, we feel
				653	that enforcing the rule consistently lets us provide a better
				654	experience, but unfortunately it also means we reject some code that
				655	other compilers accept.
				656
				657	<p>We've explained the rule here in very imprecise terms; see
				658	[temp.res]p8 for details.
				659
				660	<!-- ======================================================================= -->
				661	<h3 id="bad_templates">Templates with no valid instantiations</h3>
				662	<!-- ======================================================================= -->
				663
				664	The following code contains a typo: the programmer
				665	meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
				666
				667	<pre>
				668	template <class T> class Processor {
				669	...
				670	void init();
				671	...
				672	};
				673	...
				674	template <class T> void process() {
				675	Processor<T> processor;
				676	processor.innit(); // <-- should be 'init()'
				677	...
				678	}
				679	</pre>
				680
				681	Unfortunately, we can't flag this mistake as soon as we see it: inside
				682	a template, we're not allowed to make assumptions about "dependent
				683	types" like <tt>Processor<T></tt>. Suppose that later on in
				684	this file the programmer adds an explicit specialization
				685	of <tt>Processor</tt>, like so:
				686
				687	<pre>
				688	template <> class Processor<char*> {
				689	void innit();
				690	};
				691	</pre>
				692
				693	Now the program will work — as long as the programmer only ever
				694	instantiates <tt>process()</tt> with <tt>T = char*</tt>! This is why
				695	it's hard, and sometimes impossible, to diagnose mistakes in a
				696	template definition before it's instantiated.
				697
				698	<p>The standard says that a template with no valid instantiations is
				699	ill-formed. Clang tries to do as much checking as possible at
				700	definition-time instead of instantiation-time: not only does this
				701	produce clearer diagnostics, but it also substantially improves
				702	compile times when using pre-compiled headers. The downside to this
				703	philosophy is that Clang sometimes fails to process files because they
				704	contain broken templates that are no longer used. The solution is
				705	simple: since the code is unused, just remove it.
				706
				707	<!-- ======================================================================= -->
				708	<h3 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h3>
				709	<!-- ======================================================================= -->
				710
				711	If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
				712	constructor, C++ doesn't allow you to default construct a <tt>const</tt>
				713	instance of it like this ([dcl.init], p9):
				714
				715	<pre>
				716	class Foo {
				717	public:
				718	// The compiler-supplied default constructor works fine, so we
				719	// don't bother with defining one.
				720	...
				721	};
				722
				723	void Bar() {
				724	const Foo foo; // Error!
				725	...
				726	}
				727	</pre>
				728
				729	To fix this, you can define a default constructor for the class:
				730
				731	<pre>
				732	class Foo {
				733	public:
				734	Foo() {}
				735	...
				736	};
				737
				738	void Bar() {
				739	const Foo foo; // Now the compiler is happy.
				740	...
				741	}
				742	</pre>
				743
				744	<!-- ======================================================================= -->
Douglas Gregor	a66d3bb	2010-11-10 20:24:21 +0000	[diff] [blame]	745	<h3 id="param_name_lookup">Parameter name lookup</h3>
				746	<!-- ======================================================================= -->
				747
				748	<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>
				749	<blockquote>
				750	<pre>
				751	void f(int a, int a);
				752	</pre>
				753	</blockquote>
				754	<p>Clang diagnoses this error (where the parameter name has been redeclared). To fix this problem, rename one of the parameters.</p>
				755
				756	<!-- ======================================================================= -->
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	757	<h2 id="objective-c++">Objective-C++ compatibility</h3>
				758	<!-- ======================================================================= -->
				759
				760	<!-- ======================================================================= -->
				761	<h3 id="implicit-downcasts">Implicit downcasts</h3>
				762	<!-- ======================================================================= -->
				763
				764	<p>Due to a bug in its implementation, GCC allows implicit downcasts
				765	(from base class to a derived class) when calling functions. Such code is
				766	inherently unsafe, since the object might not actually be an instance
				767	of the derived class, and is rejected by Clang. For example, given
				768	this code:</p>
				769
				770	<pre>
				771	@interface Base @end
				772	@interface Derived : Base @end
				773
				774	void f(Derived *);
				775	void g(Base *base) {
				776	f(base);
				777	}
				778	</pre>
				779
				780	<p>Clang produces the following error:</p>
				781
				782	<pre>
				783	downcast.mm:6:3: error: no matching function for call to 'f'
				784	f(base);
				785	^
Douglas Gregor	92bc027	2010-07-01 03:50:01 +0000	[diff] [blame]	786	downcast.mm:4:6: note: candidate function not viable: cannot convert from
				787	superclass 'Base ' to subclass 'Derived ' for 1st argument
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	788	void f(Derived *);
				789	^
				790	</pre>
				791
				792	<p>If the downcast is actually correct (e.g., because the code has
				793	already checked that the object has the appropriate type), add an
				794	explicit cast:</p>
				795
				796	<pre>
				797	f((Derived *)base);
				798	</pre>
				799
Fariborz Jahanian	36e738a	2010-08-11 18:57:26 +0000	[diff] [blame]	800	<!-- ======================================================================= -->
				801	<h3 id="Use of class as method name">Use of class as method name</h3>
				802	<!-- ======================================================================= -->
				803
				804	<p>Use of 'class' name to declare a method is allowed in objective-c++ mode to
				805	be compatible with GCC. However, use of property dot syntax notation to call
				806	this method is not allowed in clang++, as [I class] is a suitable syntax that
				807	will work. So, this test will fail in clang++.
				808
				809	<pre>
				810	@interface I {
				811	int cls;
				812	}
				813	+ (int)class;
				814	@end
				815
				816	@implementation I
				817	- (int) Meth { return I.class; }
				818	@end
				819	<pre>
				820
				821
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	822	</div>
				823	</body>
				824	</html>