blob: 4167f6183f04129aba0c38c61948702292e9f95b [file] [log] [blame]
Chris Lattnercf17d9d2009-04-20 04:23:09 +00001<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 +000027<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 +000033<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 +0000170depth 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 +0000172</p>
173
Chris Lattner65a795b2009-04-20 06:00:23 +0000174
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 +0000196preferences, 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 +0000200
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<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
Chris Lattner2a9cc232009-04-21 05:35:32 +0000303<dt id="opt_fdiagnostics-print-source-range-info">
304<b>-f[no-]diagnostics-print-source-range-info</b>:
Chris Lattner65a795b2009-04-20 06:00:23 +0000305Print machine parsable information about source ranges.</dt>
306<dd>This option, which defaults to off, controls whether or not Clang prints
307information about source ranges in a machine parsable format after the
308file/line/column number information. The information is a simple sequence of
309brace enclosed ranges, where each range lists the start and end line/column
310locations. For example, in this output:</p>
311
312<pre>
313exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
314 P = (P-42) + Gamma*4;
315 ~~~~~~ ^ ~~~~~~~
316</pre>
317
Chris Lattner2a9cc232009-04-21 05:35:32 +0000318<p>The {}'s are generated by -fdiagnostics-print-source-range-info.</p>
Chris Lattner65a795b2009-04-20 06:00:23 +0000319</dd>
320
321
322</dl>
323
324
325
326
327<!-- ===================================================== -->
328<h4 id="cl_diag_warning_groups">Individual Warning Groups</h4>
329<!-- ===================================================== -->
330
331<p>TODO: Generate this from tblgen. Define one anchor per warning group.</p>
332
333
334<dl>
335
336
337<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
338<dt id="opt_Wextra-tokens"><b>-Wextra-tokens</b>: Warn about excess tokens at
339 the end of a preprocessor directive.</dt>
340<dd>This option, which defaults to on, enables warnings about extra tokens at
341the end of preprocessor directives. For example:</p>
342
343<pre>
344 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
345 #endif bad
346 ^
347</pre>
348
349<p>These extra tokens are not strictly conforming, and are usually best handled
350by commenting them out.</p>
351
352<p>This option is also enabled by <a href="">-Wfoo</a>, <a href="">-Wbar</a>,
353 and <a href="">-Wbaz</a>.</p>
354</dd>
355
356</dl>
357
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000358<!-- ======================================================================= -->
359<h2 id="general_features">Language and Target-Independent Features</h2>
360<!-- ======================================================================= -->
361
362
363<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
364<h3 id="diagnostics">Controlling Errors and Warnings</h3>
365<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
366
Chris Lattner65a795b2009-04-20 06:00:23 +0000367<p>Clang provides a number of ways to control which code constructs cause it to
Chris Lattner8217f4e2009-04-20 06:26:18 +0000368emit errors and warning messages, and how they are displayed to the console.</p>
Chris Lattner65a795b2009-04-20 06:00:23 +0000369
Chris Lattner8217f4e2009-04-20 06:26:18 +0000370<h4>Controlling How Clang Displays Diagnostics</h4>
Chris Lattner65a795b2009-04-20 06:00:23 +0000371
Chris Lattner8217f4e2009-04-20 06:26:18 +0000372<p>When Clang emits a diagnostic, it includes rich information in the output,
373and gives you fine-grain control over which information is printed. Clang has
374the ability to print this information, and these are the options that control
375it:</p>
376
377<p>
378<ol>
379<li>A file/line/column indicator that shows exactly where the diagnostic occurs
380 in your code [<a href="#opt_fshow-column">-fshow-column</a>, <a
381 href="#opt_fshow-source-location">-fshow-source-location</a>].</li>
382<li>A categorization of the diagnostic as a note, warning, error, or fatal
383 error.</li>
384<li>A text string that describes what the problem is.</li>
385<li>An option that indicates how to control the diagnostic (for diagnostics that
386 support it) [<a
387 href="#opt_fdiagnostics-show-option">-fdiagnostics-show-option</a>].</li>
388<li>The line of source code that the issue occurs on, along with a caret and
389 ranges that indicate the important locations [<a
390 href="opt_fcaret-diagnostics">-fcaret-diagnostics</a>].</li>
391<li>"FixIt" information, which is a concise explanation of how to fix the
392 problem (when Clang is certain it knows) [<a
393 href="opt_fdiagnostics-fixit-info">-fdiagnostics-fixit-info</a>].</li>
394<li>A machine-parsable representation of the ranges involved (off by
395 default) [<a
Chris Lattner2a9cc232009-04-21 05:35:32 +0000396 href="opt_fdiagnostics-print-source-range-info">-fdiagnostics-print-source-range-info</a>].</li>
Chris Lattner8217f4e2009-04-20 06:26:18 +0000397</ol></p>
398
399<p>For more information please see <a href="#cl_diag_formatting">Formatting of
400Diagnostics</a>.</p>
401
402<h4>Controlling Which Diagnostics Clang Generates</h4>
403
404<p>mappings: ignore, note, warning, error, fatal</p>
405
406<p>
407The two major classes are control from the command line and control via pragmas
408in your code.</p>
409
410
411<p>-W flags, -pedantic, etc</p>
412
413<p>pragma GCC diagnostic</p>
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000414
415<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
416<h3 id="precompiledheaders">Precompiled Headers</h3>
417<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
418
Chris Lattner5c3074f2009-04-20 04:37:38 +0000419<p><a href="http://en.wikipedia.org/wiki/Precompiled_header">Precompiled
420headers</a> are a general approach employed by many compilers to reduce
421compilation time. The underlying motivation of the approach is that it is
422common for the same (and often large) header files to be included by
423multiple source files. Consequently, compile times can often be greatly improved
424by caching some of the (redundant) work done by a compiler to process headers.
425Precompiled header files, which represent one of many ways to implement
426this optimization, are literally files that represent an on-disk cache that
427contains the vital information necessary to reduce some of the work
428needed to process a corresponding header file. While details of precompiled
429headers vary between compilers, precompiled headers have been shown to be a
430highly effective at speeding up program compilation on systems with very large
431system headers (e.g., Mac OS/X).</p>
432
433<p>Clang supports an implementation of precompiled headers known as
434<em>pre-tokenized headers</em> (PTH). Clang's pre-tokenized headers support most
435of same interfaces as GCC's pre-compiled headers (as well as others) but are
436completely different in their implementation. If you are interested in how
437PTH is implemented, please see the <a href="PTHInternals.html">PTH Internals
438 document</a>.</p>
439
440<h4>Generating a PTH File</h4>
441
442<p>To generate a PTH file using Clang, one invokes Clang with
443the <b><tt>-x <i>&lt;language&gt;</i>-header</tt></b> option. This mirrors the
444interface in GCC for generating PCH files:</p>
445
446<pre>
447 $ gcc -x c-header test.h -o test.h.gch
448 $ clang -x c-header test.h -o test.h.pth
449</pre>
450
451<h4>Using a PTH File</h4>
452
453<p>A PTH file can then be used as a prefix header when a
454<b><tt>-include</tt></b> option is passed to <tt>clang</tt>:</p>
455
456<pre>
457 $ clang -include test.h test.c -o test
458</pre>
459
460<p>The <tt>clang</tt> driver will first check if a PTH file for <tt>test.h</tt>
461is available; if so, the contents of <tt>test.h</tt> (and the files it includes)
462will be processed from the PTH file. Otherwise, Clang falls back to
463directly processing the content of <tt>test.h</tt>. This mirrors the behavior of
464GCC.</p>
465
Ted Kremenekbf94ca62009-04-21 17:14:24 +0000466<p><b>NOTE:</b> Clang does <em>not</em> automatically use PTH files
Chris Lattner5c3074f2009-04-20 04:37:38 +0000467for headers that are directly included within a source file. For example:</p>
468
469<pre>
470 $ clang -x c-header test.h -o test.h.pth
471 $ cat test.c
472 #include "test.h"
473 $ clang test.c -o test
474</pre>
475
476<p>In this example, <tt>clang</tt> will not automatically use the PTH file for
477<tt>test.h</tt> since <tt>test.h</tt> was included directly in the source file
478and not specified on the command line using <tt>-include</tt>.</p>
Chris Lattnercf17d9d2009-04-20 04:23:09 +0000479
480
481<!-- ======================================================================= -->
482<h2 id="c">C Language Features</h2>
483<!-- ======================================================================= -->
484
485
486<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
487<h3 id="c_incompatibilities">Intentional Incompatibilities with GCC</h3>
488<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
489
490<p>No VLAs in structs.</p>
491
492
493
494
495<!-- ======================================================================= -->
496<h2 id="objc">Objective-C Language Features</h2>
497<!-- ======================================================================= -->
498
499
500<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
501<h3 id="objc_incompatibilities">Intentional Incompatibilities with GCC</h3>
502<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
503
504<p>No cast of super, no lvalue casts.</p>
505
506
507
508<!-- ======================================================================= -->
509<h2 id="cxx">C++ Language Features</h2>
510<!-- ======================================================================= -->
511
512<p>At this point, Clang C++ is not generally useful. However, Clang C++ support
513is under active development and is progressing rapidly. Please see the <a
514href="http://clang.llvm.org/cxx_status.html">C++ Status</a> page for details or
515ask on the mailing list about how you can help.</p>
516
517<p>Note that the clang driver will refuse to even try to use clang to compile
518C++ code unless you pass the <tt>-ccc-clang-cxx</tt> option to the driver. If
519you really want to play with Clang's C++ support, please pass that flag. </p>
520
521<!-- ======================================================================= -->
522<h2 id="objcxx">Objective C++ Language Features</h2>
523<!-- ======================================================================= -->
524
525<p>At this point, Clang C++ support is not generally useful (and therefore,
526neither is Objective-C++). Please see the <a href="#cxx">C++ section</a> for
527more information.</p>
528
529<!-- ======================================================================= -->
530<h2 id="target_features">Target-Specific Features and Limitations</h2>
531<!-- ======================================================================= -->
532
533
534<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
535<h3 id="target_arch">CPU Architectures Features and Limitations</h3>
536<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
537
538<!-- ======================== -->
539<h4 id="target_arch_x86">X86</h4>
540<!-- ======================== -->
541
542
543<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
544<h3 id="target_os">Operating System Features and Limitations</h3>
545<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
546
547<!-- ======================================= -->
548<h4 id="target_os_darwin">Darwin (Mac OS/X)</h4>
549<!-- ======================================= -->
550
551<p>No __thread support, 64-bit ObjC support requires SL tools.</p>
552
553</div>
554</body>
555</html>