docs: More reST conversion.
Sorry for the large commit, but it is much faster to convert in batches.
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@170067 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst
new file mode 100644
index 0000000..6284255
--- /dev/null
+++ b/docs/UsersManual.rst
@@ -0,0 +1,1238 @@
+============================
+Clang Compiler User's Manual
+============================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+The Clang Compiler is an open-source compiler for the C family of
+programming languages, aiming to be the best in class implementation of
+these languages. Clang builds on the LLVM optimizer and code generator,
+allowing it to provide high-quality optimization and code generation
+support for many targets. For more general information, please see the
+`Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web
+Site <http://llvm.org>`_.
+
+This document describes important notes about using Clang as a compiler
+for an end-user, documenting the supported features, command line
+options, etc. If you are interested in using Clang to build a tool that
+processes code, please see `the Clang Internals
+Manual <InternalsManual.html>`_. If you are interested in the `Clang
+Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
+page.
+
+Clang is designed to support the C family of programming languages,
+which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
+:ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
+language-specific information, please see the corresponding language
+specific section:
+
+- :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
+ C99 (+TC1, TC2, TC3).
+- :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
+ variants depending on base language.
+- :ref:`C++ Language <cxx>`
+- :ref:`Objective C++ Language <objcxx>`
+
+In addition to these base languages and their dialects, Clang supports a
+broad variety of language extensions, which are documented in the
+corresponding language section. These extensions are provided to be
+compatible with the GCC, Microsoft, and other popular compilers as well
+as to improve functionality through Clang-specific features. The Clang
+driver and language features are intentionally designed to be as
+compatible with the GNU GCC compiler as reasonably possible, easing
+migration from GCC to Clang. In most cases, code "just works".
+
+In addition to language specific features, Clang has a variety of
+features that depend on what CPU architecture or operating system is
+being compiled for. Please see the :ref:`Target-Specific Features and
+Limitations <target_features>` section for more details.
+
+The rest of the introduction introduces some basic :ref:`compiler
+terminology <terminology>` that is used throughout this manual and
+contains a basic :ref:`introduction to using Clang <basicusage>` as a
+command line compiler.
+
+.. _terminology:
+
+Terminology
+-----------
+
+Front end, parser, backend, preprocessor, undefined behavior,
+diagnostic, optimizer
+
+.. _basicusage:
+
+Basic Usage
+-----------
+
+Intro to how to use a C compiler for newbies.
+
+compile + link compile then link debug info enabling optimizations
+picking a language to use, defaults to C99 by default. Autosenses based
+on extension. using a makefile
+
+Command Line Options
+====================
+
+This section is generally an index into other sections. It does not go
+into depth on the ones that are covered by other sections. However, the
+first part introduces the language selection and other high level
+options like -c, -g, etc.
+
+Options to Control Error and Warning Messages
+---------------------------------------------
+
+**-Werror**: Turn warnings into errors.
+
+**-Werror=foo**: Turn warning "foo" into an error.
+
+**-Wno-error=foo**: Turn warning "foo" into an warning even if -Werror
+is specified.
+
+**-Wfoo**: Enable warning "foo".
+
+**-Wno-foo**: Disable warning "foo".
+
+**-w**: Disable all warnings.
+
+**-Weverything**: :ref:`Enable **all**
+warnings. <diagnostics_enable_everything>`
+
+**-pedantic**: Warn on language extensions.
+
+**-pedantic-errors**: Error on language extensions.
+
+**-Wsystem-headers**: Enable warnings from system headers.
+
+**-ferror-limit=123**: Stop emitting diagnostics after 123 errors have
+been produced. The default is 20, and the error limit can be disabled
+with -ferror-limit=0.
+
+**-ftemplate-backtrace-limit=123**: Only emit up to 123 template
+instantiation notes within the template instantiation backtrace for a
+single warning or error. The default is 10, and the limit can be
+disabled with -ftemplate-backtrace-limit=0.
+
+.. _cl_diag_formatting:
+
+Formatting of Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clang aims to produce beautiful diagnostics by default, particularly for
+new users that first come to Clang. However, different people have
+different preferences, and sometimes Clang is driven by another program
+that wants to parse simple and consistent output, not a person. For
+these cases, Clang provides a wide range of options to control the exact
+output format of the diagnostics that it generates.
+
+.. _opt_fshow-column:
+
+**-f[no-]show-column**
+ Print column number in diagnostic.
+
+ This option, which defaults to on, controls whether or not Clang
+ prints the column number of a diagnostic. For example, when this is
+ enabled, Clang will print something like:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+ When this is disabled, Clang will print "test.c:28: warning..." with
+ no column number.
+
+ The printed column numbers count bytes from the beginning of the
+ line; take care if your source contains multibyte characters.
+
+.. _opt_fshow-source-location:
+
+**-f[no-]show-source-location**
+ Print source file/line/column information in diagnostic.
+
+ This option, which defaults to on, controls whether or not Clang
+ prints the filename, line number and column number of a diagnostic.
+ For example, when this is enabled, Clang will print something like:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+ When this is disabled, Clang will not print the "test.c:28:8: "
+ part.
+
+.. _opt_fcaret-diagnostics:
+
+**-f[no-]caret-diagnostics**
+ Print source line and ranges from source code in diagnostic.
+ This option, which defaults to on, controls whether or not Clang
+ prints the source line, source ranges, and caret when emitting a
+ diagnostic. For example, when this is enabled, Clang will print
+ something like:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+**-f[no-]color-diagnostics**
+ This option, which defaults to on when a color-capable terminal is
+ detected, controls whether or not Clang prints diagnostics in color.
+
+ When this option is enabled, Clang will use colors to highlight
+ specific parts of the diagnostic, e.g.,
+
+ .. nasty hack to not lose our dignity
+
+ .. raw:: html
+
+ <pre>
+ <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>
+ #endif bad
+ <span style="color:green">^</span>
+ <span style="color:green">//</span>
+ </pre>
+
+ When this is disabled, Clang will just print:
+
+ ::
+
+ test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+**-fdiagnostics-format=clang/msvc/vi**
+ Changes diagnostic output format to better match IDEs and command line tools.
+
+ This option controls the output format of the filename, line number,
+ and column printed in diagnostic messages. The options, and their
+ affect on formatting a simple conversion diagnostic, follow:
+
+ **clang** (default)
+ ::
+
+ t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+
+ **msvc**
+ ::
+
+ t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
+
+ **vi**
+ ::
+
+ t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+
+**-f[no-]diagnostics-show-name**
+ Enable the display of the diagnostic name.
+ This option, which defaults to off, controls whether or not Clang
+ prints the associated name.
+
+.. _opt_fdiagnostics-show-option:
+
+**-f[no-]diagnostics-show-option**
+ Enable ``[-Woption]`` information in diagnostic line.
+
+ This option, which defaults to on, controls whether or not Clang
+ prints the associated :ref:`warning group <cl_diag_warning_groups>`
+ option name when outputting a warning diagnostic. For example, in
+ this output:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+ Passing **-fno-diagnostics-show-option** will prevent Clang from
+ printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
+ the diagnostic. This information tells you the flag needed to enable
+ or disable the diagnostic, either from the command line or through
+ :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
+
+.. _opt_fdiagnostics-show-category:
+
+**-fdiagnostics-show-category=none/id/name**
+ Enable printing category information in diagnostic line.
+
+ This option, which defaults to "none", controls whether or not Clang
+ prints the category associated with a diagnostic when emitting it.
+ Each diagnostic may or many not have an associated category, if it
+ has one, it is listed in the diagnostic categorization field of the
+ diagnostic line (in the []'s).
+
+ For example, a format string warning will produce these three
+ renditions based on the setting of this option:
+
+ ::
+
+ t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
+ t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
+ t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
+
+ This category can be used by clients that want to group diagnostics
+ by category, so it should be a high level category. We want dozens
+ of these, not hundreds or thousands of them.
+
+.. _opt_fdiagnostics-fixit-info:
+
+**-f[no-]diagnostics-fixit-info**
+ Enable "FixIt" information in the diagnostics output.
+
+ This option, which defaults to on, controls whether or not Clang
+ prints the information on how to fix a specific diagnostic
+ underneath it when it knows. For example, in this output:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+ //
+
+ Passing **-fno-diagnostics-fixit-info** will prevent Clang from
+ printing the "//" line at the end of the message. This information
+ is useful for users who may not understand what is wrong, but can be
+ confusing for machine parsing.
+
+.. _opt_fdiagnostics-print-source-range-info:
+
+**-f[no-]diagnostics-print-source-range-info**
+ Print machine parsable information about source ranges.
+ This option, which defaults to off, controls whether or not Clang
+ prints information about source ranges in a machine parsable format
+ after the file/line/column number information. The information is a
+ simple sequence of brace enclosed ranges, where each range lists the
+ start and end line/column locations. For example, in this output:
+
+ ::
+
+ exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
+ P = (P-42) + Gamma*4;
+ ~~~~~~ ^ ~~~~~~~
+
+ The {}'s are generated by -fdiagnostics-print-source-range-info.
+
+ The printed column numbers count bytes from the beginning of the
+ line; take care if your source contains multibyte characters.
+
+**-fdiagnostics-parseable-fixits**
+ Print Fix-Its in a machine parseable form.
+
+ This option makes Clang print available Fix-Its in a machine
+ parseable format at the end of diagnostics. The following example
+ illustrates the format:
+
+ ::
+
+ fix-it:"t.cpp":{7:25-7:29}:"Gamma"
+
+ The range printed is a half-open range, so in this example the
+ characters at column 25 up to but not including column 29 on line 7
+ in t.cpp should be replaced with the string "Gamma". Either the
+ range or the replacement string may be empty (representing strict
+ insertions and strict erasures, respectively). Both the file name
+ and the insertion string escape backslash (as "\\\\"), tabs (as
+ "\\t"), newlines (as "\\n"), double quotes(as "\\"") and
+ non-printable characters (as octal "\\xxx").
+
+ The printed column numbers count bytes from the beginning of the
+ line; take care if your source contains multibyte characters.
+
+**-fno-elide-type**
+ Turns off elision in template type printing.
+
+ The default for template type printing is to elide as many template
+ arguments as possible, removing those which are the same in both
+ template types, leaving only the differences. Adding this flag will
+ print all the template arguments. If supported by the terminal,
+ highlighting will still appear on differing arguments.
+
+ Default:
+
+ ::
+
+ 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;
+
+ -fno-elide-type:
+
+ ::
+
+ 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;
+
+**-fdiagnostics-show-template-tree**
+ Template type diffing prints a text tree.
+
+ For diffing large templated types, this option will cause Clang to
+ display the templates as an indented text tree, one argument per
+ line, with differences marked inline. This is compatible with
+ -fno-elide-type.
+
+ Default:
+
+ ::
+
+ 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;
+
+ -fdiagnostics-show-template-tree
+
+ ::
+
+ t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
+ vector<
+ map<
+ [...],
+ map<
+ [float != float],
+ [...]>>>
+
+.. _cl_diag_warning_groups:
+
+Individual Warning Groups
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TODO: Generate this from tblgen. Define one anchor per warning group.
+
+.. _opt_wextra-tokens:
+
+**-Wextra-tokens**
+ Warn about excess tokens at the end of a preprocessor directive.
+
+ This option, which defaults to on, enables warnings about extra
+ tokens at the end of preprocessor directives. For example:
+
+ ::
+
+ test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+ #endif bad
+ ^
+
+ These extra tokens are not strictly conforming, and are usually best
+ handled by commenting them out.
+
+**-Wambiguous-member-template**
+ Warn about unqualified uses of a member template whose name resolves to
+ another template at the location of the use.
+
+ This option, which defaults to on, enables a warning in the
+ following code:
+
+ ::
+
+ template<typename T> struct set{};
+ template<typename T> struct trait { typedef const T& type; };
+ struct Value {
+ template<typename T> void set(typename trait<T>::type value) {}
+ };
+ void foo() {
+ Value v;
+ v.set<double>(3.2);
+ }
+
+ C++ [basic.lookup.classref] requires this to be an error, but,
+ because it's hard to work around, Clang downgrades it to a warning
+ as an extension.
+
+**-Wbind-to-temporary-copy**
+ Warn about an unusable copy constructor when binding a reference to a
+ temporary.
+
+ This option, which defaults to on, enables warnings about binding a
+ reference to a temporary when the temporary doesn't have a usable
+ copy constructor. For example:
+
+ ::
+
+ struct NonCopyable {
+ NonCopyable();
+ private:
+ NonCopyable(const NonCopyable&);
+ };
+ void foo(const NonCopyable&);
+ void bar() {
+ foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
+ }
+
+ ::
+
+ struct NonCopyable2 {
+ NonCopyable2();
+ NonCopyable2(NonCopyable2&);
+ };
+ void foo(const NonCopyable2&);
+ void bar() {
+ foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
+ }
+
+ Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
+ whose instantiation produces a compile error, that error will still
+ be a hard error in C++98 mode even if this warning is turned off.
+
+Options to Control Clang Crash Diagnostics
+------------------------------------------
+
+As unbelievable as it may sound, Clang does crash from time to time.
+Generally, this only occurs to those living on the `bleeding
+edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
+lengths to assist you in filing a bug report. Specifically, Clang
+generates preprocessed source file(s) and associated run script(s) upon
+a crash. These files should be attached to a bug report to ease
+reproducibility of the failure. Below are the command line options to
+control the crash diagnostics.
+
+**-fno-crash-diagnostics**: Disable auto-generation of preprocessed
+source files during a clang crash.
+
+The -fno-crash-diagnostics flag can be helpful for speeding the process
+of generating a delta reduced test case.
+
+Language and Target-Independent Features
+========================================
+
+Controlling Errors and Warnings
+-------------------------------
+
+Clang provides a number of ways to control which code constructs cause
+it to emit errors and warning messages, and how they are displayed to
+the console.
+
+Controlling How Clang Displays Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When Clang emits a diagnostic, it includes rich information in the
+output, and gives you fine-grain control over which information is
+printed. Clang has the ability to print this information, and these are
+the options that control it:
+
+#. A file/line/column indicator that shows exactly where the diagnostic
+ occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
+ :ref:`-fshow-source-location <opt_fshow-source-location>`].
+#. A categorization of the diagnostic as a note, warning, error, or
+ fatal error.
+#. A text string that describes what the problem is.
+#. An option that indicates how to control the diagnostic (for
+ diagnostics that support it)
+ [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
+#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
+ for clients that want to group diagnostics by class (for diagnostics
+ that support it)
+ [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
+#. The line of source code that the issue occurs on, along with a caret
+ and ranges that indicate the important locations
+ [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
+#. "FixIt" information, which is a concise explanation of how to fix the
+ problem (when Clang is certain it knows)
+ [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
+#. A machine-parsable representation of the ranges involved (off by
+ default)
+ [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
+
+For more information please see :ref:`Formatting of
+Diagnostics <cl_diag_formatting>`.
+
+Diagnostic Mappings
+^^^^^^^^^^^^^^^^^^^
+
+All diagnostics are mapped into one of these 5 classes:
+
+- Ignored
+- Note
+- Warning
+- Error
+- Fatal
+
+.. _diagnostics_categories:
+
+Diagnostic Categories
+^^^^^^^^^^^^^^^^^^^^^
+
+Though not shown by default, diagnostics may each be associated with a
+high-level category. This category is intended to make it possible to
+triage builds that produce a large number of errors or warnings in a
+grouped way.
+
+Categories are not shown by default, but they can be turned on with the
+:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
+When set to "``name``", the category is printed textually in the
+diagnostic output. When it is set to "``id``", a category number is
+printed. The mapping of category names to category id's can be obtained
+by running '``clang --print-diagnostic-categories``'.
+
+Controlling Diagnostics via Command Line Flags
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TODO: -W flags, -pedantic, etc
+
+.. _pragma_gcc_diagnostic:
+
+Controlling Diagnostics via Pragmas
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clang can also control what diagnostics are enabled through the use of
+pragmas in the source code. This is useful for turning off specific
+warnings in a section of source code. Clang supports GCC's pragma for
+compatibility with existing source code, as well as several extensions.
+
+The pragma may control any warning that can be used from the command
+line. Warnings may be set to ignored, warning, error, or fatal. The
+following example code will tell Clang or GCC to ignore the -Wall
+warnings:
+
+::
+
+ #pragma GCC diagnostic ignored "-Wall"
+
+In addition to all of the functionality provided by GCC's pragma, Clang
+also allows you to push and pop the current warning state. This is
+particularly useful when writing a header file that will be compiled by
+other people, because you don't know what warning flags they build with.
+
+In the below example -Wmultichar is ignored for only a single line of
+code, after which the diagnostics return to whatever state had
+previously existed.
+
+::
+
+ #pragma clang diagnostic push
+ #pragma clang diagnostic ignored "-Wmultichar"
+
+ char b = 'df'; // no warning.
+
+ #pragma clang diagnostic pop
+
+The push and pop pragmas will save and restore the full diagnostic state
+of the compiler, regardless of how it was set. That means that it is
+possible to use push and pop around GCC compatible diagnostics and Clang
+will push and pop them appropriately, while GCC will ignore the pushes
+and pops as unknown pragmas. It should be noted that while Clang
+supports the GCC pragma, Clang and GCC do not support the exact same set
+of warnings, so even when using GCC compatible #pragmas there is no
+guarantee that they will have identical behaviour on both compilers.
+
+Controlling Diagnostics in System Headers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Warnings are suppressed when they occur in system headers. By default,
+an included file is treated as a system header if it is found in an
+include path specified by ``-isystem``, but this can be overridden in
+several ways.
+
+The ``system_header`` pragma can be used to mark the current file as
+being a system header. No warnings will be produced from the location of
+the pragma onwards within the same file.
+
+::
+
+ char a = 'xy'; // warning
+
+ #pragma clang system_header
+
+ char b = 'ab'; // no warning
+
+The ``-isystem-prefix`` and ``-ino-system-prefix`` command-line
+arguments can be used to override whether subsets of an include path are
+treated as system headers. When the name in a ``#include`` directive is
+found within a header search path and starts with a system prefix, the
+header is treated as a system header. The last prefix on the
+command-line which matches the specified header name takes precedence.
+For instance:
+
+::
+
+ clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/
+
+Here, ``#include "x/a.h"`` is treated as including a system header, even
+if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
+as not including a system header, even if the header is found in
+``bar``.
+
+A ``#include`` directive which finds a file relative to the current
+directory is treated as including a system header if the including file
+is treated as a system header.
+
+.. _diagnostics_enable_everything:
+
+Enabling All Warnings
+^^^^^^^^^^^^^^^^^^^^^
+
+In addition to the traditional ``-W`` flags, one can enable **all**
+warnings by passing ``-Weverything``. This works as expected with
+``-Werror``, and also includes the warnings from ``-pedantic``.
+
+Note that when combined with ``-w`` (which disables all warnings), that
+flag wins.
+
+Controlling Static Analyzer Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While not strictly part of the compiler, the diagnostics from Clang's
+`static analyzer <http://clang-analyzer.llvm.org>`_ can also be
+influenced by the user via changes to the source code. See the available
+`annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
+analyzer's `FAQ
+page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
+information.
+
+Precompiled Headers
+-------------------
+
+`Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
+are a general approach employed by many compilers to reduce compilation
+time. The underlying motivation of the approach is that it is common for
+the same (and often large) header files to be included by multiple
+source files. Consequently, compile times can often be greatly improved
+by caching some of the (redundant) work done by a compiler to process
+headers. Precompiled header files, which represent one of many ways to
+implement this optimization, are literally files that represent an
+on-disk cache that contains the vital information necessary to reduce
+some of the work needed to process a corresponding header file. While
+details of precompiled headers vary between compilers, precompiled
+headers have been shown to be highly effective at speeding up program
+compilation on systems with very large system headers (e.g., Mac OS/X).
+
+Generating a PCH File
+^^^^^^^^^^^^^^^^^^^^^
+
+To generate a PCH file using Clang, one invokes Clang with the
+**``-x <language>-header``** option. This mirrors the interface in GCC
+for generating PCH files:
+
+::
+
+ $ gcc -x c-header test.h -o test.h.gch
+ $ clang -x c-header test.h -o test.h.pch
+
+Using a PCH File
+^^^^^^^^^^^^^^^^
+
+A PCH file can then be used as a prefix header when a **``-include``**
+option is passed to ``clang``:
+
+::
+
+ $ clang -include test.h test.c -o test
+
+The ``clang`` driver will first check if a PCH file for ``test.h`` is
+available; if so, the contents of ``test.h`` (and the files it includes)
+will be processed from the PCH file. Otherwise, Clang falls back to
+directly processing the content of ``test.h``. This mirrors the behavior
+of GCC.
+
+.. note::
+ Clang does *not* automatically use PCH files for headers that are
+ directly included within a source file. For example:
+
+::
+
+ $ clang -x c-header test.h -o test.h.pch
+ $ cat test.c
+ #include "test.h"
+ $ clang test.c -o test
+
+In this example, ``clang`` will not automatically use the PCH file for
+``test.h`` since ``test.h`` was included directly in the source file and
+not specified on the command line using ``-include``.
+
+Relocatable PCH Files
+^^^^^^^^^^^^^^^^^^^^^
+
+It is sometimes necessary to build a precompiled header from headers
+that are not yet in their final, installed locations. For example, one
+might build a precompiled header within the build tree that is then
+meant to be installed alongside the headers. Clang permits the creation
+of "relocatable" precompiled headers, which are built with a given path
+(into the build directory) and can later be used from an installed
+location.
+
+To build a relocatable precompiled header, place your headers into a
+subdirectory whose structure mimics the installed location. For example,
+if you want to build a precompiled header for the header ``mylib.h``
+that will be installed into ``/usr/include``, create a subdirectory
+``build/usr/include`` and place the header ``mylib.h`` into that
+subdirectory. If ``mylib.h`` depends on other headers, then they can be
+stored within ``build/usr/include`` in a way that mimics the installed
+location.
+
+Building a relocatable precompiled header requires two additional
+arguments. First, pass the ``--relocatable-pch`` flag to indicate that
+the resulting PCH file should be relocatable. Second, pass
+``-isysroot /path/to/build``, which makes all includes for your library
+relative to the build directory. For example:
+
+::
+
+ # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+
+When loading the relocatable PCH file, the various headers used in the
+PCH file are found from the system header root. For example, ``mylib.h``
+can be found in ``/usr/include/mylib.h``. If the headers are installed
+in some other system root, the ``-isysroot`` option can be used provide
+a different system root from which the headers will be based. For
+example, ``-isysroot /Developer/SDKs/MacOSX10.4u.sdk`` will look for
+``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
+
+Relocatable precompiled headers are intended to be used in a limited
+number of cases where the compilation environment is tightly controlled
+and the precompiled header cannot be generated after headers have been
+installed. Relocatable precompiled headers also have some performance
+impact, because the difference in location between the header locations
+at PCH build time vs. at the time of PCH use requires one of the PCH
+optimizations, ``stat()`` caching, to be disabled. However, this change
+is only likely to affect PCH files that reference a large number of
+headers.
+
+Controlling Code Generation
+---------------------------
+
+Clang provides a number of ways to control code generation. The options
+are listed below.
+
+**-fsanitize=check1,check2**
+ Turn on runtime checks for various forms of undefined or suspicious
+ behavior.
+
+ This option controls whether Clang adds runtime checks for various
+ forms of undefined or suspicious behavior, and is disabled by
+ default. If a check fails, a diagnostic message is produced at
+ runtime explaining the problem. The main checks are:
+
+ .. _opt_fsanitize_address:
+
+ - ``-fsanitize=address``:
+ :doc:`AddressSanitizer`, a memory error
+ detector.
+ - ``-fsanitize=address-full``: AddressSanitizer with all the
+ experimental features listed below.
+ - ``-fsanitize=integer``: Enables checks for undefined or
+ suspicious integer behavior.
+ - ``-fsanitize=thread``: :doc:`ThreadSanitizer`,
+ an *experimental* data race detector. Not ready for widespread
+ use.
+
+ .. _opt_fsanitize_undefined:
+
+ - ``-fsanitize=undefined``: Fast and compatible undefined behavior
+ checker. Enables the undefined behavior checks that have small
+ runtime cost and no impact on address space layout or ABI. This
+ includes all of the checks listed below other than
+ ``unsigned-integer-overflow``.
+
+ The following more fine-grained checks are also available:
+
+ - ``-fsanitize=alignment``: Use of a misaligned pointer or creation
+ of a misaligned reference.
+ - ``-fsanitize=bounds``: Out of bounds array indexing, in cases
+ where the array bound can be statically determined.
+ - ``-fsanitize=float-cast-overflow``: Conversion to, from, or
+ between floating-point types which would overflow the
+ destination.
+ - ``-fsanitize=float-divide-by-zero``: Floating point division by
+ zero.
+ - ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
+ - ``-fsanitize=null``: Use of a null pointer or creation of a null
+ reference.
+ - ``-fsanitize=object-size``: An attempt to use bytes which the
+ optimizer can determine are not part of the object being
+ accessed. The sizes of objects are determined using
+ ``__builtin_object_size``, and consequently may be able to detect
+ more problems at higher optimization levels.
+ - ``-fsanitize=return``: In C++, reaching the end of a
+ value-returning function without returning a value.
+ - ``-fsanitize=shift``: Shift operators where the amount shifted is
+ greater or equal to the promoted bit-width of the left hand side
+ or less than zero, or where the left hand side is negative. For a
+ signed left shift, also checks for signed overflow in C, and for
+ unsigned overflow in C++.
+ - ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
+ including all the checks added by ``-ftrapv``, and checking for
+ overflow in signed division (``INT_MIN / -1``).
+ - ``-fsanitize=unreachable``: If control flow reaches
+ ``__builtin_unreachable``.
+ - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
+ overflows.
+ - ``-fsanitize=vla-bound``: A variable-length array whose bound
+ does not evaluate to a positive value.
+ - ``-fsanitize=vptr``: Use of an object whose vptr indicates that
+ it is of the wrong dynamic type, or that its lifetime has not
+ begun or has ended. Incompatible with ``-fno-rtti``.
+
+ Experimental features of AddressSanitizer (not ready for widespread
+ use, require explicit ``-fsanitize=address``):
+
+ - ``-fsanitize=init-order``: Check for dynamic initialization order
+ problems.
+ - ``-fsanitize=use-after-return``: Check for use-after-return
+ errors (accessing local variable after the function exit).
+ - ``-fsanitize=use-after-scope``: Check for use-after-scope errors
+ (accesing local variable after it went out of scope).
+
+ The ``-fsanitize=`` argument must also be provided when linking, in
+ order to link to the appropriate runtime library. It is not possible
+ to combine the ``-fsanitize=address`` and ``-fsanitize=thread``
+ checkers in the same program.
+**-f[no-]address-sanitizer**
+ Deprecated synonym for :ref:`-f[no-]sanitize=address
+ <opt_fsanitize_address>`.
+**-f[no-]thread-sanitizer**
+ Deprecated synonym for :ref:`-f[no-]sanitize=thread
+ <opt_fsanitize_address>`.
+**-fcatch-undefined-behavior**
+ Deprecated synonym for :ref:`-fsanitize=undefined
+ <opt_fsanitize_undefined>`.
+**-fno-assume-sane-operator-new**
+ Don't assume that the C++'s new operator is sane.
+
+ This option tells the compiler to do not assume that C++'s global
+ new operator will always return a pointer that does not alias any
+ other pointer when the function returns.
+
+**-ftrap-function=[name]**
+ Instruct code generator to emit a function call to the specified
+ function name for ``__builtin_trap()``.
+
+ LLVM code generator translates ``__builtin_trap()`` to a trap
+ instruction if it is supported by the target ISA. Otherwise, the
+ builtin is translated into a call to ``abort``. If this option is
+ set, then the code generator will always lower the builtin to a call
+ to the specified function regardless of whether the target ISA has a
+ trap instruction. This option is useful for environments (e.g.
+ deeply embedded) where a trap cannot be properly handled, or when
+ some custom behavior is desired.
+
+**-ftls-model=[model]**
+ Select which TLS model to use.
+
+ Valid values are: ``global-dynamic``, ``local-dynamic``,
+ ``initial-exec`` and ``local-exec``. The default value is
+ ``global-dynamic``. The compiler may use a different model if the
+ selected model is not supported by the target, or if a more
+ efficient model can be used. The TLS model can be overridden per
+ variable using the ``tls_model`` attribute.
+
+Controlling Size of Debug Information
+-------------------------------------
+
+Debug info kind generated by Clang can be set by one of the flags listed
+below. If multiple flags are present, the last one is used.
+
+**-g0**: Don't generate any debug info (default).
+
+**-gline-tables-only**: Generate line number tables only.
+
+This kind of debug info allows to obtain stack traces with function
+names, file names and line numbers (by such tools as gdb or addr2line).
+It doesn't contain any other data (e.g. description of local variables
+or function parameters).
+
+**-g**: Generate complete debug info.
+
+.. _c:
+
+C Language Features
+===================
+
+The support for standard C in clang is feature-complete except for the
+C99 floating-point pragmas.
+
+Extensions supported by clang
+-----------------------------
+
+See `clang language extensions <LanguageExtensions.html>`_.
+
+Differences between various standard modes
+------------------------------------------
+
+clang supports the -std option, which changes what language mode clang
+uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and
+various aliases for those modes. If no -std option is specified, clang
+defaults to gnu99 mode.
+
+Differences between all ``c*`` and ``gnu*`` modes:
+
+- ``c*`` modes define "``__STRICT_ANSI__``".
+- Target-specific defines not prefixed by underscores, like "linux",
+ are defined in ``gnu*`` modes.
+- Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
+ the -trigraphs option.
+- The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
+ the variants "``__asm__``" and "``__typeof__``" are recognized in all
+ modes.
+- The Apple "blocks" extension is recognized by default in ``gnu*`` modes
+ on some platforms; it can be enabled in any mode with the "-fblocks"
+ option.
+- Arrays that are VLA's according to the standard, but which can be
+ constant folded by the frontend are treated as fixed size arrays.
+ This occurs for things like "int X[(1, 2)];", which is technically a
+ VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
+
+Differences between ``*89`` and ``*99`` modes:
+
+- The ``*99`` modes default to implementing "inline" as specified in C99,
+ while the ``*89`` modes implement the GNU version. This can be
+ overridden for individual functions with the ``__gnu_inline__``
+ attribute.
+- Digraphs are not recognized in c89 mode.
+- The scope of names defined inside a "for", "if", "switch", "while",
+ or "do" statement is different. (example: "``if ((struct x {int
+ x;}*)0) {}``".)
+- ``__STDC_VERSION__`` is not defined in ``*89`` modes.
+- "inline" is not recognized as a keyword in c89 mode.
+- "restrict" is not recognized as a keyword in ``*89`` modes.
+- Commas are allowed in integer constant expressions in ``*99`` modes.
+- Arrays which are not lvalues are not implicitly promoted to pointers
+ in ``*89`` modes.
+- Some warnings are different.
+
+c94 mode is identical to c89 mode except that digraphs are enabled in
+c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
+
+GCC extensions not implemented yet
+----------------------------------
+
+clang tries to be compatible with gcc as much as possible, but some gcc
+extensions are not implemented yet:
+
+- clang does not support #pragma weak (`bug
+ 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses
+ described in the bug, this is likely to be implemented at some point,
+ at least partially.
+- clang does not support decimal floating point types (``_Decimal32`` and
+ friends) or fixed-point types (``_Fract`` and friends); nobody has
+ expressed interest in these features yet, so it's hard to say when
+ they will be implemented.
+- clang does not support nested functions; this is a complex feature
+ which is infrequently used, so it is unlikely to be implemented
+ anytime soon. In C++11 it can be emulated by assigning lambda
+ functions to local variables, e.g:
+
+ ::
+
+ auto const local_function = [&](int parameter) {
+ // Do something
+ };
+ ...
+ local_function(1);
+
+- clang does not support global register variables; this is unlikely to
+ be implemented soon because it requires additional LLVM backend
+ support.
+- clang does not support static initialization of flexible array
+ members. This appears to be a rarely used extension, but could be
+ implemented pending user demand.
+- clang does not support
+ ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
+ used rarely, but in some potentially interesting places, like the
+ glibc headers, so it may be implemented pending user demand. Note
+ that because clang pretends to be like GCC 4.2, and this extension
+ was introduced in 4.3, the glibc headers will not try to use this
+ extension with clang at the moment.
+- clang does not support the gcc extension for forward-declaring
+ function parameters; this has not shown up in any real-world code
+ yet, though, so it might never be implemented.
+
+This is not a complete list; if you find an unsupported extension
+missing from this list, please send an e-mail to cfe-dev. This list
+currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
+list does not include bugs in mostly-implemented features; please see
+the `bug
+tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
+for known existing bugs (FIXME: Is there a section for bug-reporting
+guidelines somewhere?).
+
+Intentionally unsupported GCC extensions
+----------------------------------------
+
+- clang does not support the gcc extension that allows variable-length
+ arrays in structures. This is for a few reasons: one, it is tricky to
+ implement, two, the extension is completely undocumented, and three,
+ the extension appears to be rarely used. Note that clang *does*
+ support flexible array members (arrays with a zero or unspecified
+ size at the end of a structure).
+- clang does not have an equivalent to gcc's "fold"; this means that
+ clang doesn't accept some constructs gcc might accept in contexts
+ where a constant expression is required, like "x-x" where x is a
+ variable.
+- clang does not support ``__builtin_apply`` and friends; this extension
+ is extremely obscure and difficult to implement reliably.
+
+.. _c_ms:
+
+Microsoft extensions
+--------------------
+
+clang has some experimental support for extensions from Microsoft Visual
+C++; to enable it, use the -fms-extensions command-line option. This is
+the default for Windows targets. Note that the support is incomplete;
+enabling Microsoft extensions will silently drop certain constructs
+(including ``__declspec`` and Microsoft-style asm statements).
+
+clang has a -fms-compatibility flag that makes clang accept enough
+invalid C++ to be able to parse most Microsoft headers. This flag is
+enabled by default for Windows targets.
+
+-fdelayed-template-parsing lets clang delay all template instantiation
+until the end of a translation unit. This flag is enabled by default for
+Windows targets.
+
+- clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to
+ 1300 which is the same as Visual C/C++ 2003. Any number is supported
+ and can greatly affect what Windows SDK and c++stdlib headers clang
+ can compile. This option will be removed when clang supports the full
+ set of MS extensions required for these headers.
+- clang does not support the Microsoft extension where anonymous record
+ members can be declared using user defined typedefs.
+- clang supports the Microsoft "#pragma pack" feature for controlling
+ record layout. GCC also contains support for this feature, however
+ where MSVC and GCC are incompatible clang follows the MSVC
+ definition.
+- clang defaults to C++11 for Windows targets.
+
+.. _cxx:
+
+C++ Language Features
+=====================
+
+clang fully implements all of standard C++98 except for exported
+templates (which were removed in C++11), and `many C++11
+features <http://clang.llvm.org/cxx_status.html>`_ are also implemented.
+
+Controlling implementation limits
+---------------------------------
+
+**-fconstexpr-depth=N**: Sets the limit for recursive constexpr function
+invocations to N. The default is 512.
+
+**-ftemplate-depth=N**: Sets the limit for recursively nested template
+instantiations to N. The default is 1024.
+
+.. _objc:
+
+Objective-C Language Features
+=============================
+
+.. _objcxx:
+
+Objective-C++ Language Features
+===============================
+
+
+.. _target_features:
+
+Target-Specific Features and Limitations
+========================================
+
+CPU Architectures Features and Limitations
+------------------------------------------
+
+X86
+^^^
+
+The support for X86 (both 32-bit and 64-bit) is considered stable on
+Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
+to correctly compile many large C, C++, Objective-C, and Objective-C++
+codebases.
+
+On ``x86_64-mingw32``, passing i128(by value) is incompatible to Microsoft
+x64 calling conversion. You might need to tweak
+``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
+
+ARM
+^^^
+
+The support for ARM (specifically ARMv6 and ARMv7) is considered stable
+on Darwin (iOS): it has been tested to correctly compile many large C,
+C++, Objective-C, and Objective-C++ codebases. Clang only supports a
+limited number of ARM architectures. It does not yet fully support
+ARMv5, for example.
+
+Other platforms
+^^^^^^^^^^^^^^^
+
+clang currently contains some support for PPC and Sparc; however,
+significant pieces of code generation are still missing, and they
+haven't undergone significant testing.
+
+clang contains limited support for the MSP430 embedded processor, but
+both the clang support and the LLVM backend support are highly
+experimental.
+
+Other platforms are completely unsupported at the moment. Adding the
+minimal support needed for parsing and semantic analysis on a new
+platform is quite easy; see lib/Basic/Targets.cpp in the clang source
+tree. This level of support is also sufficient for conversion to LLVM IR
+for simple programs. Proper support for conversion to LLVM IR requires
+adding code to lib/CodeGen/CGCall.cpp at the moment; this is likely to
+change soon, though. Generating assembly requires a suitable LLVM
+backend.
+
+Operating System Features and Limitations
+-----------------------------------------
+
+Darwin (Mac OS/X)
+^^^^^^^^^^^^^^^^^
+
+None
+
+Windows
+^^^^^^^
+
+Experimental supports are on Cygming.
+
+See also `Microsoft Extensions <c_ms>`.
+
+Cygwin
+""""""
+
+Clang works on Cygwin-1.7.
+
+MinGW32
+"""""""
+
+Clang works on some mingw32 distributions. Clang assumes directories as
+below;
+
+- ``C:/mingw/include``
+- ``C:/mingw/lib``
+- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
+
+On MSYS, a few tests might fail.
+
+MinGW-w64
+"""""""""
+
+For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
+assumes as below;
+
+- ``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)``
+- ``some_directory/bin/gcc.exe``
+- ``some_directory/bin/clang.exe``
+- ``some_directory/bin/clang++.exe``
+- ``some_directory/bin/../include/c++/GCC_version``
+- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
+- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
+- ``some_directory/bin/../include/c++/GCC_version/backward``
+- ``some_directory/bin/../x86_64-w64-mingw32/include``
+- ``some_directory/bin/../i686-w64-mingw32/include``
+- ``some_directory/bin/../include``
+
+This directory layout is standard for any toolchain you will find on the
+official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
+
+Clang expects the GCC executable "gcc.exe" compiled for
+``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
+
+`Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
+``x86_64-w64-mingw32``.