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

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