Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 8217f4ed9c652de1f29693eca3958a4a05863bdb / . / docs / UsersManual.html
blob: 86185754ca558ab36f756980bf202a3ec449a2ae [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
Chris Lattner8217f4e2009-04-20 06:26:18 +0000[diff] [blame^]196preferences, and sometimes Clang is driven by another program that wants to
197parse simple and consistent output, not a person. For these cases, Clang
198provides a wide range of options to control the exact output format of the
199diagnostics that it generates.</p>
Chris Lattner65a795b2009-04-20 06:00:23 +0000[diff] [blame]200
201<dl>
202
203<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
204<dt id="opt_fshow-column"><b>-f[no-]show-column</b>: Print column number in
205diagnostic.</dt>
206<dd>This option, which defaults to on, controls whether or not Clang prints the
207column number of a diagnostic. For example, when this is enabled, Clang will
208print something like:</p>
209
210<pre>
211 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
212 #endif bad
213 ^
214 //
215</pre>
216
217<p>When this is disabled, Clang will print "test.c:28: warning..." with no
218column number.</p>
219</dd>
220
221<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
222<dt id="opt_fshow-source-location"><b>-f[no-]show-source-location</b>: Print
223source file/line/column information in diagnostic.</dt>
224<dd>This option, which defaults to on, controls whether or not Clang prints the
225filename, line number and column number of a diagnostic. For example,
226when this is enabled, Clang will print something like:</p>
227
228<pre>
229 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
230 #endif bad
231 ^
232 //
233</pre>
234
235<p>When this is disabled, Clang will not print the "test.c:28:8: " part.</p>
236</dd>
237
238<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
239<dt id="opt_fcaret-diagnostics"><b>-f[no-]caret-diagnostics</b>: Print source
240line and ranges from source code in diagnostic.</dt>
241<dd>This option, which defaults to on, controls whether or not Clang prints the
242source line, source ranges, and caret when emitting a diagnostic. For example,
243when this is enabled, Clang will print something like:</p>
244
245<pre>
246 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
247 #endif bad
248 ^
249 //
250</pre>
251
252<p>When this is disabled, Clang will just print:</p>
253
254<pre>
255 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
256</pre>
257
258</dd>
259
260<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
261<dt id="opt_fdiagnostics-show-option"><b>-f[no-]diagnostics-show-option</b>:
262Enable <tt>[-Woption]</tt> information in diagnostic line.</dt>
263<dd>This option, which defaults to on,
264controls whether or not Clang prints the associated <A
265href="#cl_diag_warning_groups">warning group</a> option name when outputting
266a warning diagnostic. For example, in this output:</p>
267
268<pre>
269 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
270 #endif bad
271 ^
272 //
273</pre>
274
275<p>Passing <b>-fno-diagnostics-show-option</b> will prevent Clang from printing
276the [<a href="#opt_Wextra-tokens">-Wextra-tokens</a>] information in the
277diagnostic. This information tells you the flag needed to enable or disable the
278diagnostic, either from the command line or through <a
279href="#pragma_GCC_diagnostic">#pragma GCC diagnostic</a>.</dd>
280
281
282<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
283<dt id="opt_fdiagnostics-fixit-info"><b>-f[no-]diagnostics-fixit-info</b>:
284Enable "FixIt" information in the diagnostics output.</dt>
285<dd>This option, which defaults to on, controls whether or not Clang prints the
286information on how to fix a specific diagnostic underneath it when it knows.
287For example, in this output:</p>
288
289<pre>
290 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
291 #endif bad
292 ^
293 //
294</pre>
295
296<p>Passing <b>-fno-diagnostics-fixit-info</b> will prevent Clang from printing
297the "//" line at the end of the message. This information is useful for users
298who may not understand what is wrong, but can be confusing for machine
299parsing.</p>
300</dd>
301
302<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
303<dt id="opt_fprint-source-range-info"><b>-f[no-]print-source-range-info</b>:
304Print machine parsable information about source ranges.</dt>
305<dd>This option, which defaults to off, controls whether or not Clang prints
306information about source ranges in a machine parsable format after the
307file/line/column number information. The information is a simple sequence of
308brace enclosed ranges, where each range lists the start and end line/column
309locations. For example, in this output:</p>
310
311<pre>
312exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
313 P = (P-42) + Gamma*4;
314 ~~~~~~ ^ ~~~~~~~
315</pre>
316
317<p>The {}'s are generated by -fprint-source-range-info.</p>
318</dd>
319
320
321</dl>
322
323
324
325
326<!-- ===================================================== -->
327<h4 id="cl_diag_warning_groups">Individual Warning Groups</h4>
328<!-- ===================================================== -->
329
330<p>TODO: Generate this from tblgen. Define one anchor per warning group.</p>
331
332
333<dl>
334
335
336<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
337<dt id="opt_Wextra-tokens"><b>-Wextra-tokens</b>: Warn about excess tokens at
338 the end of a preprocessor directive.</dt>
339<dd>This option, which defaults to on, enables warnings about extra tokens at
340the end of preprocessor directives. For example:</p>
341
342<pre>
343 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
344 #endif bad
345 ^
346</pre>
347
348<p>These extra tokens are not strictly conforming, and are usually best handled
349by commenting them out.</p>
350
351<p>This option is also enabled by <a href="">-Wfoo</a>, <a href="">-Wbar</a>,
352 and <a href="">-Wbaz</a>.</p>
353</dd>
354
355</dl>
356
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]357<!-- ======================================================================= -->
358<h2 id="general_features">Language and Target-Independent Features</h2>
359<!-- ======================================================================= -->
360
361
362<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
363<h3 id="diagnostics">Controlling Errors and Warnings</h3>
364<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
365
Chris Lattner65a795b2009-04-20 06:00:23 +0000[diff] [blame]366<p>Clang provides a number of ways to control which code constructs cause it to
Chris Lattner8217f4e2009-04-20 06:26:18 +0000[diff] [blame^]367emit errors and warning messages, and how they are displayed to the console.</p>
Chris Lattner65a795b2009-04-20 06:00:23 +0000[diff] [blame]368
Chris Lattner8217f4e2009-04-20 06:26:18 +0000[diff] [blame^]369<h4>Controlling How Clang Displays Diagnostics</h4>
Chris Lattner65a795b2009-04-20 06:00:23 +0000[diff] [blame]370
Chris Lattner8217f4e2009-04-20 06:26:18 +0000[diff] [blame^]371<p>When Clang emits a diagnostic, it includes rich information in the output,
372and gives you fine-grain control over which information is printed. Clang has
373the ability to print this information, and these are the options that control
374it:</p>
375
376<p>
377<ol>
378<li>A file/line/column indicator that shows exactly where the diagnostic occurs
379 in your code [<a href="#opt_fshow-column">-fshow-column</a>, <a
380 href="#opt_fshow-source-location">-fshow-source-location</a>].</li>
381<li>A categorization of the diagnostic as a note, warning, error, or fatal
382 error.</li>
383<li>A text string that describes what the problem is.</li>
384<li>An option that indicates how to control the diagnostic (for diagnostics that
385 support it) [<a
386 href="#opt_fdiagnostics-show-option">-fdiagnostics-show-option</a>].</li>
387<li>The line of source code that the issue occurs on, along with a caret and
388 ranges that indicate the important locations [<a
389 href="opt_fcaret-diagnostics">-fcaret-diagnostics</a>].</li>
390<li>"FixIt" information, which is a concise explanation of how to fix the
391 problem (when Clang is certain it knows) [<a
392 href="opt_fdiagnostics-fixit-info">-fdiagnostics-fixit-info</a>].</li>
393<li>A machine-parsable representation of the ranges involved (off by
394 default) [<a
395 href="opt_fprint-source-range-info">-fprint-source-range-info</a>].</li>
396</ol></p>
397
398<p>For more information please see <a href="#cl_diag_formatting">Formatting of
399Diagnostics</a>.</p>
400
401<h4>Controlling Which Diagnostics Clang Generates</h4>
402
403<p>mappings: ignore, note, warning, error, fatal</p>
404
405<p>
406The two major classes are control from the command line and control via pragmas
407in your code.</p>
408
409
410<p>-W flags, -pedantic, etc</p>
411
412<p>pragma GCC diagnostic</p>
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]413
414<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
415<h3 id="precompiledheaders">Precompiled Headers</h3>
416<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
417
Chris Lattner5c3074f2009-04-20 04:37:38 +0000[diff] [blame]418<p><a href="http://en.wikipedia.org/wiki/Precompiled_header">Precompiled
419headers</a> are a general approach employed by many compilers to reduce
420compilation time. The underlying motivation of the approach is that it is
421common for the same (and often large) header files to be included by
422multiple source files. Consequently, compile times can often be greatly improved
423by caching some of the (redundant) work done by a compiler to process headers.
424Precompiled header files, which represent one of many ways to implement
425this optimization, are literally files that represent an on-disk cache that
426contains the vital information necessary to reduce some of the work
427needed to process a corresponding header file. While details of precompiled
428headers vary between compilers, precompiled headers have been shown to be a
429highly effective at speeding up program compilation on systems with very large
430system headers (e.g., Mac OS/X).</p>
431
432<p>Clang supports an implementation of precompiled headers known as
433<em>pre-tokenized headers</em> (PTH). Clang's pre-tokenized headers support most
434of same interfaces as GCC's pre-compiled headers (as well as others) but are
435completely different in their implementation. If you are interested in how
436PTH is implemented, please see the <a href="PTHInternals.html">PTH Internals
437 document</a>.</p>
438
439<h4>Generating a PTH File</h4>
440
441<p>To generate a PTH file using Clang, one invokes Clang with
442the <b><tt>-x <i>&lt;language&gt;</i>-header</tt></b> option. This mirrors the
443interface in GCC for generating PCH files:</p>
444
445<pre>
446 $ gcc -x c-header test.h -o test.h.gch
447 $ clang -x c-header test.h -o test.h.pth
448</pre>
449
450<h4>Using a PTH File</h4>
451
452<p>A PTH file can then be used as a prefix header when a
453<b><tt>-include</tt></b> option is passed to <tt>clang</tt>:</p>
454
455<pre>
456 $ clang -include test.h test.c -o test
457</pre>
458
459<p>The <tt>clang</tt> driver will first check if a PTH file for <tt>test.h</tt>
460is available; if so, the contents of <tt>test.h</tt> (and the files it includes)
461will be processed from the PTH file. Otherwise, Clang falls back to
462directly processing the content of <tt>test.h</tt>. This mirrors the behavior of
463GCC.</p>
464
465<p><b>NOTE:</b> Clang does <em>not</em> automatically used PTH files
466for headers that are directly included within a source file. For example:</p>
467
468<pre>
469 $ clang -x c-header test.h -o test.h.pth
470 $ cat test.c
471 #include "test.h"
472 $ clang test.c -o test
473</pre>
474
475<p>In this example, <tt>clang</tt> will not automatically use the PTH file for
476<tt>test.h</tt> since <tt>test.h</tt> was included directly in the source file
477and not specified on the command line using <tt>-include</tt>.</p>
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000[diff] [blame]478
479
480<!-- ======================================================================= -->
481<h2 id="c">C Language Features</h2>
482<!-- ======================================================================= -->
483
484
485<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
486<h3 id="c_incompatibilities">Intentional Incompatibilities with GCC</h3>
487<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
488
489<p>No VLAs in structs.</p>
490
491
492
493
494<!-- ======================================================================= -->
495<h2 id="objc">Objective-C Language Features</h2>
496<!-- ======================================================================= -->
497
498
499<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
500<h3 id="objc_incompatibilities">Intentional Incompatibilities with GCC</h3>
501<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
502
503<p>No cast of super, no lvalue casts.</p>
504
505
506
507<!-- ======================================================================= -->
508<h2 id="cxx">C++ Language Features</h2>
509<!-- ======================================================================= -->
510
511<p>At this point, Clang C++ is not generally useful. However, Clang C++ support
512is under active development and is progressing rapidly. Please see the <a
513href="http://clang.llvm.org/cxx_status.html">C++ Status</a> page for details or
514ask on the mailing list about how you can help.</p>
515
516<p>Note that the clang driver will refuse to even try to use clang to compile
517C++ code unless you pass the <tt>-ccc-clang-cxx</tt> option to the driver. If
518you really want to play with Clang's C++ support, please pass that flag. </p>
519
520<!-- ======================================================================= -->
521<h2 id="objcxx">Objective C++ Language Features</h2>
522<!-- ======================================================================= -->
523
524<p>At this point, Clang C++ support is not generally useful (and therefore,
525neither is Objective-C++). Please see the <a href="#cxx">C++ section</a> for
526more information.</p>
527
528<!-- ======================================================================= -->
529<h2 id="target_features">Target-Specific Features and Limitations</h2>
530<!-- ======================================================================= -->
531
532
533<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
534<h3 id="target_arch">CPU Architectures Features and Limitations</h3>
535<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
536
537<!-- ======================== -->
538<h4 id="target_arch_x86">X86</h4>
539<!-- ======================== -->
540
541
542<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
543<h3 id="target_os">Operating System Features and Limitations</h3>
544<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
545
546<!-- ======================================= -->
547<h4 id="target_os_darwin">Darwin (Mac OS/X)</h4>
548<!-- ======================================= -->
549
550<p>No __thread support, 64-bit ObjC support requires SL tools.</p>
551
552</div>
553</body>
554</html>