Home | History | Annotate | Download | only in docs
      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 `-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 `-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:`-Wextra-tokens` is ignored for only a single line
    715 of code, after which the diagnostics return to whatever state had previously
    716 existed.
    717 
    718 .. code-block:: c
    719 
    720   #if foo
    721   #endif foo // warning: extra tokens at end of #endif directive
    722 
    723   #pragma clang diagnostic ignored "-Wextra-tokens"
    724 
    725   #if foo
    726   #endif foo // no warning
    727 
    728   #pragma clang diagnostic pop
    729 
    730 The push and pop pragmas will save and restore the full diagnostic state
    731 of the compiler, regardless of how it was set. That means that it is
    732 possible to use push and pop around GCC compatible diagnostics and Clang
    733 will push and pop them appropriately, while GCC will ignore the pushes
    734 and pops as unknown pragmas. It should be noted that while Clang
    735 supports the GCC pragma, Clang and GCC do not support the exact same set
    736 of warnings, so even when using GCC compatible #pragmas there is no
    737 guarantee that they will have identical behaviour on both compilers.
    738 
    739 In addition to controlling warnings and errors generated by the compiler, it is
    740 possible to generate custom warning and error messages through the following
    741 pragmas:
    742 
    743 .. code-block:: c
    744 
    745   // The following will produce warning messages
    746   #pragma message "some diagnostic message"
    747   #pragma GCC warning "TODO: replace deprecated feature"
    748 
    749   // The following will produce an error message
    750   #pragma GCC error "Not supported"
    751 
    752 These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
    753 directives, except that they may also be embedded into preprocessor macros via
    754 the C99 ``_Pragma`` operator, for example:
    755 
    756 .. code-block:: c
    757 
    758   #define STR(X) #X
    759   #define DEFER(M,...) M(__VA_ARGS__)
    760   #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
    761 
    762   CUSTOM_ERROR("Feature not available");
    763 
    764 Controlling Diagnostics in System Headers
    765 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    766 
    767 Warnings are suppressed when they occur in system headers. By default,
    768 an included file is treated as a system header if it is found in an
    769 include path specified by ``-isystem``, but this can be overridden in
    770 several ways.
    771 
    772 The ``system_header`` pragma can be used to mark the current file as
    773 being a system header. No warnings will be produced from the location of
    774 the pragma onwards within the same file.
    775 
    776 .. code-block:: c
    777 
    778   #if foo
    779   #endif foo // warning: extra tokens at end of #endif directive
    780 
    781   #pragma clang system_header
    782 
    783   #if foo
    784   #endif foo // no warning
    785 
    786 The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=`
    787 command-line arguments can be used to override whether subsets of an include
    788 path are treated as system headers. When the name in a ``#include`` directive
    789 is found within a header search path and starts with a system prefix, the
    790 header is treated as a system header. The last prefix on the
    791 command-line which matches the specified header name takes precedence.
    792 For instance:
    793 
    794 .. code-block:: console
    795 
    796   $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
    797       --no-system-header-prefix=x/y/
    798 
    799 Here, ``#include "x/a.h"`` is treated as including a system header, even
    800 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
    801 as not including a system header, even if the header is found in
    802 ``bar``.
    803 
    804 A ``#include`` directive which finds a file relative to the current
    805 directory is treated as including a system header if the including file
    806 is treated as a system header.
    807 
    808 .. _diagnostics_enable_everything:
    809 
    810 Enabling All Diagnostics
    811 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    812 
    813 In addition to the traditional ``-W`` flags, one can enable **all**
    814 diagnostics by passing :option:`-Weverything`. This works as expected
    815 with
    816 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
    817 
    818 Note that when combined with :option:`-w` (which disables all warnings), that
    819 flag wins.
    820 
    821 Controlling Static Analyzer Diagnostics
    822 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    823 
    824 While not strictly part of the compiler, the diagnostics from Clang's
    825 `static analyzer <http://clang-analyzer.llvm.org>`_ can also be
    826 influenced by the user via changes to the source code. See the available
    827 `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
    828 analyzer's `FAQ
    829 page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
    830 information.
    831 
    832 .. _usersmanual-precompiled-headers:
    833 
    834 Precompiled Headers
    835 -------------------
    836 
    837 `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
    838 are a general approach employed by many compilers to reduce compilation
    839 time. The underlying motivation of the approach is that it is common for
    840 the same (and often large) header files to be included by multiple
    841 source files. Consequently, compile times can often be greatly improved
    842 by caching some of the (redundant) work done by a compiler to process
    843 headers. Precompiled header files, which represent one of many ways to
    844 implement this optimization, are literally files that represent an
    845 on-disk cache that contains the vital information necessary to reduce
    846 some of the work needed to process a corresponding header file. While
    847 details of precompiled headers vary between compilers, precompiled
    848 headers have been shown to be highly effective at speeding up program
    849 compilation on systems with very large system headers (e.g., Mac OS X).
    850 
    851 Generating a PCH File
    852 ^^^^^^^^^^^^^^^^^^^^^
    853 
    854 To generate a PCH file using Clang, one invokes Clang with the
    855 :option:`-x <language>-header` option. This mirrors the interface in GCC
    856 for generating PCH files:
    857 
    858 .. code-block:: console
    859 
    860   $ gcc -x c-header test.h -o test.h.gch
    861   $ clang -x c-header test.h -o test.h.pch
    862 
    863 Using a PCH File
    864 ^^^^^^^^^^^^^^^^
    865 
    866 A PCH file can then be used as a prefix header when a :option:`-include`
    867 option is passed to ``clang``:
    868 
    869 .. code-block:: console
    870 
    871   $ clang -include test.h test.c -o test
    872 
    873 The ``clang`` driver will first check if a PCH file for ``test.h`` is
    874 available; if so, the contents of ``test.h`` (and the files it includes)
    875 will be processed from the PCH file. Otherwise, Clang falls back to
    876 directly processing the content of ``test.h``. This mirrors the behavior
    877 of GCC.
    878 
    879 .. note::
    880 
    881   Clang does *not* automatically use PCH files for headers that are directly
    882   included within a source file. For example:
    883 
    884   .. code-block:: console
    885 
    886     $ clang -x c-header test.h -o test.h.pch
    887     $ cat test.c
    888     #include "test.h"
    889     $ clang test.c -o test
    890 
    891   In this example, ``clang`` will not automatically use the PCH file for
    892   ``test.h`` since ``test.h`` was included directly in the source file and not
    893   specified on the command line using :option:`-include`.
    894 
    895 Relocatable PCH Files
    896 ^^^^^^^^^^^^^^^^^^^^^
    897 
    898 It is sometimes necessary to build a precompiled header from headers
    899 that are not yet in their final, installed locations. For example, one
    900 might build a precompiled header within the build tree that is then
    901 meant to be installed alongside the headers. Clang permits the creation
    902 of "relocatable" precompiled headers, which are built with a given path
    903 (into the build directory) and can later be used from an installed
    904 location.
    905 
    906 To build a relocatable precompiled header, place your headers into a
    907 subdirectory whose structure mimics the installed location. For example,
    908 if you want to build a precompiled header for the header ``mylib.h``
    909 that will be installed into ``/usr/include``, create a subdirectory
    910 ``build/usr/include`` and place the header ``mylib.h`` into that
    911 subdirectory. If ``mylib.h`` depends on other headers, then they can be
    912 stored within ``build/usr/include`` in a way that mimics the installed
    913 location.
    914 
    915 Building a relocatable precompiled header requires two additional
    916 arguments. First, pass the ``--relocatable-pch`` flag to indicate that
    917 the resulting PCH file should be relocatable. Second, pass
    918 :option:`-isysroot /path/to/build`, which makes all includes for your library
    919 relative to the build directory. For example:
    920 
    921 .. code-block:: console
    922 
    923   # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
    924 
    925 When loading the relocatable PCH file, the various headers used in the
    926 PCH file are found from the system header root. For example, ``mylib.h``
    927 can be found in ``/usr/include/mylib.h``. If the headers are installed
    928 in some other system root, the :option:`-isysroot` option can be used provide
    929 a different system root from which the headers will be based. For
    930 example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
    931 ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
    932 
    933 Relocatable precompiled headers are intended to be used in a limited
    934 number of cases where the compilation environment is tightly controlled
    935 and the precompiled header cannot be generated after headers have been
    936 installed.
    937 
    938 .. _controlling-code-generation:
    939 
    940 Controlling Code Generation
    941 ---------------------------
    942 
    943 Clang provides a number of ways to control code generation. The options
    944 are listed below.
    945 
    946 **-f[no-]sanitize=check1,check2,...**
    947    Turn on runtime checks for various forms of undefined or suspicious
    948    behavior.
    949 
    950    This option controls whether Clang adds runtime checks for various
    951    forms of undefined or suspicious behavior, and is disabled by
    952    default. If a check fails, a diagnostic message is produced at
    953    runtime explaining the problem. The main checks are:
    954 
    955    -  .. _opt_fsanitize_address:
    956 
    957       ``-fsanitize=address``:
    958       :doc:`AddressSanitizer`, a memory error
    959       detector.
    960    -  .. _opt_fsanitize_thread:
    961 
    962       ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
    963    -  .. _opt_fsanitize_memory:
    964 
    965       ``-fsanitize=memory``: :doc:`MemorySanitizer`,
    966       a detector of uninitialized reads. Requires instrumentation of all
    967       program code.
    968    -  .. _opt_fsanitize_undefined:
    969 
    970       ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`,
    971       a fast and compatible undefined behavior checker.
    972 
    973    -  ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
    974       flow analysis.
    975    -  ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>`
    976       checks. Requires ``-flto``.
    977    -  ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>`
    978       protection against stack-based memory corruption errors.
    979 
    980    There are more fine-grained checks available: see
    981    the :ref:`list <ubsan-checks>` of specific kinds of
    982    undefined behavior that can be detected and the :ref:`list <cfi-schemes>`
    983    of control flow integrity schemes.
    984 
    985    The ``-fsanitize=`` argument must also be provided when linking, in
    986    order to link to the appropriate runtime library.
    987 
    988    It is not possible to combine more than one of the ``-fsanitize=address``,
    989    ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
    990    program.
    991 
    992 **-f[no-]sanitize-recover=check1,check2,...**
    993 
    994 **-f[no-]sanitize-recover=all**
    995 
    996    Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
    997    If the check is fatal, program will halt after the first error
    998    of this kind is detected and error report is printed.
    999 
   1000    By default, non-fatal checks are those enabled by
   1001    :doc:`UndefinedBehaviorSanitizer`,
   1002    except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some
   1003    sanitizers may not support recovery (or not support it by default
   1004    e.g. :doc:`AddressSanitizer`), and always crash the program after the issue
   1005    is detected.
   1006 
   1007    Note that the ``-fsanitize-trap`` flag has precedence over this flag.
   1008    This means that if a check has been configured to trap elsewhere on the
   1009    command line, or if the check traps by default, this flag will not have
   1010    any effect unless that sanitizer's trapping behavior is disabled with
   1011    ``-fno-sanitize-trap``.
   1012 
   1013    For example, if a command line contains the flags ``-fsanitize=undefined
   1014    -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment``
   1015    will have no effect on its own; it will need to be accompanied by
   1016    ``-fno-sanitize-trap=alignment``.
   1017 
   1018 **-f[no-]sanitize-trap=check1,check2,...**
   1019 
   1020    Controls which checks enabled by the ``-fsanitize=`` flag trap. This
   1021    option is intended for use in cases where the sanitizer runtime cannot
   1022    be used (for instance, when building libc or a kernel module), or where
   1023    the binary size increase caused by the sanitizer runtime is a concern.
   1024 
   1025    This flag is only compatible with :doc:`control flow integrity
   1026    <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer`
   1027    checks other than ``vptr``. If this flag
   1028    is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer
   1029    will be implicitly disabled.
   1030 
   1031    This flag is enabled by default for sanitizers in the ``cfi`` group.
   1032 
   1033 .. option:: -fsanitize-blacklist=/path/to/blacklist/file
   1034 
   1035    Disable or modify sanitizer checks for objects (source files, functions,
   1036    variables, types) listed in the file. See
   1037    :doc:`SanitizerSpecialCaseList` for file format description.
   1038 
   1039 .. option:: -fno-sanitize-blacklist
   1040 
   1041    Don't use blacklist file, if it was specified earlier in the command line.
   1042 
   1043 **-f[no-]sanitize-coverage=[type,features,...]**
   1044 
   1045    Enable simple code coverage in addition to certain sanitizers.
   1046    See :doc:`SanitizerCoverage` for more details.
   1047 
   1048 **-f[no-]sanitize-stats**
   1049 
   1050    Enable simple statistics gathering for the enabled sanitizers.
   1051    See :doc:`SanitizerStats` for more details.
   1052 
   1053 .. option:: -fsanitize-undefined-trap-on-error
   1054 
   1055    Deprecated alias for ``-fsanitize-trap=undefined``.
   1056 
   1057 .. option:: -fsanitize-cfi-cross-dso
   1058 
   1059    Enable cross-DSO control flow integrity checks. This flag modifies
   1060    the behavior of sanitizers in the ``cfi`` group to allow checking
   1061    of cross-DSO virtual and indirect calls.
   1062 
   1063 .. option:: -ffast-math
   1064 
   1065    Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor
   1066    macro, and lets the compiler make aggressive, potentially-lossy assumptions
   1067    about floating-point math.  These include:
   1068 
   1069    * Floating-point math obeys regular algebraic rules for real numbers (e.g.
   1070      ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and
   1071      ``(a + b) * c == a * c + b * c``),
   1072    * operands to floating-point operations are not equal to ``NaN`` and
   1073      ``Inf``, and
   1074    * ``+0`` and ``-0`` are interchangeable.
   1075 
   1076 .. option:: -fwhole-program-vtables
   1077 
   1078    Enable whole-program vtable optimizations, such as single-implementation
   1079    devirtualization and virtual constant propagation, for classes with
   1080    :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``.
   1081 
   1082 .. option:: -fno-assume-sane-operator-new
   1083 
   1084    Don't assume that the C++'s new operator is sane.
   1085 
   1086    This option tells the compiler to do not assume that C++'s global
   1087    new operator will always return a pointer that does not alias any
   1088    other pointer when the function returns.
   1089 
   1090 .. option:: -ftrap-function=[name]
   1091 
   1092    Instruct code generator to emit a function call to the specified
   1093    function name for ``__builtin_trap()``.
   1094 
   1095    LLVM code generator translates ``__builtin_trap()`` to a trap
   1096    instruction if it is supported by the target ISA. Otherwise, the
   1097    builtin is translated into a call to ``abort``. If this option is
   1098    set, then the code generator will always lower the builtin to a call
   1099    to the specified function regardless of whether the target ISA has a
   1100    trap instruction. This option is useful for environments (e.g.
   1101    deeply embedded) where a trap cannot be properly handled, or when
   1102    some custom behavior is desired.
   1103 
   1104 .. option:: -ftls-model=[model]
   1105 
   1106    Select which TLS model to use.
   1107 
   1108    Valid values are: ``global-dynamic``, ``local-dynamic``,
   1109    ``initial-exec`` and ``local-exec``. The default value is
   1110    ``global-dynamic``. The compiler may use a different model if the
   1111    selected model is not supported by the target, or if a more
   1112    efficient model can be used. The TLS model can be overridden per
   1113    variable using the ``tls_model`` attribute.
   1114 
   1115 .. option:: -femulated-tls
   1116 
   1117    Select emulated TLS model, which overrides all -ftls-model choices.
   1118 
   1119    In emulated TLS mode, all access to TLS variables are converted to
   1120    calls to __emutls_get_address in the runtime library.
   1121 
   1122 .. option:: -mhwdiv=[values]
   1123 
   1124    Select the ARM modes (arm or thumb) that support hardware division
   1125    instructions.
   1126 
   1127    Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
   1128    This option is used to indicate which mode (arm or thumb) supports
   1129    hardware division instructions. This only applies to the ARM
   1130    architecture.
   1131 
   1132 .. option:: -m[no-]crc
   1133 
   1134    Enable or disable CRC instructions.
   1135 
   1136    This option is used to indicate whether CRC instructions are to
   1137    be generated. This only applies to the ARM architecture.
   1138 
   1139    CRC instructions are enabled by default on ARMv8.
   1140 
   1141 .. option:: -mgeneral-regs-only
   1142 
   1143    Generate code which only uses the general purpose registers.
   1144 
   1145    This option restricts the generated code to use general registers
   1146    only. This only applies to the AArch64 architecture.
   1147 
   1148 .. option:: -mcompact-branches=[values]
   1149 
   1150    Control the usage of compact branches for MIPSR6.
   1151 
   1152    Valid values are: ``never``, ``optimal`` and ``always``.
   1153    The default value is ``optimal`` which generates compact branches
   1154    when a delay slot cannot be filled. ``never`` disables the usage of
   1155    compact branches and ``always`` generates compact branches whenever
   1156    possible.
   1157 
   1158 **-f[no-]max-type-align=[number]**
   1159    Instruct the code generator to not enforce a higher alignment than the given
   1160    number (of bytes) when accessing memory via an opaque pointer or reference.
   1161    This cap is ignored when directly accessing a variable or when the pointee
   1162    type has an explicit aligned attribute.
   1163 
   1164    The value should usually be determined by the properties of the system allocator.
   1165    Some builtin types, especially vector types, have very high natural alignments;
   1166    when working with values of those types, Clang usually wants to use instructions
   1167    that take advantage of that alignment.  However, many system allocators do
   1168    not promise to return memory that is more than 8-byte or 16-byte-aligned.  Use
   1169    this option to limit the alignment that the compiler can assume for an arbitrary
   1170    pointer, which may point onto the heap.
   1171 
   1172    This option does not affect the ABI alignment of types; the layout of structs and
   1173    unions and the value returned by the alignof operator remain the same.
   1174 
   1175    This option can be overridden on a case-by-case basis by putting an explicit
   1176    aligned alignment on a struct, union, or typedef.  For example:
   1177 
   1178    .. code-block:: console
   1179 
   1180       #include <immintrin.h>
   1181       // Make an aligned typedef of the AVX-512 16-int vector type.
   1182       typedef __v16si __aligned_v16si __attribute__((aligned(64)));
   1183 
   1184       void initialize_vector(__aligned_v16si *v) {
   1185         // The compiler may assume that v is 64-byte aligned, regardless of the
   1186         // value of -fmax-type-align.
   1187       }
   1188 
   1189 
   1190 Profile Guided Optimization
   1191 ---------------------------
   1192 
   1193 Profile information enables better optimization. For example, knowing that a
   1194 branch is taken very frequently helps the compiler make better decisions when
   1195 ordering basic blocks. Knowing that a function ``foo`` is called more
   1196 frequently than another function ``bar`` helps the inliner.
   1197 
   1198 Clang supports profile guided optimization with two different kinds of
   1199 profiling. A sampling profiler can generate a profile with very low runtime
   1200 overhead, or you can build an instrumented version of the code that collects
   1201 more detailed profile information. Both kinds of profiles can provide execution
   1202 counts for instructions in the code and information on branches taken and
   1203 function invocation.
   1204 
   1205 Regardless of which kind of profiling you use, be careful to collect profiles
   1206 by running your code with inputs that are representative of the typical
   1207 behavior. Code that is not exercised in the profile will be optimized as if it
   1208 is unimportant, and the compiler may make poor optimization choices for code
   1209 that is disproportionately used while profiling.
   1210 
   1211 Differences Between Sampling and Instrumentation
   1212 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1213 
   1214 Although both techniques are used for similar purposes, there are important
   1215 differences between the two:
   1216 
   1217 1. Profile data generated with one cannot be used by the other, and there is no
   1218    conversion tool that can convert one to the other. So, a profile generated
   1219    via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``.
   1220    Similarly, sampling profiles generated by external profilers must be
   1221    converted and used with ``-fprofile-sample-use``.
   1222 
   1223 2. Instrumentation profile data can be used for code coverage analysis and
   1224    optimization.
   1225 
   1226 3. Sampling profiles can only be used for optimization. They cannot be used for
   1227    code coverage analysis. Although it would be technically possible to use
   1228    sampling profiles for code coverage, sample-based profiles are too
   1229    coarse-grained for code coverage purposes; it would yield poor results.
   1230 
   1231 4. Sampling profiles must be generated by an external tool. The profile
   1232    generated by that tool must then be converted into a format that can be read
   1233    by LLVM. The section on sampling profilers describes one of the supported
   1234    sampling profile formats.
   1235 
   1236 
   1237 Using Sampling Profilers
   1238 ^^^^^^^^^^^^^^^^^^^^^^^^
   1239 
   1240 Sampling profilers are used to collect runtime information, such as
   1241 hardware counters, while your application executes. They are typically
   1242 very efficient and do not incur a large runtime overhead. The
   1243 sample data collected by the profiler can be used during compilation
   1244 to determine what the most executed areas of the code are.
   1245 
   1246 Using the data from a sample profiler requires some changes in the way
   1247 a program is built. Before the compiler can use profiling information,
   1248 the code needs to execute under the profiler. The following is the
   1249 usual build cycle when using sample profilers for optimization:
   1250 
   1251 1. Build the code with source line table information. You can use all the
   1252    usual build flags that you always build your application with. The only
   1253    requirement is that you add ``-gline-tables-only`` or ``-g`` to the
   1254    command line. This is important for the profiler to be able to map
   1255    instructions back to source line locations.
   1256 
   1257    .. code-block:: console
   1258 
   1259      $ clang++ -O2 -gline-tables-only code.cc -o code
   1260 
   1261 2. Run the executable under a sampling profiler. The specific profiler
   1262    you use does not really matter, as long as its output can be converted
   1263    into the format that the LLVM optimizer understands. Currently, there
   1264    exists a conversion tool for the Linux Perf profiler
   1265    (https://perf.wiki.kernel.org/), so these examples assume that you
   1266    are using Linux Perf to profile your code.
   1267 
   1268    .. code-block:: console
   1269 
   1270      $ perf record -b ./code
   1271 
   1272    Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
   1273    Record (LBR) to record call chains. While this is not strictly required,
   1274    it provides better call information, which improves the accuracy of
   1275    the profile data.
   1276 
   1277 3. Convert the collected profile data to LLVM's sample profile format.
   1278    This is currently supported via the AutoFDO converter ``create_llvm_prof``.
   1279    It is available at http://github.com/google/autofdo. Once built and
   1280    installed, you can convert the ``perf.data`` file to LLVM using
   1281    the command:
   1282 
   1283    .. code-block:: console
   1284 
   1285      $ create_llvm_prof --binary=./code --out=code.prof
   1286 
   1287    This will read ``perf.data`` and the binary file ``./code`` and emit
   1288    the profile data in ``code.prof``. Note that if you ran ``perf``
   1289    without the ``-b`` flag, you need to use ``--use_lbr=false`` when
   1290    calling ``create_llvm_prof``.
   1291 
   1292 4. Build the code again using the collected profile. This step feeds
   1293    the profile back to the optimizers. This should result in a binary
   1294    that executes faster than the original one. Note that you are not
   1295    required to build the code with the exact same arguments that you
   1296    used in the first step. The only requirement is that you build the code
   1297    with ``-gline-tables-only`` and ``-fprofile-sample-use``.
   1298 
   1299    .. code-block:: console
   1300 
   1301      $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
   1302 
   1303 
   1304 Sample Profile Formats
   1305 """"""""""""""""""""""
   1306 
   1307 Since external profilers generate profile data in a variety of custom formats,
   1308 the data generated by the profiler must be converted into a format that can be
   1309 read by the backend. LLVM supports three different sample profile formats:
   1310 
   1311 1. ASCII text. This is the easiest one to generate. The file is divided into
   1312    sections, which correspond to each of the functions with profile
   1313    information. The format is described below. It can also be generated from
   1314    the binary or gcov formats using the ``llvm-profdata`` tool.
   1315 
   1316 2. Binary encoding. This uses a more efficient encoding that yields smaller
   1317    profile files. This is the format generated by the ``create_llvm_prof`` tool
   1318    in http://github.com/google/autofdo.
   1319 
   1320 3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
   1321    is only interesting in environments where GCC and Clang co-exist. This
   1322    encoding is only generated by the ``create_gcov`` tool in
   1323    http://github.com/google/autofdo. It can be read by LLVM and
   1324    ``llvm-profdata``, but it cannot be generated by either.
   1325 
   1326 If you are using Linux Perf to generate sampling profiles, you can use the
   1327 conversion tool ``create_llvm_prof`` described in the previous section.
   1328 Otherwise, you will need to write a conversion tool that converts your
   1329 profiler's native format into one of these three.
   1330 
   1331 
   1332 Sample Profile Text Format
   1333 """"""""""""""""""""""""""
   1334 
   1335 This section describes the ASCII text format for sampling profiles. It is,
   1336 arguably, the easiest one to generate. If you are interested in generating any
   1337 of the other two, consult the ``ProfileData`` library in in LLVM's source tree
   1338 (specifically, ``include/llvm/ProfileData/SampleProfReader.h``).
   1339 
   1340 .. code-block:: console
   1341 
   1342     function1:total_samples:total_head_samples
   1343      offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
   1344      offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
   1345      ...
   1346      offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
   1347      offsetA[.discriminator]: fnA:num_of_total_samples
   1348       offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]
   1349       offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]
   1350       offsetB[.discriminator]: fnB:num_of_total_samples
   1351        offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]
   1352 
   1353 This is a nested tree in which the identation represents the nesting level
   1354 of the inline stack. There are no blank lines in the file. And the spacing
   1355 within a single line is fixed. Additional spaces will result in an error
   1356 while reading the file.
   1357 
   1358 Any line starting with the '#' character is completely ignored.
   1359 
   1360 Inlined calls are represented with indentation. The Inline stack is a
   1361 stack of source locations in which the top of the stack represents the
   1362 leaf function, and the bottom of the stack represents the actual
   1363 symbol to which the instruction belongs.
   1364 
   1365 Function names must be mangled in order for the profile loader to
   1366 match them in the current translation unit. The two numbers in the
   1367 function header specify how many total samples were accumulated in the
   1368 function (first number), and the total number of samples accumulated
   1369 in the prologue of the function (second number). This head sample
   1370 count provides an indicator of how frequently the function is invoked.
   1371 
   1372 There are two types of lines in the function body.
   1373 
   1374 -  Sampled line represents the profile information of a source location.
   1375    ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]``
   1376 
   1377 -  Callsite line represents the profile information of an inlined callsite.
   1378    ``offsetA[.discriminator]: fnA:num_of_total_samples``
   1379 
   1380 Each sampled line may contain several items. Some are optional (marked
   1381 below):
   1382 
   1383 a. Source line offset. This number represents the line number
   1384    in the function where the sample was collected. The line number is
   1385    always relative to the line where symbol of the function is
   1386    defined. So, if the function has its header at line 280, the offset
   1387    13 is at line 293 in the file.
   1388 
   1389    Note that this offset should never be a negative number. This could
   1390    happen in cases like macros. The debug machinery will register the
   1391    line number at the point of macro expansion. So, if the macro was
   1392    expanded in a line before the start of the function, the profile
   1393    converter should emit a 0 as the offset (this means that the optimizers
   1394    will not be able to associate a meaningful weight to the instructions
   1395    in the macro).
   1396 
   1397 b. [OPTIONAL] Discriminator. This is used if the sampled program
   1398    was compiled with DWARF discriminator support
   1399    (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
   1400    DWARF discriminators are unsigned integer values that allow the
   1401    compiler to distinguish between multiple execution paths on the
   1402    same source line location.
   1403 
   1404    For example, consider the line of code ``if (cond) foo(); else bar();``.
   1405    If the predicate ``cond`` is true 80% of the time, then the edge
   1406    into function ``foo`` should be considered to be taken most of the
   1407    time. But both calls to ``foo`` and ``bar`` are at the same source
   1408    line, so a sample count at that line is not sufficient. The
   1409    compiler needs to know which part of that line is taken more
   1410    frequently.
   1411 
   1412    This is what discriminators provide. In this case, the calls to
   1413    ``foo`` and ``bar`` will be at the same line, but will have
   1414    different discriminator values. This allows the compiler to correctly
   1415    set edge weights into ``foo`` and ``bar``.
   1416 
   1417 c. Number of samples. This is an integer quantity representing the
   1418    number of samples collected by the profiler at this source
   1419    location.
   1420 
   1421 d. [OPTIONAL] Potential call targets and samples. If present, this
   1422    line contains a call instruction. This models both direct and
   1423    number of samples. For example,
   1424 
   1425    .. code-block:: console
   1426 
   1427      130: 7  foo:3  bar:2  baz:7
   1428 
   1429    The above means that at relative line offset 130 there is a call
   1430    instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
   1431    with ``baz()`` being the relatively more frequently called target.
   1432 
   1433 As an example, consider a program with the call chain ``main -> foo -> bar``.
   1434 When built with optimizations enabled, the compiler may inline the
   1435 calls to ``bar`` and ``foo`` inside ``main``. The generated profile
   1436 could then be something like this:
   1437 
   1438 .. code-block:: console
   1439 
   1440     main:35504:0
   1441     1: _Z3foov:35504
   1442       2: _Z32bari:31977
   1443       1.1: 31977
   1444     2: 0
   1445 
   1446 This profile indicates that there were a total of 35,504 samples
   1447 collected in main. All of those were at line 1 (the call to ``foo``).
   1448 Of those, 31,977 were spent inside the body of ``bar``. The last line
   1449 of the profile (``2: 0``) corresponds to line 2 inside ``main``. No
   1450 samples were collected there.
   1451 
   1452 Profiling with Instrumentation
   1453 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1454 
   1455 Clang also supports profiling via instrumentation. This requires building a
   1456 special instrumented version of the code and has some runtime
   1457 overhead during the profiling, but it provides more detailed results than a
   1458 sampling profiler. It also provides reproducible results, at least to the
   1459 extent that the code behaves consistently across runs.
   1460 
   1461 Here are the steps for using profile guided optimization with
   1462 instrumentation:
   1463 
   1464 1. Build an instrumented version of the code by compiling and linking with the
   1465    ``-fprofile-instr-generate`` option.
   1466 
   1467    .. code-block:: console
   1468 
   1469      $ clang++ -O2 -fprofile-instr-generate code.cc -o code
   1470 
   1471 2. Run the instrumented executable with inputs that reflect the typical usage.
   1472    By default, the profile data will be written to a ``default.profraw`` file
   1473    in the current directory. You can override that default by setting the
   1474    ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file.
   1475    Any instance of ``%p`` in that file name will be replaced by the process
   1476    ID, so that you can easily distinguish the profile output from multiple
   1477    runs.
   1478 
   1479    .. code-block:: console
   1480 
   1481      $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
   1482 
   1483 3. Combine profiles from multiple runs and convert the "raw" profile format to
   1484    the input expected by clang. Use the ``merge`` command of the
   1485    ``llvm-profdata`` tool to do this.
   1486 
   1487    .. code-block:: console
   1488 
   1489      $ llvm-profdata merge -output=code.profdata code-*.profraw
   1490 
   1491    Note that this step is necessary even when there is only one "raw" profile,
   1492    since the merge operation also changes the file format.
   1493 
   1494 4. Build the code again using the ``-fprofile-instr-use`` option to specify the
   1495    collected profile data.
   1496 
   1497    .. code-block:: console
   1498 
   1499      $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
   1500 
   1501    You can repeat step 4 as often as you like without regenerating the
   1502    profile. As you make changes to your code, clang may no longer be able to
   1503    use the profile data. It will warn you when this happens.
   1504 
   1505 Profile generation and use can also be controlled by the GCC-compatible flags
   1506 ``-fprofile-generate`` and ``-fprofile-use``. Although these flags are
   1507 semantically equivalent to their GCC counterparts, they *do not* handle
   1508 GCC-compatible profiles. They are only meant to implement GCC's semantics
   1509 with respect to profile creation and use.
   1510 
   1511 .. option:: -fprofile-generate[=<dirname>]
   1512 
   1513   Without any other arguments, ``-fprofile-generate`` behaves identically to
   1514   ``-fprofile-instr-generate``. When given a directory name, it generates the
   1515   profile file ``default.profraw`` in the directory named ``dirname``. If
   1516   ``dirname`` does not exist, it will be created at runtime. The environment
   1517   variable ``LLVM_PROFILE_FILE`` can be used to override the directory and
   1518   filename for the profile file at runtime. For example,
   1519 
   1520   .. code-block:: console
   1521 
   1522     $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
   1523 
   1524   When ``code`` is executed, the profile will be written to the file
   1525   ``yyy/zzz/default.profraw``. This can be altered at runtime via the
   1526   ``LLVM_PROFILE_FILE`` environment variable:
   1527 
   1528   .. code-block:: console
   1529 
   1530     $ LLVM_PROFILE_FILE=/tmp/myprofile/code.profraw ./code
   1531 
   1532   The above invocation will produce the profile file
   1533   ``/tmp/myprofile/code.profraw`` instead of ``yyy/zzz/default.profraw``.
   1534   Notice that ``LLVM_PROFILE_FILE`` overrides the directory *and* the file
   1535   name for the profile file.
   1536 
   1537 .. option:: -fprofile-use[=<pathname>]
   1538 
   1539   Without any other arguments, ``-fprofile-use`` behaves identically to
   1540   ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a
   1541   profile file, it reads from that file. If ``pathname`` is a directory name,
   1542   it reads from ``pathname/default.profdata``.
   1543 
   1544 Disabling Instrumentation
   1545 ^^^^^^^^^^^^^^^^^^^^^^^^^
   1546 
   1547 In certain situations, it may be useful to disable profile generation or use
   1548 for specific files in a build, without affecting the main compilation flags
   1549 used for the other files in the project.
   1550 
   1551 In these cases, you can use the flag ``-fno-profile-instr-generate`` (or
   1552 ``-fno-profile-generate``) to disable profile generation, and
   1553 ``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use.
   1554 
   1555 Note that these flags should appear after the corresponding profile
   1556 flags to have an effect.
   1557 
   1558 Controlling Debug Information
   1559 -----------------------------
   1560 
   1561 Controlling Size of Debug Information
   1562 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1563 
   1564 Debug info kind generated by Clang can be set by one of the flags listed
   1565 below. If multiple flags are present, the last one is used.
   1566 
   1567 .. option:: -g0
   1568 
   1569   Don't generate any debug info (default).
   1570 
   1571 .. option:: -gline-tables-only
   1572 
   1573   Generate line number tables only.
   1574 
   1575   This kind of debug info allows to obtain stack traces with function names,
   1576   file names and line numbers (by such tools as ``gdb`` or ``addr2line``).  It
   1577   doesn't contain any other data (e.g. description of local variables or
   1578   function parameters).
   1579 
   1580 .. option:: -fstandalone-debug
   1581 
   1582   Clang supports a number of optimizations to reduce the size of debug
   1583   information in the binary. They work based on the assumption that
   1584   the debug type information can be spread out over multiple
   1585   compilation units.  For instance, Clang will not emit type
   1586   definitions for types that are not needed by a module and could be
   1587   replaced with a forward declaration.  Further, Clang will only emit
   1588   type info for a dynamic C++ class in the module that contains the
   1589   vtable for the class.
   1590 
   1591   The **-fstandalone-debug** option turns off these optimizations.
   1592   This is useful when working with 3rd-party libraries that don't come
   1593   with debug information.  Note that Clang will never emit type
   1594   information for types that are not referenced at all by the program.
   1595 
   1596 .. option:: -fno-standalone-debug
   1597 
   1598    On Darwin **-fstandalone-debug** is enabled by default. The
   1599    **-fno-standalone-debug** option can be used to get to turn on the
   1600    vtable-based optimization described above.
   1601 
   1602 .. option:: -g
   1603 
   1604   Generate complete debug info.
   1605 
   1606 Controlling Debugger "Tuning"
   1607 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1608 
   1609 While Clang generally emits standard DWARF debug info (http://dwarfstd.org),
   1610 different debuggers may know how to take advantage of different specific DWARF
   1611 features. You can "tune" the debug info for one of several different debuggers.
   1612 
   1613 .. option:: -ggdb, -glldb, -gsce
   1614 
   1615   Tune the debug info for the ``gdb``, ``lldb``, or Sony Computer Entertainment
   1616   debugger, respectively. Each of these options implies **-g**. (Therefore, if
   1617   you want both **-gline-tables-only** and debugger tuning, the tuning option
   1618   must come first.)
   1619 
   1620 
   1621 Comment Parsing Options
   1622 -----------------------
   1623 
   1624 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
   1625 them to the appropriate declaration nodes.  By default, it only parses
   1626 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
   1627 ``/*``.
   1628 
   1629 .. option:: -Wdocumentation
   1630 
   1631   Emit warnings about use of documentation comments.  This warning group is off
   1632   by default.
   1633 
   1634   This includes checking that ``\param`` commands name parameters that actually
   1635   present in the function signature, checking that ``\returns`` is used only on
   1636   functions that actually return a value etc.
   1637 
   1638 .. option:: -Wno-documentation-unknown-command
   1639 
   1640   Don't warn when encountering an unknown Doxygen command.
   1641 
   1642 .. option:: -fparse-all-comments
   1643 
   1644   Parse all comments as documentation comments (including ordinary comments
   1645   starting with ``//`` and ``/*``).
   1646 
   1647 .. option:: -fcomment-block-commands=[commands]
   1648 
   1649   Define custom documentation commands as block commands.  This allows Clang to
   1650   construct the correct AST for these custom commands, and silences warnings
   1651   about unknown commands.  Several commands must be separated by a comma
   1652   *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
   1653   custom commands ``\foo`` and ``\bar``.
   1654 
   1655   It is also possible to use ``-fcomment-block-commands`` several times; e.g.
   1656   ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
   1657   as above.
   1658 
   1659 .. _c:
   1660 
   1661 C Language Features
   1662 ===================
   1663 
   1664 The support for standard C in clang is feature-complete except for the
   1665 C99 floating-point pragmas.
   1666 
   1667 Extensions supported by clang
   1668 -----------------------------
   1669 
   1670 See :doc:`LanguageExtensions`.
   1671 
   1672 Differences between various standard modes
   1673 ------------------------------------------
   1674 
   1675 clang supports the -std option, which changes what language mode clang
   1676 uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11,
   1677 gnu11, and various aliases for those modes. If no -std option is
   1678 specified, clang defaults to gnu11 mode. Many C99 and C11 features are
   1679 supported in earlier modes as a conforming extension, with a warning. Use
   1680 ``-pedantic-errors`` to request an error if a feature from a later standard
   1681 revision is used in an earlier mode.
   1682 
   1683 Differences between all ``c*`` and ``gnu*`` modes:
   1684 
   1685 -  ``c*`` modes define "``__STRICT_ANSI__``".
   1686 -  Target-specific defines not prefixed by underscores, like "linux",
   1687    are defined in ``gnu*`` modes.
   1688 -  Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
   1689    the -trigraphs option.
   1690 -  The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
   1691    the variants "``__asm__``" and "``__typeof__``" are recognized in all
   1692    modes.
   1693 -  The Apple "blocks" extension is recognized by default in ``gnu*`` modes
   1694    on some platforms; it can be enabled in any mode with the "-fblocks"
   1695    option.
   1696 -  Arrays that are VLA's according to the standard, but which can be
   1697    constant folded by the frontend are treated as fixed size arrays.
   1698    This occurs for things like "int X[(1, 2)];", which is technically a
   1699    VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
   1700 
   1701 Differences between ``*89`` and ``*99`` modes:
   1702 
   1703 -  The ``*99`` modes default to implementing "inline" as specified in C99,
   1704    while the ``*89`` modes implement the GNU version. This can be
   1705    overridden for individual functions with the ``__gnu_inline__``
   1706    attribute.
   1707 -  Digraphs are not recognized in c89 mode.
   1708 -  The scope of names defined inside a "for", "if", "switch", "while",
   1709    or "do" statement is different. (example: "``if ((struct x {int
   1710    x;}*)0) {}``".)
   1711 -  ``__STDC_VERSION__`` is not defined in ``*89`` modes.
   1712 -  "inline" is not recognized as a keyword in c89 mode.
   1713 -  "restrict" is not recognized as a keyword in ``*89`` modes.
   1714 -  Commas are allowed in integer constant expressions in ``*99`` modes.
   1715 -  Arrays which are not lvalues are not implicitly promoted to pointers
   1716    in ``*89`` modes.
   1717 -  Some warnings are different.
   1718 
   1719 Differences between ``*99`` and ``*11`` modes:
   1720 
   1721 -  Warnings for use of C11 features are disabled.
   1722 -  ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``.
   1723 
   1724 c94 mode is identical to c89 mode except that digraphs are enabled in
   1725 c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
   1726 
   1727 GCC extensions not implemented yet
   1728 ----------------------------------
   1729 
   1730 clang tries to be compatible with gcc as much as possible, but some gcc
   1731 extensions are not implemented yet:
   1732 
   1733 -  clang does not support decimal floating point types (``_Decimal32`` and
   1734    friends) or fixed-point types (``_Fract`` and friends); nobody has
   1735    expressed interest in these features yet, so it's hard to say when
   1736    they will be implemented.
   1737 -  clang does not support nested functions; this is a complex feature
   1738    which is infrequently used, so it is unlikely to be implemented
   1739    anytime soon. In C++11 it can be emulated by assigning lambda
   1740    functions to local variables, e.g:
   1741 
   1742    .. code-block:: cpp
   1743 
   1744      auto const local_function = [&](int parameter) {
   1745        // Do something
   1746      };
   1747      ...
   1748      local_function(1);
   1749 
   1750 -  clang does not support static initialization of flexible array
   1751    members. This appears to be a rarely used extension, but could be
   1752    implemented pending user demand.
   1753 -  clang does not support
   1754    ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
   1755    used rarely, but in some potentially interesting places, like the
   1756    glibc headers, so it may be implemented pending user demand. Note
   1757    that because clang pretends to be like GCC 4.2, and this extension
   1758    was introduced in 4.3, the glibc headers will not try to use this
   1759    extension with clang at the moment.
   1760 -  clang does not support the gcc extension for forward-declaring
   1761    function parameters; this has not shown up in any real-world code
   1762    yet, though, so it might never be implemented.
   1763 
   1764 This is not a complete list; if you find an unsupported extension
   1765 missing from this list, please send an e-mail to cfe-dev. This list
   1766 currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
   1767 list does not include bugs in mostly-implemented features; please see
   1768 the `bug
   1769 tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
   1770 for known existing bugs (FIXME: Is there a section for bug-reporting
   1771 guidelines somewhere?).
   1772 
   1773 Intentionally unsupported GCC extensions
   1774 ----------------------------------------
   1775 
   1776 -  clang does not support the gcc extension that allows variable-length
   1777    arrays in structures. This is for a few reasons: one, it is tricky to
   1778    implement, two, the extension is completely undocumented, and three,
   1779    the extension appears to be rarely used. Note that clang *does*
   1780    support flexible array members (arrays with a zero or unspecified
   1781    size at the end of a structure).
   1782 -  clang does not have an equivalent to gcc's "fold"; this means that
   1783    clang doesn't accept some constructs gcc might accept in contexts
   1784    where a constant expression is required, like "x-x" where x is a
   1785    variable.
   1786 -  clang does not support ``__builtin_apply`` and friends; this extension
   1787    is extremely obscure and difficult to implement reliably.
   1788 
   1789 .. _c_ms:
   1790 
   1791 Microsoft extensions
   1792 --------------------
   1793 
   1794 clang has support for many extensions from Microsoft Visual C++. To enable these
   1795 extensions, use the ``-fms-extensions`` command-line option. This is the default
   1796 for Windows targets. Clang does not implement every pragma or declspec provided
   1797 by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma
   1798 comment(lib)`` are well supported.
   1799 
   1800 clang has a ``-fms-compatibility`` flag that makes clang accept enough
   1801 invalid C++ to be able to parse most Microsoft headers. For example, it
   1802 allows `unqualified lookup of dependent base class members
   1803 <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
   1804 a common compatibility issue with clang. This flag is enabled by default
   1805 for Windows targets.
   1806 
   1807 ``-fdelayed-template-parsing`` lets clang delay parsing of function template
   1808 definitions until the end of a translation unit. This flag is enabled by
   1809 default for Windows targets.
   1810 
   1811 For compatibility with existing code that compiles with MSVC, clang defines the
   1812 ``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800
   1813 and 180000000 respectively, making clang look like an early release of Visual
   1814 C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values.  It
   1815 accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC
   1816 compatibility version makes clang behave more like that version of MSVC. For
   1817 example, ``-fms-compatibility-version=19`` will enable C++14 features and define
   1818 ``char16_t`` and ``char32_t`` as builtin types.
   1819 
   1820 .. _cxx:
   1821 
   1822 C++ Language Features
   1823 =====================
   1824 
   1825 clang fully implements all of standard C++98 except for exported
   1826 templates (which were removed in C++11), and all of standard C++11
   1827 and the current draft standard for C++1y.
   1828 
   1829 Controlling implementation limits
   1830 ---------------------------------
   1831 
   1832 .. option:: -fbracket-depth=N
   1833 
   1834   Sets the limit for nested parentheses, brackets, and braces to N.  The
   1835   default is 256.
   1836 
   1837 .. option:: -fconstexpr-depth=N
   1838 
   1839   Sets the limit for recursive constexpr function invocations to N.  The
   1840   default is 512.
   1841 
   1842 .. option:: -ftemplate-depth=N
   1843 
   1844   Sets the limit for recursively nested template instantiations to N.  The
   1845   default is 256.
   1846 
   1847 .. option:: -foperator-arrow-depth=N
   1848 
   1849   Sets the limit for iterative calls to 'operator->' functions to N.  The
   1850   default is 256.
   1851 
   1852 .. _objc:
   1853 
   1854 Objective-C Language Features
   1855 =============================
   1856 
   1857 .. _objcxx:
   1858 
   1859 Objective-C++ Language Features
   1860 ===============================
   1861 
   1862 .. _openmp:
   1863 
   1864 OpenMP Features
   1865 ===============
   1866 
   1867 Clang supports all OpenMP 3.1 directives and clauses.  In addition, some
   1868 features of OpenMP 4.0 are supported.  For example, ``#pragma omp simd``,
   1869 ``#pragma omp for simd``, ``#pragma omp parallel for simd`` directives, extended
   1870 set of atomic constructs, ``proc_bind`` clause for all parallel-based
   1871 directives, ``depend`` clause for ``#pragma omp task`` directive (except for
   1872 array sections), ``#pragma omp cancel`` and ``#pragma omp cancellation point``
   1873 directives, and ``#pragma omp taskgroup`` directive.
   1874 
   1875 Use :option:`-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with
   1876 :option:`-fno-openmp`.
   1877 
   1878 Controlling implementation limits
   1879 ---------------------------------
   1880 
   1881 .. option:: -fopenmp-use-tls
   1882 
   1883  Controls code generation for OpenMP threadprivate variables. In presence of
   1884  this option all threadprivate variables are generated the same way as thread
   1885  local variables, using TLS support. If :option:`-fno-openmp-use-tls`
   1886  is provided or target does not support TLS, code generation for threadprivate
   1887  variables relies on OpenMP runtime library.
   1888 
   1889 .. _target_features:
   1890 
   1891 Target-Specific Features and Limitations
   1892 ========================================
   1893 
   1894 CPU Architectures Features and Limitations
   1895 ------------------------------------------
   1896 
   1897 X86
   1898 ^^^
   1899 
   1900 The support for X86 (both 32-bit and 64-bit) is considered stable on
   1901 Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
   1902 to correctly compile many large C, C++, Objective-C, and Objective-C++
   1903 codebases.
   1904 
   1905 On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
   1906 Microsoft x64 calling convention. You might need to tweak
   1907 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
   1908 
   1909 For the X86 target, clang supports the :option:`-m16` command line
   1910 argument which enables 16-bit code output. This is broadly similar to
   1911 using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
   1912 and the ABI remains 32-bit but the assembler emits instructions
   1913 appropriate for a CPU running in 16-bit mode, with address-size and
   1914 operand-size prefixes to enable 32-bit addressing and operations.
   1915 
   1916 ARM
   1917 ^^^
   1918 
   1919 The support for ARM (specifically ARMv6 and ARMv7) is considered stable
   1920 on Darwin (iOS): it has been tested to correctly compile many large C,
   1921 C++, Objective-C, and Objective-C++ codebases. Clang only supports a
   1922 limited number of ARM architectures. It does not yet fully support
   1923 ARMv5, for example.
   1924 
   1925 PowerPC
   1926 ^^^^^^^
   1927 
   1928 The support for PowerPC (especially PowerPC64) is considered stable
   1929 on Linux and FreeBSD: it has been tested to correctly compile many
   1930 large C and C++ codebases. PowerPC (32bit) is still missing certain
   1931 features (e.g. PIC code on ELF platforms).
   1932 
   1933 Other platforms
   1934 ^^^^^^^^^^^^^^^
   1935 
   1936 clang currently contains some support for other architectures (e.g. Sparc);
   1937 however, significant pieces of code generation are still missing, and they
   1938 haven't undergone significant testing.
   1939 
   1940 clang contains limited support for the MSP430 embedded processor, but
   1941 both the clang support and the LLVM backend support are highly
   1942 experimental.
   1943 
   1944 Other platforms are completely unsupported at the moment. Adding the
   1945 minimal support needed for parsing and semantic analysis on a new
   1946 platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
   1947 tree. This level of support is also sufficient for conversion to LLVM IR
   1948 for simple programs. Proper support for conversion to LLVM IR requires
   1949 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
   1950 change soon, though. Generating assembly requires a suitable LLVM
   1951 backend.
   1952 
   1953 Operating System Features and Limitations
   1954 -----------------------------------------
   1955 
   1956 Darwin (Mac OS X)
   1957 ^^^^^^^^^^^^^^^^^
   1958 
   1959 Thread Sanitizer is not supported.
   1960 
   1961 Windows
   1962 ^^^^^^^
   1963 
   1964 Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
   1965 platforms.
   1966 
   1967 See also :ref:`Microsoft Extensions <c_ms>`.
   1968 
   1969 Cygwin
   1970 """"""
   1971 
   1972 Clang works on Cygwin-1.7.
   1973 
   1974 MinGW32
   1975 """""""
   1976 
   1977 Clang works on some mingw32 distributions. Clang assumes directories as
   1978 below;
   1979 
   1980 -  ``C:/mingw/include``
   1981 -  ``C:/mingw/lib``
   1982 -  ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
   1983 
   1984 On MSYS, a few tests might fail.
   1985 
   1986 MinGW-w64
   1987 """""""""
   1988 
   1989 For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
   1990 assumes as below;
   1991 
   1992 -  ``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)``
   1993 -  ``some_directory/bin/gcc.exe``
   1994 -  ``some_directory/bin/clang.exe``
   1995 -  ``some_directory/bin/clang++.exe``
   1996 -  ``some_directory/bin/../include/c++/GCC_version``
   1997 -  ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
   1998 -  ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
   1999 -  ``some_directory/bin/../include/c++/GCC_version/backward``
   2000 -  ``some_directory/bin/../x86_64-w64-mingw32/include``
   2001 -  ``some_directory/bin/../i686-w64-mingw32/include``
   2002 -  ``some_directory/bin/../include``
   2003 
   2004 This directory layout is standard for any toolchain you will find on the
   2005 official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
   2006 
   2007 Clang expects the GCC executable "gcc.exe" compiled for
   2008 ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
   2009 
   2010 `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
   2011 ``x86_64-w64-mingw32``.
   2012 
   2013 .. _clang-cl:
   2014 
   2015 clang-cl
   2016 ========
   2017 
   2018 clang-cl is an alternative command-line interface to Clang driver, designed for
   2019 compatibility with the Visual C++ compiler, cl.exe.
   2020 
   2021 To enable clang-cl to find system headers, libraries, and the linker when run
   2022 from the command-line, it should be executed inside a Visual Studio Native Tools
   2023 Command Prompt or a regular Command Prompt where the environment has been set
   2024 up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
   2025 
   2026 clang-cl can also be used from inside Visual Studio  by using an LLVM Platform
   2027 Toolset.
   2028 
   2029 Command-Line Options
   2030 --------------------
   2031 
   2032 To be compatible with cl.exe, clang-cl supports most of the same command-line
   2033 options. Those options can start with either ``/`` or ``-``. It also supports
   2034 some of Clang's core options, such as the ``-W`` options.
   2035 
   2036 Options that are known to clang-cl, but not currently supported, are ignored
   2037 with a warning. For example:
   2038 
   2039   ::
   2040 
   2041     clang-cl.exe: warning: argument unused during compilation: '/AI'
   2042 
   2043 To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
   2044 
   2045 Options that are not known to clang-cl will be ignored by default. Use the
   2046 ``-Werror=unknown-argument`` option in order to treat them as errors. If these
   2047 options are spelled with a leading ``/``, they will be mistaken for a filename:
   2048 
   2049   ::
   2050 
   2051     clang-cl.exe: error: no such file or directory: '/foobar'
   2052 
   2053 Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
   2054 for any valid cl.exe flags that clang-cl does not understand.
   2055 
   2056 Execute ``clang-cl /?`` to see a list of supported options:
   2057 
   2058   ::
   2059 
   2060     CL.EXE COMPATIBILITY OPTIONS:
   2061       /?                     Display available options
   2062       /arch:<value>          Set architecture for code generation
   2063       /Brepro-               Emit an object file which cannot be reproduced over time
   2064       /Brepro                Emit an object file which can be reproduced over time
   2065       /C                     Don't discard comments when preprocessing
   2066       /c                     Compile only
   2067       /D <macro[=value]>     Define macro
   2068       /EH<value>             Exception handling model
   2069       /EP                    Disable linemarker output and preprocess to stdout
   2070       /E                     Preprocess to stdout
   2071       /fallback              Fall back to cl.exe if clang-cl fails to compile
   2072       /FA                    Output assembly code file during compilation
   2073       /Fa<file or directory> Output assembly code to this file during compilation (with /FA)
   2074       /Fe<file or directory> Set output executable file or directory (ends in / or \)
   2075       /FI <value>            Include file before parsing
   2076       /Fi<file>              Set preprocess output file name (with /P)
   2077       /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
   2078       /fp:except-
   2079       /fp:except
   2080       /fp:fast
   2081       /fp:precise
   2082       /fp:strict
   2083       /GA                    Assume thread-local variables are defined in the executable
   2084       /GF-                   Disable string pooling
   2085       /GR-                   Disable emission of RTTI data
   2086       /GR                    Enable emission of RTTI data
   2087       /Gs<value>             Set stack probe size
   2088       /Gw-                   Don't put each data item in its own section
   2089       /Gw                    Put each data item in its own section
   2090       /Gy-                   Don't put each function in its own section
   2091       /Gy                    Put each function in its own section
   2092       /help                  Display available options
   2093       /I <dir>               Add directory to include search path
   2094       /J                     Make char type unsigned
   2095       /LDd                   Create debug DLL
   2096       /LD                    Create DLL
   2097       /link <options>        Forward options to the linker
   2098       /MDd                   Use DLL debug run-time
   2099       /MD                    Use DLL run-time
   2100       /MTd                   Use static debug run-time
   2101       /MT                    Use static run-time
   2102       /Ob0                   Disable inlining
   2103       /Od                    Disable optimization
   2104       /Oi-                   Disable use of builtin functions
   2105       /Oi                    Enable use of builtin functions
   2106       /Os                    Optimize for size
   2107       /Ot                    Optimize for speed
   2108       /O<value>              Optimization level
   2109       /o <file or directory> Set output file or directory (ends in / or \)
   2110       /P                     Preprocess to file
   2111       /Qvec-                 Disable the loop vectorization passes
   2112       /Qvec                  Enable the loop vectorization passes
   2113       /showIncludes          Print info about included files to stderr
   2114       /TC                    Treat all source files as C
   2115       /Tc <filename>         Specify a C source file
   2116       /TP                    Treat all source files as C++
   2117       /Tp <filename>         Specify a C++ source file
   2118       /U <macro>             Undefine macro
   2119       /vd<value>             Control vtordisp placement
   2120       /vmb                   Use a best-case representation method for member pointers
   2121       /vmg                   Use a most-general representation for member pointers
   2122       /vmm                   Set the default most-general representation to multiple inheritance
   2123       /vms                   Set the default most-general representation to single inheritance
   2124       /vmv                   Set the default most-general representation to virtual inheritance
   2125       /volatile:iso          Volatile loads and stores have standard semantics
   2126       /volatile:ms           Volatile loads and stores have acquire and release semantics
   2127       /W0                    Disable all warnings
   2128       /W1                    Enable -Wall
   2129       /W2                    Enable -Wall
   2130       /W3                    Enable -Wall
   2131       /W4                    Enable -Wall and -Wextra
   2132       /Wall                  Enable -Wall and -Wextra
   2133       /WX-                   Do not treat warnings as errors
   2134       /WX                    Treat warnings as errors
   2135       /w                     Disable all warnings
   2136       /Z7                    Enable CodeView debug information in object files
   2137       /Zc:sizedDealloc-      Disable C++14 sized global deallocation functions
   2138       /Zc:sizedDealloc       Enable C++14 sized global deallocation functions
   2139       /Zc:strictStrings      Treat string literals as const
   2140       /Zc:threadSafeInit-    Disable thread-safe initialization of static variables
   2141       /Zc:threadSafeInit     Enable thread-safe initialization of static variables
   2142       /Zc:trigraphs-         Disable trigraphs (default)
   2143       /Zc:trigraphs          Enable trigraphs
   2144       /Zi                    Alias for /Z7. Does not produce PDBs.
   2145       /Zl                    Don't mention any default libraries in the object file
   2146       /Zp                    Set the default maximum struct packing alignment to 1
   2147       /Zp<value>             Specify the default maximum struct packing alignment
   2148       /Zs                    Syntax-check only
   2149 
   2150     OPTIONS:
   2151       -###                    Print (but do not run) the commands to run for this compilation
   2152       --analyze               Run the static analyzer
   2153       -fansi-escape-codes     Use ANSI escape codes for diagnostics
   2154       -fcolor-diagnostics     Use colors in diagnostics
   2155       -fdiagnostics-parseable-fixits
   2156                               Print fix-its in machine parseable form
   2157       -fms-compatibility-version=<value>
   2158                               Dot-separated value representing the Microsoft compiler version
   2159                               number to report in _MSC_VER (0 = don't define it (default))
   2160       -fms-compatibility      Enable full Microsoft Visual C++ compatibility
   2161       -fms-extensions         Accept some non-standard constructs supported by the Microsoft compiler
   2162       -fmsc-version=<value>   Microsoft compiler version number to report in _MSC_VER
   2163                               (0 = don't define it (default))
   2164       -fno-sanitize-coverage=<value>
   2165                               Disable specified features of coverage instrumentation for Sanitizers
   2166       -fno-sanitize-recover=<value>
   2167                               Disable recovery for specified sanitizers
   2168       -fno-sanitize-trap=<value>
   2169                               Disable trapping for specified sanitizers
   2170       -fsanitize-blacklist=<value>
   2171                               Path to blacklist file for sanitizers
   2172       -fsanitize-coverage=<value>
   2173                               Specify the type of coverage instrumentation for Sanitizers
   2174       -fsanitize-recover=<value>
   2175                               Enable recovery for specified sanitizers
   2176       -fsanitize-trap=<value> Enable trapping for specified sanitizers
   2177       -fsanitize=<check>      Turn on runtime checks for various forms of undefined or suspicious
   2178                               behavior. See user manual for available checks
   2179       -gcodeview              Generate CodeView debug information
   2180       -mllvm <value>          Additional arguments to forward to LLVM's option processing
   2181       -Qunused-arguments      Don't emit warning for unused driver arguments
   2182       -R<remark>              Enable the specified remark
   2183       --target=<value>        Generate code for the given target
   2184       -v                      Show commands to run and use verbose output
   2185       -W<warning>             Enable the specified warning
   2186       -Xclang <arg>           Pass <arg> to the clang compiler
   2187 
   2188 The /fallback Option
   2189 ^^^^^^^^^^^^^^^^^^^^
   2190 
   2191 When clang-cl is run with the ``/fallback`` option, it will first try to
   2192 compile files itself. For any file that it fails to compile, it will fall back
   2193 and try to compile the file by invoking cl.exe.
   2194 
   2195 This option is intended to be used as a temporary means to build projects where
   2196 clang-cl cannot successfully compile all the files. clang-cl may fail to compile
   2197 a file either because it cannot generate code for some C++ feature, or because
   2198 it cannot parse some Microsoft language extension.
   2199