Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / 65a795bb30ee35ddfbf3b9f400c170b32baaf37b / . / docs / UsersManual.html
blob: 5e6f5565c9ea303f140a6bc7101448004aad6986 [file] [log] [blame]
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]1<html>
2<head>
3<title>Clang Compiler User's Manual</title>
4<link type="text/css" rel="stylesheet" href="../menu.css" />
5<link type="text/css" rel="stylesheet" href="../content.css" />
6<style type="text/css">
7td {
8 vertical-align: top;
9}
10</style>
11</head>
12<body>
13
14<!--#include virtual="../menu.html.incl"-->
15
16<div id="content">
17
18<h1>Clang Compiler User's Manual</h1>
19
20<ul>
21<li><a href="#intro">Introduction</a>
22 <ul>
23 <li><a href="#terminology">Terminology</a></li>
24 <li><a href="#basicusage">Basic Usage</a></li>
25 </ul>
26</li>
Chris Lattner65a795b2009-04-20 06:00:23 +0000[diff] [blame^]27<li><a href="#commandline">Command Line Options</a>
28 <ul>
29 <li><a href="#cl_diagnostics">Options to Control Error and Warning
30 Messages</a></li>
31 </ul>
32</li>
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]33<li><a href="#general_features">Language and Target-Independent Features</a>
34 <ul>
35 <li><a href="#diagnostics">Controlling Errors and Warnings</a></li>
36 <li><a href="#precompiledheaders">Precompiled Headers</a></li>
37 </ul>
38</li>
39<li><a href="#c">C Language Features</a>
40 <ul>
41<!-- <li><a href="#pragmas">Pragmas Supported</a></li> -->
42 <li><a href="#c_extensions">C Extensions Supported</a></li>
43 <li><a href="#c_incompatibilities">Intentional Incompatibilities with
44 GCC</a></li>
45 </ul>
46</li>
47<li><a href="#objc">Objective-C Language Features</a>
48 <ul>
49 <li><a href="#objc_incompatibilities">Intentional Incompatibilities with
50 GCC</a></li>
51 </ul>
52</li>
53<li><a href="#cxx">C++ Language Features</a>
54 <ul>
55 <li>...</li>
56 </ul>
57</li>
58<li><a href="#objcxx">Objective C++ Language Features</a>
59 <ul>
60 <li>...</li>
61 </ul>
62</li>
63<li><a href="#target_features">Target-Specific Features and Limitations</a>
64 <ul>
65 <li><a href="#target_arch">CPU Architectures Features and Limitations</a>
66 <ul>
67 <li><a href="#target_arch_x86">X86</a></li>
68 <li>PPC</li>
69 <li>ARM</li>
70 </ul>
71 </li>
72 <li><a href="#target_os">Operating System Features and Limitations</a>
73 <ul>
74 <li><a href="#target_os_darwin">Darwin (Mac OS/X)</a></li>
75 <li>Linux, etc.</li>
76 </ul>
77
78 </li>
79 </ul>
80</li>
81</ul>
82
83
84<!-- ======================================================================= -->
85<h2 id="intro">Introduction</h2>
86<!-- ======================================================================= -->
87
88<p>The Clang Compiler is an open-source compiler for the C family of programming
89languages, aiming to be the best in class implementation of these languages.
90Clang builds on the LLVM optimizer and code generator, allowing it to provide
91high-quality optimization and code generation support for many targets. For
92more general information, please see the <a href="http://clang.llvm.org">Clang
93Web Site</a> or the <a href="http://llvm.org">LLVM Web Site</a>.</p>
94
95<p>This document describes important notes about using Clang as a compiler for
96an end-user, documenting the supported features, command line options, etc. If
97you are interested in using Clang to build a tool that processes code, please
98see <a href="InternalsManual.html">the Clang Internals Manual</a>. If you are
99interested in the <a href="http://clang.llvm.org/StaticAnalysis.html">Clang
100Static Analyzer</a>, please see its web page.</p>
101
102<p>Clang is designed to support the C family of programming languages, which
103includes <a href="#c">C</a>, <a href="#objc">Objective-C</a>, <a
104href="#cxx">C++</a>, and <a href="#objcxx">Objective-C++</a> as well as many
105dialects of those. For language-specific information, please see the
106corresponding language specific section:</p>
107
108<ul>
109<li><a href="#c">C Language</a>: K&amp;R C, ANSI C89, ISO C90, ISO C94
110 (C89+AMD1), ISO C99 (+TC1, TC2, TC3). </li>
111<li><a href="#objc">Objective-C Language</a>: ObjC 1, ObjC 2, ObjC 2.1, plus
112 variants depending on base language.</li>
113<li><a href="#cxx">C++ Language Features</a></li>
114<li><a href="#objcxx">Objective C++ Language</a></li>
115</ul>
116
117<p>In addition to these base languages and their dialects, Clang supports a
118broad variety of language extensions, which are documented in the corresponding
119language section. These extensions are provided to be compatible with the GCC,
120Microsoft, and other popular compilers as well as to improve functionality
121through Clang-specific features. The Clang driver and language features are
122intentionally designed to be as compatible with the GNU GCC compiler as
123reasonably possible, easing migration from GCC to Clang. In most cases, code
124"just works".</p>
125
126<p>In addition to language specific features, Clang has a variety of features
127that depend on what CPU architecture or operating system is being compiled for.
128Please see the <a href="target_features">Target-Specific Features and
129Limitations</a> section for more details.</p>
130
131<p>The rest of the introduction introduces some basic <a
132href="#terminology">compiler terminology</a> that is used throughout this manual
133and contains a basic <a href="#basicusage">introduction to using Clang</a>
134as a command line compiler.</p>
135
136<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
137<h3 id="terminology">Terminology</h3>
138<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
139
140<p>Front end, parser, backend, preprocessor, undefined behavior, diagnostic,
141 optimizer</p>
142
143<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
144<h3 id="basicusage">Basic Usage</h3>
145<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
146
147<p>Intro to how to use a C compiler for newbies.</p>
148<p>
149compile + link
150
151compile then link
152
153debug info
154
155enabling optimizations
156
157picking a language to use, defaults to C99 by default. Autosenses based on
158extension.
159
160using a makefile
161</p>
162
163
164<!-- ======================================================================= -->
165<h2 id="commandline">Command Line Options</h2>
166<!-- ======================================================================= -->
167
168<p>
169This section is generally an index into other sections. It does not go into
Chris Lattner65a795b2009-04-20 06:00:23 +0000[diff] [blame^]170depth on the ones that are covered by other sections. However, the first part
171introduces the language selection and other high level options like -c, -g, etc.
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]172</p>
173
Chris Lattner65a795b2009-04-20 06:00:23 +0000[diff] [blame^]174
175<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
176<h3 id="cl_diagnostics">Options to Control Error and Warning Messages</h3>
177<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
178
179<p><b>-Werror</b>: Turn warnings into errors.</p>
180<p><b>-Werror=foo</b>: Turn warning "foo" into an error.</p>
181<p><b>-Wno-error=foo</b>: Turn warning "foo" into an warning even if -Werror is
182 specified.</p>
183<p><b>-Wfoo</b>: Enable warning foo</p>
184<p><b>-Wno-foo</b>: Disable warning foo</p>
185<p><b>-w</b>: Disable all warnings.</p>
186<p><b>-pedantic</b>: Warn on language extensions.</p>
187<p><b>-pedantic-errors</b>: Error on language extensions.</p>
188<p><b>-Wsystem-headers</b>: Enable warnings from system headers.</p>
189
190<!-- ================================================= -->
191<h4 id="cl_diag_formatting">Formatting of Diagnostics</h4>
192<!-- ================================================= -->
193
194<p>Clang aims to produce beautiful diagnostics by default, particularly for new
195users that first come to Clang. However, different people have different
196preferences, and sometimes Clang is driven by another program, not a person. For
197these cases, Clang provides a wide range of options to control the exact output
198format of the diagnostics that it generates.</p>
199
200<dl>
201
202<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
203<dt id="opt_fshow-column"><b>-f[no-]show-column</b>: Print column number in
204diagnostic.</dt>
205<dd>This option, which defaults to on, controls whether or not Clang prints the
206column number of a diagnostic. For example, when this is enabled, Clang will
207print something like:</p>
208
209<pre>
210 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
211 #endif bad
212 ^
213 //
214</pre>
215
216<p>When this is disabled, Clang will print "test.c:28: warning..." with no
217column number.</p>
218</dd>
219
220<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
221<dt id="opt_fshow-source-location"><b>-f[no-]show-source-location</b>: Print
222source file/line/column information in diagnostic.</dt>
223<dd>This option, which defaults to on, controls whether or not Clang prints the
224filename, line number and column number of a diagnostic. For example,
225when this is enabled, Clang will print something like:</p>
226
227<pre>
228 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
229 #endif bad
230 ^
231 //
232</pre>
233
234<p>When this is disabled, Clang will not print the "test.c:28:8: " part.</p>
235</dd>
236
237<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
238<dt id="opt_fcaret-diagnostics"><b>-f[no-]caret-diagnostics</b>: Print source
239line and ranges from source code in diagnostic.</dt>
240<dd>This option, which defaults to on, controls whether or not Clang prints the
241source line, source ranges, and caret when emitting a diagnostic. For example,
242when this is enabled, Clang will print something like:</p>
243
244<pre>
245 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
246 #endif bad
247 ^
248 //
249</pre>
250
251<p>When this is disabled, Clang will just print:</p>
252
253<pre>
254 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
255</pre>
256
257</dd>
258
259<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
260<dt id="opt_fdiagnostics-show-option"><b>-f[no-]diagnostics-show-option</b>:
261Enable <tt>[-Woption]</tt> information in diagnostic line.</dt>
262<dd>This option, which defaults to on,
263controls whether or not Clang prints the associated <A
264href="#cl_diag_warning_groups">warning group</a> option name when outputting
265a warning diagnostic. For example, in this output:</p>
266
267<pre>
268 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
269 #endif bad
270 ^
271 //
272</pre>
273
274<p>Passing <b>-fno-diagnostics-show-option</b> will prevent Clang from printing
275the [<a href="#opt_Wextra-tokens">-Wextra-tokens</a>] information in the
276diagnostic. This information tells you the flag needed to enable or disable the
277diagnostic, either from the command line or through <a
278href="#pragma_GCC_diagnostic">#pragma GCC diagnostic</a>.</dd>
279
280
281<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
282<dt id="opt_fdiagnostics-fixit-info"><b>-f[no-]diagnostics-fixit-info</b>:
283Enable "FixIt" information in the diagnostics output.</dt>
284<dd>This option, which defaults to on, controls whether or not Clang prints the
285information on how to fix a specific diagnostic underneath it when it knows.
286For example, in this output:</p>
287
288<pre>
289 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
290 #endif bad
291 ^
292 //
293</pre>
294
295<p>Passing <b>-fno-diagnostics-fixit-info</b> will prevent Clang from printing
296the "//" line at the end of the message. This information is useful for users
297who may not understand what is wrong, but can be confusing for machine
298parsing.</p>
299</dd>
300
301<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
302<dt id="opt_fprint-source-range-info"><b>-f[no-]print-source-range-info</b>:
303Print machine parsable information about source ranges.</dt>
304<dd>This option, which defaults to off, controls whether or not Clang prints
305information about source ranges in a machine parsable format after the
306file/line/column number information. The information is a simple sequence of
307brace enclosed ranges, where each range lists the start and end line/column
308locations. For example, in this output:</p>
309
310<pre>
311exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
312 P = (P-42) + Gamma*4;
313 ~~~~~~ ^ ~~~~~~~
314</pre>
315
316<p>The {}'s are generated by -fprint-source-range-info.</p>
317</dd>
318
319
320</dl>
321
322
323
324
325<!-- ===================================================== -->
326<h4 id="cl_diag_warning_groups">Individual Warning Groups</h4>
327<!-- ===================================================== -->
328
329<p>TODO: Generate this from tblgen. Define one anchor per warning group.</p>
330
331
332<dl>
333
334
335<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
336<dt id="opt_Wextra-tokens"><b>-Wextra-tokens</b>: Warn about excess tokens at
337 the end of a preprocessor directive.</dt>
338<dd>This option, which defaults to on, enables warnings about extra tokens at
339the end of preprocessor directives. For example:</p>
340
341<pre>
342 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
343 #endif bad
344 ^
345</pre>
346
347<p>These extra tokens are not strictly conforming, and are usually best handled
348by commenting them out.</p>
349
350<p>This option is also enabled by <a href="">-Wfoo</a>, <a href="">-Wbar</a>,
351 and <a href="">-Wbaz</a>.</p>
352</dd>
353
354</dl>
355
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]356<!-- ======================================================================= -->
357<h2 id="general_features">Language and Target-Independent Features</h2>
358<!-- ======================================================================= -->
359
360
361<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
362<h3 id="diagnostics">Controlling Errors and Warnings</h3>
363<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
364
Chris Lattner65a795b2009-04-20 06:00:23 +0000[diff] [blame^]365<p>Clang provides a number of ways to control which code constructs cause it to
366emit errors and warning messages.
367
368error and warning cases
369
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]370
371<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
372<h3 id="precompiledheaders">Precompiled Headers</h3>
373<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
374
Chris Lattner5c3074f2009-04-20 04:37:38 +0000[diff] [blame]375<p><a href="http://en.wikipedia.org/wiki/Precompiled_header">Precompiled
376headers</a> are a general approach employed by many compilers to reduce
377compilation time. The underlying motivation of the approach is that it is
378common for the same (and often large) header files to be included by
379multiple source files. Consequently, compile times can often be greatly improved
380by caching some of the (redundant) work done by a compiler to process headers.
381Precompiled header files, which represent one of many ways to implement
382this optimization, are literally files that represent an on-disk cache that
383contains the vital information necessary to reduce some of the work
384needed to process a corresponding header file. While details of precompiled
385headers vary between compilers, precompiled headers have been shown to be a
386highly effective at speeding up program compilation on systems with very large
387system headers (e.g., Mac OS/X).</p>
388
389<p>Clang supports an implementation of precompiled headers known as
390<em>pre-tokenized headers</em> (PTH). Clang's pre-tokenized headers support most
391of same interfaces as GCC's pre-compiled headers (as well as others) but are
392completely different in their implementation. If you are interested in how
393PTH is implemented, please see the <a href="PTHInternals.html">PTH Internals
394 document</a>.</p>
395
396<h4>Generating a PTH File</h4>
397
398<p>To generate a PTH file using Clang, one invokes Clang with
399the <b><tt>-x <i>&lt;language&gt;</i>-header</tt></b> option. This mirrors the
400interface in GCC for generating PCH files:</p>
401
402<pre>
403 $ gcc -x c-header test.h -o test.h.gch
404 $ clang -x c-header test.h -o test.h.pth
405</pre>
406
407<h4>Using a PTH File</h4>
408
409<p>A PTH file can then be used as a prefix header when a
410<b><tt>-include</tt></b> option is passed to <tt>clang</tt>:</p>
411
412<pre>
413 $ clang -include test.h test.c -o test
414</pre>
415
416<p>The <tt>clang</tt> driver will first check if a PTH file for <tt>test.h</tt>
417is available; if so, the contents of <tt>test.h</tt> (and the files it includes)
418will be processed from the PTH file. Otherwise, Clang falls back to
419directly processing the content of <tt>test.h</tt>. This mirrors the behavior of
420GCC.</p>
421
422<p><b>NOTE:</b> Clang does <em>not</em> automatically used PTH files
423for headers that are directly included within a source file. For example:</p>
424
425<pre>
426 $ clang -x c-header test.h -o test.h.pth
427 $ cat test.c
428 #include "test.h"
429 $ clang test.c -o test
430</pre>
431
432<p>In this example, <tt>clang</tt> will not automatically use the PTH file for
433<tt>test.h</tt> since <tt>test.h</tt> was included directly in the source file
434and not specified on the command line using <tt>-include</tt>.</p>
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]435
436
437<!-- ======================================================================= -->
438<h2 id="c">C Language Features</h2>
439<!-- ======================================================================= -->
440
441
442<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
443<h3 id="c_incompatibilities">Intentional Incompatibilities with GCC</h3>
444<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
445
446<p>No VLAs in structs.</p>
447
448
449
450
451<!-- ======================================================================= -->
452<h2 id="objc">Objective-C Language Features</h2>
453<!-- ======================================================================= -->
454
455
456<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
457<h3 id="objc_incompatibilities">Intentional Incompatibilities with GCC</h3>
458<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
459
460<p>No cast of super, no lvalue casts.</p>
461
462
463
464<!-- ======================================================================= -->
465<h2 id="cxx">C++ Language Features</h2>
466<!-- ======================================================================= -->
467
468<p>At this point, Clang C++ is not generally useful. However, Clang C++ support
469is under active development and is progressing rapidly. Please see the <a
470href="http://clang.llvm.org/cxx_status.html">C++ Status</a> page for details or
471ask on the mailing list about how you can help.</p>
472
473<p>Note that the clang driver will refuse to even try to use clang to compile
474C++ code unless you pass the <tt>-ccc-clang-cxx</tt> option to the driver. If
475you really want to play with Clang's C++ support, please pass that flag. </p>
476
477<!-- ======================================================================= -->
478<h2 id="objcxx">Objective C++ Language Features</h2>
479<!-- ======================================================================= -->
480
481<p>At this point, Clang C++ support is not generally useful (and therefore,
482neither is Objective-C++). Please see the <a href="#cxx">C++ section</a> for
483more information.</p>
484
485<!-- ======================================================================= -->
486<h2 id="target_features">Target-Specific Features and Limitations</h2>
487<!-- ======================================================================= -->
488
489
490<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
491<h3 id="target_arch">CPU Architectures Features and Limitations</h3>
492<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
493
494<!-- ======================== -->
495<h4 id="target_arch_x86">X86</h4>
496<!-- ======================== -->
497
498
499<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
500<h3 id="target_os">Operating System Features and Limitations</h3>
501<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
502
503<!-- ======================================= -->
504<h4 id="target_os_darwin">Darwin (Mac OS/X)</h4>
505<!-- ======================================= -->
506
507<p>No __thread support, 64-bit ObjC support requires SL tools.</p>
508
509</div>
510</body>
511</html>