]> granicus.if.org Git - clang/blob - docs/UsersManual.rst
Grammar: Don't imply that a program wouldn't want a person as its output.
[clang] / docs / UsersManual.rst
1 ============================
2 Clang Compiler User's Manual
3 ============================
4
5 .. contents::
6    :local:
7
8 Introduction
9 ============
10
11 The Clang Compiler is an open-source compiler for the C family of
12 programming languages, aiming to be the best in class implementation of
13 these languages. Clang builds on the LLVM optimizer and code generator,
14 allowing it to provide high-quality optimization and code generation
15 support for many targets. For more general information, please see the
16 `Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web
17 Site <http://llvm.org>`_.
18
19 This document describes important notes about using Clang as a compiler
20 for an end-user, documenting the supported features, command line
21 options, etc. If you are interested in using Clang to build a tool that
22 processes code, please see :doc:`InternalsManual`. If you are interested in the
23 `Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
24 page.
25
26 Clang is designed to support the C family of programming languages,
27 which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
28 :ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
29 language-specific information, please see the corresponding language
30 specific section:
31
32 -  :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
33    C99 (+TC1, TC2, TC3).
34 -  :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
35    variants depending on base language.
36 -  :ref:`C++ Language <cxx>`
37 -  :ref:`Objective C++ Language <objcxx>`
38
39 In addition to these base languages and their dialects, Clang supports a
40 broad variety of language extensions, which are documented in the
41 corresponding language section. These extensions are provided to be
42 compatible with the GCC, Microsoft, and other popular compilers as well
43 as to improve functionality through Clang-specific features. The Clang
44 driver and language features are intentionally designed to be as
45 compatible with the GNU GCC compiler as reasonably possible, easing
46 migration from GCC to Clang. In most cases, code "just works".
47 Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
48 to be compatible with the Visual C++ compiler, cl.exe.
49
50 In addition to language specific features, Clang has a variety of
51 features that depend on what CPU architecture or operating system is
52 being compiled for. Please see the :ref:`Target-Specific Features and
53 Limitations <target_features>` section for more details.
54
55 The rest of the introduction introduces some basic :ref:`compiler
56 terminology <terminology>` that is used throughout this manual and
57 contains a basic :ref:`introduction to using Clang <basicusage>` as a
58 command line compiler.
59
60 .. _terminology:
61
62 Terminology
63 -----------
64
65 Front end, parser, backend, preprocessor, undefined behavior,
66 diagnostic, optimizer
67
68 .. _basicusage:
69
70 Basic Usage
71 -----------
72
73 Intro to how to use a C compiler for newbies.
74
75 compile + link compile then link debug info enabling optimizations
76 picking a language to use, defaults to C11 by default. Autosenses based
77 on extension. using a makefile
78
79 Command Line Options
80 ====================
81
82 This section is generally an index into other sections. It does not go
83 into depth on the ones that are covered by other sections. However, the
84 first part introduces the language selection and other high level
85 options like :option:`-c`, :option:`-g`, etc.
86
87 Options to Control Error and Warning Messages
88 ---------------------------------------------
89
90 .. option:: -Werror
91
92   Turn warnings into errors.
93
94 .. This is in plain monospaced font because it generates the same label as
95 .. -Werror, and Sphinx complains.
96
97 ``-Werror=foo``
98
99   Turn warning "foo" into an error.
100
101 .. option:: -Wno-error=foo
102
103   Turn warning "foo" into an warning even if :option:`-Werror` is specified.
104
105 .. option:: -Wfoo
106
107   Enable warning "foo".
108
109 .. option:: -Wno-foo
110
111   Disable warning "foo".
112
113 .. option:: -w
114
115   Disable all diagnostics.
116
117 .. option:: -Weverything
118
119   :ref:`Enable all diagnostics. <diagnostics_enable_everything>`
120
121 .. option:: -pedantic
122
123   Warn on language extensions.
124
125 .. option:: -pedantic-errors
126
127   Error on language extensions.
128
129 .. option:: -Wsystem-headers
130
131   Enable warnings from system headers.
132
133 .. option:: -ferror-limit=123
134
135   Stop emitting diagnostics after 123 errors have been produced. The default is
136   20, and the error limit can be disabled with :option:`-ferror-limit=0`.
137
138 .. option:: -ftemplate-backtrace-limit=123
139
140   Only emit up to 123 template instantiation notes within the template
141   instantiation backtrace for a single warning or error. The default is 10, and
142   the limit can be disabled with :option:`-ftemplate-backtrace-limit=0`.
143
144 .. _cl_diag_formatting:
145
146 Formatting of Diagnostics
147 ^^^^^^^^^^^^^^^^^^^^^^^^^
148
149 Clang aims to produce beautiful diagnostics by default, particularly for
150 new users that first come to Clang. However, different people have
151 different preferences, and sometimes Clang is driven not by a human,
152 but by a program that wants consistent and easily parsable output. For
153 these cases, Clang provides a wide range of options to control the exact
154 output format of the diagnostics that it generates.
155
156 .. _opt_fshow-column:
157
158 **-f[no-]show-column**
159    Print column number in diagnostic.
160
161    This option, which defaults to on, controls whether or not Clang
162    prints the column number of a diagnostic. For example, when this is
163    enabled, Clang will print something like:
164
165    ::
166
167          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
168          #endif bad
169                 ^
170                 //
171
172    When this is disabled, Clang will print "test.c:28: warning..." with
173    no column number.
174
175    The printed column numbers count bytes from the beginning of the
176    line; take care if your source contains multibyte characters.
177
178 .. _opt_fshow-source-location:
179
180 **-f[no-]show-source-location**
181    Print source file/line/column information in diagnostic.
182
183    This option, which defaults to on, controls whether or not Clang
184    prints the filename, line number and column number of a diagnostic.
185    For example, when this is enabled, Clang will print something like:
186
187    ::
188
189          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
190          #endif bad
191                 ^
192                 //
193
194    When this is disabled, Clang will not print the "test.c:28:8: "
195    part.
196
197 .. _opt_fcaret-diagnostics:
198
199 **-f[no-]caret-diagnostics**
200    Print source line and ranges from source code in diagnostic.
201    This option, which defaults to on, controls whether or not Clang
202    prints the source line, source ranges, and caret when emitting a
203    diagnostic. For example, when this is enabled, Clang will print
204    something like:
205
206    ::
207
208          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
209          #endif bad
210                 ^
211                 //
212
213 **-f[no-]color-diagnostics**
214    This option, which defaults to on when a color-capable terminal is
215    detected, controls whether or not Clang prints diagnostics in color.
216
217    When this option is enabled, Clang will use colors to highlight
218    specific parts of the diagnostic, e.g.,
219
220    .. nasty hack to not lose our dignity
221
222    .. raw:: html
223
224        <pre>
225          <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b>
226          #endif bad
227                 <span style="color:green">^</span>
228                 <span style="color:green">//</span>
229        </pre>
230
231    When this is disabled, Clang will just print:
232
233    ::
234
235          test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
236          #endif bad
237                 ^
238                 //
239
240 **-fansi-escape-codes**
241    Controls whether ANSI escape codes are used instead of the Windows Console
242    API to output colored diagnostics. This option is only used on Windows and
243    defaults to off.
244
245 .. option:: -fdiagnostics-format=clang/msvc/vi
246
247    Changes diagnostic output format to better match IDEs and command line tools.
248
249    This option controls the output format of the filename, line number,
250    and column printed in diagnostic messages. The options, and their
251    affect on formatting a simple conversion diagnostic, follow:
252
253    **clang** (default)
254        ::
255
256            t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
257
258    **msvc**
259        ::
260
261            t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
262
263    **vi**
264        ::
265
266            t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
267
268 .. _opt_fdiagnostics-show-option:
269
270 **-f[no-]diagnostics-show-option**
271    Enable ``[-Woption]`` information in diagnostic line.
272
273    This option, which defaults to on, controls whether or not Clang
274    prints the associated :ref:`warning group <cl_diag_warning_groups>`
275    option name when outputting a warning diagnostic. For example, in
276    this output:
277
278    ::
279
280          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
281          #endif bad
282                 ^
283                 //
284
285    Passing **-fno-diagnostics-show-option** will prevent Clang from
286    printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
287    the diagnostic. This information tells you the flag needed to enable
288    or disable the diagnostic, either from the command line or through
289    :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
290
291 .. _opt_fdiagnostics-show-category:
292
293 .. option:: -fdiagnostics-show-category=none/id/name
294
295    Enable printing category information in diagnostic line.
296
297    This option, which defaults to "none", controls whether or not Clang
298    prints the category associated with a diagnostic when emitting it.
299    Each diagnostic may or many not have an associated category, if it
300    has one, it is listed in the diagnostic categorization field of the
301    diagnostic line (in the []'s).
302
303    For example, a format string warning will produce these three
304    renditions based on the setting of this option:
305
306    ::
307
308          t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
309          t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
310          t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
311
312    This category can be used by clients that want to group diagnostics
313    by category, so it should be a high level category. We want dozens
314    of these, not hundreds or thousands of them.
315
316 .. _opt_fdiagnostics-fixit-info:
317
318 **-f[no-]diagnostics-fixit-info**
319    Enable "FixIt" information in the diagnostics output.
320
321    This option, which defaults to on, controls whether or not Clang
322    prints the information on how to fix a specific diagnostic
323    underneath it when it knows. For example, in this output:
324
325    ::
326
327          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
328          #endif bad
329                 ^
330                 //
331
332    Passing **-fno-diagnostics-fixit-info** will prevent Clang from
333    printing the "//" line at the end of the message. This information
334    is useful for users who may not understand what is wrong, but can be
335    confusing for machine parsing.
336
337 .. _opt_fdiagnostics-print-source-range-info:
338
339 **-fdiagnostics-print-source-range-info**
340    Print machine parsable information about source ranges.
341    This option makes Clang print information about source ranges in a machine
342    parsable format after the file/line/column number information. The
343    information is a simple sequence of brace enclosed ranges, where each range
344    lists the start and end line/column locations. For example, in this output:
345
346    ::
347
348        exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
349           P = (P-42) + Gamma*4;
350               ~~~~~~ ^ ~~~~~~~
351
352    The {}'s are generated by -fdiagnostics-print-source-range-info.
353
354    The printed column numbers count bytes from the beginning of the
355    line; take care if your source contains multibyte characters.
356
357 .. option:: -fdiagnostics-parseable-fixits
358
359    Print Fix-Its in a machine parseable form.
360
361    This option makes Clang print available Fix-Its in a machine
362    parseable format at the end of diagnostics. The following example
363    illustrates the format:
364
365    ::
366
367         fix-it:"t.cpp":{7:25-7:29}:"Gamma"
368
369    The range printed is a half-open range, so in this example the
370    characters at column 25 up to but not including column 29 on line 7
371    in t.cpp should be replaced with the string "Gamma". Either the
372    range or the replacement string may be empty (representing strict
373    insertions and strict erasures, respectively). Both the file name
374    and the insertion string escape backslash (as "\\\\"), tabs (as
375    "\\t"), newlines (as "\\n"), double quotes(as "\\"") and
376    non-printable characters (as octal "\\xxx").
377
378    The printed column numbers count bytes from the beginning of the
379    line; take care if your source contains multibyte characters.
380
381 .. option:: -fno-elide-type
382
383    Turns off elision in template type printing.
384
385    The default for template type printing is to elide as many template
386    arguments as possible, removing those which are the same in both
387    template types, leaving only the differences. Adding this flag will
388    print all the template arguments. If supported by the terminal,
389    highlighting will still appear on differing arguments.
390
391    Default:
392
393    ::
394
395        t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
396
397    -fno-elide-type:
398
399    ::
400
401        t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;
402
403 .. option:: -fdiagnostics-show-template-tree
404
405    Template type diffing prints a text tree.
406
407    For diffing large templated types, this option will cause Clang to
408    display the templates as an indented text tree, one argument per
409    line, with differences marked inline. This is compatible with
410    -fno-elide-type.
411
412    Default:
413
414    ::
415
416        t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
417
418    With :option:`-fdiagnostics-show-template-tree`:
419
420    ::
421
422        t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
423          vector<
424            map<
425              [...],
426              map<
427                [float != double],
428                [...]>>>
429
430 .. _cl_diag_warning_groups:
431
432 Individual Warning Groups
433 ^^^^^^^^^^^^^^^^^^^^^^^^^
434
435 TODO: Generate this from tblgen. Define one anchor per warning group.
436
437 .. _opt_wextra-tokens:
438
439 .. option:: -Wextra-tokens
440
441    Warn about excess tokens at the end of a preprocessor directive.
442
443    This option, which defaults to on, enables warnings about extra
444    tokens at the end of preprocessor directives. For example:
445
446    ::
447
448          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
449          #endif bad
450                 ^
451
452    These extra tokens are not strictly conforming, and are usually best
453    handled by commenting them out.
454
455 .. option:: -Wambiguous-member-template
456
457    Warn about unqualified uses of a member template whose name resolves to
458    another template at the location of the use.
459
460    This option, which defaults to on, enables a warning in the
461    following code:
462
463    ::
464
465        template<typename T> struct set{};
466        template<typename T> struct trait { typedef const T& type; };
467        struct Value {
468          template<typename T> void set(typename trait<T>::type value) {}
469        };
470        void foo() {
471          Value v;
472          v.set<double>(3.2);
473        }
474
475    C++ [basic.lookup.classref] requires this to be an error, but,
476    because it's hard to work around, Clang downgrades it to a warning
477    as an extension.
478
479 .. option:: -Wbind-to-temporary-copy
480
481    Warn about an unusable copy constructor when binding a reference to a
482    temporary.
483
484    This option enables warnings about binding a
485    reference to a temporary when the temporary doesn't have a usable
486    copy constructor. For example:
487
488    ::
489
490          struct NonCopyable {
491            NonCopyable();
492          private:
493            NonCopyable(const NonCopyable&);
494          };
495          void foo(const NonCopyable&);
496          void bar() {
497            foo(NonCopyable());  // Disallowed in C++98; allowed in C++11.
498          }
499
500    ::
501
502          struct NonCopyable2 {
503            NonCopyable2();
504            NonCopyable2(NonCopyable2&);
505          };
506          void foo(const NonCopyable2&);
507          void bar() {
508            foo(NonCopyable2());  // Disallowed in C++98; allowed in C++11.
509          }
510
511    Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
512    whose instantiation produces a compile error, that error will still
513    be a hard error in C++98 mode even if this warning is turned off.
514
515 Options to Control Clang Crash Diagnostics
516 ------------------------------------------
517
518 As unbelievable as it may sound, Clang does crash from time to time.
519 Generally, this only occurs to those living on the `bleeding
520 edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
521 lengths to assist you in filing a bug report. Specifically, Clang
522 generates preprocessed source file(s) and associated run script(s) upon
523 a crash. These files should be attached to a bug report to ease
524 reproducibility of the failure. Below are the command line options to
525 control the crash diagnostics.
526
527 .. option:: -fno-crash-diagnostics
528
529   Disable auto-generation of preprocessed source files during a clang crash.
530
531 The -fno-crash-diagnostics flag can be helpful for speeding the process
532 of generating a delta reduced test case.
533
534 Options to Emit Optimization Reports
535 ------------------------------------
536
537 Optimization reports trace, at a high-level, all the major decisions
538 done by compiler transformations. For instance, when the inliner
539 decides to inline function ``foo()`` into ``bar()``, or the loop unroller
540 decides to unroll a loop N times, or the vectorizer decides to
541 vectorize a loop body.
542
543 Clang offers a family of flags which the optimizers can use to emit
544 a diagnostic in three cases:
545
546 1. When the pass makes a transformation (:option:`-Rpass`).
547
548 2. When the pass fails to make a transformation (:option:`-Rpass-missed`).
549
550 3. When the pass determines whether or not to make a transformation
551    (:option:`-Rpass-analysis`).
552
553 NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact
554 same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`.
555
556 Since there are dozens of passes inside the compiler, each of these flags
557 take a regular expression that identifies the name of the pass which should
558 emit the associated diagnostic. For example, to get a report from the inliner,
559 compile the code with:
560
561 .. code-block:: console
562
563    $ clang -O2 -Rpass=inline code.cc -o code
564    code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
565    int bar(int j) { return foo(j, j - 2); }
566                            ^
567
568 Note that remarks from the inliner are identified with `[-Rpass=inline]`.
569 To request a report from every optimization pass, you should use
570 :option:`-Rpass=.*` (in fact, you can use any valid POSIX regular
571 expression). However, do not expect a report from every transformation
572 made by the compiler. Optimization remarks do not really make sense
573 outside of the major transformations (e.g., inlining, vectorization,
574 loop optimizations) and not every optimization pass supports this
575 feature.
576
577 Current limitations
578 ^^^^^^^^^^^^^^^^^^^
579
580 1. Optimization remarks that refer to function names will display the
581    mangled name of the function. Since these remarks are emitted by the
582    back end of the compiler, it does not know anything about the input
583    language, nor its mangling rules.
584
585 2. Some source locations are not displayed correctly. The front end has
586    a more detailed source location tracking than the locations included
587    in the debug info (e.g., the front end can locate code inside macro
588    expansions). However, the locations used by :option:`-Rpass` are
589    translated from debug annotations. That translation can be lossy,
590    which results in some remarks having no location information.
591
592 Other Options
593 -------------
594 Clang options that that don't fit neatly into other categories.
595
596 .. option:: -MV
597
598   When emitting a dependency file, use formatting conventions appropriate
599   for NMake or Jom. Ignored unless another option causes Clang to emit a
600   dependency file.
601
602 When Clang emits a dependency file (e.g., you supplied the -M option)
603 most filenames can be written to the file without any special formatting.
604 Different Make tools will treat different sets of characters as "special"
605 and use different conventions for telling the Make tool that the character
606 is actually part of the filename. Normally Clang uses backslash to "escape"
607 a special character, which is the convention used by GNU Make. The -MV
608 option tells Clang to put double-quotes around the entire filename, which
609 is the convention used by NMake and Jom.
610
611
612 Language and Target-Independent Features
613 ========================================
614
615 Controlling Errors and Warnings
616 -------------------------------
617
618 Clang provides a number of ways to control which code constructs cause
619 it to emit errors and warning messages, and how they are displayed to
620 the console.
621
622 Controlling How Clang Displays Diagnostics
623 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
624
625 When Clang emits a diagnostic, it includes rich information in the
626 output, and gives you fine-grain control over which information is
627 printed. Clang has the ability to print this information, and these are
628 the options that control it:
629
630 #. A file/line/column indicator that shows exactly where the diagnostic
631    occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
632    :ref:`-fshow-source-location <opt_fshow-source-location>`].
633 #. A categorization of the diagnostic as a note, warning, error, or
634    fatal error.
635 #. A text string that describes what the problem is.
636 #. An option that indicates how to control the diagnostic (for
637    diagnostics that support it)
638    [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
639 #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
640    for clients that want to group diagnostics by class (for diagnostics
641    that support it)
642    [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
643 #. The line of source code that the issue occurs on, along with a caret
644    and ranges that indicate the important locations
645    [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
646 #. "FixIt" information, which is a concise explanation of how to fix the
647    problem (when Clang is certain it knows)
648    [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
649 #. A machine-parsable representation of the ranges involved (off by
650    default)
651    [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
652
653 For more information please see :ref:`Formatting of
654 Diagnostics <cl_diag_formatting>`.
655
656 Diagnostic Mappings
657 ^^^^^^^^^^^^^^^^^^^
658
659 All diagnostics are mapped into one of these 6 classes:
660
661 -  Ignored
662 -  Note
663 -  Remark
664 -  Warning
665 -  Error
666 -  Fatal
667
668 .. _diagnostics_categories:
669
670 Diagnostic Categories
671 ^^^^^^^^^^^^^^^^^^^^^
672
673 Though not shown by default, diagnostics may each be associated with a
674 high-level category. This category is intended to make it possible to
675 triage builds that produce a large number of errors or warnings in a
676 grouped way.
677
678 Categories are not shown by default, but they can be turned on with the
679 :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
680 When set to "``name``", the category is printed textually in the
681 diagnostic output. When it is set to "``id``", a category number is
682 printed. The mapping of category names to category id's can be obtained
683 by running '``clang   --print-diagnostic-categories``'.
684
685 Controlling Diagnostics via Command Line Flags
686 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
687
688 TODO: -W flags, -pedantic, etc
689
690 .. _pragma_gcc_diagnostic:
691
692 Controlling Diagnostics via Pragmas
693 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
694
695 Clang can also control what diagnostics are enabled through the use of
696 pragmas in the source code. This is useful for turning off specific
697 warnings in a section of source code. Clang supports GCC's pragma for
698 compatibility with existing source code, as well as several extensions.
699
700 The pragma may control any warning that can be used from the command
701 line. Warnings may be set to ignored, warning, error, or fatal. The
702 following example code will tell Clang or GCC to ignore the -Wall
703 warnings:
704
705 .. code-block:: c
706
707   #pragma GCC diagnostic ignored "-Wall"
708
709 In addition to all of the functionality provided by GCC's pragma, Clang
710 also allows you to push and pop the current warning state. This is
711 particularly useful when writing a header file that will be compiled by
712 other people, because you don't know what warning flags they build with.
713
714 In the below example :option:`-Wmultichar` is ignored for only a single line of
715 code, after which the diagnostics return to whatever state had previously
716 existed.
717
718 .. code-block:: c
719
720   #pragma clang diagnostic push
721   #pragma clang diagnostic ignored "-Wmultichar"
722
723   char b = 'df'; // no warning.
724
725   #pragma clang diagnostic pop
726
727 The push and pop pragmas will save and restore the full diagnostic state
728 of the compiler, regardless of how it was set. That means that it is
729 possible to use push and pop around GCC compatible diagnostics and Clang
730 will push and pop them appropriately, while GCC will ignore the pushes
731 and pops as unknown pragmas. It should be noted that while Clang
732 supports the GCC pragma, Clang and GCC do not support the exact same set
733 of warnings, so even when using GCC compatible #pragmas there is no
734 guarantee that they will have identical behaviour on both compilers.
735
736 In addition to controlling warnings and errors generated by the compiler, it is
737 possible to generate custom warning and error messages through the following
738 pragmas:
739
740 .. code-block:: c
741
742   // The following will produce warning messages
743   #pragma message "some diagnostic message"
744   #pragma GCC warning "TODO: replace deprecated feature"
745
746   // The following will produce an error message
747   #pragma GCC error "Not supported"
748
749 These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
750 directives, except that they may also be embedded into preprocessor macros via
751 the C99 ``_Pragma`` operator, for example:
752
753 .. code-block:: c
754
755   #define STR(X) #X
756   #define DEFER(M,...) M(__VA_ARGS__)
757   #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
758
759   CUSTOM_ERROR("Feature not available");
760
761 Controlling Diagnostics in System Headers
762 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
763
764 Warnings are suppressed when they occur in system headers. By default,
765 an included file is treated as a system header if it is found in an
766 include path specified by ``-isystem``, but this can be overridden in
767 several ways.
768
769 The ``system_header`` pragma can be used to mark the current file as
770 being a system header. No warnings will be produced from the location of
771 the pragma onwards within the same file.
772
773 .. code-block:: c
774
775   char a = 'xy'; // warning
776
777   #pragma clang system_header
778
779   char b = 'ab'; // no warning
780
781 The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=`
782 command-line arguments can be used to override whether subsets of an include
783 path are treated as system headers. When the name in a ``#include`` directive
784 is found within a header search path and starts with a system prefix, the
785 header is treated as a system header. The last prefix on the
786 command-line which matches the specified header name takes precedence.
787 For instance:
788
789 .. code-block:: console
790
791   $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
792       --no-system-header-prefix=x/y/
793
794 Here, ``#include "x/a.h"`` is treated as including a system header, even
795 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
796 as not including a system header, even if the header is found in
797 ``bar``.
798
799 A ``#include`` directive which finds a file relative to the current
800 directory is treated as including a system header if the including file
801 is treated as a system header.
802
803 .. _diagnostics_enable_everything:
804
805 Enabling All Diagnostics
806 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
807
808 In addition to the traditional ``-W`` flags, one can enable **all**
809 diagnostics by passing :option:`-Weverything`. This works as expected
810 with
811 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
812
813 Note that when combined with :option:`-w` (which disables all warnings), that
814 flag wins.
815
816 Controlling Static Analyzer Diagnostics
817 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
818
819 While not strictly part of the compiler, the diagnostics from Clang's
820 `static analyzer <http://clang-analyzer.llvm.org>`_ can also be
821 influenced by the user via changes to the source code. See the available
822 `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
823 analyzer's `FAQ
824 page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
825 information.
826
827 .. _usersmanual-precompiled-headers:
828
829 Precompiled Headers
830 -------------------
831
832 `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
833 are a general approach employed by many compilers to reduce compilation
834 time. The underlying motivation of the approach is that it is common for
835 the same (and often large) header files to be included by multiple
836 source files. Consequently, compile times can often be greatly improved
837 by caching some of the (redundant) work done by a compiler to process
838 headers. Precompiled header files, which represent one of many ways to
839 implement this optimization, are literally files that represent an
840 on-disk cache that contains the vital information necessary to reduce
841 some of the work needed to process a corresponding header file. While
842 details of precompiled headers vary between compilers, precompiled
843 headers have been shown to be highly effective at speeding up program
844 compilation on systems with very large system headers (e.g., Mac OS X).
845
846 Generating a PCH File
847 ^^^^^^^^^^^^^^^^^^^^^
848
849 To generate a PCH file using Clang, one invokes Clang with the
850 :option:`-x <language>-header` option. This mirrors the interface in GCC
851 for generating PCH files:
852
853 .. code-block:: console
854
855   $ gcc -x c-header test.h -o test.h.gch
856   $ clang -x c-header test.h -o test.h.pch
857
858 Using a PCH File
859 ^^^^^^^^^^^^^^^^
860
861 A PCH file can then be used as a prefix header when a :option:`-include`
862 option is passed to ``clang``:
863
864 .. code-block:: console
865
866   $ clang -include test.h test.c -o test
867
868 The ``clang`` driver will first check if a PCH file for ``test.h`` is
869 available; if so, the contents of ``test.h`` (and the files it includes)
870 will be processed from the PCH file. Otherwise, Clang falls back to
871 directly processing the content of ``test.h``. This mirrors the behavior
872 of GCC.
873
874 .. note::
875
876   Clang does *not* automatically use PCH files for headers that are directly
877   included within a source file. For example:
878
879   .. code-block:: console
880
881     $ clang -x c-header test.h -o test.h.pch
882     $ cat test.c
883     #include "test.h"
884     $ clang test.c -o test
885
886   In this example, ``clang`` will not automatically use the PCH file for
887   ``test.h`` since ``test.h`` was included directly in the source file and not
888   specified on the command line using :option:`-include`.
889
890 Relocatable PCH Files
891 ^^^^^^^^^^^^^^^^^^^^^
892
893 It is sometimes necessary to build a precompiled header from headers
894 that are not yet in their final, installed locations. For example, one
895 might build a precompiled header within the build tree that is then
896 meant to be installed alongside the headers. Clang permits the creation
897 of "relocatable" precompiled headers, which are built with a given path
898 (into the build directory) and can later be used from an installed
899 location.
900
901 To build a relocatable precompiled header, place your headers into a
902 subdirectory whose structure mimics the installed location. For example,
903 if you want to build a precompiled header for the header ``mylib.h``
904 that will be installed into ``/usr/include``, create a subdirectory
905 ``build/usr/include`` and place the header ``mylib.h`` into that
906 subdirectory. If ``mylib.h`` depends on other headers, then they can be
907 stored within ``build/usr/include`` in a way that mimics the installed
908 location.
909
910 Building a relocatable precompiled header requires two additional
911 arguments. First, pass the ``--relocatable-pch`` flag to indicate that
912 the resulting PCH file should be relocatable. Second, pass
913 :option:`-isysroot /path/to/build`, which makes all includes for your library
914 relative to the build directory. For example:
915
916 .. code-block:: console
917
918   # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
919
920 When loading the relocatable PCH file, the various headers used in the
921 PCH file are found from the system header root. For example, ``mylib.h``
922 can be found in ``/usr/include/mylib.h``. If the headers are installed
923 in some other system root, the :option:`-isysroot` option can be used provide
924 a different system root from which the headers will be based. For
925 example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
926 ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
927
928 Relocatable precompiled headers are intended to be used in a limited
929 number of cases where the compilation environment is tightly controlled
930 and the precompiled header cannot be generated after headers have been
931 installed.
932
933 .. _controlling-code-generation:
934
935 Controlling Code Generation
936 ---------------------------
937
938 Clang provides a number of ways to control code generation. The options
939 are listed below.
940
941 **-f[no-]sanitize=check1,check2,...**
942    Turn on runtime checks for various forms of undefined or suspicious
943    behavior.
944
945    This option controls whether Clang adds runtime checks for various
946    forms of undefined or suspicious behavior, and is disabled by
947    default. If a check fails, a diagnostic message is produced at
948    runtime explaining the problem. The main checks are:
949
950    -  .. _opt_fsanitize_address:
951
952       ``-fsanitize=address``:
953       :doc:`AddressSanitizer`, a memory error
954       detector.
955    -  ``-fsanitize=integer``: Enables checks for undefined or
956       suspicious integer behavior.
957    -  .. _opt_fsanitize_thread:
958
959       ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
960    -  .. _opt_fsanitize_memory:
961
962       ``-fsanitize=memory``: :doc:`MemorySanitizer`,
963       an *experimental* detector of uninitialized reads. Not ready for
964       widespread use.
965    -  .. _opt_fsanitize_undefined:
966
967       ``-fsanitize=undefined``: Fast and compatible undefined behavior
968       checker. Enables the undefined behavior checks that have small
969       runtime cost and no impact on address space layout or ABI. This
970       includes all of the checks listed below other than
971       ``unsigned-integer-overflow``.
972
973    -  ``-fsanitize=undefined-trap``: This is a deprecated alias for
974       ``-fsanitize=undefined``.
975
976    -  ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
977       flow analysis.
978    -  ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>`
979       checks. Requires ``-flto``.
980    -  ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>`
981       protection against stack-based memory corruption errors.
982
983    The following more fine-grained checks are also available:
984
985    -  ``-fsanitize=alignment``: Use of a misaligned pointer or creation
986       of a misaligned reference.
987    -  ``-fsanitize=bool``: Load of a ``bool`` value which is neither
988       ``true`` nor ``false``.
989    -  ``-fsanitize=bounds``: Out of bounds array indexing, in cases
990       where the array bound can be statically determined.
991    -  ``-fsanitize=cfi-cast-strict``: Enables :ref:`strict cast checks
992       <cfi-strictness>`.
993    -  ``-fsanitize=cfi-derived-cast``: Base-to-derived cast to the wrong
994       dynamic type. Requires ``-flto``.
995    -  ``-fsanitize=cfi-unrelated-cast``: Cast from ``void*`` or another
996       unrelated type to the wrong dynamic type. Requires ``-flto``.
997    -  ``-fsanitize=cfi-nvcall``: Non-virtual call via an object whose vptr is of
998       the wrong dynamic type. Requires ``-flto``.
999    -  ``-fsanitize=cfi-vcall``: Virtual call via an object whose vptr is of the
1000       wrong dynamic type. Requires ``-flto``.
1001    -  ``-fsanitize=enum``: Load of a value of an enumerated type which
1002       is not in the range of representable values for that enumerated
1003       type.
1004    -  ``-fsanitize=float-cast-overflow``: Conversion to, from, or
1005       between floating-point types which would overflow the
1006       destination.
1007    -  ``-fsanitize=float-divide-by-zero``: Floating point division by
1008       zero.
1009    -  ``-fsanitize=function``: Indirect call of a function through a
1010       function pointer of the wrong type (Linux, C++ and x86/x86_64 only).
1011    -  ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
1012    -  ``-fsanitize=nonnull-attribute``: Passing null pointer as a function
1013       parameter which is declared to never be null.
1014    -  ``-fsanitize=null``: Use of a null pointer or creation of a null
1015       reference.
1016    -  ``-fsanitize=object-size``: An attempt to use bytes which the
1017       optimizer can determine are not part of the object being
1018       accessed. The sizes of objects are determined using
1019       ``__builtin_object_size``, and consequently may be able to detect
1020       more problems at higher optimization levels.
1021    -  ``-fsanitize=return``: In C++, reaching the end of a
1022       value-returning function without returning a value.
1023    -  ``-fsanitize=returns-nonnull-attribute``: Returning null pointer
1024       from a function which is declared to never return null.
1025    -  ``-fsanitize=shift``: Shift operators where the amount shifted is
1026       greater or equal to the promoted bit-width of the left hand side
1027       or less than zero, or where the left hand side is negative. For a
1028       signed left shift, also checks for signed overflow in C, and for
1029       unsigned overflow in C++. You can use ``-fsanitize=shift-base`` or
1030       ``-fsanitize=shift-exponent`` to check only left-hand side or
1031       right-hand side of shift operation, respectively.
1032    -  ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
1033       including all the checks added by ``-ftrapv``, and checking for
1034       overflow in signed division (``INT_MIN / -1``).
1035    -  ``-fsanitize=unreachable``: If control flow reaches
1036       ``__builtin_unreachable``.
1037    -  ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
1038       overflows.
1039    -  ``-fsanitize=vla-bound``: A variable-length array whose bound
1040       does not evaluate to a positive value.
1041    -  ``-fsanitize=vptr``: Use of an object whose vptr indicates that
1042       it is of the wrong dynamic type, or that its lifetime has not
1043       begun or has ended. Incompatible with ``-fno-rtti``.
1044
1045    You can turn off or modify checks for certain source files, functions
1046    or even variables by providing a special file:
1047
1048    -  ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
1049       sanitizer checks for objects listed in the file. See
1050       :doc:`SanitizerSpecialCaseList` for file format description.
1051    -  ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
1052       specified earlier in the command line.
1053
1054    Extra features of MemorySanitizer (require explicit
1055    ``-fsanitize=memory``):
1056
1057    -  ``-fsanitize-memory-track-origins[=level]``: Enables origin tracking in
1058       MemorySanitizer. Adds a second section to MemorySanitizer
1059       reports pointing to the heap or stack allocation the
1060       uninitialized bits came from. Slows down execution by additional
1061       1.5x-2x.
1062
1063       Possible values for level are 0 (off), 1, 2 (default). Level 2
1064       adds more sections to MemorySanitizer reports describing the
1065       order of memory stores the uninitialized value went
1066       through. This mode may use extra memory in programs that copy
1067       uninitialized memory a lot.
1068
1069    The ``-fsanitize=`` argument must also be provided when linking, in
1070    order to link to the appropriate runtime library. When using
1071    ``-fsanitize=vptr`` (or a group that includes it, such as
1072    ``-fsanitize=undefined``) with a C++ program, the link must be
1073    performed by ``clang++``, not ``clang``, in order to link against the
1074    C++-specific parts of the runtime library.
1075
1076    It is not possible to combine more than one of the ``-fsanitize=address``,
1077    ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
1078    program. The ``-fsanitize=undefined`` checks can only be combined with
1079    ``-fsanitize=address``.
1080
1081 **-f[no-]sanitize-recover=check1,check2,...**
1082
1083    Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
1084    If the check is fatal, program will halt after the first error
1085    of this kind is detected and error report is printed.
1086
1087    By default, non-fatal checks are those enabled by UndefinedBehaviorSanitizer,
1088    except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some
1089    sanitizers (e.g. :doc:`AddressSanitizer`) may not support recovery,
1090    and always crash the program after the issue is detected.
1091
1092    Note that the ``-fsanitize-trap`` flag has precedence over this flag.
1093    This means that if a check has been configured to trap elsewhere on the
1094    command line, or if the check traps by default, this flag will not have
1095    any effect unless that sanitizer's trapping behavior is disabled with
1096    ``-fno-sanitize-trap``.
1097
1098    For example, if a command line contains the flags ``-fsanitize=undefined
1099    -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment``
1100    will have no effect on its own; it will need to be accompanied by
1101    ``-fno-sanitize-trap=alignment``.
1102
1103 **-f[no-]sanitize-trap=check1,check2,...**
1104
1105    Controls which checks enabled by the ``-fsanitize=`` flag trap. This
1106    option is intended for use in cases where the sanitizer runtime cannot
1107    be used (for instance, when building libc or a kernel module), or where
1108    the binary size increase caused by the sanitizer runtime is a concern.
1109
1110    This flag is only compatible with ``local-bounds``,
1111    ``unsigned-integer-overflow``, sanitizers in the ``cfi`` group and
1112    sanitizers in the ``undefined`` group other than ``vptr``. If this flag
1113    is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer
1114    will be implicitly disabled.
1115
1116    This flag is enabled by default for sanitizers in the ``cfi`` group.
1117
1118 **-f[no-]sanitize-coverage=[type,features,...]**
1119
1120    Enable simple code coverage in addition to certain sanitizers.
1121    See :doc:`SanitizerCoverage` for more details.
1122
1123 .. option:: -fsanitize-undefined-trap-on-error
1124
1125    Deprecated alias for ``-fsanitize-trap=undefined``.
1126
1127 .. option:: -fno-assume-sane-operator-new
1128
1129    Don't assume that the C++'s new operator is sane.
1130
1131    This option tells the compiler to do not assume that C++'s global
1132    new operator will always return a pointer that does not alias any
1133    other pointer when the function returns.
1134
1135 .. option:: -ftrap-function=[name]
1136
1137    Instruct code generator to emit a function call to the specified
1138    function name for ``__builtin_trap()``.
1139
1140    LLVM code generator translates ``__builtin_trap()`` to a trap
1141    instruction if it is supported by the target ISA. Otherwise, the
1142    builtin is translated into a call to ``abort``. If this option is
1143    set, then the code generator will always lower the builtin to a call
1144    to the specified function regardless of whether the target ISA has a
1145    trap instruction. This option is useful for environments (e.g.
1146    deeply embedded) where a trap cannot be properly handled, or when
1147    some custom behavior is desired.
1148
1149 .. option:: -ftls-model=[model]
1150
1151    Select which TLS model to use.
1152
1153    Valid values are: ``global-dynamic``, ``local-dynamic``,
1154    ``initial-exec`` and ``local-exec``. The default value is
1155    ``global-dynamic``. The compiler may use a different model if the
1156    selected model is not supported by the target, or if a more
1157    efficient model can be used. The TLS model can be overridden per
1158    variable using the ``tls_model`` attribute.
1159
1160 .. option:: -femulated-tls
1161
1162    Select emulated TLS model, which overrides all -ftls-model choices.
1163
1164    In emulated TLS mode, all access to TLS variables are converted to
1165    calls to __emutls_get_address in the runtime library.
1166
1167 .. option:: -mhwdiv=[values]
1168
1169    Select the ARM modes (arm or thumb) that support hardware division
1170    instructions.
1171
1172    Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
1173    This option is used to indicate which mode (arm or thumb) supports
1174    hardware division instructions. This only applies to the ARM
1175    architecture.
1176
1177 .. option:: -m[no-]crc
1178
1179    Enable or disable CRC instructions.
1180
1181    This option is used to indicate whether CRC instructions are to
1182    be generated. This only applies to the ARM architecture.
1183
1184    CRC instructions are enabled by default on ARMv8.
1185
1186 .. option:: -mgeneral-regs-only
1187
1188    Generate code which only uses the general purpose registers.
1189
1190    This option restricts the generated code to use general registers
1191    only. This only applies to the AArch64 architecture.
1192
1193 **-f[no-]max-unknown-pointer-align=[number]**
1194    Instruct the code generator to not enforce a higher alignment than the given
1195    number (of bytes) when accessing memory via an opaque pointer or reference.
1196    This cap is ignored when directly accessing a variable or when the pointee
1197    type has an explicit “aligned” attribute.
1198
1199    The value should usually be determined by the properties of the system allocator.
1200    Some builtin types, especially vector types, have very high natural alignments;
1201    when working with values of those types, Clang usually wants to use instructions
1202    that take advantage of that alignment.  However, many system allocators do
1203    not promise to return memory that is more than 8-byte or 16-byte-aligned.  Use
1204    this option to limit the alignment that the compiler can assume for an arbitrary
1205    pointer, which may point onto the heap.
1206
1207    This option does not affect the ABI alignment of types; the layout of structs and
1208    unions and the value returned by the alignof operator remain the same.
1209
1210    This option can be overridden on a case-by-case basis by putting an explicit
1211    “aligned” alignment on a struct, union, or typedef.  For example:
1212
1213    .. code-block:: console
1214
1215       #include <immintrin.h>
1216       // Make an aligned typedef of the AVX-512 16-int vector type.
1217       typedef __v16si __aligned_v16si __attribute__((aligned(64)));
1218
1219       void initialize_vector(__aligned_v16si *v) {
1220         // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the
1221         // value of -fmax-unknown-pointer-align.
1222       }
1223
1224
1225 Profile Guided Optimization
1226 ---------------------------
1227
1228 Profile information enables better optimization. For example, knowing that a
1229 branch is taken very frequently helps the compiler make better decisions when
1230 ordering basic blocks. Knowing that a function ``foo`` is called more
1231 frequently than another function ``bar`` helps the inliner.
1232
1233 Clang supports profile guided optimization with two different kinds of
1234 profiling. A sampling profiler can generate a profile with very low runtime
1235 overhead, or you can build an instrumented version of the code that collects
1236 more detailed profile information. Both kinds of profiles can provide execution
1237 counts for instructions in the code and information on branches taken and
1238 function invocation.
1239
1240 Regardless of which kind of profiling you use, be careful to collect profiles
1241 by running your code with inputs that are representative of the typical
1242 behavior. Code that is not exercised in the profile will be optimized as if it
1243 is unimportant, and the compiler may make poor optimization choices for code
1244 that is disproportionately used while profiling.
1245
1246 Differences Between Sampling and Instrumentation
1247 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1248
1249 Although both techniques are used for similar purposes, there are important
1250 differences between the two:
1251
1252 1. Profile data generated with one cannot be used by the other, and there is no
1253    conversion tool that can convert one to the other. So, a profile generated
1254    via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``.
1255    Similarly, sampling profiles generated by external profilers must be
1256    converted and used with ``-fprofile-sample-use``.
1257
1258 2. Instrumentation profile data can be used for code coverage analysis and
1259    optimization.
1260
1261 3. Sampling profiles can only be used for optimization. They cannot be used for
1262    code coverage analysis. Although it would be technically possible to use
1263    sampling profiles for code coverage, sample-based profiles are too
1264    coarse-grained for code coverage purposes; it would yield poor results.
1265
1266 4. Sampling profiles must be generated by an external tool. The profile
1267    generated by that tool must then be converted into a format that can be read
1268    by LLVM. The section on sampling profilers describes one of the supported
1269    sampling profile formats.
1270
1271
1272 Using Sampling Profilers
1273 ^^^^^^^^^^^^^^^^^^^^^^^^
1274
1275 Sampling profilers are used to collect runtime information, such as
1276 hardware counters, while your application executes. They are typically
1277 very efficient and do not incur a large runtime overhead. The
1278 sample data collected by the profiler can be used during compilation
1279 to determine what the most executed areas of the code are.
1280
1281 Using the data from a sample profiler requires some changes in the way
1282 a program is built. Before the compiler can use profiling information,
1283 the code needs to execute under the profiler. The following is the
1284 usual build cycle when using sample profilers for optimization:
1285
1286 1. Build the code with source line table information. You can use all the
1287    usual build flags that you always build your application with. The only
1288    requirement is that you add ``-gline-tables-only`` or ``-g`` to the
1289    command line. This is important for the profiler to be able to map
1290    instructions back to source line locations.
1291
1292    .. code-block:: console
1293
1294      $ clang++ -O2 -gline-tables-only code.cc -o code
1295
1296 2. Run the executable under a sampling profiler. The specific profiler
1297    you use does not really matter, as long as its output can be converted
1298    into the format that the LLVM optimizer understands. Currently, there
1299    exists a conversion tool for the Linux Perf profiler
1300    (https://perf.wiki.kernel.org/), so these examples assume that you
1301    are using Linux Perf to profile your code.
1302
1303    .. code-block:: console
1304
1305      $ perf record -b ./code
1306
1307    Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
1308    Record (LBR) to record call chains. While this is not strictly required,
1309    it provides better call information, which improves the accuracy of
1310    the profile data.
1311
1312 3. Convert the collected profile data to LLVM's sample profile format.
1313    This is currently supported via the AutoFDO converter ``create_llvm_prof``.
1314    It is available at http://github.com/google/autofdo. Once built and
1315    installed, you can convert the ``perf.data`` file to LLVM using
1316    the command:
1317
1318    .. code-block:: console
1319
1320      $ create_llvm_prof --binary=./code --out=code.prof
1321
1322    This will read ``perf.data`` and the binary file ``./code`` and emit
1323    the profile data in ``code.prof``. Note that if you ran ``perf``
1324    without the ``-b`` flag, you need to use ``--use_lbr=false`` when
1325    calling ``create_llvm_prof``.
1326
1327 4. Build the code again using the collected profile. This step feeds
1328    the profile back to the optimizers. This should result in a binary
1329    that executes faster than the original one. Note that you are not
1330    required to build the code with the exact same arguments that you
1331    used in the first step. The only requirement is that you build the code
1332    with ``-gline-tables-only`` and ``-fprofile-sample-use``.
1333
1334    .. code-block:: console
1335
1336      $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
1337
1338
1339 Sample Profile Formats
1340 """"""""""""""""""""""
1341
1342 Since external profilers generate profile data in a variety of custom formats,
1343 the data generated by the profiler must be converted into a format that can be
1344 read by the backend. LLVM supports three different sample profile formats:
1345
1346 1. ASCII text. This is the easiest one to generate. The file is divided into
1347    sections, which correspond to each of the functions with profile
1348    information. The format is described below.
1349
1350 2. Binary encoding. This uses a more efficient encoding that yields smaller
1351    profile files, which may be useful when generating large profiles. It can be
1352    generated from the text format using the ``llvm-profdata`` tool.
1353
1354 3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
1355    is only interesting in environments where GCC and Clang co-exist. Similarly
1356    to the binary encoding, it can be generated using the ``llvm-profdata`` tool.
1357
1358 If you are using Linux Perf to generate sampling profiles, you can use the
1359 conversion tool ``create_llvm_prof`` described in the previous section.
1360 Otherwise, you will need to write a conversion tool that converts your
1361 profiler's native format into one of these three.
1362
1363
1364 Sample Profile Text Format
1365 """"""""""""""""""""""""""
1366
1367 This section describes the ASCII text format for sampling profiles. It is,
1368 arguably, the easiest one to generate. If you are interested in generating any
1369 of the other two, consult the ``ProfileData`` library in in LLVM's source tree
1370 (specifically, ``llvm/lib/ProfileData/SampleProfWriter.cpp``).
1371
1372 .. code-block:: console
1373
1374     function1:total_samples:total_head_samples
1375     offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
1376     offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
1377     ...
1378     offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
1379
1380 The file may contain blank lines between sections and within a
1381 section. However, the spacing within a single line is fixed. Additional
1382 spaces will result in an error while reading the file.
1383
1384 Function names must be mangled in order for the profile loader to
1385 match them in the current translation unit. The two numbers in the
1386 function header specify how many total samples were accumulated in the
1387 function (first number), and the total number of samples accumulated
1388 in the prologue of the function (second number). This head sample
1389 count provides an indicator of how frequently the function is invoked.
1390
1391 Each sampled line may contain several items. Some are optional (marked
1392 below):
1393
1394 a. Source line offset. This number represents the line number
1395    in the function where the sample was collected. The line number is
1396    always relative to the line where symbol of the function is
1397    defined. So, if the function has its header at line 280, the offset
1398    13 is at line 293 in the file.
1399
1400    Note that this offset should never be a negative number. This could
1401    happen in cases like macros. The debug machinery will register the
1402    line number at the point of macro expansion. So, if the macro was
1403    expanded in a line before the start of the function, the profile
1404    converter should emit a 0 as the offset (this means that the optimizers
1405    will not be able to associate a meaningful weight to the instructions
1406    in the macro).
1407
1408 b. [OPTIONAL] Discriminator. This is used if the sampled program
1409    was compiled with DWARF discriminator support
1410    (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
1411    DWARF discriminators are unsigned integer values that allow the
1412    compiler to distinguish between multiple execution paths on the
1413    same source line location.
1414
1415    For example, consider the line of code ``if (cond) foo(); else bar();``.
1416    If the predicate ``cond`` is true 80% of the time, then the edge
1417    into function ``foo`` should be considered to be taken most of the
1418    time. But both calls to ``foo`` and ``bar`` are at the same source
1419    line, so a sample count at that line is not sufficient. The
1420    compiler needs to know which part of that line is taken more
1421    frequently.
1422
1423    This is what discriminators provide. In this case, the calls to
1424    ``foo`` and ``bar`` will be at the same line, but will have
1425    different discriminator values. This allows the compiler to correctly
1426    set edge weights into ``foo`` and ``bar``.
1427
1428 c. Number of samples. This is an integer quantity representing the
1429    number of samples collected by the profiler at this source
1430    location.
1431
1432 d. [OPTIONAL] Potential call targets and samples. If present, this
1433    line contains a call instruction. This models both direct and
1434    number of samples. For example,
1435
1436    .. code-block:: console
1437
1438      130: 7  foo:3  bar:2  baz:7
1439
1440    The above means that at relative line offset 130 there is a call
1441    instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
1442    with ``baz()`` being the relatively more frequently called target.
1443
1444
1445 Profiling with Instrumentation
1446 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1447
1448 Clang also supports profiling via instrumentation. This requires building a
1449 special instrumented version of the code and has some runtime
1450 overhead during the profiling, but it provides more detailed results than a
1451 sampling profiler. It also provides reproducible results, at least to the
1452 extent that the code behaves consistently across runs.
1453
1454 Here are the steps for using profile guided optimization with
1455 instrumentation:
1456
1457 1. Build an instrumented version of the code by compiling and linking with the
1458    ``-fprofile-instr-generate`` option.
1459
1460    .. code-block:: console
1461
1462      $ clang++ -O2 -fprofile-instr-generate code.cc -o code
1463
1464 2. Run the instrumented executable with inputs that reflect the typical usage.
1465    By default, the profile data will be written to a ``default.profraw`` file
1466    in the current directory. You can override that default by setting the
1467    ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file.
1468    Any instance of ``%p`` in that file name will be replaced by the process
1469    ID, so that you can easily distinguish the profile output from multiple
1470    runs.
1471
1472    .. code-block:: console
1473
1474      $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
1475
1476 3. Combine profiles from multiple runs and convert the "raw" profile format to
1477    the input expected by clang. Use the ``merge`` command of the
1478    ``llvm-profdata`` tool to do this.
1479
1480    .. code-block:: console
1481
1482      $ llvm-profdata merge -output=code.profdata code-*.profraw
1483
1484    Note that this step is necessary even when there is only one "raw" profile,
1485    since the merge operation also changes the file format.
1486
1487 4. Build the code again using the ``-fprofile-instr-use`` option to specify the
1488    collected profile data.
1489
1490    .. code-block:: console
1491
1492      $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
1493
1494    You can repeat step 4 as often as you like without regenerating the
1495    profile. As you make changes to your code, clang may no longer be able to
1496    use the profile data. It will warn you when this happens.
1497
1498 Profile generation and use can also be controlled by the GCC-compatible flags
1499 ``-fprofile-generate`` and ``-fprofile-use``. Although these flags are
1500 semantically equivalent to their GCC counterparts, they *do not* handle
1501 GCC-compatible profiles. They are only meant to implement GCC's semantics
1502 with respect to profile creation and use.
1503
1504 .. option:: -fprofile-generate[=<dirname>]
1505
1506   Without any other arguments, ``-fprofile-generate`` behaves identically to
1507   ``-fprofile-instr-generate``. When given a directory name, it generates the
1508   profile file ``default.profraw`` in the directory named ``dirname``. If
1509   ``dirname`` does not exist, it will be created at runtime. The environment
1510   variable ``LLVM_PROFILE_FILE`` can be used to override the directory and
1511   filename for the profile file at runtime. For example,
1512
1513   .. code-block:: console
1514
1515     $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
1516
1517   When ``code`` is executed, the profile will be written to the file
1518   ``yyy/zzz/default.profraw``. This can be altered at runtime via the
1519   ``LLVM_PROFILE_FILE`` environment variable:
1520
1521   .. code-block:: console
1522
1523     $ LLVM_PROFILE_FILE=/tmp/myprofile/code.profraw ./code
1524
1525   The above invocation will produce the profile file
1526   ``/tmp/myprofile/code.profraw`` instead of ``yyy/zzz/default.profraw``.
1527   Notice that ``LLVM_PROFILE_FILE`` overrides the directory *and* the file
1528   name for the profile file.
1529
1530 .. option:: -fprofile-use[=<pathname>]
1531
1532   Without any other arguments, ``-fprofile-use`` behaves identically to
1533   ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a
1534   profile file, it reads from that file. If ``pathname`` is a directory name,
1535   it reads from ``pathname/default.profdata``.
1536
1537
1538 Controlling Size of Debug Information
1539 -------------------------------------
1540
1541 Debug info kind generated by Clang can be set by one of the flags listed
1542 below. If multiple flags are present, the last one is used.
1543
1544 .. option:: -g0
1545
1546   Don't generate any debug info (default).
1547
1548 .. option:: -gline-tables-only
1549
1550   Generate line number tables only.
1551
1552   This kind of debug info allows to obtain stack traces with function names,
1553   file names and line numbers (by such tools as ``gdb`` or ``addr2line``).  It
1554   doesn't contain any other data (e.g. description of local variables or
1555   function parameters).
1556
1557 .. option:: -fstandalone-debug
1558
1559   Clang supports a number of optimizations to reduce the size of debug
1560   information in the binary. They work based on the assumption that
1561   the debug type information can be spread out over multiple
1562   compilation units.  For instance, Clang will not emit type
1563   definitions for types that are not needed by a module and could be
1564   replaced with a forward declaration.  Further, Clang will only emit
1565   type info for a dynamic C++ class in the module that contains the
1566   vtable for the class.
1567
1568   The **-fstandalone-debug** option turns off these optimizations.
1569   This is useful when working with 3rd-party libraries that don't come
1570   with debug information.  Note that Clang will never emit type
1571   information for types that are not referenced at all by the program.
1572
1573 .. option:: -fno-standalone-debug
1574
1575    On Darwin **-fstandalone-debug** is enabled by default. The
1576    **-fno-standalone-debug** option can be used to get to turn on the
1577    vtable-based optimization described above.
1578
1579 .. option:: -g
1580
1581   Generate complete debug info.
1582
1583 Comment Parsing Options
1584 -----------------------
1585
1586 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
1587 them to the appropriate declaration nodes.  By default, it only parses
1588 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
1589 ``/*``.
1590
1591 .. option:: -Wdocumentation
1592
1593   Emit warnings about use of documentation comments.  This warning group is off
1594   by default.
1595
1596   This includes checking that ``\param`` commands name parameters that actually
1597   present in the function signature, checking that ``\returns`` is used only on
1598   functions that actually return a value etc.
1599
1600 .. option:: -Wno-documentation-unknown-command
1601
1602   Don't warn when encountering an unknown Doxygen command.
1603
1604 .. option:: -fparse-all-comments
1605
1606   Parse all comments as documentation comments (including ordinary comments
1607   starting with ``//`` and ``/*``).
1608
1609 .. option:: -fcomment-block-commands=[commands]
1610
1611   Define custom documentation commands as block commands.  This allows Clang to
1612   construct the correct AST for these custom commands, and silences warnings
1613   about unknown commands.  Several commands must be separated by a comma
1614   *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
1615   custom commands ``\foo`` and ``\bar``.
1616
1617   It is also possible to use ``-fcomment-block-commands`` several times; e.g.
1618   ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
1619   as above.
1620
1621 .. _c:
1622
1623 C Language Features
1624 ===================
1625
1626 The support for standard C in clang is feature-complete except for the
1627 C99 floating-point pragmas.
1628
1629 Extensions supported by clang
1630 -----------------------------
1631
1632 See :doc:`LanguageExtensions`.
1633
1634 Differences between various standard modes
1635 ------------------------------------------
1636
1637 clang supports the -std option, which changes what language mode clang
1638 uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11,
1639 gnu11, and various aliases for those modes. If no -std option is
1640 specified, clang defaults to gnu11 mode. Many C99 and C11 features are
1641 supported in earlier modes as a conforming extension, with a warning. Use
1642 ``-pedantic-errors`` to request an error if a feature from a later standard
1643 revision is used in an earlier mode.
1644
1645 Differences between all ``c*`` and ``gnu*`` modes:
1646
1647 -  ``c*`` modes define "``__STRICT_ANSI__``".
1648 -  Target-specific defines not prefixed by underscores, like "linux",
1649    are defined in ``gnu*`` modes.
1650 -  Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
1651    the -trigraphs option.
1652 -  The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
1653    the variants "``__asm__``" and "``__typeof__``" are recognized in all
1654    modes.
1655 -  The Apple "blocks" extension is recognized by default in ``gnu*`` modes
1656    on some platforms; it can be enabled in any mode with the "-fblocks"
1657    option.
1658 -  Arrays that are VLA's according to the standard, but which can be
1659    constant folded by the frontend are treated as fixed size arrays.
1660    This occurs for things like "int X[(1, 2)];", which is technically a
1661    VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
1662
1663 Differences between ``*89`` and ``*99`` modes:
1664
1665 -  The ``*99`` modes default to implementing "inline" as specified in C99,
1666    while the ``*89`` modes implement the GNU version. This can be
1667    overridden for individual functions with the ``__gnu_inline__``
1668    attribute.
1669 -  Digraphs are not recognized in c89 mode.
1670 -  The scope of names defined inside a "for", "if", "switch", "while",
1671    or "do" statement is different. (example: "``if ((struct x {int
1672    x;}*)0) {}``".)
1673 -  ``__STDC_VERSION__`` is not defined in ``*89`` modes.
1674 -  "inline" is not recognized as a keyword in c89 mode.
1675 -  "restrict" is not recognized as a keyword in ``*89`` modes.
1676 -  Commas are allowed in integer constant expressions in ``*99`` modes.
1677 -  Arrays which are not lvalues are not implicitly promoted to pointers
1678    in ``*89`` modes.
1679 -  Some warnings are different.
1680
1681 Differences between ``*99`` and ``*11`` modes:
1682
1683 -  Warnings for use of C11 features are disabled.
1684 -  ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``.
1685
1686 c94 mode is identical to c89 mode except that digraphs are enabled in
1687 c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
1688
1689 GCC extensions not implemented yet
1690 ----------------------------------
1691
1692 clang tries to be compatible with gcc as much as possible, but some gcc
1693 extensions are not implemented yet:
1694
1695 -  clang does not support #pragma weak (`bug
1696    3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses
1697    described in the bug, this is likely to be implemented at some point,
1698    at least partially.
1699 -  clang does not support decimal floating point types (``_Decimal32`` and
1700    friends) or fixed-point types (``_Fract`` and friends); nobody has
1701    expressed interest in these features yet, so it's hard to say when
1702    they will be implemented.
1703 -  clang does not support nested functions; this is a complex feature
1704    which is infrequently used, so it is unlikely to be implemented
1705    anytime soon. In C++11 it can be emulated by assigning lambda
1706    functions to local variables, e.g:
1707
1708    .. code-block:: cpp
1709
1710      auto const local_function = [&](int parameter) {
1711        // Do something
1712      };
1713      ...
1714      local_function(1);
1715
1716 -  clang does not support global register variables; this is unlikely to
1717    be implemented soon because it requires additional LLVM backend
1718    support.
1719 -  clang does not support static initialization of flexible array
1720    members. This appears to be a rarely used extension, but could be
1721    implemented pending user demand.
1722 -  clang does not support
1723    ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
1724    used rarely, but in some potentially interesting places, like the
1725    glibc headers, so it may be implemented pending user demand. Note
1726    that because clang pretends to be like GCC 4.2, and this extension
1727    was introduced in 4.3, the glibc headers will not try to use this
1728    extension with clang at the moment.
1729 -  clang does not support the gcc extension for forward-declaring
1730    function parameters; this has not shown up in any real-world code
1731    yet, though, so it might never be implemented.
1732
1733 This is not a complete list; if you find an unsupported extension
1734 missing from this list, please send an e-mail to cfe-dev. This list
1735 currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
1736 list does not include bugs in mostly-implemented features; please see
1737 the `bug
1738 tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
1739 for known existing bugs (FIXME: Is there a section for bug-reporting
1740 guidelines somewhere?).
1741
1742 Intentionally unsupported GCC extensions
1743 ----------------------------------------
1744
1745 -  clang does not support the gcc extension that allows variable-length
1746    arrays in structures. This is for a few reasons: one, it is tricky to
1747    implement, two, the extension is completely undocumented, and three,
1748    the extension appears to be rarely used. Note that clang *does*
1749    support flexible array members (arrays with a zero or unspecified
1750    size at the end of a structure).
1751 -  clang does not have an equivalent to gcc's "fold"; this means that
1752    clang doesn't accept some constructs gcc might accept in contexts
1753    where a constant expression is required, like "x-x" where x is a
1754    variable.
1755 -  clang does not support ``__builtin_apply`` and friends; this extension
1756    is extremely obscure and difficult to implement reliably.
1757
1758 .. _c_ms:
1759
1760 Microsoft extensions
1761 --------------------
1762
1763 clang has some experimental support for extensions from Microsoft Visual
1764 C++; to enable it, use the ``-fms-extensions`` command-line option. This is
1765 the default for Windows targets. Note that the support is incomplete.
1766 Some constructs such as ``dllexport`` on classes are ignored with a warning,
1767 and others such as `Microsoft IDL annotations
1768 <http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx>`_ are silently
1769 ignored.
1770
1771 clang has a ``-fms-compatibility`` flag that makes clang accept enough
1772 invalid C++ to be able to parse most Microsoft headers. For example, it
1773 allows `unqualified lookup of dependent base class members
1774 <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
1775 a common compatibility issue with clang. This flag is enabled by default
1776 for Windows targets.
1777
1778 ``-fdelayed-template-parsing`` lets clang delay parsing of function template
1779 definitions until the end of a translation unit. This flag is enabled by
1780 default for Windows targets.
1781
1782 -  clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to
1783    1700 which is the same as Visual C/C++ 2012. Any number is supported
1784    and can greatly affect what Windows SDK and c++stdlib headers clang
1785    can compile.
1786 -  clang does not support the Microsoft extension where anonymous record
1787    members can be declared using user defined typedefs.
1788 -  clang supports the Microsoft ``#pragma pack`` feature for controlling
1789    record layout. GCC also contains support for this feature, however
1790    where MSVC and GCC are incompatible clang follows the MSVC
1791    definition.
1792 -  clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for
1793    automatically linking against the specified library.  Currently this feature
1794    only works with the Visual C++ linker.
1795 -  clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature
1796    for adding linker flags to COFF object files.  The user is responsible for
1797    ensuring that the linker understands the flags.
1798 -  clang defaults to C++11 for Windows targets.
1799
1800 .. _cxx:
1801
1802 C++ Language Features
1803 =====================
1804
1805 clang fully implements all of standard C++98 except for exported
1806 templates (which were removed in C++11), and all of standard C++11
1807 and the current draft standard for C++1y.
1808
1809 Controlling implementation limits
1810 ---------------------------------
1811
1812 .. option:: -fbracket-depth=N
1813
1814   Sets the limit for nested parentheses, brackets, and braces to N.  The
1815   default is 256.
1816
1817 .. option:: -fconstexpr-depth=N
1818
1819   Sets the limit for recursive constexpr function invocations to N.  The
1820   default is 512.
1821
1822 .. option:: -ftemplate-depth=N
1823
1824   Sets the limit for recursively nested template instantiations to N.  The
1825   default is 256.
1826
1827 .. option:: -foperator-arrow-depth=N
1828
1829   Sets the limit for iterative calls to 'operator->' functions to N.  The
1830   default is 256.
1831
1832 .. _objc:
1833
1834 Objective-C Language Features
1835 =============================
1836
1837 .. _objcxx:
1838
1839 Objective-C++ Language Features
1840 ===============================
1841
1842
1843 .. _target_features:
1844
1845 Target-Specific Features and Limitations
1846 ========================================
1847
1848 CPU Architectures Features and Limitations
1849 ------------------------------------------
1850
1851 X86
1852 ^^^
1853
1854 The support for X86 (both 32-bit and 64-bit) is considered stable on
1855 Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
1856 to correctly compile many large C, C++, Objective-C, and Objective-C++
1857 codebases.
1858
1859 On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
1860 Microsoft x64 calling convention. You might need to tweak
1861 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
1862
1863 For the X86 target, clang supports the :option:`-m16` command line
1864 argument which enables 16-bit code output. This is broadly similar to
1865 using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
1866 and the ABI remains 32-bit but the assembler emits instructions
1867 appropriate for a CPU running in 16-bit mode, with address-size and
1868 operand-size prefixes to enable 32-bit addressing and operations.
1869
1870 ARM
1871 ^^^
1872
1873 The support for ARM (specifically ARMv6 and ARMv7) is considered stable
1874 on Darwin (iOS): it has been tested to correctly compile many large C,
1875 C++, Objective-C, and Objective-C++ codebases. Clang only supports a
1876 limited number of ARM architectures. It does not yet fully support
1877 ARMv5, for example.
1878
1879 PowerPC
1880 ^^^^^^^
1881
1882 The support for PowerPC (especially PowerPC64) is considered stable
1883 on Linux and FreeBSD: it has been tested to correctly compile many
1884 large C and C++ codebases. PowerPC (32bit) is still missing certain
1885 features (e.g. PIC code on ELF platforms).
1886
1887 Other platforms
1888 ^^^^^^^^^^^^^^^
1889
1890 clang currently contains some support for other architectures (e.g. Sparc);
1891 however, significant pieces of code generation are still missing, and they
1892 haven't undergone significant testing.
1893
1894 clang contains limited support for the MSP430 embedded processor, but
1895 both the clang support and the LLVM backend support are highly
1896 experimental.
1897
1898 Other platforms are completely unsupported at the moment. Adding the
1899 minimal support needed for parsing and semantic analysis on a new
1900 platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
1901 tree. This level of support is also sufficient for conversion to LLVM IR
1902 for simple programs. Proper support for conversion to LLVM IR requires
1903 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
1904 change soon, though. Generating assembly requires a suitable LLVM
1905 backend.
1906
1907 Operating System Features and Limitations
1908 -----------------------------------------
1909
1910 Darwin (Mac OS X)
1911 ^^^^^^^^^^^^^^^^^
1912
1913 Thread Sanitizer is not supported.
1914
1915 Windows
1916 ^^^^^^^
1917
1918 Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
1919 platforms.
1920
1921 See also :ref:`Microsoft Extensions <c_ms>`.
1922
1923 Cygwin
1924 """"""
1925
1926 Clang works on Cygwin-1.7.
1927
1928 MinGW32
1929 """""""
1930
1931 Clang works on some mingw32 distributions. Clang assumes directories as
1932 below;
1933
1934 -  ``C:/mingw/include``
1935 -  ``C:/mingw/lib``
1936 -  ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
1937
1938 On MSYS, a few tests might fail.
1939
1940 MinGW-w64
1941 """""""""
1942
1943 For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
1944 assumes as below;
1945
1946 -  ``GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)``
1947 -  ``some_directory/bin/gcc.exe``
1948 -  ``some_directory/bin/clang.exe``
1949 -  ``some_directory/bin/clang++.exe``
1950 -  ``some_directory/bin/../include/c++/GCC_version``
1951 -  ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
1952 -  ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
1953 -  ``some_directory/bin/../include/c++/GCC_version/backward``
1954 -  ``some_directory/bin/../x86_64-w64-mingw32/include``
1955 -  ``some_directory/bin/../i686-w64-mingw32/include``
1956 -  ``some_directory/bin/../include``
1957
1958 This directory layout is standard for any toolchain you will find on the
1959 official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
1960
1961 Clang expects the GCC executable "gcc.exe" compiled for
1962 ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
1963
1964 `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
1965 ``x86_64-w64-mingw32``.
1966
1967 .. _clang-cl:
1968
1969 clang-cl
1970 ========
1971
1972 clang-cl is an alternative command-line interface to Clang driver, designed for
1973 compatibility with the Visual C++ compiler, cl.exe.
1974
1975 To enable clang-cl to find system headers, libraries, and the linker when run
1976 from the command-line, it should be executed inside a Visual Studio Native Tools
1977 Command Prompt or a regular Command Prompt where the environment has been set
1978 up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
1979
1980 clang-cl can also be used from inside Visual Studio  by using an LLVM Platform
1981 Toolset.
1982
1983 Command-Line Options
1984 --------------------
1985
1986 To be compatible with cl.exe, clang-cl supports most of the same command-line
1987 options. Those options can start with either ``/`` or ``-``. It also supports
1988 some of Clang's core options, such as the ``-W`` options.
1989
1990 Options that are known to clang-cl, but not currently supported, are ignored
1991 with a warning. For example:
1992
1993   ::
1994
1995     clang-cl.exe: warning: argument unused during compilation: '/Zi'
1996
1997 To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
1998
1999 Options that are not known to clang-cl will cause errors. If they are spelled with a
2000 leading ``/``, they will be mistaken for a filename:
2001
2002   ::
2003
2004     clang-cl.exe: error: no such file or directory: '/foobar'
2005
2006 Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
2007 for any valid cl.exe flags that clang-cl does not understand.
2008
2009 Execute ``clang-cl /?`` to see a list of supported options:
2010
2011   ::
2012
2013     CL.EXE COMPATIBILITY OPTIONS:
2014       /?                     Display available options
2015       /arch:<value>          Set architecture for code generation
2016       /C                     Don't discard comments when preprocessing
2017       /c                     Compile only
2018       /D <macro[=value]>     Define macro
2019       /EH<value>             Exception handling model
2020       /EP                    Disable linemarker output and preprocess to stdout
2021       /E                     Preprocess to stdout
2022       /fallback              Fall back to cl.exe if clang-cl fails to compile
2023       /FA                    Output assembly code file during compilation
2024       /Fa<file or directory> Output assembly code to this file during compilation
2025       /Fe<file or directory> Set output executable file or directory (ends in / or \)
2026       /FI <value>            Include file before parsing
2027       /Fi<file>              Set preprocess output file name
2028       /Fo<file or directory> Set output object file, or directory (ends in / or \)
2029       /GF-                   Disable string pooling
2030       /GR-                   Disable emission of RTTI data
2031       /GR                    Enable emission of RTTI data
2032       /Gw-                   Don't put each data item in its own section
2033       /Gw                    Put each data item in its own section
2034       /Gy-                   Don't put each function in its own section
2035       /Gy                    Put each function in its own section
2036       /help                  Display available options
2037       /I <dir>               Add directory to include search path
2038       /J                     Make char type unsigned
2039       /LDd                   Create debug DLL
2040       /LD                    Create DLL
2041       /link <options>        Forward options to the linker
2042       /MDd                   Use DLL debug run-time
2043       /MD                    Use DLL run-time
2044       /MTd                   Use static debug run-time
2045       /MT                    Use static run-time
2046       /Ob0                   Disable inlining
2047       /Od                    Disable optimization
2048       /Oi-                   Disable use of builtin functions
2049       /Oi                    Enable use of builtin functions
2050       /Os                    Optimize for size
2051       /Ot                    Optimize for speed
2052       /Ox                    Maximum optimization
2053       /Oy-                   Disable frame pointer omission
2054       /Oy                    Enable frame pointer omission
2055       /O<n>                  Optimization level
2056       /P                     Preprocess to file
2057       /showIncludes          Print info about included files to stderr
2058       /TC                    Treat all source files as C
2059       /Tc <filename>         Specify a C source file
2060       /TP                    Treat all source files as C++
2061       /Tp <filename>         Specify a C++ source file
2062       /U <macro>             Undefine macro
2063       /vd<value>             Control vtordisp placement
2064       /vmb                   Use a best-case representation method for member pointers
2065       /vmg                   Use a most-general representation for member pointers
2066       /vmm                   Set the default most-general representation to multiple inheritance
2067       /vms                   Set the default most-general representation to single inheritance
2068       /vmv                   Set the default most-general representation to virtual inheritance
2069       /W0                    Disable all warnings
2070       /W1                    Enable -Wall
2071       /W2                    Enable -Wall
2072       /W3                    Enable -Wall
2073       /W4                    Enable -Wall
2074       /Wall                  Enable -Wall
2075       /WX-                   Do not treat warnings as errors
2076       /WX                    Treat warnings as errors
2077       /w                     Disable all warnings
2078       /Zi                    Enable debug information
2079       /Zp                    Set the default maximum struct packing alignment to 1
2080       /Zp<value>             Specify the default maximum struct packing alignment
2081       /Zs                    Syntax-check only
2082
2083     OPTIONS:
2084       -###                  Print (but do not run) the commands to run for this compilation
2085       -fms-compatibility-version=<value>
2086                             Dot-separated value representing the Microsoft compiler version
2087                             number to report in _MSC_VER (0 = don't define it (default))
2088       -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER (0 = don't
2089                             define it (default))
2090       -fsanitize-blacklist=<value>
2091                             Path to blacklist file for sanitizers
2092       -fsanitize=<check>    Enable runtime instrumentation for bug detection: address (memory
2093                             errors) | thread (race detection) | undefined (miscellaneous
2094                             undefined behavior)
2095       -mllvm <value>        Additional arguments to forward to LLVM's option processing
2096       -Qunused-arguments    Don't emit warning for unused driver arguments
2097       --target=<value>      Generate code for the given target
2098       -v                    Show commands to run and use verbose output
2099       -W<warning>           Enable the specified warning
2100       -Xclang <arg>         Pass <arg> to the clang compiler
2101
2102 The /fallback Option
2103 ^^^^^^^^^^^^^^^^^^^^
2104
2105 When clang-cl is run with the ``/fallback`` option, it will first try to
2106 compile files itself. For any file that it fails to compile, it will fall back
2107 and try to compile the file by invoking cl.exe.
2108
2109 This option is intended to be used as a temporary means to build projects where
2110 clang-cl cannot successfully compile all the files. clang-cl may fail to compile
2111 a file either because it cannot generate code for some C++ feature, or because
2112 it cannot parse some Microsoft language extension.