[www-releases] r372328 - Check in 9.0.0 source and docs
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Thu Sep 19 07:32:55 PDT 2019
Added: www-releases/trunk/9.0.0/tools/clang/docs/DriverInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/DriverInternals.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/DriverInternals.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/DriverInternals.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,442 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Driver Design & Internals — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Precompiled Header and Modules Internals" href="PCHInternals.html" />
+ <link rel="prev" title="âClangâ CFE Internals Manual" href="InternalsManual.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Driver Design & Internals</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="InternalsManual.html">âClangâ CFE Internals Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="PCHInternals.html">Precompiled Header and Modules Internals</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="driver-design-internals">
+<h1>Driver Design & Internals<a class="headerlink" href="#driver-design-internals" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
+<li><a class="reference internal" href="#features-and-goals" id="id3">Features and Goals</a><ul>
+<li><a class="reference internal" href="#gcc-compatibility" id="id4">GCC Compatibility</a></li>
+<li><a class="reference internal" href="#flexible" id="id5">Flexible</a></li>
+<li><a class="reference internal" href="#low-overhead" id="id6">Low Overhead</a></li>
+<li><a class="reference internal" href="#simple" id="id7">Simple</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#internal-design-and-implementation" id="id8">Internal Design and Implementation</a><ul>
+<li><a class="reference internal" href="#internals-introduction" id="id9">Internals Introduction</a></li>
+<li><a class="reference internal" href="#design-overview" id="id10">Design Overview</a></li>
+<li><a class="reference internal" href="#driver-stages" id="id11">Driver Stages</a></li>
+<li><a class="reference internal" href="#additional-notes" id="id12">Additional Notes</a><ul>
+<li><a class="reference internal" href="#the-compilation-object" id="id13">The Compilation Object</a></li>
+<li><a class="reference internal" href="#unified-parsing-pipelining" id="id14">Unified Parsing & Pipelining</a></li>
+<li><a class="reference internal" href="#toolchain-argument-translation" id="id15">ToolChain Argument Translation</a></li>
+<li><a class="reference internal" href="#unused-argument-warnings" id="id16">Unused Argument Warnings</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#relation-to-gcc-driver-concepts" id="id17">Relation to GCC Driver Concepts</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the Clang driver. The purpose of this document
+is to describe both the motivation and design goals for the driver, as
+well as details of the internal implementation.</p>
+</div>
+<div class="section" id="features-and-goals">
+<h2><a class="toc-backref" href="#id3">Features and Goals</a><a class="headerlink" href="#features-and-goals" title="Permalink to this headline">¶</a></h2>
+<p>The Clang driver is intended to be a production quality compiler driver
+providing access to the Clang compiler and tools, with a command line
+interface which is compatible with the gcc driver.</p>
+<p>Although the driver is part of and driven by the Clang project, it is
+logically a separate tool which shares many of the same goals as Clang:</p>
+<div class="contents local topic" id="features">
+<p class="topic-title first">Features</p>
+<ul class="simple">
+<li><a class="reference internal" href="#gcc-compatibility" id="id18">GCC Compatibility</a></li>
+<li><a class="reference internal" href="#flexible" id="id19">Flexible</a></li>
+<li><a class="reference internal" href="#low-overhead" id="id20">Low Overhead</a></li>
+<li><a class="reference internal" href="#simple" id="id21">Simple</a></li>
+</ul>
+</div>
+<div class="section" id="gcc-compatibility">
+<h3><a class="toc-backref" href="#id18">GCC Compatibility</a><a class="headerlink" href="#gcc-compatibility" title="Permalink to this headline">¶</a></h3>
+<p>The number one goal of the driver is to ease the adoption of Clang by
+allowing users to drop Clang into a build system which was designed to
+call GCC. Although this makes the driver much more complicated than
+might otherwise be necessary, we decided that being very compatible with
+the gcc command line interface was worth it in order to allow users to
+quickly test clang on their projects.</p>
+</div>
+<div class="section" id="flexible">
+<h3><a class="toc-backref" href="#id19">Flexible</a><a class="headerlink" href="#flexible" title="Permalink to this headline">¶</a></h3>
+<p>The driver was designed to be flexible and easily accommodate new uses
+as we grow the clang and LLVM infrastructure. As one example, the driver
+can easily support the introduction of tools which have an integrated
+assembler; something we hope to add to LLVM in the future.</p>
+<p>Similarly, most of the driver functionality is kept in a library which
+can be used to build other tools which want to implement or accept a gcc
+like interface.</p>
+</div>
+<div class="section" id="low-overhead">
+<h3><a class="toc-backref" href="#id20">Low Overhead</a><a class="headerlink" href="#low-overhead" title="Permalink to this headline">¶</a></h3>
+<p>The driver should have as little overhead as possible. In practice, we
+found that the gcc driver by itself incurred a small but meaningful
+overhead when compiling many small files. The driver doesnât do much
+work compared to a compilation, but we have tried to keep it as
+efficient as possible by following a few simple principles:</p>
+<ul class="simple">
+<li>Avoid memory allocation and string copying when possible.</li>
+<li>Donât parse arguments more than once.</li>
+<li>Provide a few simple interfaces for efficiently searching arguments.</li>
+</ul>
+</div>
+<div class="section" id="simple">
+<h3><a class="toc-backref" href="#id21">Simple</a><a class="headerlink" href="#simple" title="Permalink to this headline">¶</a></h3>
+<p>Finally, the driver was designed to be âas simple as possibleâ, given
+the other goals. Notably, trying to be completely compatible with the
+gcc driver adds a significant amount of complexity. However, the design
+of the driver attempts to mitigate this complexity by dividing the
+process into a number of independent stages instead of a single
+monolithic task.</p>
+</div>
+</div>
+<div class="section" id="internal-design-and-implementation">
+<h2><a class="toc-backref" href="#id8">Internal Design and Implementation</a><a class="headerlink" href="#internal-design-and-implementation" title="Permalink to this headline">¶</a></h2>
+<div class="contents local topic" id="id1">
+<ul class="simple">
+<li><a class="reference internal" href="#internals-introduction" id="id22">Internals Introduction</a></li>
+<li><a class="reference internal" href="#design-overview" id="id23">Design Overview</a></li>
+<li><a class="reference internal" href="#driver-stages" id="id24">Driver Stages</a></li>
+<li><a class="reference internal" href="#additional-notes" id="id25">Additional Notes</a></li>
+<li><a class="reference internal" href="#relation-to-gcc-driver-concepts" id="id26">Relation to GCC Driver Concepts</a></li>
+</ul>
+</div>
+<div class="section" id="internals-introduction">
+<h3><a class="toc-backref" href="#id22">Internals Introduction</a><a class="headerlink" href="#internals-introduction" title="Permalink to this headline">¶</a></h3>
+<p>In order to satisfy the stated goals, the driver was designed to
+completely subsume the functionality of the gcc executable; that is, the
+driver should not need to delegate to gcc to perform subtasks. On
+Darwin, this implies that the Clang driver also subsumes the gcc
+driver-driver, which is used to implement support for building universal
+images (binaries and object files). This also implies that the driver
+should be able to call the language specific compilers (e.g. cc1)
+directly, which means that it must have enough information to forward
+command line arguments to child processes correctly.</p>
+</div>
+<div class="section" id="design-overview">
+<h3><a class="toc-backref" href="#id23">Design Overview</a><a class="headerlink" href="#design-overview" title="Permalink to this headline">¶</a></h3>
+<p>The diagram below shows the significant components of the driver
+architecture and how they relate to one another. The orange components
+represent concrete data structures built by the driver, the green
+components indicate conceptually distinct stages which manipulate these
+data structures, and the blue components are important helper classes.</p>
+<img alt="Driver Architecture Diagram" class="align-center" src="_images/DriverArchitecture.png" />
+</div>
+<div class="section" id="driver-stages">
+<h3><a class="toc-backref" href="#id24">Driver Stages</a><a class="headerlink" href="#driver-stages" title="Permalink to this headline">¶</a></h3>
+<p>The driver functionality is conceptually divided into five stages:</p>
+<ol class="arabic">
+<li><p class="first"><strong>Parse: Option Parsing</strong></p>
+<p>The command line argument strings are decomposed into arguments
+(<code class="docutils literal notranslate"><span class="pre">Arg</span></code> instances). The driver expects to understand all available
+options, although there is some facility for just passing certain
+classes of options through (like <code class="docutils literal notranslate"><span class="pre">-Wl,</span></code>).</p>
+<p>Each argument corresponds to exactly one abstract <code class="docutils literal notranslate"><span class="pre">Option</span></code>
+definition, which describes how the option is parsed along with some
+additional metadata. The Arg instances themselves are lightweight and
+merely contain enough information for clients to determine which
+option they correspond to and their values (if they have additional
+parameters).</p>
+<p>For example, a command line like â-Ifoo -I fooâ would parse to two
+Arg instances (a JoinedArg and a SeparateArg instance), but each
+would refer to the same Option.</p>
+<p>Options are lazily created in order to avoid populating all Option
+classes when the driver is loaded. Most of the driver code only needs
+to deal with options by their unique ID (e.g., <code class="docutils literal notranslate"><span class="pre">options::OPT_I</span></code>),</p>
+<p>Arg instances themselves do not generally store the values of
+parameters. In many cases, this would simply result in creating
+unnecessary string copies. Instead, Arg instances are always embedded
+inside an ArgList structure, which contains the original vector of
+argument strings. Each Arg itself only needs to contain an index into
+this vector instead of storing its values directly.</p>
+<p>The clang driver can dump the results of this stage using the
+<code class="docutils literal notranslate"><span class="pre">-###</span></code> flag (which must precede any actual command
+line arguments). For example:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -### -Xarch_i386 -fomit-frame-pointer -Wa,-fast -Ifoo -I foo t.c
+<span class="go">Option 0 - Name: "-Xarch_", Values: {"i386", "-fomit-frame-pointer"}</span>
+<span class="go">Option 1 - Name: "-Wa,", Values: {"-fast"}</span>
+<span class="go">Option 2 - Name: "-I", Values: {"foo"}</span>
+<span class="go">Option 3 - Name: "-I", Values: {"foo"}</span>
+<span class="go">Option 4 - Name: "<input>", Values: {"t.c"}</span>
+</pre></div>
+</div>
+<p>After this stage is complete the command line should be broken down
+into well defined option objects with their appropriate parameters.
+Subsequent stages should rarely, if ever, need to do any string
+processing.</p>
+</li>
+<li><p class="first"><strong>Pipeline: Compilation Action Construction</strong></p>
+<p>Once the arguments are parsed, the tree of subprocess jobs needed for
+the desired compilation sequence are constructed. This involves
+determining the input files and their types, what work is to be done
+on them (preprocess, compile, assemble, link, etc.), and constructing
+a list of Action instances for each task. The result is a list of one
+or more top-level actions, each of which generally corresponds to a
+single output (for example, an object or linked executable).</p>
+<p>The majority of Actions correspond to actual tasks, however there are
+two special Actions. The first is InputAction, which simply serves to
+adapt an input argument for use as an input to other Actions. The
+second is BindArchAction, which conceptually alters the architecture
+to be used for all of its input Actions.</p>
+<p>The clang driver can dump the results of this stage using the
+<code class="docutils literal notranslate"><span class="pre">-ccc-print-phases</span></code> flag. For example:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -ccc-print-phases -x c t.c -x assembler t.s
+<span class="go">0: input, "t.c", c</span>
+<span class="go">1: preprocessor, {0}, cpp-output</span>
+<span class="go">2: compiler, {1}, assembler</span>
+<span class="go">3: assembler, {2}, object</span>
+<span class="go">4: input, "t.s", assembler</span>
+<span class="go">5: assembler, {4}, object</span>
+<span class="go">6: linker, {3, 5}, image</span>
+</pre></div>
+</div>
+<p>Here the driver is constructing seven distinct actions, four to
+compile the ât.câ input into an object file, two to assemble the
+ât.sâ input, and one to link them together.</p>
+<p>A rather different compilation pipeline is shown here; in this
+example there are two top level actions to compile the input files
+into two separate object files, where each object file is built using
+<code class="docutils literal notranslate"><span class="pre">lipo</span></code> to merge results built for two separate architectures.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -ccc-print-phases -c -arch i386 -arch x86_64 t0.c t1.c
+<span class="go">0: input, "t0.c", c</span>
+<span class="go">1: preprocessor, {0}, cpp-output</span>
+<span class="go">2: compiler, {1}, assembler</span>
+<span class="go">3: assembler, {2}, object</span>
+<span class="go">4: bind-arch, "i386", {3}, object</span>
+<span class="go">5: bind-arch, "x86_64", {3}, object</span>
+<span class="go">6: lipo, {4, 5}, object</span>
+<span class="go">7: input, "t1.c", c</span>
+<span class="go">8: preprocessor, {7}, cpp-output</span>
+<span class="go">9: compiler, {8}, assembler</span>
+<span class="go">10: assembler, {9}, object</span>
+<span class="go">11: bind-arch, "i386", {10}, object</span>
+<span class="go">12: bind-arch, "x86_64", {10}, object</span>
+<span class="go">13: lipo, {11, 12}, object</span>
+</pre></div>
+</div>
+<p>After this stage is complete the compilation process is divided into
+a simple set of actions which need to be performed to produce
+intermediate or final outputs (in some cases, like <code class="docutils literal notranslate"><span class="pre">-fsyntax-only</span></code>,
+there is no ârealâ final output). Phases are well known compilation
+steps, such as âpreprocessâ, âcompileâ, âassembleâ, âlinkâ, etc.</p>
+</li>
+<li><p class="first"><strong>Bind: Tool & Filename Selection</strong></p>
+<p>This stage (in conjunction with the Translate stage) turns the tree
+of Actions into a list of actual subprocess to run. Conceptually, the
+driver performs a top down matching to assign Action(s) to Tools. The
+ToolChain is responsible for selecting the tool to perform a
+particular action; once selected the driver interacts with the tool
+to see if it can match additional actions (for example, by having an
+integrated preprocessor).</p>
+<p>Once Tools have been selected for all actions, the driver determines
+how the tools should be connected (for example, using an inprocess
+module, pipes, temporary files, or user provided filenames). If an
+output file is required, the driver also computes the appropriate
+file name (the suffix and file location depend on the input types and
+options such as <code class="docutils literal notranslate"><span class="pre">-save-temps</span></code>).</p>
+<p>The driver interacts with a ToolChain to perform the Tool bindings.
+Each ToolChain contains information about all the tools needed for
+compilation for a particular architecture, platform, and operating
+system. A single driver invocation may query multiple ToolChains
+during one compilation in order to interact with tools for separate
+architectures.</p>
+<p>The results of this stage are not computed directly, but the driver
+can print the results via the <code class="docutils literal notranslate"><span class="pre">-ccc-print-bindings</span></code> option. For
+example:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -ccc-print-bindings -arch i386 -arch ppc t0.c
+<span class="gp">#</span> <span class="s2">"i386-apple-darwin9"</span> - <span class="s2">"clang"</span>, inputs: <span class="o">[</span><span class="s2">"t0.c"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-Sn4RKF.s"</span>
+<span class="gp">#</span> <span class="s2">"i386-apple-darwin9"</span> - <span class="s2">"darwin::Assemble"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-Sn4RKF.s"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-gvSnbS.o"</span>
+<span class="gp">#</span> <span class="s2">"i386-apple-darwin9"</span> - <span class="s2">"darwin::Link"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-gvSnbS.o"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-jgHQxi.out"</span>
+<span class="gp">#</span> <span class="s2">"ppc-apple-darwin9"</span> - <span class="s2">"gcc::Compile"</span>, inputs: <span class="o">[</span><span class="s2">"t0.c"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-Q0bTox.s"</span>
+<span class="gp">#</span> <span class="s2">"ppc-apple-darwin9"</span> - <span class="s2">"gcc::Assemble"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-Q0bTox.s"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-WCdicw.o"</span>
+<span class="gp">#</span> <span class="s2">"ppc-apple-darwin9"</span> - <span class="s2">"gcc::Link"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-WCdicw.o"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-HHBEBh.out"</span>
+<span class="gp">#</span> <span class="s2">"i386-apple-darwin9"</span> - <span class="s2">"darwin::Lipo"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-jgHQxi.out"</span>, <span class="s2">"/tmp/cc-HHBEBh.out"</span><span class="o">]</span>, output: <span class="s2">"a.out"</span>
+</pre></div>
+</div>
+<p>This shows the tool chain, tool, inputs and outputs which have been
+bound for this compilation sequence. Here clang is being used to
+compile t0.c on the i386 architecture and darwin specific versions of
+the tools are being used to assemble and link the result, but generic
+gcc versions of the tools are being used on PowerPC.</p>
+</li>
+<li><p class="first"><strong>Translate: Tool Specific Argument Translation</strong></p>
+<p>Once a Tool has been selected to perform a particular Action, the
+Tool must construct concrete Commands which will be executed during
+compilation. The main work is in translating from the gcc style
+command line options to whatever options the subprocess expects.</p>
+<p>Some tools, such as the assembler, only interact with a handful of
+arguments and just determine the path of the executable to call and
+pass on their input and output arguments. Others, like the compiler
+or the linker, may translate a large number of arguments in addition.</p>
+<p>The ArgList class provides a number of simple helper methods to
+assist with translating arguments; for example, to pass on only the
+last of arguments corresponding to some option, or all arguments for
+an option.</p>
+<p>The result of this stage is a list of Commands (executable paths and
+argument strings) to execute.</p>
+</li>
+<li><p class="first"><strong>Execute</strong></p>
+<p>Finally, the compilation pipeline is executed. This is mostly
+straightforward, although there is some interaction with options like
+<code class="docutils literal notranslate"><span class="pre">-pipe</span></code>, <code class="docutils literal notranslate"><span class="pre">-pass-exit-codes</span></code> and <code class="docutils literal notranslate"><span class="pre">-time</span></code>.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="additional-notes">
+<h3><a class="toc-backref" href="#id25">Additional Notes</a><a class="headerlink" href="#additional-notes" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="the-compilation-object">
+<h4><a class="toc-backref" href="#id13">The Compilation Object</a><a class="headerlink" href="#the-compilation-object" title="Permalink to this headline">¶</a></h4>
+<p>The driver constructs a Compilation object for each set of command line
+arguments. The Driver itself is intended to be invariant during
+construction of a Compilation; an IDE should be able to construct a
+single long lived driver instance to use for an entire build, for
+example.</p>
+<p>The Compilation object holds information that is particular to each
+compilation sequence. For example, the list of used temporary files
+(which must be removed once compilation is finished) and result files
+(which should be removed if compilation fails).</p>
+</div>
+<div class="section" id="unified-parsing-pipelining">
+<h4><a class="toc-backref" href="#id14">Unified Parsing & Pipelining</a><a class="headerlink" href="#unified-parsing-pipelining" title="Permalink to this headline">¶</a></h4>
+<p>Parsing and pipelining both occur without reference to a Compilation
+instance. This is by design; the driver expects that both of these
+phases are platform neutral, with a few very well defined exceptions
+such as whether the platform uses a driver driver.</p>
+</div>
+<div class="section" id="toolchain-argument-translation">
+<h4><a class="toc-backref" href="#id15">ToolChain Argument Translation</a><a class="headerlink" href="#toolchain-argument-translation" title="Permalink to this headline">¶</a></h4>
+<p>In order to match gcc very closely, the clang driver currently allows
+tool chains to perform their own translation of the argument list (into
+a new ArgList data structure). Although this allows the clang driver to
+match gcc easily, it also makes the driver operation much harder to
+understand (since the Tools stop seeing some arguments the user
+provided, and see new ones instead).</p>
+<p>For example, on Darwin <code class="docutils literal notranslate"><span class="pre">-gfull</span></code> gets translated into two separate
+arguments, <code class="docutils literal notranslate"><span class="pre">-g</span></code> and <code class="docutils literal notranslate"><span class="pre">-fno-eliminate-unused-debug-symbols</span></code>. Trying to
+write Tool logic to do something with <code class="docutils literal notranslate"><span class="pre">-gfull</span></code> will not work, because
+Tool argument translation is done after the arguments have been
+translated.</p>
+<p>A long term goal is to remove this tool chain specific translation, and
+instead force each tool to change its own logic to do the right thing on
+the untranslated original arguments.</p>
+</div>
+<div class="section" id="unused-argument-warnings">
+<h4><a class="toc-backref" href="#id16">Unused Argument Warnings</a><a class="headerlink" href="#unused-argument-warnings" title="Permalink to this headline">¶</a></h4>
+<p>The driver operates by parsing all arguments but giving Tools the
+opportunity to choose which arguments to pass on. One downside of this
+infrastructure is that if the user misspells some option, or is confused
+about which options to use, some command line arguments the user really
+cared about may go unused. This problem is particularly important when
+using clang as a compiler, since the clang compiler does not support
+anywhere near all the options that gcc does, and we want to make sure
+users know which ones are being used.</p>
+<p>To support this, the driver maintains a bit associated with each
+argument of whether it has been used (at all) during the compilation.
+This bit usually doesnât need to be set by hand, as the key ArgList
+accessors will set it automatically.</p>
+<p>When a compilation is successful (there are no errors), the driver
+checks the bit and emits an âunused argumentâ warning for any arguments
+which were never accessed. This is conservative (the argument may not
+have been used to do what the user wanted) but still catches the most
+obvious cases.</p>
+</div>
+</div>
+<div class="section" id="relation-to-gcc-driver-concepts">
+<h3><a class="toc-backref" href="#id26">Relation to GCC Driver Concepts</a><a class="headerlink" href="#relation-to-gcc-driver-concepts" title="Permalink to this headline">¶</a></h3>
+<p>For those familiar with the gcc driver, this section provides a brief
+overview of how things from the gcc driver map to the clang driver.</p>
+<ul>
+<li><p class="first"><strong>Driver Driver</strong></p>
+<p>The driver driver is fully integrated into the clang driver. The
+driver simply constructs additional Actions to bind the architecture
+during the <em>Pipeline</em> phase. The tool chain specific argument
+translation is responsible for handling <code class="docutils literal notranslate"><span class="pre">-Xarch_</span></code>.</p>
+<p>The one caveat is that this approach requires <code class="docutils literal notranslate"><span class="pre">-Xarch_</span></code> not be used
+to alter the compilation itself (for example, one cannot provide
+<code class="docutils literal notranslate"><span class="pre">-S</span></code> as an <code class="docutils literal notranslate"><span class="pre">-Xarch_</span></code> argument). The driver attempts to reject
+such invocations, and overall there isnât a good reason to abuse
+<code class="docutils literal notranslate"><span class="pre">-Xarch_</span></code> to that end in practice.</p>
+<p>The upside is that the clang driver is more efficient and does little
+extra work to support universal builds. It also provides better error
+reporting and UI consistency.</p>
+</li>
+<li><p class="first"><strong>Specs</strong></p>
+<p>The clang driver has no direct correspondent for âspecsâ. The
+majority of the functionality that is embedded in specs is in the
+Tool specific argument translation routines. The parts of specs which
+control the compilation pipeline are generally part of the <em>Pipeline</em>
+stage.</p>
+</li>
+<li><p class="first"><strong>Toolchains</strong></p>
+<p>The gcc driver has no direct understanding of tool chains. Each gcc
+binary roughly corresponds to the information which is embedded
+inside a single ToolChain.</p>
+<p>The clang driver is intended to be portable and support complex
+compilation environments. All platform and tool chain specific code
+should be protected behind either abstract or well defined interfaces
+(such as whether the platform supports use as a driver driver).</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="InternalsManual.html">âClangâ CFE Internals Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="PCHInternals.html">Precompiled Header and Modules Internals</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/ExternalClangExamples.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/ExternalClangExamples.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/ExternalClangExamples.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/ExternalClangExamples.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,143 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>External Clang Examples — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Introduction to the Clang AST" href="IntroductionToTheClangAST.html" />
+ <link rel="prev" title="Choosing the Right Interface for Your Application" href="Tooling.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>External Clang Examples</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="Tooling.html">Choosing the Right Interface for Your Application</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="external-clang-examples">
+<h1>External Clang Examples<a class="headerlink" href="#external-clang-examples" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This page provides some examples of the kinds of things that people have
+done with Clang that might serve as useful guides (or starting points) from
+which to develop your own tools. They may be helpful even for something as
+banal (but necessary) as how to set up your build to integrate Clang.</p>
+<p>Clangâs library-based design is deliberately aimed at facilitating use by
+external projects, and we are always interested in improving Clang to
+better serve our external users. Some typical categories of applications
+where Clang is used are:</p>
+<ul class="simple">
+<li>Static analysis.</li>
+<li>Documentation/cross-reference generation.</li>
+</ul>
+<p>If you know of (or wrote!) a tool or project using Clang, please send an
+email to Clangâs <a class="reference external" href="https://lists.llvm.org/mailman/listinfo/cfe-dev">development discussion mailing list</a> to have it added.
+(or if you are already a Clang contributor, feel free to directly commit
+additions). Since the primary purpose of this page is to provide examples
+that can help developers, generally they must have code available.</p>
+</div>
+<div class="section" id="list-of-projects-and-tools">
+<h2>List of projects and tools<a class="headerlink" href="#list-of-projects-and-tools" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt><a class="reference external" href="https://github.com/Andersbakken/rtags/">https://github.com/Andersbakken/rtags/</a></dt>
+<dd>âRTags is a client/server application that indexes c/c++ code and keeps
+a persistent in-memory database of references, symbolnames, completions
+etc.â</dd>
+<dt><a class="reference external" href="https://rprichard.github.com/sourceweb/">https://rprichard.github.com/sourceweb/</a></dt>
+<dd>âA C/C++ source code indexer and navigatorâ</dd>
+<dt><a class="reference external" href="https://github.com/etaoins/qconnectlint">https://github.com/etaoins/qconnectlint</a></dt>
+<dd>âqconnectlint is a Clang tool for statically verifying the consistency
+of signal and slot connections made with Qtâs <code class="docutils literal notranslate"><span class="pre">QObject::connect</span></code>.â</dd>
+<dt><a class="reference external" href="https://github.com/woboq/woboq_codebrowser">https://github.com/woboq/woboq_codebrowser</a></dt>
+<dd>âThe Woboq Code Browser is a web-based code browser for C/C++ projects.
+Check out <a class="reference external" href="https://code.woboq.org/">https://code.woboq.org/</a> for an example!â</dd>
+<dt><a class="reference external" href="https://github.com/mozilla/dxr">https://github.com/mozilla/dxr</a></dt>
+<dd>âDXR is a source code cross-reference tool that uses static analysis
+data collected by instrumented compilers.â</dd>
+<dt><a class="reference external" href="https://github.com/eschulte/clang-mutate">https://github.com/eschulte/clang-mutate</a></dt>
+<dd>âThis tool performs a number of operations on C-language source files.â</dd>
+<dt><a class="reference external" href="https://github.com/gmarpons/Crisp">https://github.com/gmarpons/Crisp</a></dt>
+<dd>âA coding rule validation add-on for LLVM/clang. Crisp rules are written
+in Prolog. A high-level declarative DSL to easily write new rules is under
+development. It will be called CRISP, an acronym for <em>Coding Rules in
+Sugared Prolog</em>.â</dd>
+<dt><a class="reference external" href="https://github.com/drothlis/clang-ctags">https://github.com/drothlis/clang-ctags</a></dt>
+<dd>âGenerate tag file for C++ source code.â</dd>
+<dt><a class="reference external" href="https://github.com/exclipy/clang_indexer">https://github.com/exclipy/clang_indexer</a></dt>
+<dd>âThis is an indexer for C and C++ based on the libclang library.â</dd>
+<dt><a class="reference external" href="https://github.com/holtgrewe/linty">https://github.com/holtgrewe/linty</a></dt>
+<dd>âLinty - C/C++ Style Checking with Python & libclang.â</dd>
+<dt><a class="reference external" href="https://github.com/axw/cmonster">https://github.com/axw/cmonster</a></dt>
+<dd>âcmonster is a Python wrapper for the Clang C++ parser.â</dd>
+<dt><a class="reference external" href="https://github.com/rizsotto/Constantine">https://github.com/rizsotto/Constantine</a></dt>
+<dd>âConstantine is a toy project to learn how to write clang plugin.
+Implements pseudo const analysis. Generates warnings about variables,
+which were declared without const qualifier.â</dd>
+<dt><a class="reference external" href="https://github.com/jessevdk/cldoc">https://github.com/jessevdk/cldoc</a></dt>
+<dd>âcldoc is a Clang based documentation generator for C and C++.
+cldoc tries to solve the issue of writing C/C++ software documentation
+with a modern, non-intrusive and robust approach.â</dd>
+<dt><a class="reference external" href="https://github.com/AlexDenisov/ToyClangPlugin">https://github.com/AlexDenisov/ToyClangPlugin</a></dt>
+<dd>âThe simplest Clang plugin implementing a semantic check for Objective-C.
+This example shows how to use the <code class="docutils literal notranslate"><span class="pre">DiagnosticsEngine</span></code> (emit warnings,
+errors, fixit hints). See also <a class="reference external" href="http://l.rw.rw/clang_plugin">http://l.rw.rw/clang_plugin</a> for
+step-by-step instructions.â</dd>
+<dt><a class="reference external" href="https://phabricator.kde.org/source/clazy">https://phabricator.kde.org/source/clazy</a></dt>
+<dd>âclazy is a compiler plugin which allows clang to understand Qt semantics.
+You get more than 50 Qt related compiler warnings, ranging from unneeded
+memory allocations to misusage of API, including fix-its for automatic
+refactoring.â</dd>
+<dt><a class="reference external" href="https://gerrit.libreoffice.org/gitweb?p=core.git;a=blob_plain;f=compilerplugins/README;hb=HEAD">https://gerrit.libreoffice.org/gitweb?p=core.git;a=blob_plain;f=compilerplugins/README;hb=HEAD</a></dt>
+<dd>âLibreOffice uses a Clang plugin infrastructure to check during the build
+various things, some more, some less specific to the LibreOffice source code.
+There are currently around 50 such checkers, from flagging C-style casts and
+uses of reserved identifiers to ensuring that code adheres to lifecycle
+protocols for certain LibreOffice-specific classes. They may serve as
+examples for writing RecursiveASTVisitor-based plugins.â</dd>
+</dl>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="Tooling.html">Choosing the Right Interface for Your Application</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/FAQ.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/FAQ.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/FAQ.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/FAQ.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,117 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Frequently Asked Questions (FAQ) — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Choosing the Right Interface for Your Application" href="Tooling.html" />
+ <link rel="prev" title="diagtool - clang diagnostics tool" href="CommandGuide/diagtool.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Frequently Asked Questions (FAQ)</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="CommandGuide/diagtool.html">diagtool - clang diagnostics tool</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Tooling.html">Choosing the Right Interface for Your Application</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="frequently-asked-questions-faq">
+<h1>Frequently Asked Questions (FAQ)<a class="headerlink" href="#frequently-asked-questions-faq" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#driver" id="id1">Driver</a><ul>
+<li><a class="reference internal" href="#i-run-clang-cc1-and-get-weird-errors-about-missing-headers" id="id2">I run <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span> <span class="pre">...</span></code> and get weird errors about missing headers</a></li>
+<li><a class="reference internal" href="#i-get-errors-about-some-headers-being-missing-stddef-h-stdarg-h" id="id3">I get errors about some headers being missing (<code class="docutils literal notranslate"><span class="pre">stddef.h</span></code>, <code class="docutils literal notranslate"><span class="pre">stdarg.h</span></code>)</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="driver">
+<h2><a class="toc-backref" href="#id1">Driver</a><a class="headerlink" href="#driver" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="i-run-clang-cc1-and-get-weird-errors-about-missing-headers">
+<h3><a class="toc-backref" href="#id2">I run <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span> <span class="pre">...</span></code> and get weird errors about missing headers</a><a class="headerlink" href="#i-run-clang-cc1-and-get-weird-errors-about-missing-headers" title="Permalink to this headline">¶</a></h3>
+<p>Given this source file:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"Hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If you run:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -cc1 hello.c
+<span class="go">hello.c:1:10: fatal error: 'stdio.h' file not found</span>
+<span class="gp">#</span>include <stdio.h>
+<span class="go"> ^</span>
+<span class="go">1 error generated.</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span></code> is the frontend, <code class="docutils literal notranslate"><span class="pre">clang</span></code> is the <a class="reference internal" href="DriverInternals.html"><span class="doc">driver</span></a>. The driver invokes the frontend with options appropriate
+for your system. To see these options, run:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -### -c hello.c
+</pre></div>
+</div>
+<p>Some clang command line options are driver-only options, some are frontend-only
+options. Frontend-only options are intended to be used only by clang developers.
+Users should not run <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span></code> directly, because <code class="docutils literal notranslate"><span class="pre">-cc1</span></code> options are not
+guaranteed to be stable.</p>
+<p>If you want to use a frontend-only option (âa <code class="docutils literal notranslate"><span class="pre">-cc1</span></code> optionâ), for example
+<code class="docutils literal notranslate"><span class="pre">-ast-dump</span></code>, then you need to take the <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span></code> line generated by the
+driver and add the option you need. Alternatively, you can run
+<code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-Xclang</span> <span class="pre"><option></span> <span class="pre">...</span></code> to force the driver pass <code class="docutils literal notranslate"><span class="pre"><option></span></code> to
+<code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span></code>.</p>
+</div>
+<div class="section" id="i-get-errors-about-some-headers-being-missing-stddef-h-stdarg-h">
+<h3><a class="toc-backref" href="#id3">I get errors about some headers being missing (<code class="docutils literal notranslate"><span class="pre">stddef.h</span></code>, <code class="docutils literal notranslate"><span class="pre">stdarg.h</span></code>)</a><a class="headerlink" href="#i-get-errors-about-some-headers-being-missing-stddef-h-stdarg-h" title="Permalink to this headline">¶</a></h3>
+<p>Some header files (<code class="docutils literal notranslate"><span class="pre">stddef.h</span></code>, <code class="docutils literal notranslate"><span class="pre">stdarg.h</span></code>, and others) are shipped with
+Clang â these are called builtin includes. Clang searches for them in a
+directory relative to the location of the <code class="docutils literal notranslate"><span class="pre">clang</span></code> binary. If you moved the
+<code class="docutils literal notranslate"><span class="pre">clang</span></code> binary, you need to move the builtin headers, too.</p>
+<p>More information can be found in the <a class="reference internal" href="LibTooling.html#libtooling-builtin-includes"><span class="std std-ref">Builtin includes</span></a>
+section.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="CommandGuide/diagtool.html">diagtool - clang diagnostics tool</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Tooling.html">Choosing the Right Interface for Your Application</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/HardwareAssistedAddressSanitizerDesign.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/HardwareAssistedAddressSanitizerDesign.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/HardwareAssistedAddressSanitizerDesign.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/HardwareAssistedAddressSanitizerDesign.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,248 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Hardware-assisted AddressSanitizer Design Documentation — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="prev" title="ABI tags" href="ItaniumMangleAbiTags.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Hardware-assisted AddressSanitizer Design Documentation</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="ItaniumMangleAbiTags.html">ABI tags</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="hardware-assisted-addresssanitizer-design-documentation">
+<h1>Hardware-assisted AddressSanitizer Design Documentation<a class="headerlink" href="#hardware-assisted-addresssanitizer-design-documentation" title="Permalink to this headline">¶</a></h1>
+<p>This page is a design document for
+<strong>hardware-assisted AddressSanitizer</strong> (or <strong>HWASAN</strong>)
+a tool similar to <a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>,
+but based on partial hardware assistance.</p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>
+tags every 8 bytes of the application memory with a 1 byte tag (using <em>shadow memory</em>),
+uses <em>redzones</em> to find buffer-overflows and
+<em>quarantine</em> to find use-after-free.
+The redzones, the quarantine, and, to a less extent, the shadow, are the
+sources of AddressSanitizerâs memory overhead.
+See the <a class="reference external" href="https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf">AddressSanitizer paper</a> for details.</p>
+<p>AArch64 has the <a class="reference external" href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.den0024a/ch12s05s01.html">Address Tagging</a> (or top-byte-ignore, TBI), a hardware feature that allows
+software to use 8 most significant bits of a 64-bit pointer as
+a tag. HWASAN uses <a class="reference external" href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.den0024a/ch12s05s01.html">Address Tagging</a>
+to implement a memory safety tool, similar to <a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>,
+but with smaller memory overhead and slightly different (mostly better)
+accuracy guarantees.</p>
+</div>
+<div class="section" id="algorithm">
+<h2>Algorithm<a class="headerlink" href="#algorithm" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>Every heap/stack/global memory object is forcibly aligned by <cite>TG</cite> bytes
+(<cite>TG</cite> is e.g. 16 or 64). We call <cite>TG</cite> the <strong>tagging granularity</strong>.</li>
+<li>For every such object a random <cite>TS</cite>-bit tag <cite>T</cite> is chosen (<cite>TS</cite>, or tag size, is e.g. 4 or 8)</li>
+<li>The pointer to the object is tagged with <cite>T</cite>.</li>
+<li>The memory for the object is also tagged with <cite>T</cite> (using a <cite>TG=>1</cite> shadow memory)</li>
+<li>Every load and store is instrumented to read the memory tag and compare it
+with the pointer tag, exception is raised on tag mismatch.</li>
+</ul>
+<p>For a more detailed discussion of this approach see <a class="reference external" href="https://arxiv.org/pdf/1802.09517.pdf">https://arxiv.org/pdf/1802.09517.pdf</a></p>
+<div class="section" id="short-granules">
+<h3>Short granules<a class="headerlink" href="#short-granules" title="Permalink to this headline">¶</a></h3>
+<p>A short granule is a granule of size between 1 and <cite>TG-1</cite> bytes. The size
+of a short granule is stored at the location in shadow memory where the
+granuleâs tag is normally stored, while the granuleâs actual tag is stored
+in the last byte of the granule. This means that in order to verify that a
+pointer tag matches a memory tag, HWASAN must check for two possibilities:</p>
+<ul class="simple">
+<li>the pointer tag is equal to the memory tag in shadow memory, or</li>
+<li>the shadow memory tag is actually a short granule size, the value being loaded
+is in bounds of the granule and the pointer tag is equal to the last byte of
+the granule.</li>
+</ul>
+<p>Pointer tags between 1 to <cite>TG-1</cite> are possible and are as likely as any other
+tag. This means that these tags in memory have two interpretations: the full
+tag interpretation (where the pointer tag is between 1 and <cite>TG-1</cite> and the
+last byte of the granule is ordinary data) and the short tag interpretation
+(where the pointer tag is stored in the granule).</p>
+<p>When HWASAN detects an error near a memory tag between 1 and <cite>TG-1</cite>, it
+will show both the memory tag and the last byte of the granule. Currently,
+it is up to the user to disambiguate the two possibilities.</p>
+</div>
+</div>
+<div class="section" id="instrumentation">
+<h2>Instrumentation<a class="headerlink" href="#instrumentation" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="memory-accesses">
+<h3>Memory Accesses<a class="headerlink" href="#memory-accesses" title="Permalink to this headline">¶</a></h3>
+<p>All memory accesses are prefixed with an inline instruction sequence that
+verifies the tags. Currently, the following sequence is used:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>// int foo(int *a) { return *a; }
+// clang -O2 --target=aarch64-linux -fsanitize=hwaddress -fsanitize-recover=hwaddress -c load.c
+foo:
+ 0: 90000008 adrp x8, 0 <__hwasan_shadow>
+ 4: f9400108 ldr x8, [x8] // shadow base (to be resolved by the loader)
+ 8: d344dc09 ubfx x9, x0, #4, #52 // shadow offset
+ c: 38696909 ldrb w9, [x8, x9] // load shadow tag
+ 10: d378fc08 lsr x8, x0, #56 // extract address tag
+ 14: 6b09011f cmp w8, w9 // compare tags
+ 18: 54000061 b.ne 24 <foo+0x24> // jump to short tag handler on mismatch
+ 1c: b9400000 ldr w0, [x0] // original load
+ 20: d65f03c0 ret
+ 24: 7100413f cmp w9, #0x10 // is this a short tag?
+ 28: 54000142 b.cs 50 <foo+0x50> // if not, trap
+ 2c: 12000c0a and w10, w0, #0xf // find the address's position in the short granule
+ 30: 11000d4a add w10, w10, #0x3 // adjust to the position of the last byte loaded
+ 34: 6b09015f cmp w10, w9 // check that position is in bounds
+ 38: 540000c2 b.cs 50 <foo+0x50> // if not, trap
+ 3c: 9240dc09 and x9, x0, #0xffffffffffffff
+ 40: b2400d29 orr x9, x9, #0xf // compute address of last byte of granule
+ 44: 39400129 ldrb w9, [x9] // load tag from it
+ 48: 6b09011f cmp w8, w9 // compare with pointer tag
+ 4c: 54fffe80 b.eq 1c <foo+0x1c> // if so, continue
+ 50: d4212440 brk #0x922 // otherwise trap
+ 54: b9400000 ldr w0, [x0] // tail duplicated original load (to handle recovery)
+ 58: d65f03c0 ret
+</pre></div>
+</div>
+<p>Alternatively, memory accesses are prefixed with a function call.
+On AArch64, a function call is used by default in trapping mode. The code size
+and performance overhead of the call is reduced by using a custom calling
+convention that preserves most registers and is specialized to the register
+containing the address and the type and size of the memory access.</p>
+</div>
+<div class="section" id="heap">
+<h3>Heap<a class="headerlink" href="#heap" title="Permalink to this headline">¶</a></h3>
+<p>Tagging the heap memory/pointers is done by <cite>malloc</cite>.
+This can be based on any malloc that forces all objects to be TG-aligned.
+<cite>free</cite> tags the memory with a different tag.</p>
+</div>
+<div class="section" id="stack">
+<h3>Stack<a class="headerlink" href="#stack" title="Permalink to this headline">¶</a></h3>
+<p>Stack frames are instrumented by aligning all non-promotable allocas
+by <cite>TG</cite> and tagging stack memory in function prologue and epilogue.</p>
+<p>Tags for different allocas in one function are <strong>not</strong> generated
+independently; doing that in a function with <cite>M</cite> allocas would require
+maintaining <cite>M</cite> live stack pointers, significantly increasing register
+pressure. Instead we generate a single base tag value in the prologue,
+and build the tag for alloca number <cite>M</cite> as <cite>ReTag(BaseTag, M)</cite>, where
+ReTag can be as simple as exclusive-or with constant <cite>M</cite>.</p>
+<p>Stack instrumentation is expected to be a major source of overhead,
+but could be optional.</p>
+</div>
+<div class="section" id="globals">
+<h3>Globals<a class="headerlink" href="#globals" title="Permalink to this headline">¶</a></h3>
+<p>TODO: details.</p>
+</div>
+<div class="section" id="error-reporting">
+<h3>Error reporting<a class="headerlink" href="#error-reporting" title="Permalink to this headline">¶</a></h3>
+<p>Errors are generated by the <cite>HLT</cite> instruction and are handled by a signal handler.</p>
+</div>
+<div class="section" id="attribute">
+<h3>Attribute<a class="headerlink" href="#attribute" title="Permalink to this headline">¶</a></h3>
+<p>HWASAN uses its own LLVM IR Attribute <cite>sanitize_hwaddress</cite> and a matching
+C function attribute. An alternative would be to re-use ASANâs attribute
+<cite>sanitize_address</cite>. The reasons to use a separate attribute are:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Users may need to disable ASAN but not HWASAN, or vise versa,
+because the tools have different trade-offs and compatibility issues.</li>
+<li>LLVM (ideally) does not use flags to decide which pass is being used,
+ASAN or HWASAN are being applied, based on the function attributes.</li>
+</ul>
+</div></blockquote>
+<p>This does mean that users of HWASAN may need to add the new attribute
+to the code that already uses the old attribute.</p>
+</div>
+</div>
+<div class="section" id="comparison-with-addresssanitizer">
+<h2>Comparison with AddressSanitizer<a class="headerlink" href="#comparison-with-addresssanitizer" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt>HWASAN:</dt>
+<dd><ul class="first last simple">
+<li>Is less portable than <a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>
+as it relies on hardware <a class="reference external" href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.den0024a/ch12s05s01.html">Address Tagging</a> (AArch64).
+Address Tagging can be emulated with compiler instrumentation,
+but it will require the instrumentation to remove the tags before
+any load or store, which is infeasible in any realistic environment
+that contains non-instrumented code.</li>
+<li>May have compatibility problems if the target code uses higher
+pointer bits for other purposes.</li>
+<li>May require changes in the OS kernels (e.g. Linux seems to dislike
+tagged pointers passed from address space:
+<a class="reference external" href="https://www.kernel.org/doc/Documentation/arm64/tagged-pointers.txt">https://www.kernel.org/doc/Documentation/arm64/tagged-pointers.txt</a>).</li>
+<li><strong>Does not require redzones to detect buffer overflows</strong>,
+but the buffer overflow detection is probabilistic, with roughly
+<cite>1/(2**TS)</cite> chance of missing a bug (6.25% or 0.39% with 4 and 8-bit TS
+respectively).</li>
+<li><strong>Does not require quarantine to detect heap-use-after-free,
+or stack-use-after-return</strong>.
+The detection is similarly probabilistic.</li>
+</ul>
+</dd>
+</dl>
+<p>The memory overhead of HWASAN is expected to be much smaller
+than that of AddressSanitizer:
+<cite>1/TG</cite> extra memory for the shadow
+and some overhead due to <cite>TG</cite>-aligning all objects.</p>
+</div>
+<div class="section" id="supported-architectures">
+<h2>Supported architectures<a class="headerlink" href="#supported-architectures" title="Permalink to this headline">¶</a></h2>
+<p>HWASAN relies on <a class="reference external" href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.den0024a/ch12s05s01.html">Address Tagging</a> which is only available on AArch64.
+For other 64-bit architectures it is possible to remove the address tags
+before every load and store by compiler instrumentation, but this variant
+will have limited deployability since not all of the code is
+typically instrumented.</p>
+<p>The HWASANâs approach is not applicable to 32-bit architectures.</p>
+</div>
+<div class="section" id="related-work">
+<h2>Related Work<a class="headerlink" href="#related-work" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="https://lazytyped.blogspot.com/2017/09/getting-started-with-adi.html">SPARC ADI</a> implements a similar tool mostly in hardware.</li>
+<li><a class="reference external" href="https://www.cc.gatech.edu/~orso/papers/clause.doudalis.orso.prvulovic.pdf">Effective and Efficient Memory Protection Using Dynamic Tainting</a> discusses
+similar approaches (âlock & keyâ).</li>
+<li><a class="reference external" href="https://www.cis.upenn.edu/acg/papers/isca12_watchdog.pdf">Watchdog</a> discussed a heavier, but still somewhat similar
+âlock & keyâ approach.</li>
+<li><em>TODO: add more ârelated workâ links. Suggestions are welcome.</em></li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="ItaniumMangleAbiTags.html">ABI tags</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/HowToSetupToolingForLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/HowToSetupToolingForLLVM.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/HowToSetupToolingForLLVM.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/HowToSetupToolingForLLVM.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,228 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Setup Clang Tooling For LLVM — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="JSON Compilation Database Format Specification" href="JSONCompilationDatabase.html" />
+ <link rel="prev" title="Matching the Clang AST" href="LibASTMatchers.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>How To Setup Clang Tooling For LLVM</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="LibASTMatchers.html">Matching the Clang AST</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="how-to-setup-clang-tooling-for-llvm">
+<h1>How To Setup Clang Tooling For LLVM<a class="headerlink" href="#how-to-setup-clang-tooling-for-llvm" title="Permalink to this headline">¶</a></h1>
+<p>Clang Tooling provides infrastructure to write tools that need syntactic
+and semantic information about a program. This term also relates to a set
+of specific tools using this infrastructure (e.g. <code class="docutils literal notranslate"><span class="pre">clang-check</span></code>). This
+document provides information on how to set up and use Clang Tooling for
+the LLVM source code.</p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang Tooling needs a compilation database to figure out specific build
+options for each file. Currently it can create a compilation database
+from the <code class="docutils literal notranslate"><span class="pre">compile_commands.json</span></code> file, generated by CMake. When
+invoking clang tools, you can either specify a path to a build directory
+using a command line parameter <code class="docutils literal notranslate"><span class="pre">-p</span></code> or let Clang Tooling find this
+file in your source tree. In either case you need to configure your
+build using CMake to use clang tools.</p>
+</div>
+<div class="section" id="setup-clang-tooling-using-cmake-and-make">
+<h2>Setup Clang Tooling Using CMake and Make<a class="headerlink" href="#setup-clang-tooling-using-cmake-and-make" title="Permalink to this headline">¶</a></h2>
+<p>If you intend to use make to build LLVM, you should have CMake 2.8.6 or
+later installed (can be found <a class="reference external" href="https://cmake.org">here</a>).</p>
+<p>First, you need to generate Makefiles for LLVM with CMake. You need to
+make a build directory and run CMake from it:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> mkdir your/build/directory
+<span class="gp">$</span> <span class="nb">cd</span> your/build/directory
+<span class="gp">$</span> cmake -DCMAKE_EXPORT_COMPILE_COMMANDS<span class="o">=</span>ON path/to/llvm/sources
+</pre></div>
+</div>
+<p>If you want to use clang instead of GCC, you can add
+<code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER=/path/to/clang</span> <span class="pre">-DCMAKE_CXX_COMPILER=/path/to/clang++</span></code>.
+You can also use <code class="docutils literal notranslate"><span class="pre">ccmake</span></code>, which provides a curses interface to configure
+CMake variables for lazy people.</p>
+<p>As a result, the new <code class="docutils literal notranslate"><span class="pre">compile_commands.json</span></code> file should appear in the
+current directory. You should link it to the LLVM source tree so that
+Clang Tooling is able to use it:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> ln -s <span class="nv">$PWD</span>/compile_commands.json path/to/llvm/source/
+</pre></div>
+</div>
+<p>Now you are ready to build and test LLVM using make:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> make check-all
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-clang-tools">
+<h2>Using Clang Tools<a class="headerlink" href="#using-clang-tools" title="Permalink to this headline">¶</a></h2>
+<p>After you completed the previous steps, you are ready to run clang tools. If
+you have a recent clang installed, you should have <code class="docutils literal notranslate"><span class="pre">clang-check</span></code> in
+<code class="docutils literal notranslate"><span class="pre">$PATH</span></code>. Try to run it on any <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> file inside the LLVM source tree:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp
+</pre></div>
+</div>
+<p>If youâre using vim, itâs convenient to have clang-check integrated. Put
+this into your <code class="docutils literal notranslate"><span class="pre">.vimrc</span></code>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>function! ClangCheckImpl(cmd)
+ if &autowrite | wall | endif
+ echo "Running " . a:cmd . " ..."
+ let l:output = system(a:cmd)
+ cexpr l:output
+ cwindow
+ let w:quickfix_title = a:cmd
+ if v:shell_error != 0
+ cc
+ endif
+ let g:clang_check_last_cmd = a:cmd
+endfunction
+
+function! ClangCheck()
+ let l:filename = expand('%')
+ if l:filename =~ '\.\(cpp\|cxx\|cc\|c\)$'
+ call ClangCheckImpl("clang-check " . l:filename)
+ elseif exists("g:clang_check_last_cmd")
+ call ClangCheckImpl(g:clang_check_last_cmd)
+ else
+ echo "Can't detect file's compilation arguments and no previous clang-check invocation!"
+ endif
+endfunction
+
+nmap <silent> <F5> :call ClangCheck()<CR><CR>
+</pre></div>
+</div>
+<p>When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In
+case the current file has a different extension (for example, .h), F5
+will re-run the last clang-check invocation made from this vim instance
+(if any). The output will go into the error window, which is opened
+automatically when clang-check finds errors, and can be re-opened with
+<code class="docutils literal notranslate"><span class="pre">:cope</span></code>.</p>
+<p>Other <code class="docutils literal notranslate"><span class="pre">clang-check</span></code> options that can be useful when working with clang
+AST:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-ast-print</span></code> â Build ASTs and then pretty-print them.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-ast-dump</span></code> â Build ASTs and then debug dump them.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-ast-dump-filter=<string></span></code> â Use with <code class="docutils literal notranslate"><span class="pre">-ast-dump</span></code> or <code class="docutils literal notranslate"><span class="pre">-ast-print</span></code> to
+dump/print only AST declaration nodes having a certain substring in a
+qualified name. Use <code class="docutils literal notranslate"><span class="pre">-ast-list</span></code> to list all filterable declaration node
+names.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-ast-list</span></code> â Build ASTs and print the list of declaration node qualified
+names.</li>
+</ul>
+<p>Examples:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer
+<span class="go">Processing: tools/clang/tools/clang-check/ClangCheck.cpp.</span>
+<span class="go">Dumping ::ActionFactory::newASTConsumer:</span>
+<span class="go">clang::ASTConsumer *newASTConsumer() (CompoundStmt 0x44da290 </home/alexfh/local/llvm/tools/clang/tools/clang-check/ClangCheck.cpp:64:40, line:72:3></span>
+<span class="go"> (IfStmt 0x44d97c8 <line:65:5, line:66:45></span>
+<span class="go"> <<<NULL>>></span>
+<span class="go"> (ImplicitCastExpr 0x44d96d0 <line:65:9> '_Bool':'_Bool' <UserDefinedConversion></span>
+<span class="go">...</span>
+<span class="gp">$</span> clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer
+<span class="go">Processing: tools/clang/tools/clang-check/ClangCheck.cpp.</span>
+<span class="go">Printing <anonymous namespace>::ActionFactory::newASTConsumer:</span>
+<span class="go">clang::ASTConsumer *newASTConsumer() {</span>
+<span class="go"> if (this->ASTList.operator _Bool())</span>
+<span class="go"> return clang::CreateASTDeclNodeLister();</span>
+<span class="go"> if (this->ASTDump.operator _Bool())</span>
+<span class="go"> return clang::CreateASTDumper(nullptr /*Dump to stdout.*/,</span>
+<span class="go"> this->ASTDumpFilter);</span>
+<span class="go"> if (this->ASTPrint.operator _Bool())</span>
+<span class="go"> return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter);</span>
+<span class="go"> return new clang::ASTConsumer();</span>
+<span class="go">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="experimental-using-ninja-build-system">
+<h2>(Experimental) Using Ninja Build System<a class="headerlink" href="#experimental-using-ninja-build-system" title="Permalink to this headline">¶</a></h2>
+<p>Optionally you can use the <a class="reference external" href="https://github.com/martine/ninja">Ninja</a>
+build system instead of make. It is aimed at making your builds faster.
+Currently this step will require building Ninja from sources.</p>
+<p>To take advantage of using Clang Tools along with Ninja build you need
+at least CMake 2.8.9.</p>
+<p>Clone the Ninja git repository and build Ninja from sources:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> git clone git://github.com/martine/ninja.git
+<span class="gp">$</span> <span class="nb">cd</span> ninja/
+<span class="gp">$</span> ./bootstrap.py
+</pre></div>
+</div>
+<p>This will result in a single binary <code class="docutils literal notranslate"><span class="pre">ninja</span></code> in the current directory.
+It doesnât require installation and can just be copied to any location
+inside <code class="docutils literal notranslate"><span class="pre">$PATH</span></code>, say <code class="docutils literal notranslate"><span class="pre">/usr/local/bin/</span></code>:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> sudo cp ninja /usr/local/bin/
+<span class="gp">$</span> sudo chmod a+rx /usr/local/bin/ninja
+</pre></div>
+</div>
+<p>After doing all of this, youâll need to generate Ninja build files for
+LLVM with CMake. You need to make a build directory and run CMake from
+it:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> mkdir your/build/directory
+<span class="gp">$</span> <span class="nb">cd</span> your/build/directory
+<span class="gp">$</span> cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS<span class="o">=</span>ON path/to/llvm/sources
+</pre></div>
+</div>
+<p>If you want to use clang instead of GCC, you can add
+<code class="docutils literal notranslate"><span class="pre">-DCMAKE_C_COMPILER=/path/to/clang</span> <span class="pre">-DCMAKE_CXX_COMPILER=/path/to/clang++</span></code>.
+You can also use <code class="docutils literal notranslate"><span class="pre">ccmake</span></code>, which provides a curses interface to configure
+CMake variables in an interactive manner.</p>
+<p>As a result, the new <code class="docutils literal notranslate"><span class="pre">compile_commands.json</span></code> file should appear in the
+current directory. You should link it to the LLVM source tree so that
+Clang Tooling is able to use it:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> ln -s <span class="nv">$PWD</span>/compile_commands.json path/to/llvm/source/
+</pre></div>
+</div>
+<p>Now you are ready to build and test LLVM using Ninja:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> ninja check-all
+</pre></div>
+</div>
+<p>Other target names can be used in the same way as with make.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="LibASTMatchers.html">Matching the Clang AST</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/InternalsManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/InternalsManual.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/InternalsManual.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/InternalsManual.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,2115 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>âClangâ CFE Internals Manual — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Driver Design & Internals" href="DriverInternals.html" />
+ <link rel="prev" title="Clang-Format Style Options" href="ClangFormatStyleOptions.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>âClangâ CFE Internals Manual</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="ClangFormatStyleOptions.html">Clang-Format Style Options</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DriverInternals.html">Driver Design & Internals</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="clang-cfe-internals-manual">
+<h1>âClangâ CFE Internals Manual<a class="headerlink" href="#clang-cfe-internals-manual" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>
+<li><a class="reference internal" href="#llvm-support-library" id="id4">LLVM Support Library</a></li>
+<li><a class="reference internal" href="#the-clang-basic-library" id="id5">The Clang âBasicâ Library</a><ul>
+<li><a class="reference internal" href="#the-diagnostics-subsystem" id="id6">The Diagnostics Subsystem</a><ul>
+<li><a class="reference internal" href="#the-diagnostic-kinds-td-files" id="id7">The <code class="docutils literal notranslate"><span class="pre">Diagnostic*Kinds.td</span></code> files</a></li>
+<li><a class="reference internal" href="#the-format-string" id="id8">The Format String</a></li>
+<li><a class="reference internal" href="#formatting-a-diagnostic-argument" id="id9">Formatting a Diagnostic Argument</a></li>
+<li><a class="reference internal" href="#producing-the-diagnostic" id="id10">Producing the Diagnostic</a></li>
+<li><a class="reference internal" href="#fix-it-hints" id="id11">Fix-It Hints</a></li>
+<li><a class="reference internal" href="#the-diagnosticconsumer-interface" id="id12">The <code class="docutils literal notranslate"><span class="pre">DiagnosticConsumer</span></code> Interface</a></li>
+<li><a class="reference internal" href="#adding-translations-to-clang" id="id13">Adding Translations to Clang</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-sourcelocation-and-sourcemanager-classes" id="id14">The <code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> and <code class="docutils literal notranslate"><span class="pre">SourceManager</span></code> classes</a></li>
+<li><a class="reference internal" href="#sourcerange-and-charsourcerange" id="id15"><code class="docutils literal notranslate"><span class="pre">SourceRange</span></code> and <code class="docutils literal notranslate"><span class="pre">CharSourceRange</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-driver-library" id="id16">The Driver Library</a></li>
+<li><a class="reference internal" href="#precompiled-headers" id="id17">Precompiled Headers</a></li>
+<li><a class="reference internal" href="#the-frontend-library" id="id18">The Frontend Library</a></li>
+<li><a class="reference internal" href="#the-lexer-and-preprocessor-library" id="id19">The Lexer and Preprocessor Library</a><ul>
+<li><a class="reference internal" href="#the-token-class" id="id20">The Token class</a></li>
+<li><a class="reference internal" href="#annotation-tokens" id="id21">Annotation Tokens</a></li>
+<li><a class="reference internal" href="#the-lexer-class" id="id22">The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> class</a></li>
+<li><a class="reference internal" href="#the-tokenlexer-class" id="id23">The <code class="docutils literal notranslate"><span class="pre">TokenLexer</span></code> class</a></li>
+<li><a class="reference internal" href="#the-multipleincludeopt-class" id="id24">The <code class="docutils literal notranslate"><span class="pre">MultipleIncludeOpt</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-parser-library" id="id25">The Parser Library</a></li>
+<li><a class="reference internal" href="#the-ast-library" id="id26">The AST Library</a><ul>
+<li><a class="reference internal" href="#design-philosophy" id="id27">Design philosophy</a><ul>
+<li><a class="reference internal" href="#immutability" id="id28">Immutability</a></li>
+<li><a class="reference internal" href="#faithfulness" id="id29">Faithfulness</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-type-class-and-its-subclasses" id="id30">The <code class="docutils literal notranslate"><span class="pre">Type</span></code> class and its subclasses</a><ul>
+<li><a class="reference internal" href="#canonical-types" id="id31">Canonical Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-qualtype-class" id="id32">The <code class="docutils literal notranslate"><span class="pre">QualType</span></code> class</a></li>
+<li><a class="reference internal" href="#declaration-names" id="id33">Declaration names</a></li>
+<li><a class="reference internal" href="#declaration-contexts" id="id34">Declaration contexts</a><ul>
+<li><a class="reference internal" href="#redeclarations-and-overloads" id="id35">Redeclarations and Overloads</a></li>
+<li><a class="reference internal" href="#lexical-and-semantic-contexts" id="id36">Lexical and Semantic Contexts</a></li>
+<li><a class="reference internal" href="#transparent-declaration-contexts" id="id37">Transparent Declaration Contexts</a></li>
+<li><a class="reference internal" href="#multiply-defined-declaration-contexts" id="id38">Multiply-Defined Declaration Contexts</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-cfg-class" id="id39">The <code class="docutils literal notranslate"><span class="pre">CFG</span></code> class</a><ul>
+<li><a class="reference internal" href="#basic-blocks" id="id40">Basic Blocks</a></li>
+<li><a class="reference internal" href="#entry-and-exit-blocks" id="id41">Entry and Exit Blocks</a></li>
+<li><a class="reference internal" href="#conditional-control-flow" id="id42">Conditional Control-Flow</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#constant-folding-in-the-clang-ast" id="id43">Constant Folding in the Clang AST</a><ul>
+<li><a class="reference internal" href="#implementation-approach" id="id44">Implementation Approach</a></li>
+<li><a class="reference internal" href="#extensions" id="id45">Extensions</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-sema-library" id="id46">The Sema Library</a></li>
+<li><a class="reference internal" href="#the-codegen-library" id="id47">The CodeGen Library</a></li>
+<li><a class="reference internal" href="#how-to-change-clang" id="id48">How to change Clang</a><ul>
+<li><a class="reference internal" href="#how-to-add-an-attribute" id="id49">How to add an attribute</a><ul>
+<li><a class="reference internal" href="#attribute-basics" id="id50">Attribute Basics</a></li>
+<li><a class="reference internal" href="#include-clang-basic-attr-td" id="id51"><code class="docutils literal notranslate"><span class="pre">include/clang/Basic/Attr.td</span></code></a><ul>
+<li><a class="reference internal" href="#spellings" id="id52">Spellings</a></li>
+<li><a class="reference internal" href="#subjects" id="id53">Subjects</a></li>
+<li><a class="reference internal" href="#documentation" id="id54">Documentation</a></li>
+<li><a class="reference internal" href="#arguments" id="id55">Arguments</a></li>
+<li><a class="reference internal" href="#other-properties" id="id56">Other Properties</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#boilerplate" id="id57">Boilerplate</a></li>
+<li><a class="reference internal" href="#semantic-handling" id="id58">Semantic handling</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-add-an-expression-or-statement" id="id59">How to add an expression or statement</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes some of the more important APIs and internal design
+decisions made in the Clang C front-end. The purpose of this document is to
+both capture some of this high level information and also describe some of the
+design decisions behind it. This is meant for people interested in hacking on
+Clang, not for end-users. The description below is categorized by libraries,
+and does not describe any of the clients of the libraries.</p>
+</div>
+<div class="section" id="llvm-support-library">
+<h2><a class="toc-backref" href="#id4">LLVM Support Library</a><a class="headerlink" href="#llvm-support-library" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM <code class="docutils literal notranslate"><span class="pre">libSupport</span></code> library provides many underlying libraries and
+<a class="reference external" href="https://llvm.org/docs/ProgrammersManual.html">data-structures</a>, including
+command line option processing, various containers and a system abstraction
+layer, which is used for file system access.</p>
+</div>
+<div class="section" id="the-clang-basic-library">
+<h2><a class="toc-backref" href="#id5">The Clang âBasicâ Library</a><a class="headerlink" href="#the-clang-basic-library" title="Permalink to this headline">¶</a></h2>
+<p>This library certainly needs a better name. The âbasicâ library contains a
+number of low-level utilities for tracking and manipulating source buffers,
+locations within the source buffers, diagnostics, tokens, target abstraction,
+and information about the subset of the language being compiled for.</p>
+<p>Part of this infrastructure is specific to C (such as the <code class="docutils literal notranslate"><span class="pre">TargetInfo</span></code>
+class), other parts could be reused for other non-C-based languages
+(<code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code>, <code class="docutils literal notranslate"><span class="pre">SourceManager</span></code>, <code class="docutils literal notranslate"><span class="pre">Diagnostics</span></code>, <code class="docutils literal notranslate"><span class="pre">FileManager</span></code>).
+When and if there is future demand we can figure out if it makes sense to
+introduce a new library, move the general classes somewhere else, or introduce
+some other solution.</p>
+<p>We describe the roles of these classes in order of their dependencies.</p>
+<div class="section" id="the-diagnostics-subsystem">
+<h3><a class="toc-backref" href="#id6">The Diagnostics Subsystem</a><a class="headerlink" href="#the-diagnostics-subsystem" title="Permalink to this headline">¶</a></h3>
+<p>The Clang Diagnostics subsystem is an important part of how the compiler
+communicates with the human. Diagnostics are the warnings and errors produced
+when the code is incorrect or dubious. In Clang, each diagnostic produced has
+(at the minimum) a unique ID, an English translation associated with it, a
+<a class="reference internal" href="#sourcelocation"><span class="std std-ref">SourceLocation</span></a> to âput the caretâ, and a severity
+(e.g., <code class="docutils literal notranslate"><span class="pre">WARNING</span></code> or <code class="docutils literal notranslate"><span class="pre">ERROR</span></code>). They can also optionally include a number of
+arguments to the diagnostic (which fill in â%0ââs in the string) as well as a
+number of source ranges that related to the diagnostic.</p>
+<p>In this section, weâll be giving examples produced by the Clang command line
+driver, but diagnostics can be <a class="reference internal" href="#diagnosticconsumer"><span class="std std-ref">rendered in many different ways</span></a> depending on how the <code class="docutils literal notranslate"><span class="pre">DiagnosticConsumer</span></code> interface is
+implemented. A representative example of a diagnostic is:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>t.c:38:15: error: invalid operands to binary expression ('int *' and '_Complex float')
+P = (P-42) + Gamma*4;
+ ~~~~~~ ^ ~~~~~~~
+</pre></div>
+</div>
+<p>In this example, you can see the English translation, the severity (error), you
+can see the source location (the caret (â<code class="docutils literal notranslate"><span class="pre">^</span></code>â) and file/line/column info),
+the source ranges â<code class="docutils literal notranslate"><span class="pre">~~~~</span></code>â, arguments to the diagnostic (â<code class="docutils literal notranslate"><span class="pre">int*</span></code>â and
+â<code class="docutils literal notranslate"><span class="pre">_Complex</span> <span class="pre">float</span></code>â). Youâll have to believe me that there is a unique ID
+backing the diagnostic :).</p>
+<p>Getting all of this to happen has several steps and involves many moving
+pieces, this section describes them and talks about best practices when adding
+a new diagnostic.</p>
+<div class="section" id="the-diagnostic-kinds-td-files">
+<h4><a class="toc-backref" href="#id7">The <code class="docutils literal notranslate"><span class="pre">Diagnostic*Kinds.td</span></code> files</a><a class="headerlink" href="#the-diagnostic-kinds-td-files" title="Permalink to this headline">¶</a></h4>
+<p>Diagnostics are created by adding an entry to one of the
+<code class="docutils literal notranslate"><span class="pre">clang/Basic/Diagnostic*Kinds.td</span></code> files, depending on what library will be
+using it. From this file, <strong class="program">tblgen</strong> generates the unique ID of the
+diagnostic, the severity of the diagnostic and the English translation + format
+string.</p>
+<p>There is little sanity with the naming of the unique IDâs right now. Some
+start with <code class="docutils literal notranslate"><span class="pre">err_</span></code>, <code class="docutils literal notranslate"><span class="pre">warn_</span></code>, <code class="docutils literal notranslate"><span class="pre">ext_</span></code> to encode the severity into the name.
+Since the enum is referenced in the C++ code that produces the diagnostic, it
+is somewhat useful for it to be reasonably short.</p>
+<p>The severity of the diagnostic comes from the set {<code class="docutils literal notranslate"><span class="pre">NOTE</span></code>, <code class="docutils literal notranslate"><span class="pre">REMARK</span></code>,
+<code class="docutils literal notranslate"><span class="pre">WARNING</span></code>,
+<code class="docutils literal notranslate"><span class="pre">EXTENSION</span></code>, <code class="docutils literal notranslate"><span class="pre">EXTWARN</span></code>, <code class="docutils literal notranslate"><span class="pre">ERROR</span></code>}. The <code class="docutils literal notranslate"><span class="pre">ERROR</span></code> severity is used for
+diagnostics indicating the program is never acceptable under any circumstances.
+When an error is emitted, the AST for the input code may not be fully built.
+The <code class="docutils literal notranslate"><span class="pre">EXTENSION</span></code> and <code class="docutils literal notranslate"><span class="pre">EXTWARN</span></code> severities are used for extensions to the
+language that Clang accepts. This means that Clang fully understands and can
+represent them in the AST, but we produce diagnostics to tell the user their
+code is non-portable. The difference is that the former are ignored by
+default, and the later warn by default. The <code class="docutils literal notranslate"><span class="pre">WARNING</span></code> severity is used for
+constructs that are valid in the currently selected source language but that
+are dubious in some way. The <code class="docutils literal notranslate"><span class="pre">REMARK</span></code> severity provides generic information
+about the compilation that is not necessarily related to any dubious code. The
+<code class="docutils literal notranslate"><span class="pre">NOTE</span></code> level is used to staple more information onto previous diagnostics.</p>
+<p>These <em>severities</em> are mapped into a smaller set (the <code class="docutils literal notranslate"><span class="pre">Diagnostic::Level</span></code>
+enum, {<code class="docutils literal notranslate"><span class="pre">Ignored</span></code>, <code class="docutils literal notranslate"><span class="pre">Note</span></code>, <code class="docutils literal notranslate"><span class="pre">Remark</span></code>, <code class="docutils literal notranslate"><span class="pre">Warning</span></code>, <code class="docutils literal notranslate"><span class="pre">Error</span></code>, <code class="docutils literal notranslate"><span class="pre">Fatal</span></code>}) of
+output
+<em>levels</em> by the diagnostics subsystem based on various configuration options.
+Clang internally supports a fully fine grained mapping mechanism that allows
+you to map almost any diagnostic to the output level that you want. The only
+diagnostics that cannot be mapped are <code class="docutils literal notranslate"><span class="pre">NOTE</span></code>s, which always follow the
+severity of the previously emitted diagnostic and <code class="docutils literal notranslate"><span class="pre">ERROR</span></code>s, which can only
+be mapped to <code class="docutils literal notranslate"><span class="pre">Fatal</span></code> (it is not possible to turn an error into a warning, for
+example).</p>
+<p>Diagnostic mappings are used in many ways. For example, if the user specifies
+<code class="docutils literal notranslate"><span class="pre">-pedantic</span></code>, <code class="docutils literal notranslate"><span class="pre">EXTENSION</span></code> maps to <code class="docutils literal notranslate"><span class="pre">Warning</span></code>, if they specify
+<code class="docutils literal notranslate"><span class="pre">-pedantic-errors</span></code>, it turns into <code class="docutils literal notranslate"><span class="pre">Error</span></code>. This is used to implement
+options like <code class="docutils literal notranslate"><span class="pre">-Wunused_macros</span></code>, <code class="docutils literal notranslate"><span class="pre">-Wundef</span></code> etc.</p>
+<p>Mapping to <code class="docutils literal notranslate"><span class="pre">Fatal</span></code> should only be used for diagnostics that are considered so
+severe that error recovery wonât be able to recover sensibly from them (thus
+spewing a ton of bogus errors). One example of this class of error are failure
+to <code class="docutils literal notranslate"><span class="pre">#include</span></code> a file.</p>
+</div>
+<div class="section" id="the-format-string">
+<h4><a class="toc-backref" href="#id8">The Format String</a><a class="headerlink" href="#the-format-string" title="Permalink to this headline">¶</a></h4>
+<p>The format string for the diagnostic is very simple, but it has some power. It
+takes the form of a string in English with markers that indicate where and how
+arguments to the diagnostic are inserted and formatted. For example, here are
+some simple format strings:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="s">"binary integer literals are an extension"</span>
+<span class="s">"format string contains '</span><span class="se">\\</span><span class="s">0' within the string body"</span>
+<span class="s">"more '%%' conversions than data arguments"</span>
+<span class="s">"invalid operands to binary expression (%0 and %1)"</span>
+<span class="s">"overloaded '%0' must be a %select{unary|binary|unary or binary}2 operator"</span>
+ <span class="s">" (has %1 parameter%s1)"</span>
+</pre></div>
+</div>
+<p>These examples show some important points of format strings. You can use any
+plain ASCII character in the diagnostic string except â<code class="docutils literal notranslate"><span class="pre">%</span></code>â without a
+problem, but these are C strings, so you have to use and be aware of all the C
+escape sequences (as in the second example). If you want to produce a â<code class="docutils literal notranslate"><span class="pre">%</span></code>â
+in the output, use the â<code class="docutils literal notranslate"><span class="pre">%%</span></code>â escape sequence, like the third diagnostic.
+Finally, Clang uses the â<code class="docutils literal notranslate"><span class="pre">%...[digit]</span></code>â sequences to specify where and how
+arguments to the diagnostic are formatted.</p>
+<p>Arguments to the diagnostic are numbered according to how they are specified by
+the C++ code that <a class="reference internal" href="#internals-producing-diag"><span class="std std-ref">produces them</span></a>, and are
+referenced by <code class="docutils literal notranslate"><span class="pre">%0</span></code> .. <code class="docutils literal notranslate"><span class="pre">%9</span></code>. If you have more than 10 arguments to your
+diagnostic, you are doing something wrong :). Unlike <code class="docutils literal notranslate"><span class="pre">printf</span></code>, there is no
+requirement that arguments to the diagnostic end up in the output in the same
+order as they are specified, you could have a format string with â<code class="docutils literal notranslate"><span class="pre">%1</span> <span class="pre">%0</span></code>â
+that swaps them, for example. The text in between the percent and digit are
+formatting instructions. If there are no instructions, the argument is just
+turned into a string and substituted in.</p>
+<p>Here are some âbest practicesâ for writing the English format string:</p>
+<ul class="simple">
+<li>Keep the string short. It should ideally fit in the 80 column limit of the
+<code class="docutils literal notranslate"><span class="pre">DiagnosticKinds.td</span></code> file. This avoids the diagnostic wrapping when
+printed, and forces you to think about the important point you are conveying
+with the diagnostic.</li>
+<li>Take advantage of location information. The user will be able to see the
+line and location of the caret, so you donât need to tell them that the
+problem is with the 4th argument to the function: just point to it.</li>
+<li>Do not capitalize the diagnostic string, and do not end it with a period.</li>
+<li>If you need to quote something in the diagnostic string, use single quotes.</li>
+</ul>
+<p>Diagnostics should never take random English strings as arguments: you
+shouldnât use â<code class="docutils literal notranslate"><span class="pre">you</span> <span class="pre">have</span> <span class="pre">a</span> <span class="pre">problem</span> <span class="pre">with</span> <span class="pre">%0</span></code>â and pass in things like â<code class="docutils literal notranslate"><span class="pre">your</span>
+<span class="pre">argument</span></code>â or â<code class="docutils literal notranslate"><span class="pre">your</span> <span class="pre">return</span> <span class="pre">value</span></code>â as arguments. Doing this prevents
+<a class="reference internal" href="#internals-diag-translation"><span class="std std-ref">translating</span></a> the Clang diagnostics to other
+languages (because theyâll get random English words in their otherwise
+localized diagnostic). The exceptions to this are C/C++ language keywords
+(e.g., <code class="docutils literal notranslate"><span class="pre">auto</span></code>, <code class="docutils literal notranslate"><span class="pre">const</span></code>, <code class="docutils literal notranslate"><span class="pre">mutable</span></code>, etc) and C/C++ operators (<code class="docutils literal notranslate"><span class="pre">/=</span></code>).
+Note that things like âpointerâ and âreferenceâ are not keywords. On the other
+hand, you <em>can</em> include anything that comes from the userâs source code,
+including variable names, types, labels, etc. The â<code class="docutils literal notranslate"><span class="pre">select</span></code>â format can be
+used to achieve this sort of thing in a localizable way, see below.</p>
+</div>
+<div class="section" id="formatting-a-diagnostic-argument">
+<h4><a class="toc-backref" href="#id9">Formatting a Diagnostic Argument</a><a class="headerlink" href="#formatting-a-diagnostic-argument" title="Permalink to this headline">¶</a></h4>
+<p>Arguments to diagnostics are fully typed internally, and come from a couple
+different classes: integers, types, names, and random strings. Depending on
+the class of the argument, it can be optionally formatted in different ways.
+This gives the <code class="docutils literal notranslate"><span class="pre">DiagnosticConsumer</span></code> information about what the argument means
+without requiring it to use a specific presentation (consider this MVC for
+Clang :).</p>
+<p>Here are the different diagnostic argument formats currently supported by
+Clang:</p>
+<p><strong>âsâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">"requires</span> <span class="pre">%1</span> <span class="pre">parameter%s1"</span></code></dd>
+<dt>Class:</dt>
+<dd>Integers</dd>
+<dt>Description:</dt>
+<dd>This is a simple formatter for integers that is useful when producing English
+diagnostics. When the integer is 1, it prints as nothing. When the integer
+is not 1, it prints as â<code class="docutils literal notranslate"><span class="pre">s</span></code>â. This allows some simple grammatical forms to
+be to be handled correctly, and eliminates the need to use gross things like
+<code class="docutils literal notranslate"><span class="pre">"requires</span> <span class="pre">%1</span> <span class="pre">parameter(s)"</span></code>.</dd>
+</dl>
+<p><strong>âselectâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">"must</span> <span class="pre">be</span> <span class="pre">a</span> <span class="pre">%select{unary|binary|unary</span> <span class="pre">or</span> <span class="pre">binary}2</span> <span class="pre">operator"</span></code></dd>
+<dt>Class:</dt>
+<dd>Integers</dd>
+<dt>Description:</dt>
+<dd>This format specifier is used to merge multiple related diagnostics together
+into one common one, without requiring the difference to be specified as an
+English string argument. Instead of specifying the string, the diagnostic
+gets an integer argument and the format string selects the numbered option.
+In this case, the â<code class="docutils literal notranslate"><span class="pre">%2</span></code>â value must be an integer in the range [0..2]. If
+it is 0, it prints âunaryâ, if it is 1 it prints âbinaryâ if it is 2, it
+prints âunary or binaryâ. This allows other language translations to
+substitute reasonable words (or entire phrases) based on the semantics of the
+diagnostic instead of having to do things textually. The selected string
+does undergo formatting.</dd>
+</dl>
+<p><strong>âpluralâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">"you</span> <span class="pre">have</span> <span class="pre">%1</span> <span class="pre">%plural{1:mouse|:mice}1</span> <span class="pre">connected</span> <span class="pre">to</span> <span class="pre">your</span> <span class="pre">computer"</span></code></dd>
+<dt>Class:</dt>
+<dd>Integers</dd>
+<dt>Description:</dt>
+<dd><p class="first">This is a formatter for complex plural forms. It is designed to handle even
+the requirements of languages with very complex plural forms, as many Baltic
+languages have. The argument consists of a series of expression/form pairs,
+separated by â:â, where the first form whose expression evaluates to true is
+the result of the modifier.</p>
+<p>An expression can be empty, in which case it is always true. See the example
+at the top. Otherwise, it is a series of one or more numeric conditions,
+separated by â,â. If any condition matches, the expression matches. Each
+numeric condition can take one of three forms.</p>
+<ul class="simple">
+<li>number: A simple decimal number matches if the argument is the same as the
+number. Example: <code class="docutils literal notranslate"><span class="pre">"%plural{1:mouse|:mice}4"</span></code></li>
+<li>range: A range in square brackets matches if the argument is within the
+range. Then range is inclusive on both ends. Example:
+<code class="docutils literal notranslate"><span class="pre">"%plural{0:none|1:one|[2,5]:some|:many}2"</span></code></li>
+<li>modulo: A modulo operator is followed by a number, and equals sign and
+either a number or a range. The tests are the same as for plain numbers
+and ranges, but the argument is taken modulo the number first. Example:
+<code class="docutils literal notranslate"><span class="pre">"%plural{%100=0:even</span> <span class="pre">hundred|%100=[1,50]:lower</span> <span class="pre">half|:everything</span> <span class="pre">else}1"</span></code></li>
+</ul>
+<p class="last">The parser is very unforgiving. A syntax error, even whitespace, will abort,
+as will a failure to match the argument against any expression.</p>
+</dd>
+</dl>
+<p><strong>âordinalâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">"ambiguity</span> <span class="pre">in</span> <span class="pre">%ordinal0</span> <span class="pre">argument"</span></code></dd>
+<dt>Class:</dt>
+<dd>Integers</dd>
+<dt>Description:</dt>
+<dd>This is a formatter which represents the argument number as an ordinal: the
+value <code class="docutils literal notranslate"><span class="pre">1</span></code> becomes <code class="docutils literal notranslate"><span class="pre">1st</span></code>, <code class="docutils literal notranslate"><span class="pre">3</span></code> becomes <code class="docutils literal notranslate"><span class="pre">3rd</span></code>, and so on. Values less
+than <code class="docutils literal notranslate"><span class="pre">1</span></code> are not supported. This formatter is currently hard-coded to use
+English ordinals.</dd>
+</dl>
+<p><strong>âobjcclassâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">"method</span> <span class="pre">%objcclass0</span> <span class="pre">not</span> <span class="pre">found"</span></code></dd>
+<dt>Class:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code></dd>
+<dt>Description:</dt>
+<dd>This is a simple formatter that indicates the <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> corresponds
+to an Objective-C class method selector. As such, it prints the selector
+with a leading â<code class="docutils literal notranslate"><span class="pre">+</span></code>â.</dd>
+</dl>
+<p><strong>âobjcinstanceâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">"method</span> <span class="pre">%objcinstance0</span> <span class="pre">not</span> <span class="pre">found"</span></code></dd>
+<dt>Class:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code></dd>
+<dt>Description:</dt>
+<dd>This is a simple formatter that indicates the <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> corresponds
+to an Objective-C instance method selector. As such, it prints the selector
+with a leading â<code class="docutils literal notranslate"><span class="pre">-</span></code>â.</dd>
+</dl>
+<p><strong>âqâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">"candidate</span> <span class="pre">found</span> <span class="pre">by</span> <span class="pre">name</span> <span class="pre">lookup</span> <span class="pre">is</span> <span class="pre">%q0"</span></code></dd>
+<dt>Class:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">NamedDecl</span> <span class="pre">*</span></code></dd>
+<dt>Description:</dt>
+<dd>This formatter indicates that the fully-qualified name of the declaration
+should be printed, e.g., â<code class="docutils literal notranslate"><span class="pre">std::vector</span></code>â rather than â<code class="docutils literal notranslate"><span class="pre">vector</span></code>â.</dd>
+</dl>
+<p><strong>âdiffâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">"no</span> <span class="pre">known</span> <span class="pre">conversion</span> <span class="pre">%diff{from</span> <span class="pre">$</span> <span class="pre">to</span> <span class="pre">$|from</span> <span class="pre">argument</span> <span class="pre">type</span> <span class="pre">to</span> <span class="pre">parameter</span> <span class="pre">type}1,2"</span></code></dd>
+<dt>Class:</dt>
+<dd><code class="docutils literal notranslate"><span class="pre">QualType</span></code></dd>
+<dt>Description:</dt>
+<dd>This formatter takes two <code class="docutils literal notranslate"><span class="pre">QualType</span></code>s and attempts to print a template
+difference between the two. If tree printing is off, the text inside the
+braces before the pipe is printed, with the formatted text replacing the $.
+If tree printing is on, the text after the pipe is printed and a type tree is
+printed after the diagnostic message.</dd>
+</dl>
+<p>It is really easy to add format specifiers to the Clang diagnostics system, but
+they should be discussed before they are added. If you are creating a lot of
+repetitive diagnostics and/or have an idea for a useful formatter, please bring
+it up on the cfe-dev mailing list.</p>
+<p><strong>âsubâ format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><p class="first">Given the following record definition of type <code class="docutils literal notranslate"><span class="pre">TextSubstitution</span></code>:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>def select_ovl_candidate : TextSubstitution<
+ "%select{function|constructor}0%select{| template| %2}1">;
+</pre></div>
+</div>
+<p>which can be used as</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>def note_ovl_candidate : Note<
+ "candidate %sub{select_ovl_candidate}3,2,1 not viable">;
+</pre></div>
+</div>
+<p class="last">and will act as if it was written
+<code class="docutils literal notranslate"><span class="pre">"candidate</span> <span class="pre">%select{function|constructor}3%select{|</span> <span class="pre">template|</span> <span class="pre">%1}2</span> <span class="pre">not</span> <span class="pre">viable"</span></code>.</p>
+</dd>
+<dt>Description:</dt>
+<dd>This format specifier is used to avoid repeating strings verbatim in multiple
+diagnostics. The argument to <code class="docutils literal notranslate"><span class="pre">%sub</span></code> must name a <code class="docutils literal notranslate"><span class="pre">TextSubstitution</span></code> tblgen
+record. The substitution must specify all arguments used by the substitution,
+and the modifier indexes in the substitution are re-numbered accordingly. The
+substituted text must itself be a valid format string before substitution.</dd>
+</dl>
+</div>
+<div class="section" id="producing-the-diagnostic">
+<span id="internals-producing-diag"></span><h4><a class="toc-backref" href="#id10">Producing the Diagnostic</a><a class="headerlink" href="#producing-the-diagnostic" title="Permalink to this headline">¶</a></h4>
+<p>Now that youâve created the diagnostic in the <code class="docutils literal notranslate"><span class="pre">Diagnostic*Kinds.td</span></code> file, you
+need to write the code that detects the condition in question and emits the new
+diagnostic. Various components of Clang (e.g., the preprocessor, <code class="docutils literal notranslate"><span class="pre">Sema</span></code>,
+etc.) provide a helper function named â<code class="docutils literal notranslate"><span class="pre">Diag</span></code>â. It creates a diagnostic and
+accepts the arguments, ranges, and other information that goes along with it.</p>
+<p>For example, the binary expression error comes from code like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">various</span> <span class="n">things</span> <span class="n">that</span> <span class="n">are</span> <span class="n">bad</span><span class="p">)</span>
+ <span class="n">Diag</span><span class="p">(</span><span class="n">Loc</span><span class="p">,</span> <span class="n">diag</span><span class="o">::</span><span class="n">err_typecheck_invalid_operands</span><span class="p">)</span>
+ <span class="o"><<</span> <span class="n">lex</span><span class="o">-></span><span class="n">getType</span><span class="p">()</span> <span class="o"><<</span> <span class="n">rex</span><span class="o">-></span><span class="n">getType</span><span class="p">()</span>
+ <span class="o"><<</span> <span class="n">lex</span><span class="o">-></span><span class="n">getSourceRange</span><span class="p">()</span> <span class="o"><<</span> <span class="n">rex</span><span class="o">-></span><span class="n">getSourceRange</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>This shows that use of the <code class="docutils literal notranslate"><span class="pre">Diag</span></code> method: it takes a location (a
+<a class="reference internal" href="#sourcelocation"><span class="std std-ref">SourceLocation</span></a> object) and a diagnostic enum value
+(which matches the name from <code class="docutils literal notranslate"><span class="pre">Diagnostic*Kinds.td</span></code>). If the diagnostic takes
+arguments, they are specified with the <code class="docutils literal notranslate"><span class="pre"><<</span></code> operator: the first argument
+becomes <code class="docutils literal notranslate"><span class="pre">%0</span></code>, the second becomes <code class="docutils literal notranslate"><span class="pre">%1</span></code>, etc. The diagnostic interface
+allows you to specify arguments of many different types, including <code class="docutils literal notranslate"><span class="pre">int</span></code> and
+<code class="docutils literal notranslate"><span class="pre">unsigned</span></code> for integer arguments, <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code> and <code class="docutils literal notranslate"><span class="pre">std::string</span></code> for
+string arguments, <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> and <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">IdentifierInfo</span> <span class="pre">*</span></code> for names,
+<code class="docutils literal notranslate"><span class="pre">QualType</span></code> for types, etc. <code class="docutils literal notranslate"><span class="pre">SourceRange</span></code>s are also specified with the
+<code class="docutils literal notranslate"><span class="pre"><<</span></code> operator, but do not have a specific ordering requirement.</p>
+<p>As you can see, adding and producing a diagnostic is pretty straightforward.
+The hard part is deciding exactly what you need to say to help the user,
+picking a suitable wording, and providing the information needed to format it
+correctly. The good news is that the call site that issues a diagnostic should
+be completely independent of how the diagnostic is formatted and in what
+language it is rendered.</p>
+</div>
+<div class="section" id="fix-it-hints">
+<h4><a class="toc-backref" href="#id11">Fix-It Hints</a><a class="headerlink" href="#fix-it-hints" title="Permalink to this headline">¶</a></h4>
+<p>In some cases, the front end emits diagnostics when it is clear that some small
+change to the source code would fix the problem. For example, a missing
+semicolon at the end of a statement or a use of deprecated syntax that is
+easily rewritten into a more modern form. Clang tries very hard to emit the
+diagnostic and recover gracefully in these and other cases.</p>
+<p>However, for these cases where the fix is obvious, the diagnostic can be
+annotated with a hint (referred to as a âfix-it hintâ) that describes how to
+change the code referenced by the diagnostic to fix the problem. For example,
+it might add the missing semicolon at the end of the statement or rewrite the
+use of a deprecated construct into something more palatable. Here is one such
+example from the C++ front end, where we warn about the right-shift operator
+changing meaning from C++98 to C++11:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>test.cpp:3:7: warning: use of right-shift operator ('>>') in template argument
+ will require parentheses in C++11
+A<100 >> 2> *a;
+ ^
+ ( )
+</pre></div>
+</div>
+<p>Here, the fix-it hint is suggesting that parentheses be added, and showing
+exactly where those parentheses would be inserted into the source code. The
+fix-it hints themselves describe what changes to make to the source code in an
+abstract manner, which the text diagnostic printer renders as a line of
+âinsertionsâ below the caret line. <a class="reference internal" href="#diagnosticconsumer"><span class="std std-ref">Other diagnostic clients</span></a> might choose to render the code differently (e.g., as
+markup inline) or even give the user the ability to automatically fix the
+problem.</p>
+<p>Fix-it hints on errors and warnings need to obey these rules:</p>
+<ul class="simple">
+<li>Since they are automatically applied if <code class="docutils literal notranslate"><span class="pre">-Xclang</span> <span class="pre">-fixit</span></code> is passed to the
+driver, they should only be used when itâs very likely they match the userâs
+intent.</li>
+<li>Clang must recover from errors as if the fix-it had been applied.</li>
+<li>Fix-it hints on a warning must not change the meaning of the code.
+However, a hint may clarify the meaning as intentional, for example by adding
+parentheses when the precedence of operators isnât obvious.</li>
+</ul>
+<p>If a fix-it canât obey these rules, put the fix-it on a note. Fix-its on notes
+are not applied automatically.</p>
+<p>All fix-it hints are described by the <code class="docutils literal notranslate"><span class="pre">FixItHint</span></code> class, instances of which
+should be attached to the diagnostic using the <code class="docutils literal notranslate"><span class="pre"><<</span></code> operator in the same way
+that highlighted source ranges and arguments are passed to the diagnostic.
+Fix-it hints can be created with one of three constructors:</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">FixItHint::CreateInsertion(Loc,</span> <span class="pre">Code)</span></code></p>
+<blockquote>
+<div><p>Specifies that the given <code class="docutils literal notranslate"><span class="pre">Code</span></code> (a string) should be inserted before the
+source location <code class="docutils literal notranslate"><span class="pre">Loc</span></code>.</p>
+</div></blockquote>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">FixItHint::CreateRemoval(Range)</span></code></p>
+<blockquote>
+<div><p>Specifies that the code in the given source <code class="docutils literal notranslate"><span class="pre">Range</span></code> should be removed.</p>
+</div></blockquote>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">FixItHint::CreateReplacement(Range,</span> <span class="pre">Code)</span></code></p>
+<blockquote>
+<div><p>Specifies that the code in the given source <code class="docutils literal notranslate"><span class="pre">Range</span></code> should be removed,
+and replaced with the given <code class="docutils literal notranslate"><span class="pre">Code</span></code> string.</p>
+</div></blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="the-diagnosticconsumer-interface">
+<span id="diagnosticconsumer"></span><h4><a class="toc-backref" href="#id12">The <code class="docutils literal notranslate"><span class="pre">DiagnosticConsumer</span></code> Interface</a><a class="headerlink" href="#the-diagnosticconsumer-interface" title="Permalink to this headline">¶</a></h4>
+<p>Once code generates a diagnostic with all of the arguments and the rest of the
+relevant information, Clang needs to know what to do with it. As previously
+mentioned, the diagnostic machinery goes through some filtering to map a
+severity onto a diagnostic level, then (assuming the diagnostic is not mapped
+to â<code class="docutils literal notranslate"><span class="pre">Ignore</span></code>â) it invokes an object that implements the <code class="docutils literal notranslate"><span class="pre">DiagnosticConsumer</span></code>
+interface with the information.</p>
+<p>It is possible to implement this interface in many different ways. For
+example, the normal Clang <code class="docutils literal notranslate"><span class="pre">DiagnosticConsumer</span></code> (named
+<code class="docutils literal notranslate"><span class="pre">TextDiagnosticPrinter</span></code>) turns the arguments into strings (according to the
+various formatting rules), prints out the file/line/column information and the
+string, then prints out the line of code, the source ranges, and the caret.
+However, this behavior isnât required.</p>
+<p>Another implementation of the <code class="docutils literal notranslate"><span class="pre">DiagnosticConsumer</span></code> interface is the
+<code class="docutils literal notranslate"><span class="pre">TextDiagnosticBuffer</span></code> class, which is used when Clang is in <code class="docutils literal notranslate"><span class="pre">-verify</span></code>
+mode. Instead of formatting and printing out the diagnostics, this
+implementation just captures and remembers the diagnostics as they fly by.
+Then <code class="docutils literal notranslate"><span class="pre">-verify</span></code> compares the list of produced diagnostics to the list of
+expected ones. If they disagree, it prints out its own output. Full
+documentation for the <code class="docutils literal notranslate"><span class="pre">-verify</span></code> mode can be found in the Clang API
+documentation for <a class="reference external" href="/doxygen/classclang_1_1VerifyDiagnosticConsumer.html#details">VerifyDiagnosticConsumer</a>.</p>
+<p>There are many other possible implementations of this interface, and this is
+why we prefer diagnostics to pass down rich structured information in
+arguments. For example, an HTML output might want declaration names be
+linkified to where they come from in the source. Another example is that a GUI
+might let you click on typedefs to expand them. This application would want to
+pass significantly more information about types through to the GUI than a
+simple flat string. The interface allows this to happen.</p>
+</div>
+<div class="section" id="adding-translations-to-clang">
+<span id="internals-diag-translation"></span><h4><a class="toc-backref" href="#id13">Adding Translations to Clang</a><a class="headerlink" href="#adding-translations-to-clang" title="Permalink to this headline">¶</a></h4>
+<p>Not possible yet! Diagnostic strings should be written in UTF-8, the client can
+translate to the relevant code page if needed. Each translation completely
+replaces the format string for the diagnostic.</p>
+</div>
+</div>
+<div class="section" id="the-sourcelocation-and-sourcemanager-classes">
+<span id="sourcemanager"></span><span id="sourcelocation"></span><h3><a class="toc-backref" href="#id14">The <code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> and <code class="docutils literal notranslate"><span class="pre">SourceManager</span></code> classes</a><a class="headerlink" href="#the-sourcelocation-and-sourcemanager-classes" title="Permalink to this headline">¶</a></h3>
+<p>Strangely enough, the <code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> class represents a location within the
+source code of the program. Important design points include:</p>
+<ol class="arabic simple">
+<li><code class="docutils literal notranslate"><span class="pre">sizeof(SourceLocation)</span></code> must be extremely small, as these are embedded
+into many AST nodes and are passed around often. Currently it is 32 bits.</li>
+<li><code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> must be a simple value object that can be efficiently
+copied.</li>
+<li>We should be able to represent a source location for any byte of any input
+file. This includes in the middle of tokens, in whitespace, in trigraphs,
+etc.</li>
+<li>A <code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> must encode the current <code class="docutils literal notranslate"><span class="pre">#include</span></code> stack that was
+active when the location was processed. For example, if the location
+corresponds to a token, it should contain the set of <code class="docutils literal notranslate"><span class="pre">#include</span></code>s active
+when the token was lexed. This allows us to print the <code class="docutils literal notranslate"><span class="pre">#include</span></code> stack
+for a diagnostic.</li>
+<li><code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> must be able to describe macro expansions, capturing both
+the ultimate instantiation point and the source of the original character
+data.</li>
+</ol>
+<p>In practice, the <code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> works together with the <code class="docutils literal notranslate"><span class="pre">SourceManager</span></code>
+class to encode two pieces of information about a location: its spelling
+location and its expansion location. For most tokens, these will be the
+same. However, for a macro expansion (or tokens that came from a <code class="docutils literal notranslate"><span class="pre">_Pragma</span></code>
+directive) these will describe the location of the characters corresponding to
+the token and the location where the token was used (i.e., the macro
+expansion point or the location of the <code class="docutils literal notranslate"><span class="pre">_Pragma</span></code> itself).</p>
+<p>The Clang front-end inherently depends on the location of a token being tracked
+correctly. If it is ever incorrect, the front-end may get confused and die.
+The reason for this is that the notion of the âspellingâ of a <code class="docutils literal notranslate"><span class="pre">Token</span></code> in
+Clang depends on being able to find the original input characters for the
+token. This concept maps directly to the âspelling locationâ for the token.</p>
+</div>
+<div class="section" id="sourcerange-and-charsourcerange">
+<h3><a class="toc-backref" href="#id15"><code class="docutils literal notranslate"><span class="pre">SourceRange</span></code> and <code class="docutils literal notranslate"><span class="pre">CharSourceRange</span></code></a><a class="headerlink" href="#sourcerange-and-charsourcerange" title="Permalink to this headline">¶</a></h3>
+<p>Clang represents most source ranges by [first, last], where âfirstâ and âlastâ
+each point to the beginning of their respective tokens. For example consider
+the <code class="docutils literal notranslate"><span class="pre">SourceRange</span></code> of the following statement:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>x = foo + bar;
+^first ^last
+</pre></div>
+</div>
+<p>To map from this representation to a character-based representation, the âlastâ
+location needs to be adjusted to point to (or past) the end of that token with
+either <code class="docutils literal notranslate"><span class="pre">Lexer::MeasureTokenLength()</span></code> or <code class="docutils literal notranslate"><span class="pre">Lexer::getLocForEndOfToken()</span></code>. For
+the rare cases where character-level source ranges information is needed we use
+the <code class="docutils literal notranslate"><span class="pre">CharSourceRange</span></code> class.</p>
+</div>
+</div>
+<div class="section" id="the-driver-library">
+<h2><a class="toc-backref" href="#id16">The Driver Library</a><a class="headerlink" href="#the-driver-library" title="Permalink to this headline">¶</a></h2>
+<p>The clang Driver and library are documented <a class="reference internal" href="DriverInternals.html"><span class="doc">here</span></a>.</p>
+</div>
+<div class="section" id="precompiled-headers">
+<h2><a class="toc-backref" href="#id17">Precompiled Headers</a><a class="headerlink" href="#precompiled-headers" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports precompiled headers (<a class="reference internal" href="PCHInternals.html"><span class="doc">PCH</span></a>), which uses a
+serialized representation of Clangâs internal data structures, encoded with the
+<a class="reference external" href="https://llvm.org/docs/BitCodeFormat.html">LLVM bitstream format</a>.</p>
+</div>
+<div class="section" id="the-frontend-library">
+<h2><a class="toc-backref" href="#id18">The Frontend Library</a><a class="headerlink" href="#the-frontend-library" title="Permalink to this headline">¶</a></h2>
+<p>The Frontend library contains functionality useful for building tools on top of
+the Clang libraries, for example several methods for outputting diagnostics.</p>
+</div>
+<div class="section" id="the-lexer-and-preprocessor-library">
+<h2><a class="toc-backref" href="#id19">The Lexer and Preprocessor Library</a><a class="headerlink" href="#the-lexer-and-preprocessor-library" title="Permalink to this headline">¶</a></h2>
+<p>The Lexer library contains several tightly-connected classes that are involved
+with the nasty process of lexing and preprocessing C source code. The main
+interface to this library for outside clients is the large <code class="docutils literal notranslate"><span class="pre">Preprocessor</span></code>
+class. It contains the various pieces of state that are required to coherently
+read tokens out of a translation unit.</p>
+<p>The core interface to the <code class="docutils literal notranslate"><span class="pre">Preprocessor</span></code> object (once it is set up) is the
+<code class="docutils literal notranslate"><span class="pre">Preprocessor::Lex</span></code> method, which returns the next <a class="reference internal" href="#token"><span class="std std-ref">Token</span></a> from
+the preprocessor stream. There are two types of token providers that the
+preprocessor is capable of reading from: a buffer lexer (provided by the
+<a class="reference internal" href="#lexer"><span class="std std-ref">Lexer</span></a> class) and a buffered token stream (provided by the
+<a class="reference internal" href="#tokenlexer"><span class="std std-ref">TokenLexer</span></a> class).</p>
+<div class="section" id="the-token-class">
+<span id="token"></span><h3><a class="toc-backref" href="#id20">The Token class</a><a class="headerlink" href="#the-token-class" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">Token</span></code> class is used to represent a single lexed token. Tokens are
+intended to be used by the lexer/preprocess and parser libraries, but are not
+intended to live beyond them (for example, they should not live in the ASTs).</p>
+<p>Tokens most often live on the stack (or some other location that is efficient
+to access) as the parser is running, but occasionally do get buffered up. For
+example, macro definitions are stored as a series of tokens, and the C++
+front-end periodically needs to buffer tokens up for tentative parsing and
+various pieces of look-ahead. As such, the size of a <code class="docutils literal notranslate"><span class="pre">Token</span></code> matters. On a
+32-bit system, <code class="docutils literal notranslate"><span class="pre">sizeof(Token)</span></code> is currently 16 bytes.</p>
+<p>Tokens occur in two forms: <a class="reference internal" href="#annotationtoken"><span class="std std-ref">annotation tokens</span></a> and
+normal tokens. Normal tokens are those returned by the lexer, annotation
+tokens represent semantic information and are produced by the parser, replacing
+normal tokens in the token stream. Normal tokens contain the following
+information:</p>
+<ul class="simple">
+<li><strong>A SourceLocation</strong> â This indicates the location of the start of the
+token.</li>
+<li><strong>A length</strong> â This stores the length of the token as stored in the
+<code class="docutils literal notranslate"><span class="pre">SourceBuffer</span></code>. For tokens that include them, this length includes
+trigraphs and escaped newlines which are ignored by later phases of the
+compiler. By pointing into the original source buffer, it is always possible
+to get the original spelling of a token completely accurately.</li>
+<li><strong>IdentifierInfo</strong> â If a token takes the form of an identifier, and if
+identifier lookup was enabled when the token was lexed (e.g., the lexer was
+not reading in ârawâ mode) this contains a pointer to the unique hash value
+for the identifier. Because the lookup happens before keyword
+identification, this field is set even for language keywords like â<code class="docutils literal notranslate"><span class="pre">for</span></code>â.</li>
+<li><strong>TokenKind</strong> â This indicates the kind of token as classified by the
+lexer. This includes things like <code class="docutils literal notranslate"><span class="pre">tok::starequal</span></code> (for the â<code class="docutils literal notranslate"><span class="pre">*=</span></code>â
+operator), <code class="docutils literal notranslate"><span class="pre">tok::ampamp</span></code> for the â<code class="docutils literal notranslate"><span class="pre">&&</span></code>â token, and keyword values (e.g.,
+<code class="docutils literal notranslate"><span class="pre">tok::kw_for</span></code>) for identifiers that correspond to keywords. Note that
+some tokens can be spelled multiple ways. For example, C++ supports
+âoperator keywordsâ, where things like â<code class="docutils literal notranslate"><span class="pre">and</span></code>â are treated exactly like the
+â<code class="docutils literal notranslate"><span class="pre">&&</span></code>â operator. In these cases, the kind value is set to <code class="docutils literal notranslate"><span class="pre">tok::ampamp</span></code>,
+which is good for the parser, which doesnât have to consider both forms. For
+something that cares about which form is used (e.g., the preprocessor
+âstringizeâ operator) the spelling indicates the original form.</li>
+<li><strong>Flags</strong> â There are currently four flags tracked by the
+lexer/preprocessor system on a per-token basis:<ol class="arabic">
+<li><strong>StartOfLine</strong> â This was the first token that occurred on its input
+source line.</li>
+<li><strong>LeadingSpace</strong> â There was a space character either immediately before
+the token or transitively before the token as it was expanded through a
+macro. The definition of this flag is very closely defined by the
+stringizing requirements of the preprocessor.</li>
+<li><strong>DisableExpand</strong> â This flag is used internally to the preprocessor to
+represent identifier tokens which have macro expansion disabled. This
+prevents them from being considered as candidates for macro expansion ever
+in the future.</li>
+<li><strong>NeedsCleaning</strong> â This flag is set if the original spelling for the
+token includes a trigraph or escaped newline. Since this is uncommon,
+many pieces of code can fast-path on tokens that did not need cleaning.</li>
+</ol>
+</li>
+</ul>
+<p>One interesting (and somewhat unusual) aspect of normal tokens is that they
+donât contain any semantic information about the lexed value. For example, if
+the token was a pp-number token, we do not represent the value of the number
+that was lexed (this is left for later pieces of code to decide).
+Additionally, the lexer library has no notion of typedef names vs variable
+names: both are returned as identifiers, and the parser is left to decide
+whether a specific identifier is a typedef or a variable (tracking this
+requires scope information among other things). The parser can do this
+translation by replacing tokens returned by the preprocessor with âAnnotation
+Tokensâ.</p>
+</div>
+<div class="section" id="annotation-tokens">
+<span id="annotationtoken"></span><h3><a class="toc-backref" href="#id21">Annotation Tokens</a><a class="headerlink" href="#annotation-tokens" title="Permalink to this headline">¶</a></h3>
+<p>Annotation tokens are tokens that are synthesized by the parser and injected
+into the preprocessorâs token stream (replacing existing tokens) to record
+semantic information found by the parser. For example, if â<code class="docutils literal notranslate"><span class="pre">foo</span></code>â is found
+to be a typedef, the â<code class="docutils literal notranslate"><span class="pre">foo</span></code>â <code class="docutils literal notranslate"><span class="pre">tok::identifier</span></code> token is replaced with an
+<code class="docutils literal notranslate"><span class="pre">tok::annot_typename</span></code>. This is useful for a couple of reasons: 1) this makes
+it easy to handle qualified type names (e.g., â<code class="docutils literal notranslate"><span class="pre">foo::bar::baz<42>::t</span></code>â) in
+C++ as a single âtokenâ in the parser. 2) if the parser backtracks, the
+reparse does not need to redo semantic analysis to determine whether a token
+sequence is a variable, type, template, etc.</p>
+<p>Annotation tokens are created by the parser and reinjected into the parserâs
+token stream (when backtracking is enabled). Because they can only exist in
+tokens that the preprocessor-proper is done with, it doesnât need to keep
+around flags like âstart of lineâ that the preprocessor uses to do its job.
+Additionally, an annotation token may âcoverâ a sequence of preprocessor tokens
+(e.g., â<code class="docutils literal notranslate"><span class="pre">a::b::c</span></code>â is five preprocessor tokens). As such, the valid fields
+of an annotation token are different than the fields for a normal token (but
+they are multiplexed into the normal <code class="docutils literal notranslate"><span class="pre">Token</span></code> fields):</p>
+<ul class="simple">
+<li><strong>SourceLocation âLocationâ</strong> â The <code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> for the annotation
+token indicates the first token replaced by the annotation token. In the
+example above, it would be the location of the â<code class="docutils literal notranslate"><span class="pre">a</span></code>â identifier.</li>
+<li><strong>SourceLocation âAnnotationEndLocâ</strong> â This holds the location of the last
+token replaced with the annotation token. In the example above, it would be
+the location of the â<code class="docutils literal notranslate"><span class="pre">c</span></code>â identifier.</li>
+<li><strong>void* âAnnotationValueâ</strong> â This contains an opaque object that the
+parser gets from <code class="docutils literal notranslate"><span class="pre">Sema</span></code>. The parser merely preserves the information for
+<code class="docutils literal notranslate"><span class="pre">Sema</span></code> to later interpret based on the annotation token kind.</li>
+<li><strong>TokenKind âKindâ</strong> â This indicates the kind of Annotation token this is.
+See below for the different valid kinds.</li>
+</ul>
+<p>Annotation tokens currently come in three kinds:</p>
+<ol class="arabic simple">
+<li><strong>tok::annot_typename</strong>: This annotation token represents a resolved
+typename token that is potentially qualified. The <code class="docutils literal notranslate"><span class="pre">AnnotationValue</span></code> field
+contains the <code class="docutils literal notranslate"><span class="pre">QualType</span></code> returned by <code class="docutils literal notranslate"><span class="pre">Sema::getTypeName()</span></code>, possibly with
+source location information attached.</li>
+<li><strong>tok::annot_cxxscope</strong>: This annotation token represents a C++ scope
+specifier, such as â<code class="docutils literal notranslate"><span class="pre">A::B::</span></code>â. This corresponds to the grammar
+productions â<em>::</em>â and â<em>:: [opt] nested-name-specifier</em>â. The
+<code class="docutils literal notranslate"><span class="pre">AnnotationValue</span></code> pointer is a <code class="docutils literal notranslate"><span class="pre">NestedNameSpecifier</span> <span class="pre">*</span></code> returned by the
+<code class="docutils literal notranslate"><span class="pre">Sema::ActOnCXXGlobalScopeSpecifier</span></code> and
+<code class="docutils literal notranslate"><span class="pre">Sema::ActOnCXXNestedNameSpecifier</span></code> callbacks.</li>
+<li><strong>tok::annot_template_id</strong>: This annotation token represents a C++
+template-id such as â<code class="docutils literal notranslate"><span class="pre">foo<int,</span> <span class="pre">4></span></code>â, where â<code class="docutils literal notranslate"><span class="pre">foo</span></code>â is the name of a
+template. The <code class="docutils literal notranslate"><span class="pre">AnnotationValue</span></code> pointer is a pointer to a <code class="docutils literal notranslate"><span class="pre">malloc</span></code>âd
+<code class="docutils literal notranslate"><span class="pre">TemplateIdAnnotation</span></code> object. Depending on the context, a parsed
+template-id that names a type might become a typename annotation token (if
+all we care about is the named type, e.g., because it occurs in a type
+specifier) or might remain a template-id token (if we want to retain more
+source location information or produce a new type, e.g., in a declaration of
+a class template specialization). template-id annotation tokens that refer
+to a type can be âupgradedâ to typename annotation tokens by the parser.</li>
+</ol>
+<p>As mentioned above, annotation tokens are not returned by the preprocessor,
+they are formed on demand by the parser. This means that the parser has to be
+aware of cases where an annotation could occur and form it where appropriate.
+This is somewhat similar to how the parser handles Translation Phase 6 of C99:
+String Concatenation (see C99 5.1.1.2). In the case of string concatenation,
+the preprocessor just returns distinct <code class="docutils literal notranslate"><span class="pre">tok::string_literal</span></code> and
+<code class="docutils literal notranslate"><span class="pre">tok::wide_string_literal</span></code> tokens and the parser eats a sequence of them
+wherever the grammar indicates that a string literal can occur.</p>
+<p>In order to do this, whenever the parser expects a <code class="docutils literal notranslate"><span class="pre">tok::identifier</span></code> or
+<code class="docutils literal notranslate"><span class="pre">tok::coloncolon</span></code>, it should call the <code class="docutils literal notranslate"><span class="pre">TryAnnotateTypeOrScopeToken</span></code> or
+<code class="docutils literal notranslate"><span class="pre">TryAnnotateCXXScopeToken</span></code> methods to form the annotation token. These
+methods will maximally form the specified annotation tokens and replace the
+current token with them, if applicable. If the current tokens is not valid for
+an annotation token, it will remain an identifier or â<code class="docutils literal notranslate"><span class="pre">::</span></code>â token.</p>
+</div>
+<div class="section" id="the-lexer-class">
+<span id="lexer"></span><h3><a class="toc-backref" href="#id22">The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> class</a><a class="headerlink" href="#the-lexer-class" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> class provides the mechanics of lexing tokens out of a source
+buffer and deciding what they mean. The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> is complicated by the fact
+that it operates on raw buffers that have not had spelling eliminated (this is
+a necessity to get decent performance), but this is countered with careful
+coding as well as standard performance techniques (for example, the comment
+handling code is vectorized on X86 and PowerPC hosts).</p>
+<p>The lexer has a couple of interesting modal features:</p>
+<ul class="simple">
+<li>The lexer can operate in ârawâ mode. This mode has several features that
+make it possible to quickly lex the file (e.g., it stops identifier lookup,
+doesnât specially handle preprocessor tokens, handles EOF differently, etc).
+This mode is used for lexing within an â<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">0</span></code>â block, for example.</li>
+<li>The lexer can capture and return comments as tokens. This is required to
+support the <code class="docutils literal notranslate"><span class="pre">-C</span></code> preprocessor mode, which passes comments through, and is
+used by the diagnostic checker to identifier expect-error annotations.</li>
+<li>The lexer can be in <code class="docutils literal notranslate"><span class="pre">ParsingFilename</span></code> mode, which happens when
+preprocessing after reading a <code class="docutils literal notranslate"><span class="pre">#include</span></code> directive. This mode changes the
+parsing of â<code class="docutils literal notranslate"><span class="pre"><</span></code>â to return an âangled stringâ instead of a bunch of tokens
+for each thing within the filename.</li>
+<li>When parsing a preprocessor directive (after â<code class="docutils literal notranslate"><span class="pre">#</span></code>â) the
+<code class="docutils literal notranslate"><span class="pre">ParsingPreprocessorDirective</span></code> mode is entered. This changes the parser to
+return EOD at a newline.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> uses a <code class="docutils literal notranslate"><span class="pre">LangOptions</span></code> object to know whether trigraphs are
+enabled, whether C++ or ObjC keywords are recognized, etc.</li>
+</ul>
+<p>In addition to these modes, the lexer keeps track of a couple of other features
+that are local to a lexed buffer, which change as the buffer is lexed:</p>
+<ul class="simple">
+<li>The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> uses <code class="docutils literal notranslate"><span class="pre">BufferPtr</span></code> to keep track of the current character being
+lexed.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> uses <code class="docutils literal notranslate"><span class="pre">IsAtStartOfLine</span></code> to keep track of whether the next
+lexed token will start with its âstart of lineâ bit set.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> keeps track of the current â<code class="docutils literal notranslate"><span class="pre">#if</span></code>â directives that are active
+(which can be nested).</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">Lexer</span></code> keeps track of an <a class="reference internal" href="#multipleincludeopt"><span class="std std-ref">MultipleIncludeOpt</span></a> object, which is used to detect whether the buffer uses
+the standard â<code class="docutils literal notranslate"><span class="pre">#ifndef</span> <span class="pre">XX</span></code> / <code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">XX</span></code>â idiom to prevent multiple
+inclusion. If a buffer does, subsequent includes can be ignored if the
+â<code class="docutils literal notranslate"><span class="pre">XX</span></code>â macro is defined.</li>
+</ul>
+</div>
+<div class="section" id="the-tokenlexer-class">
+<span id="tokenlexer"></span><h3><a class="toc-backref" href="#id23">The <code class="docutils literal notranslate"><span class="pre">TokenLexer</span></code> class</a><a class="headerlink" href="#the-tokenlexer-class" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">TokenLexer</span></code> class is a token provider that returns tokens from a list of
+tokens that came from somewhere else. It typically used for two things: 1)
+returning tokens from a macro definition as it is being expanded 2) returning
+tokens from an arbitrary buffer of tokens. The later use is used by
+<code class="docutils literal notranslate"><span class="pre">_Pragma</span></code> and will most likely be used to handle unbounded look-ahead for the
+C++ parser.</p>
+</div>
+<div class="section" id="the-multipleincludeopt-class">
+<span id="multipleincludeopt"></span><h3><a class="toc-backref" href="#id24">The <code class="docutils literal notranslate"><span class="pre">MultipleIncludeOpt</span></code> class</a><a class="headerlink" href="#the-multipleincludeopt-class" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">MultipleIncludeOpt</span></code> class implements a really simple little state
+machine that is used to detect the standard â<code class="docutils literal notranslate"><span class="pre">#ifndef</span> <span class="pre">XX</span></code> / <code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">XX</span></code>â
+idiom that people typically use to prevent multiple inclusion of headers. If a
+buffer uses this idiom and is subsequently <code class="docutils literal notranslate"><span class="pre">#include</span></code>âd, the preprocessor can
+simply check to see whether the guarding condition is defined or not. If so,
+the preprocessor can completely ignore the include of the header.</p>
+</div>
+</div>
+<div class="section" id="the-parser-library">
+<span id="parser"></span><h2><a class="toc-backref" href="#id25">The Parser Library</a><a class="headerlink" href="#the-parser-library" title="Permalink to this headline">¶</a></h2>
+<p>This library contains a recursive-descent parser that polls tokens from the
+preprocessor and notifies a client of the parsing progress.</p>
+<p>Historically, the parser used to talk to an abstract <code class="docutils literal notranslate"><span class="pre">Action</span></code> interface that
+had virtual methods for parse events, for example <code class="docutils literal notranslate"><span class="pre">ActOnBinOp()</span></code>. When Clang
+grew C++ support, the parser stopped supporting general <code class="docutils literal notranslate"><span class="pre">Action</span></code> clients â
+it now always talks to the <a class="reference internal" href="#sema"><span class="std std-ref">Sema library</span></a>. However, the Parser
+still accesses AST objects only through opaque types like <code class="docutils literal notranslate"><span class="pre">ExprResult</span></code> and
+<code class="docutils literal notranslate"><span class="pre">StmtResult</span></code>. Only <a class="reference internal" href="#sema"><span class="std std-ref">Sema</span></a> looks at the AST node contents of these
+wrappers.</p>
+</div>
+<div class="section" id="the-ast-library">
+<span id="ast"></span><h2><a class="toc-backref" href="#id26">The AST Library</a><a class="headerlink" href="#the-ast-library" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="design-philosophy">
+<span id="astphilosophy"></span><h3><a class="toc-backref" href="#id27">Design philosophy</a><a class="headerlink" href="#design-philosophy" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="immutability">
+<h4><a class="toc-backref" href="#id28">Immutability</a><a class="headerlink" href="#immutability" title="Permalink to this headline">¶</a></h4>
+<p>Clang AST nodes (types, declarations, statements, expressions, and so on) are
+generally designed to be immutable once created. This provides a number of key
+benefits:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Canonicalization of the âmeaningâ of nodes is possible as soon as the nodes
+are created, and is not invalidated by later addition of more information.
+For example, we <a class="reference internal" href="#canonicaltype"><span class="std std-ref">canonicalize types</span></a>, and use a
+canonicalized representation of expressions when determining whether two
+function template declarations involving dependent expressions declare the
+same entity.</li>
+<li>AST nodes can be reused when they have the same meaning. For example, we
+reuse <code class="docutils literal notranslate"><span class="pre">Type</span></code> nodes when representing the same type (but maintain separate
+<code class="docutils literal notranslate"><span class="pre">TypeLoc</span></code>s for each instance where a type is written), and we reuse
+non-dependent <code class="docutils literal notranslate"><span class="pre">Stmt</span></code> and <code class="docutils literal notranslate"><span class="pre">Expr</span></code> nodes across instantiations of a
+template.</li>
+<li>Serialization and deserialization of the AST to/from AST files is simpler:
+we do not need to track modifications made to AST nodes imported from AST
+files and serialize separate âupdate recordsâ.</li>
+</ul>
+</div></blockquote>
+<p>There are unfortunately exceptions to this general approach, such as:</p>
+<blockquote>
+<div><ul class="simple">
+<li>A the first declaration of a redeclarable entity maintains a pointer to the
+most recent declaration of that entity, which naturally needs to change as
+more declarations are parsed.</li>
+<li>Name lookup tables in declaration contexts change after the namespace
+declaration is formed.</li>
+<li>We attempt to maintain only a single declaration for an instantiation of a
+template, rather than having distinct declarations for an instantiation of
+the declaration versus the definition, so template instantiation often
+updates parts of existing declarations.</li>
+<li>Some parts of declarations are required to be instantiated separately (this
+includes default arguments and exception specifications), and such
+instantiations update the existing declaration.</li>
+</ul>
+</div></blockquote>
+<p>These cases tend to be fragile; mutable AST state should be avoided where
+possible.</p>
+<p>As a consequence of this design principle, we typically do not provide setters
+for AST state. (Some are provided for short-term modifications intended to be
+used immediately after an AST node is created and before itâs âpublishedâ as
+part of the complete AST, or where language semantics require after-the-fact
+updates.)</p>
+</div>
+<div class="section" id="faithfulness">
+<h4><a class="toc-backref" href="#id29">Faithfulness</a><a class="headerlink" href="#faithfulness" title="Permalink to this headline">¶</a></h4>
+<p>The AST intends to provide a representation of the program that is faithful to
+the original source. We intend for it to be possible to write refactoring tools
+using only information stored in, or easily reconstructible from, the Clang AST.
+This means that the AST representation should either not desugar source-level
+constructs to simpler forms, or â where made necessary by language semantics
+or a clear engineering tradeoff â should desugar minimally and wrap the result
+in a construct representing the original source form.</p>
+<p>For example, <code class="docutils literal notranslate"><span class="pre">CXXForRangeStmt</span></code> directly represents the syntactic form of a
+range-based for statement, but also holds a semantic representation of the
+range declaration and iterator declarations. It does not contain a
+fully-desugared <code class="docutils literal notranslate"><span class="pre">ForStmt</span></code>, however.</p>
+<p>Some AST nodes (for example, <code class="docutils literal notranslate"><span class="pre">ParenExpr</span></code>) represent only syntax, and others
+(for example, <code class="docutils literal notranslate"><span class="pre">ImplicitCastExpr</span></code>) represent only semantics, but most nodes
+will represent a combination of syntax and associated semantics. Inheritance
+is typically used when representing different (but related) syntaxes for nodes
+with the same or similar semantics.</p>
+</div>
+</div>
+<div class="section" id="the-type-class-and-its-subclasses">
+<span id="type"></span><h3><a class="toc-backref" href="#id30">The <code class="docutils literal notranslate"><span class="pre">Type</span></code> class and its subclasses</a><a class="headerlink" href="#the-type-class-and-its-subclasses" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">Type</span></code> class (and its subclasses) are an important part of the AST.
+Types are accessed through the <code class="docutils literal notranslate"><span class="pre">ASTContext</span></code> class, which implicitly creates
+and uniques them as they are needed. Types have a couple of non-obvious
+features: 1) they do not capture type qualifiers like <code class="docutils literal notranslate"><span class="pre">const</span></code> or <code class="docutils literal notranslate"><span class="pre">volatile</span></code>
+(see <a class="reference internal" href="#qualtype"><span class="std std-ref">QualType</span></a>), and 2) they implicitly capture typedef
+information. Once created, types are immutable (unlike decls).</p>
+<p>Typedefs in C make semantic analysis a bit more complex than it would be without
+them. The issue is that we want to capture typedef information and represent it
+in the AST perfectly, but the semantics of operations need to âsee throughâ
+typedefs. For example, consider this code:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">func</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">typedef</span> <span class="kt">int</span> <span class="n">foo</span><span class="p">;</span>
+ <span class="n">foo</span> <span class="n">X</span><span class="p">,</span> <span class="o">*</span><span class="n">Y</span><span class="p">;</span>
+ <span class="k">typedef</span> <span class="n">foo</span> <span class="o">*</span><span class="n">bar</span><span class="p">;</span>
+ <span class="n">bar</span> <span class="n">Z</span><span class="p">;</span>
+ <span class="o">*</span><span class="n">X</span><span class="p">;</span> <span class="c1">// error</span>
+ <span class="o">**</span><span class="n">Y</span><span class="p">;</span> <span class="c1">// error</span>
+ <span class="o">**</span><span class="n">Z</span><span class="p">;</span> <span class="c1">// error</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The code above is illegal, and thus we expect there to be diagnostics emitted
+on the annotated lines. In this example, we expect to get:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>test.c:6:1: error: indirection requires pointer operand ('foo' invalid)
+ *X; // error
+ ^~
+test.c:7:1: error: indirection requires pointer operand ('foo' invalid)
+ **Y; // error
+ ^~~
+test.c:8:1: error: indirection requires pointer operand ('foo' invalid)
+ **Z; // error
+ ^~~
+</pre></div>
+</div>
+<p>While this example is somewhat silly, it illustrates the point: we want to
+retain typedef information where possible, so that we can emit errors about
+â<code class="docutils literal notranslate"><span class="pre">std::string</span></code>â instead of â<code class="docutils literal notranslate"><span class="pre">std::basic_string<char,</span> <span class="pre">std:...</span></code>â. Doing this
+requires properly keeping typedef information (for example, the type of <code class="docutils literal notranslate"><span class="pre">X</span></code>
+is â<code class="docutils literal notranslate"><span class="pre">foo</span></code>â, not â<code class="docutils literal notranslate"><span class="pre">int</span></code>â), and requires properly propagating it through the
+various operators (for example, the type of <code class="docutils literal notranslate"><span class="pre">*Y</span></code> is â<code class="docutils literal notranslate"><span class="pre">foo</span></code>â, not
+â<code class="docutils literal notranslate"><span class="pre">int</span></code>â). In order to retain this information, the type of these expressions
+is an instance of the <code class="docutils literal notranslate"><span class="pre">TypedefType</span></code> class, which indicates that the type of
+these expressions is a typedef for â<code class="docutils literal notranslate"><span class="pre">foo</span></code>â.</p>
+<p>Representing types like this is great for diagnostics, because the
+user-specified type is always immediately available. There are two problems
+with this: first, various semantic checks need to make judgements about the
+<em>actual structure</em> of a type, ignoring typedefs. Second, we need an efficient
+way to query whether two types are structurally identical to each other,
+ignoring typedefs. The solution to both of these problems is the idea of
+canonical types.</p>
+<div class="section" id="canonical-types">
+<span id="canonicaltype"></span><h4><a class="toc-backref" href="#id31">Canonical Types</a><a class="headerlink" href="#canonical-types" title="Permalink to this headline">¶</a></h4>
+<p>Every instance of the <code class="docutils literal notranslate"><span class="pre">Type</span></code> class contains a canonical type pointer. For
+simple types with no typedefs involved (e.g., â<code class="docutils literal notranslate"><span class="pre">int</span></code>â, â<code class="docutils literal notranslate"><span class="pre">int*</span></code>â,
+â<code class="docutils literal notranslate"><span class="pre">int**</span></code>â), the type just points to itself. For types that have a typedef
+somewhere in their structure (e.g., â<code class="docutils literal notranslate"><span class="pre">foo</span></code>â, â<code class="docutils literal notranslate"><span class="pre">foo*</span></code>â, â<code class="docutils literal notranslate"><span class="pre">foo**</span></code>â,
+â<code class="docutils literal notranslate"><span class="pre">bar</span></code>â), the canonical type pointer points to their structurally equivalent
+type without any typedefs (e.g., â<code class="docutils literal notranslate"><span class="pre">int</span></code>â, â<code class="docutils literal notranslate"><span class="pre">int*</span></code>â, â<code class="docutils literal notranslate"><span class="pre">int**</span></code>â, and
+â<code class="docutils literal notranslate"><span class="pre">int*</span></code>â respectively).</p>
+<p>This design provides a constant time operation (dereferencing the canonical type
+pointer) that gives us access to the structure of types. For example, we can
+trivially tell that â<code class="docutils literal notranslate"><span class="pre">bar</span></code>â and â<code class="docutils literal notranslate"><span class="pre">foo*</span></code>â are the same type by dereferencing
+their canonical type pointers and doing a pointer comparison (they both point
+to the single â<code class="docutils literal notranslate"><span class="pre">int*</span></code>â type).</p>
+<p>Canonical types and typedef types bring up some complexities that must be
+carefully managed. Specifically, the <code class="docutils literal notranslate"><span class="pre">isa</span></code>/<code class="docutils literal notranslate"><span class="pre">cast</span></code>/<code class="docutils literal notranslate"><span class="pre">dyn_cast</span></code> operators
+generally shouldnât be used in code that is inspecting the AST. For example,
+when type checking the indirection operator (unary â<code class="docutils literal notranslate"><span class="pre">*</span></code>â on a pointer), the
+type checker must verify that the operand has a pointer type. It would not be
+correct to check that with â<code class="docutils literal notranslate"><span class="pre">isa<PointerType>(SubExpr->getType())</span></code>â, because
+this predicate would fail if the subexpression had a typedef type.</p>
+<p>The solution to this problem are a set of helper methods on <code class="docutils literal notranslate"><span class="pre">Type</span></code>, used to
+check their properties. In this case, it would be correct to use
+â<code class="docutils literal notranslate"><span class="pre">SubExpr->getType()->isPointerType()</span></code>â to do the check. This predicate will
+return true if the <em>canonical type is a pointer</em>, which is true any time the
+type is structurally a pointer type. The only hard part here is remembering
+not to use the <code class="docutils literal notranslate"><span class="pre">isa</span></code>/<code class="docutils literal notranslate"><span class="pre">cast</span></code>/<code class="docutils literal notranslate"><span class="pre">dyn_cast</span></code> operations.</p>
+<p>The second problem we face is how to get access to the pointer type once we
+know it exists. To continue the example, the result type of the indirection
+operator is the pointee type of the subexpression. In order to determine the
+type, we need to get the instance of <code class="docutils literal notranslate"><span class="pre">PointerType</span></code> that best captures the
+typedef information in the program. If the type of the expression is literally
+a <code class="docutils literal notranslate"><span class="pre">PointerType</span></code>, we can return that, otherwise we have to dig through the
+typedefs to find the pointer type. For example, if the subexpression had type
+â<code class="docutils literal notranslate"><span class="pre">foo*</span></code>â, we could return that type as the result. If the subexpression had
+type â<code class="docutils literal notranslate"><span class="pre">bar</span></code>â, we want to return â<code class="docutils literal notranslate"><span class="pre">foo*</span></code>â (note that we do <em>not</em> want
+â<code class="docutils literal notranslate"><span class="pre">int*</span></code>â). In order to provide all of this, <code class="docutils literal notranslate"><span class="pre">Type</span></code> has a
+<code class="docutils literal notranslate"><span class="pre">getAsPointerType()</span></code> method that checks whether the type is structurally a
+<code class="docutils literal notranslate"><span class="pre">PointerType</span></code> and, if so, returns the best one. If not, it returns a null
+pointer.</p>
+<p>This structure is somewhat mystical, but after meditating on it, it will make
+sense to you :).</p>
+</div>
+</div>
+<div class="section" id="the-qualtype-class">
+<span id="qualtype"></span><h3><a class="toc-backref" href="#id32">The <code class="docutils literal notranslate"><span class="pre">QualType</span></code> class</a><a class="headerlink" href="#the-qualtype-class" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">QualType</span></code> class is designed as a trivial value class that is small,
+passed by-value and is efficient to query. The idea of <code class="docutils literal notranslate"><span class="pre">QualType</span></code> is that it
+stores the type qualifiers (<code class="docutils literal notranslate"><span class="pre">const</span></code>, <code class="docutils literal notranslate"><span class="pre">volatile</span></code>, <code class="docutils literal notranslate"><span class="pre">restrict</span></code>, plus some
+extended qualifiers required by language extensions) separately from the types
+themselves. <code class="docutils literal notranslate"><span class="pre">QualType</span></code> is conceptually a pair of â<code class="docutils literal notranslate"><span class="pre">Type*</span></code>â and the bits
+for these type qualifiers.</p>
+<p>By storing the type qualifiers as bits in the conceptual pair, it is extremely
+efficient to get the set of qualifiers on a <code class="docutils literal notranslate"><span class="pre">QualType</span></code> (just return the field
+of the pair), add a type qualifier (which is a trivial constant-time operation
+that sets a bit), and remove one or more type qualifiers (just return a
+<code class="docutils literal notranslate"><span class="pre">QualType</span></code> with the bitfield set to empty).</p>
+<p>Further, because the bits are stored outside of the type itself, we do not need
+to create duplicates of types with different sets of qualifiers (i.e. there is
+only a single heap allocated â<code class="docutils literal notranslate"><span class="pre">int</span></code>â type: â<code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">int</span></code>â and â<code class="docutils literal notranslate"><span class="pre">volatile</span>
+<span class="pre">const</span> <span class="pre">int</span></code>â both point to the same heap allocated â<code class="docutils literal notranslate"><span class="pre">int</span></code>â type). This
+reduces the heap size used to represent bits and also means we do not have to
+consider qualifiers when uniquing types (<a class="reference internal" href="#type"><span class="std std-ref">Type</span></a> does not even
+contain qualifiers).</p>
+<p>In practice, the two most common type qualifiers (<code class="docutils literal notranslate"><span class="pre">const</span></code> and <code class="docutils literal notranslate"><span class="pre">restrict</span></code>)
+are stored in the low bits of the pointer to the <code class="docutils literal notranslate"><span class="pre">Type</span></code> object, together with
+a flag indicating whether extended qualifiers are present (which must be
+heap-allocated). This means that <code class="docutils literal notranslate"><span class="pre">QualType</span></code> is exactly the same size as a
+pointer.</p>
+</div>
+<div class="section" id="declaration-names">
+<span id="declarationname"></span><h3><a class="toc-backref" href="#id33">Declaration names</a><a class="headerlink" href="#declaration-names" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> class represents the name of a declaration in Clang.
+Declarations in the C family of languages can take several different forms.
+Most declarations are named by simple identifiers, e.g., â<code class="docutils literal notranslate"><span class="pre">f</span></code>â and â<code class="docutils literal notranslate"><span class="pre">x</span></code>â in
+the function declaration <code class="docutils literal notranslate"><span class="pre">f(int</span> <span class="pre">x)</span></code>. In C++, declaration names can also name
+class constructors (â<code class="docutils literal notranslate"><span class="pre">Class</span></code>â in <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">Class</span> <span class="pre">{</span> <span class="pre">Class();</span> <span class="pre">}</span></code>), class
+destructors (â<code class="docutils literal notranslate"><span class="pre">~Class</span></code>â), overloaded operator names (â<code class="docutils literal notranslate"><span class="pre">operator+</span></code>â), and
+conversion functions (â<code class="docutils literal notranslate"><span class="pre">operator</span> <span class="pre">void</span> <span class="pre">const</span> <span class="pre">*</span></code>â). In Objective-C,
+declaration names can refer to the names of Objective-C methods, which involve
+the method name and the parameters, collectively called a <em>selector</em>, e.g.,
+â<code class="docutils literal notranslate"><span class="pre">setWidth:height:</span></code>â. Since all of these kinds of entities â variables,
+functions, Objective-C methods, C++ constructors, destructors, and operators
+â are represented as subclasses of Clangâs common <code class="docutils literal notranslate"><span class="pre">NamedDecl</span></code> class,
+<code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> is designed to efficiently represent any kind of name.</p>
+<p>Given a <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> <code class="docutils literal notranslate"><span class="pre">N</span></code>, <code class="docutils literal notranslate"><span class="pre">N.getNameKind()</span></code> will produce a value
+that describes what kind of name <code class="docutils literal notranslate"><span class="pre">N</span></code> stores. There are 10 options (all of
+the names are inside the <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> class).</p>
+<p><code class="docutils literal notranslate"><span class="pre">Identifier</span></code></p>
+<blockquote>
+<div>The name is a simple identifier. Use <code class="docutils literal notranslate"><span class="pre">N.getAsIdentifierInfo()</span></code> to retrieve
+the corresponding <code class="docutils literal notranslate"><span class="pre">IdentifierInfo*</span></code> pointing to the actual identifier.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">ObjCZeroArgSelector</span></code>, <code class="docutils literal notranslate"><span class="pre">ObjCOneArgSelector</span></code>, <code class="docutils literal notranslate"><span class="pre">ObjCMultiArgSelector</span></code></p>
+<blockquote>
+<div>The name is an Objective-C selector, which can be retrieved as a <code class="docutils literal notranslate"><span class="pre">Selector</span></code>
+instance via <code class="docutils literal notranslate"><span class="pre">N.getObjCSelector()</span></code>. The three possible name kinds for
+Objective-C reflect an optimization within the <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> class:
+both zero- and one-argument selectors are stored as a masked
+<code class="docutils literal notranslate"><span class="pre">IdentifierInfo</span></code> pointer, and therefore require very little space, since
+zero- and one-argument selectors are far more common than multi-argument
+selectors (which use a different structure).</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">CXXConstructorName</span></code></p>
+<blockquote>
+<div>The name is a C++ constructor name. Use <code class="docutils literal notranslate"><span class="pre">N.getCXXNameType()</span></code> to retrieve
+the <a class="reference internal" href="#qualtype"><span class="std std-ref">type</span></a> that this constructor is meant to construct. The
+type is always the canonical type, since all constructors for a given type
+have the same name.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">CXXDestructorName</span></code></p>
+<blockquote>
+<div>The name is a C++ destructor name. Use <code class="docutils literal notranslate"><span class="pre">N.getCXXNameType()</span></code> to retrieve
+the <a class="reference internal" href="#qualtype"><span class="std std-ref">type</span></a> whose destructor is being named. This type is
+always a canonical type.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">CXXConversionFunctionName</span></code></p>
+<blockquote>
+<div>The name is a C++ conversion function. Conversion functions are named
+according to the type they convert to, e.g., â<code class="docutils literal notranslate"><span class="pre">operator</span> <span class="pre">void</span> <span class="pre">const</span> <span class="pre">*</span></code>â.
+Use <code class="docutils literal notranslate"><span class="pre">N.getCXXNameType()</span></code> to retrieve the type that this conversion function
+converts to. This type is always a canonical type.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">CXXOperatorName</span></code></p>
+<blockquote>
+<div>The name is a C++ overloaded operator name. Overloaded operators are named
+according to their spelling, e.g., â<code class="docutils literal notranslate"><span class="pre">operator+</span></code>â or â<code class="docutils literal notranslate"><span class="pre">operator</span> <span class="pre">new</span> <span class="pre">[]</span></code>â.
+Use <code class="docutils literal notranslate"><span class="pre">N.getCXXOverloadedOperator()</span></code> to retrieve the overloaded operator (a
+value of type <code class="docutils literal notranslate"><span class="pre">OverloadedOperatorKind</span></code>).</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">CXXLiteralOperatorName</span></code></p>
+<blockquote>
+<div>The name is a C++11 user defined literal operator. User defined
+Literal operators are named according to the suffix they define,
+e.g., â<code class="docutils literal notranslate"><span class="pre">_foo</span></code>â for â<code class="docutils literal notranslate"><span class="pre">operator</span> <span class="pre">""</span> <span class="pre">_foo</span></code>â. Use
+<code class="docutils literal notranslate"><span class="pre">N.getCXXLiteralIdentifier()</span></code> to retrieve the corresponding
+<code class="docutils literal notranslate"><span class="pre">IdentifierInfo*</span></code> pointing to the identifier.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">CXXUsingDirective</span></code></p>
+<blockquote>
+<div>The name is a C++ using directive. Using directives are not really
+NamedDecls, in that they all have the same name, but they are
+implemented as such in order to store them in DeclContext
+effectively.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code>s are cheap to create, copy, and compare. They require
+only a single pointerâs worth of storage in the common cases (identifiers,
+zero- and one-argument Objective-C selectors) and use dense, uniqued storage
+for the other kinds of names. Two <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code>s can be compared for
+equality (<code class="docutils literal notranslate"><span class="pre">==</span></code>, <code class="docutils literal notranslate"><span class="pre">!=</span></code>) using a simple bitwise comparison, can be ordered
+with <code class="docutils literal notranslate"><span class="pre"><</span></code>, <code class="docutils literal notranslate"><span class="pre">></span></code>, <code class="docutils literal notranslate"><span class="pre"><=</span></code>, and <code class="docutils literal notranslate"><span class="pre">>=</span></code> (which provide a lexicographical ordering
+for normal identifiers but an unspecified ordering for other kinds of names),
+and can be placed into LLVM <code class="docutils literal notranslate"><span class="pre">DenseMap</span></code>s and <code class="docutils literal notranslate"><span class="pre">DenseSet</span></code>s.</p>
+<p><code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> instances can be created in different ways depending on
+what kind of name the instance will store. Normal identifiers
+(<code class="docutils literal notranslate"><span class="pre">IdentifierInfo</span></code> pointers) and Objective-C selectors (<code class="docutils literal notranslate"><span class="pre">Selector</span></code>) can be
+implicitly converted to <code class="docutils literal notranslate"><span class="pre">DeclarationNames</span></code>. Names for C++ constructors,
+destructors, conversion functions, and overloaded operators can be retrieved
+from the <code class="docutils literal notranslate"><span class="pre">DeclarationNameTable</span></code>, an instance of which is available as
+<code class="docutils literal notranslate"><span class="pre">ASTContext::DeclarationNames</span></code>. The member functions
+<code class="docutils literal notranslate"><span class="pre">getCXXConstructorName</span></code>, <code class="docutils literal notranslate"><span class="pre">getCXXDestructorName</span></code>,
+<code class="docutils literal notranslate"><span class="pre">getCXXConversionFunctionName</span></code>, and <code class="docutils literal notranslate"><span class="pre">getCXXOperatorName</span></code>, respectively,
+return <code class="docutils literal notranslate"><span class="pre">DeclarationName</span></code> instances for the four kinds of C++ special function
+names.</p>
+</div>
+<div class="section" id="declaration-contexts">
+<span id="declcontext"></span><h3><a class="toc-backref" href="#id34">Declaration contexts</a><a class="headerlink" href="#declaration-contexts" title="Permalink to this headline">¶</a></h3>
+<p>Every declaration in a program exists within some <em>declaration context</em>, such
+as a translation unit, namespace, class, or function. Declaration contexts in
+Clang are represented by the <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> class, from which the various
+declaration-context AST nodes (<code class="docutils literal notranslate"><span class="pre">TranslationUnitDecl</span></code>, <code class="docutils literal notranslate"><span class="pre">NamespaceDecl</span></code>,
+<code class="docutils literal notranslate"><span class="pre">RecordDecl</span></code>, <code class="docutils literal notranslate"><span class="pre">FunctionDecl</span></code>, etc.) will derive. The <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> class
+provides several facilities common to each declaration context:</p>
+<p>Source-centric vs. Semantics-centric View of Declarations</p>
+<blockquote>
+<div><code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> provides two views of the declarations stored within a
+declaration context. The source-centric view accurately represents the
+program source code as written, including multiple declarations of entities
+where present (see the section <a class="reference internal" href="#redeclarations"><span class="std std-ref">Redeclarations and Overloads</span></a>), while the semantics-centric view represents the program
+semantics. The two views are kept synchronized by semantic analysis while
+the ASTs are being constructed.</div></blockquote>
+<p>Storage of declarations within that context</p>
+<blockquote>
+<div>Every declaration context can contain some number of declarations. For
+example, a C++ class (represented by <code class="docutils literal notranslate"><span class="pre">RecordDecl</span></code>) contains various member
+functions, fields, nested types, and so on. All of these declarations will
+be stored within the <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code>, and one can iterate over the
+declarations via [<code class="docutils literal notranslate"><span class="pre">DeclContext::decls_begin()</span></code>,
+<code class="docutils literal notranslate"><span class="pre">DeclContext::decls_end()</span></code>). This mechanism provides the source-centric
+view of declarations in the context.</div></blockquote>
+<p>Lookup of declarations within that context</p>
+<blockquote>
+<div>The <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> structure provides efficient name lookup for names within
+that declaration context. For example, if <code class="docutils literal notranslate"><span class="pre">N</span></code> is a namespace we can look
+for the name <code class="docutils literal notranslate"><span class="pre">N::f</span></code> using <code class="docutils literal notranslate"><span class="pre">DeclContext::lookup</span></code>. The lookup itself is
+based on a lazily-constructed array (for declaration contexts with a small
+number of declarations) or hash table (for declaration contexts with more
+declarations). The lookup operation provides the semantics-centric view of
+the declarations in the context.</div></blockquote>
+<p>Ownership of declarations</p>
+<blockquote>
+<div>The <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> owns all of the declarations that were declared within
+its declaration context, and is responsible for the management of their
+memory as well as their (de-)serialization.</div></blockquote>
+<p>All declarations are stored within a declaration context, and one can query
+information about the context in which each declaration lives. One can
+retrieve the <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> that contains a particular <code class="docutils literal notranslate"><span class="pre">Decl</span></code> using
+<code class="docutils literal notranslate"><span class="pre">Decl::getDeclContext</span></code>. However, see the section
+<a class="reference internal" href="#lexicalandsemanticcontexts"><span class="std std-ref">Lexical and Semantic Contexts</span></a> for more information about how to interpret
+this context information.</p>
+<div class="section" id="redeclarations-and-overloads">
+<span id="redeclarations"></span><h4><a class="toc-backref" href="#id35">Redeclarations and Overloads</a><a class="headerlink" href="#redeclarations-and-overloads" title="Permalink to this headline">¶</a></h4>
+<p>Within a translation unit, it is common for an entity to be declared several
+times. For example, we might declare a function â<code class="docutils literal notranslate"><span class="pre">f</span></code>â and then later
+re-declare it as part of an inlined definition:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="kt">int</span> <span class="n">y</span><span class="p">,</span> <span class="kt">int</span> <span class="n">z</span> <span class="o">=</span> <span class="mi">1</span><span class="p">);</span>
+
+<span class="kr">inline</span> <span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="kt">int</span> <span class="n">y</span><span class="p">,</span> <span class="kt">int</span> <span class="n">z</span><span class="p">)</span> <span class="p">{</span> <span class="cm">/* ... */</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>The representation of â<code class="docutils literal notranslate"><span class="pre">f</span></code>â differs in the source-centric and
+semantics-centric views of a declaration context. In the source-centric view,
+all redeclarations will be present, in the order they occurred in the source
+code, making this view suitable for clients that wish to see the structure of
+the source code. In the semantics-centric view, only the most recent â<code class="docutils literal notranslate"><span class="pre">f</span></code>â
+will be found by the lookup, since it effectively replaces the first
+declaration of â<code class="docutils literal notranslate"><span class="pre">f</span></code>â.</p>
+<p>(Note that because <code class="docutils literal notranslate"><span class="pre">f</span></code> can be redeclared at block scope, or in a friend
+declaration, etc. it is possible that the declaration of <code class="docutils literal notranslate"><span class="pre">f</span></code> found by name
+lookup will not be the most recent one.)</p>
+<p>In the semantics-centric view, overloading of functions is represented
+explicitly. For example, given two declarations of a function â<code class="docutils literal notranslate"><span class="pre">g</span></code>â that are
+overloaded, e.g.,</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">g</span><span class="p">();</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>the <code class="docutils literal notranslate"><span class="pre">DeclContext::lookup</span></code> operation will return a
+<code class="docutils literal notranslate"><span class="pre">DeclContext::lookup_result</span></code> that contains a range of iterators over
+declarations of â<code class="docutils literal notranslate"><span class="pre">g</span></code>â. Clients that perform semantic analysis on a program
+that is not concerned with the actual source code will primarily use this
+semantics-centric view.</p>
+</div>
+<div class="section" id="lexical-and-semantic-contexts">
+<span id="lexicalandsemanticcontexts"></span><h4><a class="toc-backref" href="#id36">Lexical and Semantic Contexts</a><a class="headerlink" href="#lexical-and-semantic-contexts" title="Permalink to this headline">¶</a></h4>
+<p>Each declaration has two potentially different declaration contexts: a
+<em>lexical</em> context, which corresponds to the source-centric view of the
+declaration context, and a <em>semantic</em> context, which corresponds to the
+semantics-centric view. The lexical context is accessible via
+<code class="docutils literal notranslate"><span class="pre">Decl::getLexicalDeclContext</span></code> while the semantic context is accessible via
+<code class="docutils literal notranslate"><span class="pre">Decl::getDeclContext</span></code>, both of which return <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> pointers. For
+most declarations, the two contexts are identical. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">X</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Here, the semantic and lexical contexts of <code class="docutils literal notranslate"><span class="pre">X::f</span></code> are the <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code>
+associated with the class <code class="docutils literal notranslate"><span class="pre">X</span></code> (itself stored as a <code class="docutils literal notranslate"><span class="pre">RecordDecl</span></code> AST node).
+However, we can now define <code class="docutils literal notranslate"><span class="pre">X::f</span></code> out-of-line:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="n">X</span><span class="o">::</span><span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">17</span><span class="p">)</span> <span class="p">{</span> <span class="cm">/* ... */</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>This definition of â<code class="docutils literal notranslate"><span class="pre">f</span></code>â has different lexical and semantic contexts. The
+lexical context corresponds to the declaration context in which the actual
+declaration occurred in the source code, e.g., the translation unit containing
+<code class="docutils literal notranslate"><span class="pre">X</span></code>. Thus, this declaration of <code class="docutils literal notranslate"><span class="pre">X::f</span></code> can be found by traversing the
+declarations provided by [<code class="docutils literal notranslate"><span class="pre">decls_begin()</span></code>, <code class="docutils literal notranslate"><span class="pre">decls_end()</span></code>) in the
+translation unit.</p>
+<p>The semantic context of <code class="docutils literal notranslate"><span class="pre">X::f</span></code> corresponds to the class <code class="docutils literal notranslate"><span class="pre">X</span></code>, since this
+member function is (semantically) a member of <code class="docutils literal notranslate"><span class="pre">X</span></code>. Lookup of the name <code class="docutils literal notranslate"><span class="pre">f</span></code>
+into the <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> associated with <code class="docutils literal notranslate"><span class="pre">X</span></code> will then return the definition
+of <code class="docutils literal notranslate"><span class="pre">X::f</span></code> (including information about the default argument).</p>
+</div>
+<div class="section" id="transparent-declaration-contexts">
+<h4><a class="toc-backref" href="#id37">Transparent Declaration Contexts</a><a class="headerlink" href="#transparent-declaration-contexts" title="Permalink to this headline">¶</a></h4>
+<p>In C and C++, there are several contexts in which names that are logically
+declared inside another declaration will actually âleakâ out into the enclosing
+scope from the perspective of name lookup. The most obvious instance of this
+behavior is in enumeration types, e.g.,</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="n">Color</span> <span class="p">{</span>
+ <span class="n">Red</span><span class="p">,</span>
+ <span class="n">Green</span><span class="p">,</span>
+ <span class="n">Blue</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Here, <code class="docutils literal notranslate"><span class="pre">Color</span></code> is an enumeration, which is a declaration context that contains
+the enumerators <code class="docutils literal notranslate"><span class="pre">Red</span></code>, <code class="docutils literal notranslate"><span class="pre">Green</span></code>, and <code class="docutils literal notranslate"><span class="pre">Blue</span></code>. Thus, traversing the list of
+declarations contained in the enumeration <code class="docutils literal notranslate"><span class="pre">Color</span></code> will yield <code class="docutils literal notranslate"><span class="pre">Red</span></code>,
+<code class="docutils literal notranslate"><span class="pre">Green</span></code>, and <code class="docutils literal notranslate"><span class="pre">Blue</span></code>. However, outside of the scope of <code class="docutils literal notranslate"><span class="pre">Color</span></code> one can
+name the enumerator <code class="docutils literal notranslate"><span class="pre">Red</span></code> without qualifying the name, e.g.,</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Color</span> <span class="n">c</span> <span class="o">=</span> <span class="n">Red</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>There are other entities in C++ that provide similar behavior. For example,
+linkage specifications that use curly braces:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="s">"C"</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="p">}</span>
+<span class="c1">// f and g are visible here</span>
+</pre></div>
+</div>
+<p>For source-level accuracy, we treat the linkage specification and enumeration
+type as a declaration context in which its enclosed declarations (â<code class="docutils literal notranslate"><span class="pre">Red</span></code>â,
+â<code class="docutils literal notranslate"><span class="pre">Green</span></code>â, and â<code class="docutils literal notranslate"><span class="pre">Blue</span></code>â; â<code class="docutils literal notranslate"><span class="pre">f</span></code>â and â<code class="docutils literal notranslate"><span class="pre">g</span></code>â) are declared. However, these
+declarations are visible outside of the scope of the declaration context.</p>
+<p>These language features (and several others, described below) have roughly the
+same set of requirements: declarations are declared within a particular lexical
+context, but the declarations are also found via name lookup in scopes
+enclosing the declaration itself. This feature is implemented via
+<em>transparent</em> declaration contexts (see
+<code class="docutils literal notranslate"><span class="pre">DeclContext::isTransparentContext()</span></code>), whose declarations are visible in the
+nearest enclosing non-transparent declaration context. This means that the
+lexical context of the declaration (e.g., an enumerator) will be the
+transparent <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> itself, as will the semantic context, but the
+declaration will be visible in every outer context up to and including the
+first non-transparent declaration context (since transparent declaration
+contexts can be nested).</p>
+<p>The transparent <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code>s are:</p>
+<ul>
+<li><p class="first">Enumerations (but not C++11 âscoped enumerationsâ):</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="n">Color</span> <span class="p">{</span>
+ <span class="n">Red</span><span class="p">,</span>
+ <span class="n">Green</span><span class="p">,</span>
+ <span class="n">Blue</span>
+<span class="p">};</span>
+<span class="c1">// Red, Green, and Blue are in scope</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">C++ linkage specifications:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="s">"C"</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="p">}</span>
+<span class="c1">// f and g are in scope</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Anonymous unions and structs:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">LookupTable</span> <span class="p">{</span>
+ <span class="kt">bool</span> <span class="n">IsVector</span><span class="p">;</span>
+ <span class="k">union</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">Item</span><span class="o">></span> <span class="o">*</span><span class="n">Vector</span><span class="p">;</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">set</span><span class="o"><</span><span class="n">Item</span><span class="o">></span> <span class="o">*</span><span class="n">Set</span><span class="p">;</span>
+ <span class="p">};</span>
+<span class="p">};</span>
+
+<span class="n">LookupTable</span> <span class="n">LT</span><span class="p">;</span>
+<span class="n">LT</span><span class="p">.</span><span class="n">Vector</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// Okay: finds Vector inside the unnamed union</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">C++11 inline namespaces:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> <span class="n">mylib</span> <span class="p">{</span>
+ <span class="kr">inline</span> <span class="k">namespace</span> <span class="n">debug</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">X</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+<span class="n">mylib</span><span class="o">::</span><span class="n">X</span> <span class="o">*</span><span class="n">xp</span><span class="p">;</span> <span class="c1">// okay: mylib::X refers to mylib::debug::X</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="multiply-defined-declaration-contexts">
+<span id="multideclcontext"></span><h4><a class="toc-backref" href="#id38">Multiply-Defined Declaration Contexts</a><a class="headerlink" href="#multiply-defined-declaration-contexts" title="Permalink to this headline">¶</a></h4>
+<p>C++ namespaces have the interesting property that
+the namespace can be defined multiple times, and the declarations provided by
+each namespace definition are effectively merged (from the semantic point of
+view). For example, the following two code snippets are semantically
+indistinguishable:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Snippet #1:</span>
+<span class="k">namespace</span> <span class="n">N</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">f</span><span class="p">();</span>
+<span class="p">}</span>
+<span class="k">namespace</span> <span class="n">N</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="c1">// Snippet #2:</span>
+<span class="k">namespace</span> <span class="n">N</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">f</span><span class="p">();</span>
+ <span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In Clangâs representation, the source-centric view of declaration contexts will
+actually have two separate <code class="docutils literal notranslate"><span class="pre">NamespaceDecl</span></code> nodes in Snippet #1, each of which
+is a declaration context that contains a single declaration of â<code class="docutils literal notranslate"><span class="pre">f</span></code>â.
+However, the semantics-centric view provided by name lookup into the namespace
+<code class="docutils literal notranslate"><span class="pre">N</span></code> for â<code class="docutils literal notranslate"><span class="pre">f</span></code>â will return a <code class="docutils literal notranslate"><span class="pre">DeclContext::lookup_result</span></code> that contains a
+range of iterators over declarations of â<code class="docutils literal notranslate"><span class="pre">f</span></code>â.</p>
+<p><code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> manages multiply-defined declaration contexts internally. The
+function <code class="docutils literal notranslate"><span class="pre">DeclContext::getPrimaryContext</span></code> retrieves the âprimaryâ context for
+a given <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> instance, which is the <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code> responsible for
+maintaining the lookup table used for the semantics-centric view. Given a
+DeclContext, one can obtain the set of declaration contexts that are
+semantically connected to this declaration context, in source order, including
+this context (which will be the only result, for non-namespace contexts) via
+<code class="docutils literal notranslate"><span class="pre">DeclContext::collectAllContexts</span></code>. Note that these functions are used
+internally within the lookup and insertion methods of the <code class="docutils literal notranslate"><span class="pre">DeclContext</span></code>, so
+the vast majority of clients can ignore them.</p>
+<p>Because the same entity can be defined multiple times in different modules,
+it is also possible for there to be multiple definitions of (for instance)
+a <code class="docutils literal notranslate"><span class="pre">CXXRecordDecl</span></code>, all of which describe a definition of the same class.
+In such a case, only one of those âdefinitionsâ is considered by Clang to be
+the definiition of the class, and the others are treated as non-defining
+declarations that happen to also contain member declarations. Corresponding
+members in each definition of such multiply-defined classes are identified
+either by redeclaration chains (if the members are <code class="docutils literal notranslate"><span class="pre">Redeclarable</span></code>)
+or by simply a pointer to the canonical declaration (if the declarations
+are not <code class="docutils literal notranslate"><span class="pre">Redeclarable</span></code> â in that case, a <code class="docutils literal notranslate"><span class="pre">Mergeable</span></code> base class is used
+instead).</p>
+</div>
+</div>
+<div class="section" id="the-cfg-class">
+<span id="cfg"></span><h3><a class="toc-backref" href="#id39">The <code class="docutils literal notranslate"><span class="pre">CFG</span></code> class</a><a class="headerlink" href="#the-cfg-class" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">CFG</span></code> class is designed to represent a source-level control-flow graph
+for a single statement (<code class="docutils literal notranslate"><span class="pre">Stmt*</span></code>). Typically instances of <code class="docutils literal notranslate"><span class="pre">CFG</span></code> are
+constructed for function bodies (usually an instance of <code class="docutils literal notranslate"><span class="pre">CompoundStmt</span></code>), but
+can also be instantiated to represent the control-flow of any class that
+subclasses <code class="docutils literal notranslate"><span class="pre">Stmt</span></code>, which includes simple expressions. Control-flow graphs
+are especially useful for performing <a class="reference external" href="https://en.wikipedia.org/wiki/Data_flow_analysis#Sensitivities">flow- or path-sensitive</a> program
+analyses on a given function.</p>
+<div class="section" id="basic-blocks">
+<h4><a class="toc-backref" href="#id40">Basic Blocks</a><a class="headerlink" href="#basic-blocks" title="Permalink to this headline">¶</a></h4>
+<p>Concretely, an instance of <code class="docutils literal notranslate"><span class="pre">CFG</span></code> is a collection of basic blocks. Each basic
+block is an instance of <code class="docutils literal notranslate"><span class="pre">CFGBlock</span></code>, which simply contains an ordered sequence
+of <code class="docutils literal notranslate"><span class="pre">Stmt*</span></code> (each referring to statements in the AST). The ordering of
+statements within a block indicates unconditional flow of control from one
+statement to the next. <a class="reference internal" href="#conditionalcontrolflow"><span class="std std-ref">Conditional control-flow</span></a> is represented using edges between basic blocks. The
+statements within a given <code class="docutils literal notranslate"><span class="pre">CFGBlock</span></code> can be traversed using the
+<code class="docutils literal notranslate"><span class="pre">CFGBlock::*iterator</span></code> interface.</p>
+<p>A <code class="docutils literal notranslate"><span class="pre">CFG</span></code> object owns the instances of <code class="docutils literal notranslate"><span class="pre">CFGBlock</span></code> within the control-flow
+graph it represents. Each <code class="docutils literal notranslate"><span class="pre">CFGBlock</span></code> within a CFG is also uniquely numbered
+(accessible via <code class="docutils literal notranslate"><span class="pre">CFGBlock::getBlockID()</span></code>). Currently the number is based on
+the ordering the blocks were created, but no assumptions should be made on how
+<code class="docutils literal notranslate"><span class="pre">CFGBlocks</span></code> are numbered other than their numbers are unique and that they
+are numbered from 0..N-1 (where N is the number of basic blocks in the CFG).</p>
+</div>
+<div class="section" id="entry-and-exit-blocks">
+<h4><a class="toc-backref" href="#id41">Entry and Exit Blocks</a><a class="headerlink" href="#entry-and-exit-blocks" title="Permalink to this headline">¶</a></h4>
+<p>Each instance of <code class="docutils literal notranslate"><span class="pre">CFG</span></code> contains two special blocks: an <em>entry</em> block
+(accessible via <code class="docutils literal notranslate"><span class="pre">CFG::getEntry()</span></code>), which has no incoming edges, and an
+<em>exit</em> block (accessible via <code class="docutils literal notranslate"><span class="pre">CFG::getExit()</span></code>), which has no outgoing edges.
+Neither block contains any statements, and they serve the role of providing a
+clear entrance and exit for a body of code such as a function body. The
+presence of these empty blocks greatly simplifies the implementation of many
+analyses built on top of CFGs.</p>
+</div>
+<div class="section" id="conditional-control-flow">
+<span id="conditionalcontrolflow"></span><h4><a class="toc-backref" href="#id42">Conditional Control-Flow</a><a class="headerlink" href="#conditional-control-flow" title="Permalink to this headline">¶</a></h4>
+<p>Conditional control-flow (such as those induced by if-statements and loops) is
+represented as edges between <code class="docutils literal notranslate"><span class="pre">CFGBlocks</span></code>. Because different C language
+constructs can induce control-flow, each <code class="docutils literal notranslate"><span class="pre">CFGBlock</span></code> also records an extra
+<code class="docutils literal notranslate"><span class="pre">Stmt*</span></code> that represents the <em>terminator</em> of the block. A terminator is
+simply the statement that caused the control-flow, and is used to identify the
+nature of the conditional control-flow between blocks. For example, in the
+case of an if-statement, the terminator refers to the <code class="docutils literal notranslate"><span class="pre">IfStmt</span></code> object in the
+AST that represented the given branch.</p>
+<p>To illustrate, consider the following code example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">x</span> <span class="o">=</span> <span class="n">x</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">></span> <span class="mi">2</span><span class="p">)</span>
+ <span class="n">x</span><span class="o">++</span><span class="p">;</span>
+ <span class="k">else</span> <span class="p">{</span>
+ <span class="n">x</span> <span class="o">+=</span> <span class="mi">2</span><span class="p">;</span>
+ <span class="n">x</span> <span class="o">*=</span> <span class="mi">2</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="n">x</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>After invoking the parser+semantic analyzer on this code fragment, the AST of
+the body of <code class="docutils literal notranslate"><span class="pre">foo</span></code> is referenced by a single <code class="docutils literal notranslate"><span class="pre">Stmt*</span></code>. We can then construct
+an instance of <code class="docutils literal notranslate"><span class="pre">CFG</span></code> representing the control-flow graph of this function
+body by single call to a static class method:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Stmt</span> <span class="o">*</span><span class="n">FooBody</span> <span class="o">=</span> <span class="p">...</span>
+<span class="n">std</span><span class="o">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">CFG</span><span class="o">></span> <span class="n">FooCFG</span> <span class="o">=</span> <span class="n">CFG</span><span class="o">::</span><span class="n">buildCFG</span><span class="p">(</span><span class="n">FooBody</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Along with providing an interface to iterate over its <code class="docutils literal notranslate"><span class="pre">CFGBlocks</span></code>, the
+<code class="docutils literal notranslate"><span class="pre">CFG</span></code> class also provides methods that are useful for debugging and
+visualizing CFGs. For example, the method <code class="docutils literal notranslate"><span class="pre">CFG::dump()</span></code> dumps a
+pretty-printed version of the CFG to standard error. This is especially useful
+when one is using a debugger such as gdb. For example, here is the output of
+<code class="docutils literal notranslate"><span class="pre">FooCFG->dump()</span></code>:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[ B5 (ENTRY) ]
+ Predecessors (0):
+ Successors (1): B4
+
+[ B4 ]
+ 1: x = x + 1
+ 2: (x > 2)
+ T: if [B4.2]
+ Predecessors (1): B5
+ Successors (2): B3 B2
+
+[ B3 ]
+ 1: x++
+ Predecessors (1): B4
+ Successors (1): B1
+
+[ B2 ]
+ 1: x += 2
+ 2: x *= 2
+ Predecessors (1): B4
+ Successors (1): B1
+
+[ B1 ]
+ 1: return x;
+ Predecessors (2): B2 B3
+ Successors (1): B0
+
+[ B0 (EXIT) ]
+ Predecessors (1): B1
+ Successors (0):
+</pre></div>
+</div>
+<p>For each block, the pretty-printed output displays for each block the number of
+<em>predecessor</em> blocks (blocks that have outgoing control-flow to the given
+block) and <em>successor</em> blocks (blocks that have control-flow that have incoming
+control-flow from the given block). We can also clearly see the special entry
+and exit blocks at the beginning and end of the pretty-printed output. For the
+entry block (block B5), the number of predecessor blocks is 0, while for the
+exit block (block B0) the number of successor blocks is 0.</p>
+<p>The most interesting block here is B4, whose outgoing control-flow represents
+the branching caused by the sole if-statement in <code class="docutils literal notranslate"><span class="pre">foo</span></code>. Of particular
+interest is the second statement in the block, <code class="docutils literal notranslate"><span class="pre">(x</span> <span class="pre">></span> <span class="pre">2)</span></code>, and the terminator,
+printed as <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">[B4.2]</span></code>. The second statement represents the evaluation of
+the condition of the if-statement, which occurs before the actual branching of
+control-flow. Within the <code class="docutils literal notranslate"><span class="pre">CFGBlock</span></code> for B4, the <code class="docutils literal notranslate"><span class="pre">Stmt*</span></code> for the second
+statement refers to the actual expression in the AST for <code class="docutils literal notranslate"><span class="pre">(x</span> <span class="pre">></span> <span class="pre">2)</span></code>. Thus
+pointers to subclasses of <code class="docutils literal notranslate"><span class="pre">Expr</span></code> can appear in the list of statements in a
+block, and not just subclasses of <code class="docutils literal notranslate"><span class="pre">Stmt</span></code> that refer to proper C statements.</p>
+<p>The terminator of block B4 is a pointer to the <code class="docutils literal notranslate"><span class="pre">IfStmt</span></code> object in the AST.
+The pretty-printer outputs <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">[B4.2]</span></code> because the condition expression of
+the if-statement has an actual place in the basic block, and thus the
+terminator is essentially <em>referring</em> to the expression that is the second
+statement of block B4 (i.e., B4.2). In this manner, conditions for
+control-flow (which also includes conditions for loops and switch statements)
+are hoisted into the actual basic block.</p>
+</div>
+</div>
+<div class="section" id="constant-folding-in-the-clang-ast">
+<h3><a class="toc-backref" href="#id43">Constant Folding in the Clang AST</a><a class="headerlink" href="#constant-folding-in-the-clang-ast" title="Permalink to this headline">¶</a></h3>
+<p>There are several places where constants and constant folding matter a lot to
+the Clang front-end. First, in general, we prefer the AST to retain the source
+code as close to how the user wrote it as possible. This means that if they
+wrote â<code class="docutils literal notranslate"><span class="pre">5+4</span></code>â, we want to keep the addition and two constants in the AST, we
+donât want to fold to â<code class="docutils literal notranslate"><span class="pre">9</span></code>â. This means that constant folding in various
+ways turns into a tree walk that needs to handle the various cases.</p>
+<p>However, there are places in both C and C++ that require constants to be
+folded. For example, the C standard defines what an âinteger constant
+expressionâ (i-c-e) is with very precise and specific requirements. The
+language then requires i-c-eâs in a lot of places (for example, the size of a
+bitfield, the value for a case statement, etc). For these, we have to be able
+to constant fold the constants, to do semantic checks (e.g., verify bitfield
+size is non-negative and that case statements arenât duplicated). We aim for
+Clang to be very pedantic about this, diagnosing cases when the code does not
+use an i-c-e where one is required, but accepting the code unless running with
+<code class="docutils literal notranslate"><span class="pre">-pedantic-errors</span></code>.</p>
+<p>Things get a little bit more tricky when it comes to compatibility with
+real-world source code. Specifically, GCC has historically accepted a huge
+superset of expressions as i-c-eâs, and a lot of real world code depends on
+this unfortunate accident of history (including, e.g., the glibc system
+headers). GCC accepts anything its âfoldâ optimizer is capable of reducing to
+an integer constant, which means that the definition of what it accepts changes
+as its optimizer does. One example is that GCC accepts things like â<code class="docutils literal notranslate"><span class="pre">case</span>
+<span class="pre">X-X:</span></code>â even when <code class="docutils literal notranslate"><span class="pre">X</span></code> is a variable, because it can fold this to 0.</p>
+<p>Another issue are how constants interact with the extensions we support, such
+as <code class="docutils literal notranslate"><span class="pre">__builtin_constant_p</span></code>, <code class="docutils literal notranslate"><span class="pre">__builtin_inf</span></code>, <code class="docutils literal notranslate"><span class="pre">__extension__</span></code> and many
+others. C99 obviously does not specify the semantics of any of these
+extensions, and the definition of i-c-e does not include them. However, these
+extensions are often used in real code, and we have to have a way to reason
+about them.</p>
+<p>Finally, this is not just a problem for semantic analysis. The code generator
+and other clients have to be able to fold constants (e.g., to initialize global
+variables) and has to handle a superset of what C99 allows. Further, these
+clients can benefit from extended information. For example, we know that
+â<code class="docutils literal notranslate"><span class="pre">foo()</span> <span class="pre">||</span> <span class="pre">1</span></code>â always evaluates to <code class="docutils literal notranslate"><span class="pre">true</span></code>, but we canât replace the
+expression with <code class="docutils literal notranslate"><span class="pre">true</span></code> because it has side effects.</p>
+<div class="section" id="implementation-approach">
+<h4><a class="toc-backref" href="#id44">Implementation Approach</a><a class="headerlink" href="#implementation-approach" title="Permalink to this headline">¶</a></h4>
+<p>After trying several different approaches, weâve finally converged on a design
+(Note, at the time of this writing, not all of this has been implemented,
+consider this a design goal!). Our basic approach is to define a single
+recursive evaluation method (<code class="docutils literal notranslate"><span class="pre">Expr::Evaluate</span></code>), which is implemented
+in <code class="docutils literal notranslate"><span class="pre">AST/ExprConstant.cpp</span></code>. Given an expression with âscalarâ type (integer,
+fp, complex, or pointer) this method returns the following information:</p>
+<ul class="simple">
+<li>Whether the expression is an integer constant expression, a general constant
+that was folded but has no side effects, a general constant that was folded
+but that does have side effects, or an uncomputable/unfoldable value.</li>
+<li>If the expression was computable in any way, this method returns the
+<code class="docutils literal notranslate"><span class="pre">APValue</span></code> for the result of the expression.</li>
+<li>If the expression is not evaluatable at all, this method returns information
+on one of the problems with the expression. This includes a
+<code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> for where the problem is, and a diagnostic ID that explains
+the problem. The diagnostic should have <code class="docutils literal notranslate"><span class="pre">ERROR</span></code> type.</li>
+<li>If the expression is not an integer constant expression, this method returns
+information on one of the problems with the expression. This includes a
+<code class="docutils literal notranslate"><span class="pre">SourceLocation</span></code> for where the problem is, and a diagnostic ID that
+explains the problem. The diagnostic should have <code class="docutils literal notranslate"><span class="pre">EXTENSION</span></code> type.</li>
+</ul>
+<p>This information gives various clients the flexibility that they want, and we
+will eventually have some helper methods for various extensions. For example,
+<code class="docutils literal notranslate"><span class="pre">Sema</span></code> should have a <code class="docutils literal notranslate"><span class="pre">Sema::VerifyIntegerConstantExpression</span></code> method, which
+calls <code class="docutils literal notranslate"><span class="pre">Evaluate</span></code> on the expression. If the expression is not foldable, the
+error is emitted, and it would return <code class="docutils literal notranslate"><span class="pre">true</span></code>. If the expression is not an
+i-c-e, the <code class="docutils literal notranslate"><span class="pre">EXTENSION</span></code> diagnostic is emitted. Finally it would return
+<code class="docutils literal notranslate"><span class="pre">false</span></code> to indicate that the AST is OK.</p>
+<p>Other clients can use the information in other ways, for example, codegen can
+just use expressions that are foldable in any way.</p>
+</div>
+<div class="section" id="extensions">
+<h4><a class="toc-backref" href="#id45">Extensions</a><a class="headerlink" href="#extensions" title="Permalink to this headline">¶</a></h4>
+<p>This section describes how some of the various extensions Clang supports
+interacts with constant evaluation:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__extension__</span></code>: The expression form of this extension causes any
+evaluatable subexpression to be accepted as an integer constant expression.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_constant_p</span></code>: This returns true (as an integer constant
+expression) if the operand evaluates to either a numeric value (that is, not
+a pointer cast to integral type) of integral, enumeration, floating or
+complex type, or if it evaluates to the address of the first character of a
+string literal (possibly cast to some other type). As a special case, if
+<code class="docutils literal notranslate"><span class="pre">__builtin_constant_p</span></code> is the (potentially parenthesized) condition of a
+conditional operator expression (â<code class="docutils literal notranslate"><span class="pre">?:</span></code>â), only the true side of the
+conditional operator is considered, and it is evaluated with full constant
+folding.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_choose_expr</span></code>: The condition is required to be an integer
+constant expression, but we accept any constant as an âextension of an
+extensionâ. This only evaluates one operand depending on which way the
+condition evaluates.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_classify_type</span></code>: This always returns an integer constant
+expression.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_inf,</span> <span class="pre">nan,</span> <span class="pre">...</span></code>: These are treated just like a floating-point
+literal.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_abs,</span> <span class="pre">copysign,</span> <span class="pre">...</span></code>: These are constant folded as general
+constant expressions.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_strlen</span></code> and <code class="docutils literal notranslate"><span class="pre">strlen</span></code>: These are constant folded as integer
+constant expressions if the argument is a string literal.</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="section" id="the-sema-library">
+<span id="sema"></span><h2><a class="toc-backref" href="#id46">The Sema Library</a><a class="headerlink" href="#the-sema-library" title="Permalink to this headline">¶</a></h2>
+<p>This library is called by the <a class="reference internal" href="#parser"><span class="std std-ref">Parser library</span></a> during parsing to
+do semantic analysis of the input. For valid programs, Sema builds an AST for
+parsed constructs.</p>
+</div>
+<div class="section" id="the-codegen-library">
+<span id="codegen"></span><h2><a class="toc-backref" href="#id47">The CodeGen Library</a><a class="headerlink" href="#the-codegen-library" title="Permalink to this headline">¶</a></h2>
+<p>CodeGen takes an <a class="reference internal" href="#ast"><span class="std std-ref">AST</span></a> as input and produces <a class="reference external" href="//llvm.org/docs/LangRef.html">LLVM IR code</a> from it.</p>
+</div>
+<div class="section" id="how-to-change-clang">
+<h2><a class="toc-backref" href="#id48">How to change Clang</a><a class="headerlink" href="#how-to-change-clang" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="how-to-add-an-attribute">
+<h3><a class="toc-backref" href="#id49">How to add an attribute</a><a class="headerlink" href="#how-to-add-an-attribute" title="Permalink to this headline">¶</a></h3>
+<p>Attributes are a form of metadata that can be attached to a program construct,
+allowing the programmer to pass semantic information along to the compiler for
+various uses. For example, attributes may be used to alter the code generation
+for a program construct, or to provide extra semantic information for static
+analysis. This document explains how to add a custom attribute to Clang.
+Documentation on existing attributes can be found <a class="reference external" href="//clang.llvm.org/docs/AttributeReference.html">here</a>.</p>
+<div class="section" id="attribute-basics">
+<h4><a class="toc-backref" href="#id50">Attribute Basics</a><a class="headerlink" href="#attribute-basics" title="Permalink to this headline">¶</a></h4>
+<p>Attributes in Clang are handled in three stages: parsing into a parsed attribute
+representation, conversion from a parsed attribute into a semantic attribute,
+and then the semantic handling of the attribute.</p>
+<p>Parsing of the attribute is determined by the various syntactic forms attributes
+can take, such as GNU, C++11, and Microsoft style attributes, as well as other
+information provided by the table definition of the attribute. Ultimately, the
+parsed representation of an attribute object is an <code class="docutils literal notranslate"><span class="pre">ParsedAttr</span></code> object.
+These parsed attributes chain together as a list of parsed attributes attached
+to a declarator or declaration specifier. The parsing of attributes is handled
+automatically by Clang, except for attributes spelled as keywords. When
+implementing a keyword attribute, the parsing of the keyword and creation of the
+<code class="docutils literal notranslate"><span class="pre">ParsedAttr</span></code> object must be done manually.</p>
+<p>Eventually, <code class="docutils literal notranslate"><span class="pre">Sema::ProcessDeclAttributeList()</span></code> is called with a <code class="docutils literal notranslate"><span class="pre">Decl</span></code> and
+an <code class="docutils literal notranslate"><span class="pre">ParsedAttr</span></code>, at which point the parsed attribute can be transformed
+into a semantic attribute. The process by which a parsed attribute is converted
+into a semantic attribute depends on the attribute definition and semantic
+requirements of the attribute. The end result, however, is that the semantic
+attribute object is attached to the <code class="docutils literal notranslate"><span class="pre">Decl</span></code> object, and can be obtained by a
+call to <code class="docutils literal notranslate"><span class="pre">Decl::getAttr<T>()</span></code>.</p>
+<p>The structure of the semantic attribute is also governed by the attribute
+definition given in Attr.td. This definition is used to automatically generate
+functionality used for the implementation of the attribute, such as a class
+derived from <code class="docutils literal notranslate"><span class="pre">clang::Attr</span></code>, information for the parser to use, automated
+semantic checking for some attributes, etc.</p>
+</div>
+<div class="section" id="include-clang-basic-attr-td">
+<h4><a class="toc-backref" href="#id51"><code class="docutils literal notranslate"><span class="pre">include/clang/Basic/Attr.td</span></code></a><a class="headerlink" href="#include-clang-basic-attr-td" title="Permalink to this headline">¶</a></h4>
+<p>The first step to adding a new attribute to Clang is to add its definition to
+<a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Basic/Attr.td">include/clang/Basic/Attr.td</a>.
+This tablegen definition must derive from the <code class="docutils literal notranslate"><span class="pre">Attr</span></code> (tablegen, not
+semantic) type, or one of its derivatives. Most attributes will derive from the
+<code class="docutils literal notranslate"><span class="pre">InheritableAttr</span></code> type, which specifies that the attribute can be inherited by
+later redeclarations of the <code class="docutils literal notranslate"><span class="pre">Decl</span></code> it is associated with.
+<code class="docutils literal notranslate"><span class="pre">InheritableParamAttr</span></code> is similar to <code class="docutils literal notranslate"><span class="pre">InheritableAttr</span></code>, except that the
+attribute is written on a parameter instead of a declaration. If the attribute
+is intended to apply to a type instead of a declaration, such an attribute
+should derive from <code class="docutils literal notranslate"><span class="pre">TypeAttr</span></code>, and will generally not be given an AST
+representation. (Note that this document does not cover the creation of type
+attributes.) An attribute that inherits from <code class="docutils literal notranslate"><span class="pre">IgnoredAttr</span></code> is parsed, but will
+generate an ignored attribute diagnostic when used, which may be useful when an
+attribute is supported by another vendor but not supported by clang.</p>
+<p>The definition will specify several key pieces of information, such as the
+semantic name of the attribute, the spellings the attribute supports, the
+arguments the attribute expects, and more. Most members of the <code class="docutils literal notranslate"><span class="pre">Attr</span></code> tablegen
+type do not require definitions in the derived definition as the default
+suffice. However, every attribute must specify at least a spelling list, a
+subject list, and a documentation list.</p>
+<div class="section" id="spellings">
+<h5><a class="toc-backref" href="#id52">Spellings</a><a class="headerlink" href="#spellings" title="Permalink to this headline">¶</a></h5>
+<p>All attributes are required to specify a spelling list that denotes the ways in
+which the attribute can be spelled. For instance, a single semantic attribute
+may have a keyword spelling, as well as a C++11 spelling and a GNU spelling. An
+empty spelling list is also permissible and may be useful for attributes which
+are created implicitly. The following spellings are accepted:</p>
+<blockquote>
+<div><table border="1" class="docutils">
+<colgroup>
+<col width="16%" />
+<col width="84%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Spelling</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">GNU</span></code></td>
+<td>Spelled with a GNU-style <code class="docutils literal notranslate"><span class="pre">__attribute__((attr))</span></code> syntax and
+placement.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">CXX11</span></code></td>
+<td>Spelled with a C++-style <code class="docutils literal notranslate"><span class="pre">[[attr]]</span></code> syntax. If the attribute
+is meant to be used by Clang, it should set the namespace to
+<code class="docutils literal notranslate"><span class="pre">"clang"</span></code>.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">Declspec</span></code></td>
+<td>Spelled with a Microsoft-style <code class="docutils literal notranslate"><span class="pre">__declspec(attr)</span></code> syntax.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">Keyword</span></code></td>
+<td>The attribute is spelled as a keyword, and required custom
+parsing.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">GCC</span></code></td>
+<td>Specifies two spellings: the first is a GNU-style spelling, and
+the second is a C++-style spelling with the <code class="docutils literal notranslate"><span class="pre">gnu</span></code> namespace.
+Attributes should only specify this spelling for attributes
+supported by GCC.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">Pragma</span></code></td>
+<td>The attribute is spelled as a <code class="docutils literal notranslate"><span class="pre">#pragma</span></code>, and requires custom
+processing within the preprocessor. If the attribute is meant to
+be used by Clang, it should set the namespace to <code class="docutils literal notranslate"><span class="pre">"clang"</span></code>.
+Note that this spelling is not used for declaration attributes.</td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+</div>
+<div class="section" id="subjects">
+<h5><a class="toc-backref" href="#id53">Subjects</a><a class="headerlink" href="#subjects" title="Permalink to this headline">¶</a></h5>
+<p>Attributes appertain to one or more <code class="docutils literal notranslate"><span class="pre">Decl</span></code> subjects. If the attribute attempts
+to attach to a subject that is not in the subject list, a diagnostic is issued
+automatically. Whether the diagnostic is a warning or an error depends on how
+the attributeâs <code class="docutils literal notranslate"><span class="pre">SubjectList</span></code> is defined, but the default behavior is to warn.
+The diagnostics displayed to the user are automatically determined based on the
+subjects in the list, but a custom diagnostic parameter can also be specified in
+the <code class="docutils literal notranslate"><span class="pre">SubjectList</span></code>. The diagnostics generated for subject list violations are
+either <code class="docutils literal notranslate"><span class="pre">diag::warn_attribute_wrong_decl_type</span></code> or
+<code class="docutils literal notranslate"><span class="pre">diag::err_attribute_wrong_decl_type</span></code>, and the parameter enumeration is found
+in <a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Sema/ParsedAttr.h">include/clang/Sema/ParsedAttr.h</a>
+If a previously unused Decl node is added to the <code class="docutils literal notranslate"><span class="pre">SubjectList</span></code>, the logic used
+to automatically determine the diagnostic parameter in <a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/utils/TableGen/ClangAttrEmitter.cpp">utils/TableGen/ClangAttrEmitter.cpp</a>
+may need to be updated.</p>
+<p>By default, all subjects in the SubjectList must either be a Decl node defined
+in <code class="docutils literal notranslate"><span class="pre">DeclNodes.td</span></code>, or a statement node defined in <code class="docutils literal notranslate"><span class="pre">StmtNodes.td</span></code>. However,
+more complex subjects can be created by creating a <code class="docutils literal notranslate"><span class="pre">SubsetSubject</span></code> object.
+Each such object has a base subject which it appertains to (which must be a
+Decl or Stmt node, and not a SubsetSubject node), and some custom code which is
+called when determining whether an attribute appertains to the subject. For
+instance, a <code class="docutils literal notranslate"><span class="pre">NonBitField</span></code> SubsetSubject appertains to a <code class="docutils literal notranslate"><span class="pre">FieldDecl</span></code>, and
+tests whether the given FieldDecl is a bit field. When a SubsetSubject is
+specified in a SubjectList, a custom diagnostic parameter must also be provided.</p>
+<p>Diagnostic checking for attribute subject lists is automated except when
+<code class="docutils literal notranslate"><span class="pre">HasCustomParsing</span></code> is set to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
+</div>
+<div class="section" id="documentation">
+<h5><a class="toc-backref" href="#id54">Documentation</a><a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h5>
+<p>All attributes must have some form of documentation associated with them.
+Documentation is table generated on the public web server by a server-side
+process that runs daily. Generally, the documentation for an attribute is a
+stand-alone definition in <a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Basic/AttrDocs.td">include/clang/Basic/AttrDocs.td</a>
+that is named after the attribute being documented.</p>
+<p>If the attribute is not for public consumption, or is an implicitly-created
+attribute that has no visible spelling, the documentation list can specify the
+<code class="docutils literal notranslate"><span class="pre">Undocumented</span></code> object. Otherwise, the attribute should have its documentation
+added to AttrDocs.td.</p>
+<p>Documentation derives from the <code class="docutils literal notranslate"><span class="pre">Documentation</span></code> tablegen type. All derived
+types must specify a documentation category and the actual documentation itself.
+Additionally, it can specify a custom heading for the attribute, though a
+default heading will be chosen when possible.</p>
+<p>There are four predefined documentation categories: <code class="docutils literal notranslate"><span class="pre">DocCatFunction</span></code> for
+attributes that appertain to function-like subjects, <code class="docutils literal notranslate"><span class="pre">DocCatVariable</span></code> for
+attributes that appertain to variable-like subjects, <code class="docutils literal notranslate"><span class="pre">DocCatType</span></code> for type
+attributes, and <code class="docutils literal notranslate"><span class="pre">DocCatStmt</span></code> for statement attributes. A custom documentation
+category should be used for groups of attributes with similar functionality.
+Custom categories are good for providing overview information for the attributes
+grouped under it. For instance, the consumed annotation attributes define a
+custom category, <code class="docutils literal notranslate"><span class="pre">DocCatConsumed</span></code>, that explains what consumed annotations are
+at a high level.</p>
+<p>Documentation content (whether it is for an attribute or a category) is written
+using reStructuredText (RST) syntax.</p>
+<p>After writing the documentation for the attribute, it should be locally tested
+to ensure that there are no issues generating the documentation on the server.
+Local testing requires a fresh build of clang-tblgen. To generate the attribute
+documentation, execute the following command:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clang</span><span class="o">-</span><span class="n">tblgen</span> <span class="o">-</span><span class="n">gen</span><span class="o">-</span><span class="n">attr</span><span class="o">-</span><span class="n">docs</span> <span class="o">-</span><span class="n">I</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">clang</span><span class="o">/</span><span class="n">include</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">clang</span><span class="o">/</span><span class="n">include</span><span class="o">/</span><span class="n">clang</span><span class="o">/</span><span class="n">Basic</span><span class="o">/</span><span class="n">Attr</span><span class="o">.</span><span class="n">td</span> <span class="o">-</span><span class="n">o</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">clang</span><span class="o">/</span><span class="n">docs</span><span class="o">/</span><span class="n">AttributeReference</span><span class="o">.</span><span class="n">rst</span>
+</pre></div>
+</div>
+<p>When testing locally, <em>do not</em> commit changes to <code class="docutils literal notranslate"><span class="pre">AttributeReference.rst</span></code>.
+This file is generated by the server automatically, and any changes made to this
+file will be overwritten.</p>
+</div>
+<div class="section" id="arguments">
+<h5><a class="toc-backref" href="#id55">Arguments</a><a class="headerlink" href="#arguments" title="Permalink to this headline">¶</a></h5>
+<p>Attributes may optionally specify a list of arguments that can be passed to the
+attribute. Attribute arguments specify both the parsed form and the semantic
+form of the attribute. For example, if <code class="docutils literal notranslate"><span class="pre">Args</span></code> is
+<code class="docutils literal notranslate"><span class="pre">[StringArgument<"Arg1">,</span> <span class="pre">IntArgument<"Arg2">]</span></code> then
+<code class="docutils literal notranslate"><span class="pre">__attribute__((myattribute("Hello",</span> <span class="pre">3)))</span></code> will be a valid use; it requires
+two arguments while parsing, and the Attr subclassâ constructor for the
+semantic attribute will require a string and integer argument.</p>
+<p>All arguments have a name and a flag that specifies whether the argument is
+optional. The associated C++ type of the argument is determined by the argument
+definition type. If the existing argument types are insufficient, new types can
+be created, but it requires modifying <a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/utils/TableGen/ClangAttrEmitter.cpp">utils/TableGen/ClangAttrEmitter.cpp</a>
+to properly support the type.</p>
+</div>
+<div class="section" id="other-properties">
+<h5><a class="toc-backref" href="#id56">Other Properties</a><a class="headerlink" href="#other-properties" title="Permalink to this headline">¶</a></h5>
+<p>The <code class="docutils literal notranslate"><span class="pre">Attr</span></code> definition has other members which control the behavior of the
+attribute. Many of them are special-purpose and beyond the scope of this
+document, however a few deserve mention.</p>
+<p>If the parsed form of the attribute is more complex, or differs from the
+semantic form, the <code class="docutils literal notranslate"><span class="pre">HasCustomParsing</span></code> bit can be set to <code class="docutils literal notranslate"><span class="pre">1</span></code> for the class,
+and the parsing code in <a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/lib/Parse/ParseDecl.cpp">Parser::ParseGNUAttributeArgs()</a>
+can be updated for the special case. Note that this only applies to arguments
+with a GNU spelling â attributes with a __declspec spelling currently ignore
+this flag and are handled by <code class="docutils literal notranslate"><span class="pre">Parser::ParseMicrosoftDeclSpec</span></code>.</p>
+<p>Note that setting this member to 1 will opt out of common attribute semantic
+handling, requiring extra implementation efforts to ensure the attribute
+appertains to the appropriate subject, etc.</p>
+<p>If the attribute should not be propagated from a template declaration to an
+instantiation of the template, set the <code class="docutils literal notranslate"><span class="pre">Clone</span></code> member to 0. By default, all
+attributes will be cloned to template instantiations.</p>
+<p>Attributes that do not require an AST node should set the <code class="docutils literal notranslate"><span class="pre">ASTNode</span></code> field to
+<code class="docutils literal notranslate"><span class="pre">0</span></code> to avoid polluting the AST. Note that anything inheriting from
+<code class="docutils literal notranslate"><span class="pre">TypeAttr</span></code> or <code class="docutils literal notranslate"><span class="pre">IgnoredAttr</span></code> automatically do not generate an AST node. All
+other attributes generate an AST node by default. The AST node is the semantic
+representation of the attribute.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">LangOpts</span></code> field specifies a list of language options required by the
+attribute. For instance, all of the CUDA-specific attributes specify <code class="docutils literal notranslate"><span class="pre">[CUDA]</span></code>
+for the <code class="docutils literal notranslate"><span class="pre">LangOpts</span></code> field, and when the CUDA language option is not enabled, an
+âattribute ignoredâ warning diagnostic is emitted. Since language options are
+not table generated nodes, new language options must be created manually and
+should specify the spelling used by <code class="docutils literal notranslate"><span class="pre">LangOptions</span></code> class.</p>
+<p>Custom accessors can be generated for an attribute based on the spelling list
+for that attribute. For instance, if an attribute has two different spellings:
+âFooâ and âBarâ, accessors can be created:
+<code class="docutils literal notranslate"><span class="pre">[Accessor<"isFoo",</span> <span class="pre">[GNU<"Foo">]>,</span> <span class="pre">Accessor<"isBar",</span> <span class="pre">[GNU<"Bar">]>]</span></code>
+These accessors will be generated on the semantic form of the attribute,
+accepting no arguments and returning a <code class="docutils literal notranslate"><span class="pre">bool</span></code>.</p>
+<p>Attributes that do not require custom semantic handling should set the
+<code class="docutils literal notranslate"><span class="pre">SemaHandler</span></code> field to <code class="docutils literal notranslate"><span class="pre">0</span></code>. Note that anything inheriting from
+<code class="docutils literal notranslate"><span class="pre">IgnoredAttr</span></code> automatically do not get a semantic handler. All other
+attributes are assumed to use a semantic handler by default. Attributes
+without a semantic handler are not given a parsed attribute <code class="docutils literal notranslate"><span class="pre">Kind</span></code> enumerator.</p>
+<p>Target-specific attributes may share a spelling with other attributes in
+different targets. For instance, the ARM and MSP430 targets both have an
+attribute spelled <code class="docutils literal notranslate"><span class="pre">GNU<"interrupt"></span></code>, but with different parsing and semantic
+requirements. To support this feature, an attribute inheriting from
+<code class="docutils literal notranslate"><span class="pre">TargetSpecificAttribute</span></code> may specify a <code class="docutils literal notranslate"><span class="pre">ParseKind</span></code> field. This field
+should be the same value between all arguments sharing a spelling, and
+corresponds to the parsed attributeâs <code class="docutils literal notranslate"><span class="pre">Kind</span></code> enumerator. This allows
+attributes to share a parsed attribute kind, but have distinct semantic
+attribute classes. For instance, <code class="docutils literal notranslate"><span class="pre">ParsedAttr</span></code> is the shared
+parsed attribute kind, but ARMInterruptAttr and MSP430InterruptAttr are the
+semantic attributes generated.</p>
+<p>By default, attribute arguments are parsed in an evaluated context. If the
+arguments for an attribute should be parsed in an unevaluated context (akin to
+the way the argument to a <code class="docutils literal notranslate"><span class="pre">sizeof</span></code> expression is parsed), set
+<code class="docutils literal notranslate"><span class="pre">ParseArgumentsAsUnevaluated</span></code> to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
+<p>If additional functionality is desired for the semantic form of the attribute,
+the <code class="docutils literal notranslate"><span class="pre">AdditionalMembers</span></code> field specifies code to be copied verbatim into the
+semantic attribute class object, with <code class="docutils literal notranslate"><span class="pre">public</span></code> access.</p>
+</div>
+</div>
+<div class="section" id="boilerplate">
+<h4><a class="toc-backref" href="#id57">Boilerplate</a><a class="headerlink" href="#boilerplate" title="Permalink to this headline">¶</a></h4>
+<p>All semantic processing of declaration attributes happens in <a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/lib/Sema/SemaDeclAttr.cpp">lib/Sema/SemaDeclAttr.cpp</a>,
+and generally starts in the <code class="docutils literal notranslate"><span class="pre">ProcessDeclAttribute()</span></code> function. If the
+attribute is a âsimpleâ attribute â meaning that it requires no custom semantic
+processing aside from what is automatically provided, add a call to
+<code class="docutils literal notranslate"><span class="pre">handleSimpleAttribute<YourAttr>(S,</span> <span class="pre">D,</span> <span class="pre">Attr);</span></code> to the switch statement.
+Otherwise, write a new <code class="docutils literal notranslate"><span class="pre">handleYourAttr()</span></code> function, and add that to the switch
+statement. Please do not implement handling logic directly in the <code class="docutils literal notranslate"><span class="pre">case</span></code> for
+the attribute.</p>
+<p>Unless otherwise specified by the attribute definition, common semantic checking
+of the parsed attribute is handled automatically. This includes diagnosing
+parsed attributes that do not appertain to the given <code class="docutils literal notranslate"><span class="pre">Decl</span></code>, ensuring the
+correct minimum number of arguments are passed, etc.</p>
+<p>If the attribute adds additional warnings, define a <code class="docutils literal notranslate"><span class="pre">DiagGroup</span></code> in
+<a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Basic/DiagnosticGroups.td">include/clang/Basic/DiagnosticGroups.td</a>
+named after the attributeâs <code class="docutils literal notranslate"><span class="pre">Spelling</span></code> with â_âs replaced by â-âs. If there
+is only a single diagnostic, it is permissible to use <code class="docutils literal notranslate"><span class="pre">InGroup<DiagGroup<"your-attribute">></span></code>
+directly in <a class="reference external" href="https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Basic/DiagnosticSemaKinds.td">DiagnosticSemaKinds.td</a></p>
+<p>All semantic diagnostics generated for your attribute, including automatically-
+generated ones (such as subjects and argument counts), should have a
+corresponding test case.</p>
+</div>
+<div class="section" id="semantic-handling">
+<h4><a class="toc-backref" href="#id58">Semantic handling</a><a class="headerlink" href="#semantic-handling" title="Permalink to this headline">¶</a></h4>
+<p>Most attributes are implemented to have some effect on the compiler. For
+instance, to modify the way code is generated, or to add extra semantic checks
+for an analysis pass, etc. Having added the attribute definition and conversion
+to the semantic representation for the attribute, what remains is to implement
+the custom logic requiring use of the attribute.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">clang::Decl</span></code> object can be queried for the presence or absence of an
+attribute using <code class="docutils literal notranslate"><span class="pre">hasAttr<T>()</span></code>. To obtain a pointer to the semantic
+representation of the attribute, <code class="docutils literal notranslate"><span class="pre">getAttr<T></span></code> may be used.</p>
+</div>
+</div>
+<div class="section" id="how-to-add-an-expression-or-statement">
+<h3><a class="toc-backref" href="#id59">How to add an expression or statement</a><a class="headerlink" href="#how-to-add-an-expression-or-statement" title="Permalink to this headline">¶</a></h3>
+<p>Expressions and statements are one of the most fundamental constructs within a
+compiler, because they interact with many different parts of the AST, semantic
+analysis, and IR generation. Therefore, adding a new expression or statement
+kind into Clang requires some care. The following list details the various
+places in Clang where an expression or statement needs to be introduced, along
+with patterns to follow to ensure that the new expression or statement works
+well across all of the C languages. We focus on expressions, but statements
+are similar.</p>
+<ol class="arabic simple">
+<li>Introduce parsing actions into the parser. Recursive-descent parsing is
+mostly self-explanatory, but there are a few things that are worth keeping
+in mind:<ul>
+<li>Keep as much source location information as possible! Youâll want it later
+to produce great diagnostics and support Clangâs various features that map
+between source code and the AST.</li>
+<li>Write tests for all of the âbadâ parsing cases, to make sure your recovery
+is good. If you have matched delimiters (e.g., parentheses, square
+brackets, etc.), use <code class="docutils literal notranslate"><span class="pre">Parser::BalancedDelimiterTracker</span></code> to give nice
+diagnostics when things go wrong.</li>
+</ul>
+</li>
+<li>Introduce semantic analysis actions into <code class="docutils literal notranslate"><span class="pre">Sema</span></code>. Semantic analysis should
+always involve two functions: an <code class="docutils literal notranslate"><span class="pre">ActOnXXX</span></code> function that will be called
+directly from the parser, and a <code class="docutils literal notranslate"><span class="pre">BuildXXX</span></code> function that performs the
+actual semantic analysis and will (eventually!) build the AST node. Itâs
+fairly common for the <code class="docutils literal notranslate"><span class="pre">ActOnCXX</span></code> function to do very little (often just
+some minor translation from the parserâs representation to <code class="docutils literal notranslate"><span class="pre">Sema</span></code>âs
+representation of the same thing), but the separation is still important:
+C++ template instantiation, for example, should always call the <code class="docutils literal notranslate"><span class="pre">BuildXXX</span></code>
+variant. Several notes on semantic analysis before we get into construction
+of the AST:<ul>
+<li>Your expression probably involves some types and some subexpressions.
+Make sure to fully check that those types, and the types of those
+subexpressions, meet your expectations. Add implicit conversions where
+necessary to make sure that all of the types line up exactly the way you
+want them. Write extensive tests to check that youâre getting good
+diagnostics for mistakes and that you can use various forms of
+subexpressions with your expression.</li>
+<li>When type-checking a type or subexpression, make sure to first check
+whether the type is âdependentâ (<code class="docutils literal notranslate"><span class="pre">Type::isDependentType()</span></code>) or whether a
+subexpression is type-dependent (<code class="docutils literal notranslate"><span class="pre">Expr::isTypeDependent()</span></code>). If any of
+these return <code class="docutils literal notranslate"><span class="pre">true</span></code>, then youâre inside a template and you canât do much
+type-checking now. Thatâs normal, and your AST node (when you get there)
+will have to deal with this case. At this point, you can write tests that
+use your expression within templates, but donât try to instantiate the
+templates.</li>
+<li>For each subexpression, be sure to call <code class="docutils literal notranslate"><span class="pre">Sema::CheckPlaceholderExpr()</span></code>
+to deal with âweirdâ expressions that donât behave well as subexpressions.
+Then, determine whether you need to perform lvalue-to-rvalue conversions
+(<code class="docutils literal notranslate"><span class="pre">Sema::DefaultLvalueConversions</span></code>) or the usual unary conversions
+(<code class="docutils literal notranslate"><span class="pre">Sema::UsualUnaryConversions</span></code>), for places where the subexpression is
+producing a value you intend to use.</li>
+<li>Your <code class="docutils literal notranslate"><span class="pre">BuildXXX</span></code> function will probably just return <code class="docutils literal notranslate"><span class="pre">ExprError()</span></code> at
+this point, since you donât have an AST. Thatâs perfectly fine, and
+shouldnât impact your testing.</li>
+</ul>
+</li>
+<li>Introduce an AST node for your new expression. This starts with declaring
+the node in <code class="docutils literal notranslate"><span class="pre">include/Basic/StmtNodes.td</span></code> and creating a new class for your
+expression in the appropriate <code class="docutils literal notranslate"><span class="pre">include/AST/Expr*.h</span></code> header. Itâs best to
+look at the class for a similar expression to get ideas, and there are some
+specific things to watch for:<ul>
+<li>If you need to allocate memory, use the <code class="docutils literal notranslate"><span class="pre">ASTContext</span></code> allocator to
+allocate memory. Never use raw <code class="docutils literal notranslate"><span class="pre">malloc</span></code> or <code class="docutils literal notranslate"><span class="pre">new</span></code>, and never hold any
+resources in an AST node, because the destructor of an AST node is never
+called.</li>
+<li>Make sure that <code class="docutils literal notranslate"><span class="pre">getSourceRange()</span></code> covers the exact source range of your
+expression. This is needed for diagnostics and for IDE support.</li>
+<li>Make sure that <code class="docutils literal notranslate"><span class="pre">children()</span></code> visits all of the subexpressions. This is
+important for a number of features (e.g., IDE support, C++ variadic
+templates). If you have sub-types, youâll also need to visit those
+sub-types in <code class="docutils literal notranslate"><span class="pre">RecursiveASTVisitor</span></code>.</li>
+<li>Add printing support (<code class="docutils literal notranslate"><span class="pre">StmtPrinter.cpp</span></code>) for your expression.</li>
+<li>Add profiling support (<code class="docutils literal notranslate"><span class="pre">StmtProfile.cpp</span></code>) for your AST node, noting the
+distinguishing (non-source location) characteristics of an instance of
+your expression. Omitting this step will lead to hard-to-diagnose
+failures regarding matching of template declarations.</li>
+<li>Add serialization support (<code class="docutils literal notranslate"><span class="pre">ASTReaderStmt.cpp</span></code>, <code class="docutils literal notranslate"><span class="pre">ASTWriterStmt.cpp</span></code>)
+for your AST node.</li>
+</ul>
+</li>
+<li>Teach semantic analysis to build your AST node. At this point, you can wire
+up your <code class="docutils literal notranslate"><span class="pre">Sema::BuildXXX</span></code> function to actually create your AST. A few
+things to check at this point:<ul>
+<li>If your expression can construct a new C++ class or return a new
+Objective-C object, be sure to update and then call
+<code class="docutils literal notranslate"><span class="pre">Sema::MaybeBindToTemporary</span></code> for your just-created AST node to be sure
+that the object gets properly destructed. An easy way to test this is to
+return a C++ class with a private destructor: semantic analysis should
+flag an error here with the attempt to call the destructor.</li>
+<li>Inspect the generated AST by printing it using <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span> <span class="pre">-ast-print</span></code>,
+to make sure youâre capturing all of the important information about how
+the AST was written.</li>
+<li>Inspect the generated AST under <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span> <span class="pre">-ast-dump</span></code> to verify that
+all of the types in the generated AST line up the way you want them.
+Remember that clients of the AST should never have to âthinkâ to
+understand whatâs going on. For example, all implicit conversions should
+show up explicitly in the AST.</li>
+<li>Write tests that use your expression as a subexpression of other,
+well-known expressions. Can you call a function using your expression as
+an argument? Can you use the ternary operator?</li>
+</ul>
+</li>
+<li>Teach code generation to create IR to your AST node. This step is the first
+(and only) that requires knowledge of LLVM IR. There are several things to
+keep in mind:<ul>
+<li>Code generation is separated into scalar/aggregate/complex and
+lvalue/rvalue paths, depending on what kind of result your expression
+produces. On occasion, this requires some careful factoring of code to
+avoid duplication.</li>
+<li><code class="docutils literal notranslate"><span class="pre">CodeGenFunction</span></code> contains functions <code class="docutils literal notranslate"><span class="pre">ConvertType</span></code> and
+<code class="docutils literal notranslate"><span class="pre">ConvertTypeForMem</span></code> that convert Clangâs types (<code class="docutils literal notranslate"><span class="pre">clang::Type*</span></code> or
+<code class="docutils literal notranslate"><span class="pre">clang::QualType</span></code>) to LLVM types. Use the former for values, and the
+latter for memory locations: test with the C++ â<code class="docutils literal notranslate"><span class="pre">bool</span></code>â type to check
+this. If you find that you are having to use LLVM bitcasts to make the
+subexpressions of your expression have the type that your expression
+expects, STOP! Go fix semantic analysis and the AST so that you donât
+need these bitcasts.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">CodeGenFunction</span></code> class has a number of helper functions to make
+certain operations easy, such as generating code to produce an lvalue or
+an rvalue, or to initialize a memory location with a given value. Prefer
+to use these functions rather than directly writing loads and stores,
+because these functions take care of some of the tricky details for you
+(e.g., for exceptions).</li>
+<li>If your expression requires some special behavior in the event of an
+exception, look at the <code class="docutils literal notranslate"><span class="pre">push*Cleanup</span></code> functions in <code class="docutils literal notranslate"><span class="pre">CodeGenFunction</span></code>
+to introduce a cleanup. You shouldnât have to deal with
+exception-handling directly.</li>
+<li>Testing is extremely important in IR generation. Use <code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span>
+<span class="pre">-emit-llvm</span></code> and <a class="reference external" href="https://llvm.org/docs/CommandGuide/FileCheck.html">FileCheck</a> to verify that youâre
+generating the right IR.</li>
+</ul>
+</li>
+<li>Teach template instantiation how to cope with your AST node, which requires
+some fairly simple code:<ul>
+<li>Make sure that your expressionâs constructor properly computes the flags
+for type dependence (i.e., the type your expression produces can change
+from one instantiation to the next), value dependence (i.e., the constant
+value your expression produces can change from one instantiation to the
+next), instantiation dependence (i.e., a template parameter occurs
+anywhere in your expression), and whether your expression contains a
+parameter pack (for variadic templates). Often, computing these flags
+just means combining the results from the various types and
+subexpressions.</li>
+<li>Add <code class="docutils literal notranslate"><span class="pre">TransformXXX</span></code> and <code class="docutils literal notranslate"><span class="pre">RebuildXXX</span></code> functions to the <code class="docutils literal notranslate"><span class="pre">TreeTransform</span></code>
+class template in <code class="docutils literal notranslate"><span class="pre">Sema</span></code>. <code class="docutils literal notranslate"><span class="pre">TransformXXX</span></code> should (recursively)
+transform all of the subexpressions and types within your expression,
+using <code class="docutils literal notranslate"><span class="pre">getDerived().TransformYYY</span></code>. If all of the subexpressions and
+types transform without error, it will then call the <code class="docutils literal notranslate"><span class="pre">RebuildXXX</span></code>
+function, which will in turn call <code class="docutils literal notranslate"><span class="pre">getSema().BuildXXX</span></code> to perform
+semantic analysis and build your expression.</li>
+<li>To test template instantiation, take those tests you wrote to make sure
+that you were type checking with type-dependent expressions and dependent
+types (from step #2) and instantiate those templates with various types,
+some of which type-check and some that donât, and test the error messages
+in each case.</li>
+</ul>
+</li>
+<li>There are some âextrasâ that make other features work better. Itâs worth
+handling these extras to give your expression complete integration into
+Clang:<ul>
+<li>Add code completion support for your expression in
+<code class="docutils literal notranslate"><span class="pre">SemaCodeComplete.cpp</span></code>.</li>
+<li>If your expression has types in it, or has any âinterestingâ features
+other than subexpressions, extend libclangâs <code class="docutils literal notranslate"><span class="pre">CursorVisitor</span></code> to provide
+proper visitation for your expression, enabling various IDE features such
+as syntax highlighting, cross-referencing, and so on. The
+<code class="docutils literal notranslate"><span class="pre">c-index-test</span></code> helper program can be used to test these features.</li>
+</ul>
+</li>
+</ol>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="ClangFormatStyleOptions.html">Clang-Format Style Options</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DriverInternals.html">Driver Design & Internals</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/IntroductionToTheClangAST.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/IntroductionToTheClangAST.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/IntroductionToTheClangAST.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/IntroductionToTheClangAST.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,169 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Introduction to the Clang AST — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LibTooling" href="LibTooling.html" />
+ <link rel="prev" title="External Clang Examples" href="ExternalClangExamples.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Introduction to the Clang AST</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="ExternalClangExamples.html">External Clang Examples</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LibTooling.html">LibTooling</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="introduction-to-the-clang-ast">
+<h1>Introduction to the Clang AST<a class="headerlink" href="#introduction-to-the-clang-ast" title="Permalink to this headline">¶</a></h1>
+<p>This document gives a gentle introduction to the mysteries of the Clang
+AST. It is targeted at developers who either want to contribute to
+Clang, or use tools that work based on Clangâs AST, like the AST
+matchers.</p>
+<center><iframe width="560" height="315" src="https://www.youtube.com/embed/VqCkCDFLSsc?vq=hd720" frameborder="0" allowfullscreen></iframe></center><p><a class="reference external" href="https://llvm.org/devmtg/2013-04/klimek-slides.pdf">Slides</a></p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clangâs AST is different from ASTs produced by some other compilers in
+that it closely resembles both the written C++ code and the C++
+standard. For example, parenthesis expressions and compile time
+constants are available in an unreduced form in the AST. This makes
+Clangâs AST a good fit for refactoring tools.</p>
+<p>Documentation for all Clang AST nodes is available via the generated
+<a class="reference external" href="https://clang.llvm.org/doxygen">Doxygen</a>. The doxygen online
+documentation is also indexed by your favorite search engine, which will
+make a search for clang and the AST nodeâs class name usually turn up
+the doxygen of the class youâre looking for (for example, search for:
+clang ParenExpr).</p>
+</div>
+<div class="section" id="examining-the-ast">
+<h2>Examining the AST<a class="headerlink" href="#examining-the-ast" title="Permalink to this headline">¶</a></h2>
+<p>A good way to familarize yourself with the Clang AST is to actually look
+at it on some simple example code. Clang has a builtin AST-dump mode,
+which can be enabled with the flag <code class="docutils literal notranslate"><span class="pre">-ast-dump</span></code>.</p>
+<p>Letâs look at a simple example AST:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cat test.cc
+int f(int x) {
+ int result = (x / 42);
+ return result;
+}
+
+# Clang by default is a frontend for many tools; -Xclang is used to pass
+# options directly to the C++ frontend.
+$ clang -Xclang -ast-dump -fsyntax-only test.cc
+TranslationUnitDecl 0x5aea0d0 <<invalid sloc>>
+... cutting out internal declarations of clang ...
+`-FunctionDecl 0x5aeab50 <test.cc:1:1, line:4:1> f 'int (int)'
+ |-ParmVarDecl 0x5aeaa90 <line:1:7, col:11> x 'int'
+ `-CompoundStmt 0x5aead88 <col:14, line:4:1>
+ |-DeclStmt 0x5aead10 <line:2:3, col:24>
+ | `-VarDecl 0x5aeac10 <col:3, col:23> result 'int'
+ | `-ParenExpr 0x5aeacf0 <col:16, col:23> 'int'
+ | `-BinaryOperator 0x5aeacc8 <col:17, col:21> 'int' '/'
+ | |-ImplicitCastExpr 0x5aeacb0 <col:17> 'int' <LValueToRValue>
+ | | `-DeclRefExpr 0x5aeac68 <col:17> 'int' lvalue ParmVar 0x5aeaa90 'x' 'int'
+ | `-IntegerLiteral 0x5aeac90 <col:21> 'int' 42
+ `-ReturnStmt 0x5aead68 <line:3:3, col:10>
+ `-ImplicitCastExpr 0x5aead50 <col:10> 'int' <LValueToRValue>
+ `-DeclRefExpr 0x5aead28 <col:10> 'int' lvalue Var 0x5aeac10 'result' 'int'
+</pre></div>
+</div>
+<p>The toplevel declaration in
+a translation unit is always the <a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html">translation unit
+declaration</a>.
+In this example, our first user written declaration is the <a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">function
+declaration</a>
+of â<code class="docutils literal notranslate"><span class="pre">f</span></code>â. The body of â<code class="docutils literal notranslate"><span class="pre">f</span></code>â is a <a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">compound
+statement</a>,
+whose child nodes are a <a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html">declaration
+statement</a>
+that declares our result variable, and the <a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html">return
+statement</a>.</p>
+</div>
+<div class="section" id="ast-context">
+<h2>AST Context<a class="headerlink" href="#ast-context" title="Permalink to this headline">¶</a></h2>
+<p>All information about the AST for a translation unit is bundled up in
+the class
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html">ASTContext</a>.
+It allows traversal of the whole translation unit starting from
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#abd909fb01ef10cfd0244832a67b1dd64">getTranslationUnitDecl</a>,
+or to access Clangâs <a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#a4f95adb9958e22fbe55212ae6482feb4">table of
+identifiers</a>
+for the parsed translation unit.</p>
+</div>
+<div class="section" id="ast-nodes">
+<h2>AST Nodes<a class="headerlink" href="#ast-nodes" title="Permalink to this headline">¶</a></h2>
+<p>Clangâs AST nodes are modeled on a class hierarchy that does not have a
+common ancestor. Instead, there are multiple larger hierarchies for
+basic node types like
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a> and
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>. Many
+important AST nodes derive from
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>,
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>,
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1DeclContext.html">DeclContext</a>
+or <a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>, with
+some classes deriving from both Decl and DeclContext.</p>
+<p>There are also a multitude of nodes in the AST that are not part of a
+larger hierarchy, and are only reachable from specific other nodes, like
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>.</p>
+<p>Thus, to traverse the full AST, one starts from the
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html">TranslationUnitDecl</a>
+and then recursively traverses everything that can be reached from that
+node - this information has to be encoded for each specific node type.
+This algorithm is encoded in the
+<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html">RecursiveASTVisitor</a>.
+See the <a class="reference external" href="https://clang.llvm.org/docs/RAVFrontendAction.html">RecursiveASTVisitor
+tutorial</a>.</p>
+<p>The two most basic nodes in the Clang AST are statements
+(<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>) and
+declarations
+(<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>). Note
+that expressions
+(<a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>) are
+also statements in Clangâs AST.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="ExternalClangExamples.html">External Clang Examples</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LibTooling.html">LibTooling</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/ItaniumMangleAbiTags.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/ItaniumMangleAbiTags.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/ItaniumMangleAbiTags.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/ItaniumMangleAbiTags.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,144 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>ABI tags — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Hardware-assisted AddressSanitizer Design Documentation" href="HardwareAssistedAddressSanitizerDesign.html" />
+ <link rel="prev" title="Precompiled Header and Modules Internals" href="PCHInternals.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>ABI tags</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="PCHInternals.html">Precompiled Header and Modules Internals</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="HardwareAssistedAddressSanitizerDesign.html">Hardware-assisted AddressSanitizer Design Documentation</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="abi-tags">
+<h1>ABI tags<a class="headerlink" href="#abi-tags" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This text tries to describe gcc semantic for mangling âabi_tagâ attributes
+described in <a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html">https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html</a></p>
+<p>There is no guarantee the following rules are correct, complete or make sense
+in any way as they were determined empirically by experiments with gcc5.</p>
+</div>
+<div class="section" id="declaration">
+<h2>Declaration<a class="headerlink" href="#declaration" title="Permalink to this headline">¶</a></h2>
+<p>ABI tags are declared in an abi_tag attribute and can be applied to a
+function, variable, class or inline namespace declaration. The attribute takes
+one or more strings (called tags); the order does not matter.</p>
+<p>See <a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html">https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html</a> for
+details.</p>
+<p>Tags on an inline namespace are called âimplicit tagsâ, all other tags are
+âexplicit tagsâ.</p>
+</div>
+<div class="section" id="mangling">
+<h2>Mangling<a class="headerlink" href="#mangling" title="Permalink to this headline">¶</a></h2>
+<p>All tags that are âactiveâ on an <unqualified-name> are emitted after the
+<unqualified-name>, before <template-args> or <discriminator>, and are part of
+the same <substitution> the <unqualified-name> is.</p>
+<p>They are mangled as:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><abi-tags> ::= <abi-tag>* # sort by name
+<abi-tag> ::= B <tag source-name>
+</pre></div>
+</div>
+<p>Example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__attribute__</span><span class="p">((</span><span class="n">abi_tag</span><span class="p">(</span><span class="s">"test"</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">Func</span><span class="p">();</span>
+<span class="c1">// gets mangled as: _Z4FuncB4testv (prettified as `Func[abi:test]()`)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="active-tags">
+<h2>Active tags<a class="headerlink" href="#active-tags" title="Permalink to this headline">¶</a></h2>
+<p>A namespace does not have any active tags. For types (class / struct / union /
+enum), the explicit tags are the active tags.</p>
+<p>For variables and functions, the active tags are the explicit tags plus any
+ârequired tagsâ which are not in the âavailable tagsâ set:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>derived-tags := (required-tags - available-tags)
+active-tags := explicit-tags + derived-tags
+</pre></div>
+</div>
+</div>
+<div class="section" id="required-tags-for-a-function">
+<h2>Required tags for a function<a class="headerlink" href="#required-tags-for-a-function" title="Permalink to this headline">¶</a></h2>
+<p>If a function is used as a local scope for another name, and is part of
+another function as local scope, it doesnât have any required tags.</p>
+<p>If a function is used as a local scope for a guard variable name, it doesnât
+have any required tags.</p>
+<p>Otherwise the function requires any implicit or explicit tag used in the name
+for the return type.</p>
+<p>Example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> <span class="n">A</span> <span class="p">{</span>
+ <span class="kr">inline</span> <span class="k">namespace</span> <span class="n">B</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">abi_tag</span><span class="p">))</span> <span class="p">{</span>
+ <span class="k">struct</span> <span class="n">C</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">x</span><span class="p">;</span> <span class="p">};</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">A</span><span class="o">::</span><span class="n">C</span> <span class="n">foo</span><span class="p">();</span> <span class="c1">// gets mangled as: _Z3fooB1Bv (prettified as `foo[abi:B]()`)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="required-tags-for-a-variable">
+<h2>Required tags for a variable<a class="headerlink" href="#required-tags-for-a-variable" title="Permalink to this headline">¶</a></h2>
+<p>A variable requires any implicit or explicit tag used in its type.</p>
+</div>
+<div class="section" id="available-tags">
+<h2>Available tags<a class="headerlink" href="#available-tags" title="Permalink to this headline">¶</a></h2>
+<p>All tags used in the prefix and in the template arguments for a name are
+available. Also, for functions, all tags from the <bare-function-type>
+(which might include the return type for template functions) are available.</p>
+<p>For <local-name>s all active tags used in the local part (<function-
+encoding>) are available, but not implicit tags which were not active.</p>
+<p>Implicit and explicit tags used in the <unqualified-name> for a function (as
+in the type of a cast operator) are NOT available.</p>
+<p>Example: a cast operator to std::string (which is
+std::__cxx11::basic_string<â¦>) will use âcxx11â as an active tag, as it is
+required from the return type <cite>std::string</cite> but not available.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="PCHInternals.html">Precompiled Header and Modules Internals</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="HardwareAssistedAddressSanitizerDesign.html">Hardware-assisted AddressSanitizer Design Documentation</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/JSONCompilationDatabase.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/JSONCompilationDatabase.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/JSONCompilationDatabase.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/JSONCompilationDatabase.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,150 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>JSON Compilation Database Format Specification — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Clangâs refactoring engine" href="RefactoringEngine.html" />
+ <link rel="prev" title="How To Setup Clang Tooling For LLVM" href="HowToSetupToolingForLLVM.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>JSON Compilation Database Format Specification</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="RefactoringEngine.html">Clangâs refactoring engine</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="json-compilation-database-format-specification">
+<h1>JSON Compilation Database Format Specification<a class="headerlink" href="#json-compilation-database-format-specification" title="Permalink to this headline">¶</a></h1>
+<p>This document describes a format for specifying how to replay single
+compilations independently of the build system.</p>
+<div class="section" id="background">
+<h2>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h2>
+<p>Tools based on the C++ Abstract Syntax Tree need full information how to
+parse a translation unit. Usually this information is implicitly
+available in the build system, but running tools as part of the build
+system is not necessarily the best solution:</p>
+<ul class="simple">
+<li>Build systems are inherently change driven, so running multiple tools
+over the same code base without changing the code does not fit into
+the architecture of many build systems.</li>
+<li>Figuring out whether things have changed is often an IO bound
+process; this makes it hard to build low latency end user tools based
+on the build system.</li>
+<li>Build systems are inherently sequential in the build graph, for
+example due to generated source code. While tools that run
+independently of the build still need the generated source code to
+exist, running tools multiple times over unchanging source does not
+require serialization of the runs according to the build dependency
+graph.</li>
+</ul>
+</div>
+<div class="section" id="supported-systems">
+<h2>Supported Systems<a class="headerlink" href="#supported-systems" title="Permalink to this headline">¶</a></h2>
+<p>Currently <a class="reference external" href="https://cmake.org">CMake</a> (since 2.8.5) supports generation
+of compilation databases for Unix Makefile builds (Ninja builds in the
+works) with the option <code class="docutils literal notranslate"><span class="pre">CMAKE_EXPORT_COMPILE_COMMANDS</span></code>.</p>
+<p>For projects on Linux, there is an alternative to intercept compiler
+calls with a tool called <a class="reference external" href="https://github.com/rizsotto/Bear">Bear</a>.</p>
+<p>Clangâs tooling interface supports reading compilation databases; see
+the <a class="reference internal" href="LibTooling.html"><span class="doc">LibTooling documentation</span></a>. libclang and its
+python bindings also support this (since clang 3.2); see
+<a class="reference external" href="/doxygen/group__COMPILATIONDB.html">CXCompilationDatabase.h</a>.</p>
+</div>
+<div class="section" id="format">
+<h2>Format<a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h2>
+<p>A compilation database is a JSON file, which consist of an array of
+âcommand objectsâ, where each command object specifies one way a
+translation unit is compiled in the project.</p>
+<p>Each command object contains the translation unitâs main file, the
+working directory of the compile run and the actual compile command.</p>
+<p>Example:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
+ <span class="p">{</span> <span class="s2">"directory"</span><span class="p">:</span> <span class="s2">"/home/user/llvm/build"</span><span class="p">,</span>
+ <span class="s2">"command"</span><span class="p">:</span> <span class="s2">"/usr/bin/clang++ -Irelative -DSOMEDEF=</span><span class="se">\"</span><span class="s2">With spaces, quotes and </span><span class="se">\\</span><span class="s2">-es.</span><span class="se">\"</span><span class="s2"> -c -o file.o file.cc"</span><span class="p">,</span>
+ <span class="s2">"file"</span><span class="p">:</span> <span class="s2">"file.cc"</span> <span class="p">},</span>
+ <span class="o">...</span>
+<span class="p">]</span>
+</pre></div>
+</div>
+<p>The contracts for each field in the command object are:</p>
+<ul class="simple">
+<li><strong>directory:</strong> The working directory of the compilation. All paths
+specified in the <strong>command</strong> or <strong>file</strong> fields must be either
+absolute or relative to this directory.</li>
+<li><strong>file:</strong> The main translation unit source processed by this
+compilation step. This is used by tools as the key into the
+compilation database. There can be multiple command objects for the
+same file, for example if the same source file is compiled with
+different configurations.</li>
+<li><strong>command:</strong> The compile command executed. After JSON unescaping,
+this must be a valid command to rerun the exact compilation step for
+the translation unit in the environment the build system uses.
+Parameters use shell quoting and shell escaping of quotes, with â<code class="docutils literal notranslate"><span class="pre">"</span></code>â
+and â<code class="docutils literal notranslate"><span class="pre">\</span></code>â being the only special characters. Shell expansion is not
+supported.</li>
+<li><strong>arguments:</strong> The compile command executed as list of strings.
+Either <strong>arguments</strong> or <strong>command</strong> is required.</li>
+<li><strong>output:</strong> The name of the output created by this compilation step.
+This field is optional. It can be used to distinguish different processing
+modes of the same input file.</li>
+</ul>
+</div>
+<div class="section" id="build-system-integration">
+<h2>Build System Integration<a class="headerlink" href="#build-system-integration" title="Permalink to this headline">¶</a></h2>
+<p>The convention is to name the file compile_commands.json and put it at
+the top of the build directory. Clang tools are pointed to the top of
+the build directory to detect the file and use the compilation database
+to parse C++ code in the source tree.</p>
+</div>
+<div class="section" id="alternatives">
+<h2>Alternatives<a class="headerlink" href="#alternatives" title="Permalink to this headline">¶</a></h2>
+<p>For simple projects, Clang tools also recognize a compile_flags.txt file.
+This should contain one flag per line. The same flags will be used to compile
+any file.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="RefactoringEngine.html">Clangâs refactoring engine</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/LTOVisibility.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/LTOVisibility.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/LTOVisibility.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/LTOVisibility.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,160 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>LTO Visibility — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="SafeStack" href="SafeStack.html" />
+ <link rel="prev" title="Control Flow Integrity Design Documentation" href="ControlFlowIntegrityDesign.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>LTO Visibility</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="ControlFlowIntegrityDesign.html">Control Flow Integrity Design Documentation</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SafeStack.html">SafeStack</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="lto-visibility">
+<h1>LTO Visibility<a class="headerlink" href="#lto-visibility" title="Permalink to this headline">¶</a></h1>
+<p><em>LTO visibility</em> is a property of an entity that specifies whether it can be
+referenced from outside the current LTO unit. A <em>linkage unit</em> is a set of
+translation units linked together into an executable or DSO, and a linkage
+unitâs <em>LTO unit</em> is the subset of the linkage unit that is linked together
+using link-time optimization; in the case where LTO is not being used, the
+linkage unitâs LTO unit is empty. Each linkage unit has only a single LTO unit.</p>
+<p>The LTO visibility of a class is used by the compiler to determine which
+classes the whole-program devirtualization (<code class="docutils literal notranslate"><span class="pre">-fwhole-program-vtables</span></code>) and
+control flow integrity (<code class="docutils literal notranslate"><span class="pre">-fsanitize=cfi-vcall</span></code> and <code class="docutils literal notranslate"><span class="pre">-fsanitize=cfi-mfcall</span></code>)
+features apply to. These features use whole-program information, so they
+require the entire class hierarchy to be visible in order to work correctly.</p>
+<p>If any translation unit in the program uses either of the whole-program
+devirtualization or control flow integrity features, it is effectively an ODR
+violation to define a class with hidden LTO visibility in multiple linkage
+units. A class with public LTO visibility may be defined in multiple linkage
+units, but the tradeoff is that the whole-program devirtualization and
+control flow integrity features can only be applied to classes with hidden LTO
+visibility. A classâs LTO visibility is treated as an ODR-relevant property
+of its definition, so it must be consistent between translation units.</p>
+<p>In translation units built with LTO, LTO visibility is based on the
+classâs symbol visibility as expressed at the source level (i.e. the
+<code class="docutils literal notranslate"><span class="pre">__attribute__((visibility("...")))</span></code> attribute, or the <code class="docutils literal notranslate"><span class="pre">-fvisibility=</span></code>
+flag) or, on the Windows platform, the dllimport and dllexport attributes. When
+targeting non-Windows platforms, classes with a visibility other than hidden
+visibility receive public LTO visibility. When targeting Windows, classes
+with dllimport or dllexport attributes receive public LTO visibility. All
+other classes receive hidden LTO visibility. Classes with internal linkage
+(e.g. classes declared in unnamed namespaces) also receive hidden LTO
+visibility.</p>
+<p>A class defined in a translation unit built without LTO receives public
+LTO visibility regardless of its object file visibility, linkage or other
+attributes.</p>
+<p>This mechanism will produce the correct result in most cases, but there are
+two cases where it may wrongly infer hidden LTO visibility.</p>
+<ol class="arabic simple">
+<li>As a corollary of the above rules, if a linkage unit is produced from a
+combination of LTO object files and non-LTO object files, any hidden
+visibility class defined in both a translation unit built with LTO and
+a translation unit built without LTO must be defined with public LTO
+visibility in order to avoid an ODR violation.</li>
+<li>Some ABIs provide the ability to define an abstract base class without
+visibility attributes in multiple linkage units and have virtual calls
+to derived classes in other linkage units work correctly. One example of
+this is COM on Windows platforms. If the ABI allows this, any base class
+used in this way must be defined with public LTO visibility.</li>
+</ol>
+<p>Classes that fall into either of these categories can be marked up with the
+<code class="docutils literal notranslate"><span class="pre">[[clang::lto_visibility_public]]</span></code> attribute. To specifically handle the
+COM case, classes with the <code class="docutils literal notranslate"><span class="pre">__declspec(uuid())</span></code> attribute receive public
+LTO visibility. On Windows platforms, clang-clâs <code class="docutils literal notranslate"><span class="pre">/MT</span></code> and <code class="docutils literal notranslate"><span class="pre">/MTd</span></code>
+flags statically link the program against a prebuilt standard library;
+these flags imply public LTO visibility for every class declared in the
+<code class="docutils literal notranslate"><span class="pre">std</span></code> and <code class="docutils literal notranslate"><span class="pre">stdext</span></code> namespaces.</p>
+<div class="section" id="example">
+<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
+<p>The following example shows how LTO visibility works in practice in several
+cases involving two linkage units, <code class="docutils literal notranslate"><span class="pre">main</span></code> and <code class="docutils literal notranslate"><span class="pre">dso.so</span></code>.</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>+-----------------------------------------------------------+ +----------------------------------------------------+
+| main (clang++ -fvisibility=hidden): | | dso.so (clang++ -fvisibility=hidden): |
+| | | |
+| +-----------------------------------------------------+ | | struct __attribute__((visibility("default"))) C { |
+| | LTO unit (clang++ -fvisibility=hidden -flto): | | | virtual void f(); |
+| | | | | } |
+| | struct A { ... }; | | | void C::f() {} |
+| | struct [[clang::lto_visibility_public]] B { ... }; | | | struct D { |
+| | struct __attribute__((visibility("default"))) C { | | | virtual void g() = 0; |
+| | virtual void f(); | | | }; |
+| | }; | | | struct E : D { |
+| | struct [[clang::lto_visibility_public]] D { | | | virtual void g() { ... } |
+| | virtual void g() = 0; | | | }; |
+| | }; | | | __attribute__(visibility("default"))) D *mkE() { |
+| | | | | return new E; |
+| +-----------------------------------------------------+ | | } |
+| | | |
+| struct B { ... }; | +----------------------------------------------------+
+| |
++-----------------------------------------------------------+
+</pre></div>
+</div>
+<p>We will now describe the LTO visibility of each of the classes defined in
+these linkage units.</p>
+<p>Class <code class="docutils literal notranslate"><span class="pre">A</span></code> is not defined outside of <code class="docutils literal notranslate"><span class="pre">main</span></code>âs LTO unit, so it can have
+hidden LTO visibility. This is inferred from the object file visibility
+specified on the command line.</p>
+<p>Class <code class="docutils literal notranslate"><span class="pre">B</span></code> is defined in <code class="docutils literal notranslate"><span class="pre">main</span></code>, both inside and outside its LTO unit. The
+definition outside the LTO unit has public LTO visibility, so the definition
+inside the LTO unit must also have public LTO visibility in order to avoid
+an ODR violation.</p>
+<p>Class <code class="docutils literal notranslate"><span class="pre">C</span></code> is defined in both <code class="docutils literal notranslate"><span class="pre">main</span></code> and <code class="docutils literal notranslate"><span class="pre">dso.so</span></code> and therefore must
+have public LTO visibility. This is correctly inferred from the <code class="docutils literal notranslate"><span class="pre">visibility</span></code>
+attribute.</p>
+<p>Class <code class="docutils literal notranslate"><span class="pre">D</span></code> is an abstract base class with a derived class <code class="docutils literal notranslate"><span class="pre">E</span></code> defined
+in <code class="docutils literal notranslate"><span class="pre">dso.so</span></code>. This is an example of the COM scenario; the definition of
+<code class="docutils literal notranslate"><span class="pre">D</span></code> in <code class="docutils literal notranslate"><span class="pre">main</span></code>âs LTO unit must have public LTO visibility in order to be
+compatible with the definition of <code class="docutils literal notranslate"><span class="pre">D</span></code> in <code class="docutils literal notranslate"><span class="pre">dso.so</span></code>, which is observable
+by calling the function <code class="docutils literal notranslate"><span class="pre">mkE</span></code>.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="ControlFlowIntegrityDesign.html">Control Flow Integrity Design Documentation</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SafeStack.html">SafeStack</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/LanguageExtensions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/LanguageExtensions.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/LanguageExtensions.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/LanguageExtensions.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,3026 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Clang Language Extensions — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Objective-C Literals" href="ObjectiveCLiterals.html" />
+ <link rel="prev" title="Assembling a Complete Toolchain" href="Toolchain.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Clang Language Extensions</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="Toolchain.html">Assembling a Complete Toolchain</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ObjectiveCLiterals.html">Objective-C Literals</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="clang-language-extensions">
+<h1>Clang Language Extensions<a class="headerlink" href="#clang-language-extensions" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id5">Introduction</a></li>
+<li><a class="reference internal" href="#feature-checking-macros" id="id6">Feature Checking Macros</a></li>
+<li><a class="reference internal" href="#include-file-checking-macros" id="id7">Include File Checking Macros</a></li>
+<li><a class="reference internal" href="#builtin-macros" id="id8">Builtin Macros</a></li>
+<li><a class="reference internal" href="#vectors-and-extended-vectors" id="id9">Vectors and Extended Vectors</a></li>
+<li><a class="reference internal" href="#half-precision-floating-point" id="id10">Half-Precision Floating Point</a></li>
+<li><a class="reference internal" href="#messages-on-deprecated-and-unavailable-attributes" id="id11">Messages on <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> and <code class="docutils literal notranslate"><span class="pre">unavailable</span></code> Attributes</a></li>
+<li><a class="reference internal" href="#attributes-on-enumerators" id="id12">Attributes on Enumerators</a></li>
+<li><a class="reference internal" href="#user-specified-system-frameworks" id="id13">âUser-Specifiedâ System Frameworks</a></li>
+<li><a class="reference internal" href="#checks-for-standard-language-features" id="id14">Checks for Standard Language Features</a></li>
+<li><a class="reference internal" href="#checks-for-type-trait-primitives" id="id15">Checks for Type Trait Primitives</a></li>
+<li><a class="reference internal" href="#blocks" id="id16">Blocks</a></li>
+<li><a class="reference internal" href="#objective-c-features" id="id17">Objective-C Features</a></li>
+<li><a class="reference internal" href="#opencl-features" id="id18">OpenCL Features</a></li>
+<li><a class="reference internal" href="#initializer-lists-for-complex-numbers-in-c" id="id19">Initializer lists for complex numbers in C</a></li>
+<li><a class="reference internal" href="#builtin-functions" id="id20">Builtin Functions</a></li>
+<li><a class="reference internal" href="#non-standard-c-11-attributes" id="id21">Non-standard C++11 Attributes</a></li>
+<li><a class="reference internal" href="#target-specific-extensions" id="id22">Target-Specific Extensions</a></li>
+<li><a class="reference internal" href="#extensions-for-static-analysis" id="id23">Extensions for Static Analysis</a></li>
+<li><a class="reference internal" href="#extensions-for-dynamic-analysis" id="id24">Extensions for Dynamic Analysis</a></li>
+<li><a class="reference internal" href="#extensions-for-selectively-disabling-optimization" id="id25">Extensions for selectively disabling optimization</a></li>
+<li><a class="reference internal" href="#extensions-for-loop-hint-optimizations" id="id26">Extensions for loop hint optimizations</a></li>
+<li><a class="reference internal" href="#extensions-to-specify-floating-point-flags" id="id27">Extensions to specify floating-point flags</a></li>
+<li><a class="reference internal" href="#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute" id="id28">Specifying an attribute for multiple declarations (#pragma clang attribute)</a></li>
+<li><a class="reference internal" href="#specifying-section-names-for-global-objects-pragma-clang-section" id="id29">Specifying section names for global objects (#pragma clang section)</a></li>
+<li><a class="reference internal" href="#specifying-linker-options-on-elf-targets" id="id30">Specifying Linker Options on ELF Targets</a></li>
+<li><a class="reference internal" href="#evaluating-object-size-dynamically" id="id31">Evaluating Object Size Dynamically</a></li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id5">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the language extensions provided by Clang. In addition
+to the language extensions listed here, Clang aims to support a broad range of
+GCC extensions. Please see the <a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for more information on
+these extensions.</p>
+</div>
+<div class="section" id="feature-checking-macros">
+<span id="langext-feature-check"></span><h2><a class="toc-backref" href="#id6">Feature Checking Macros</a><a class="headerlink" href="#feature-checking-macros" title="Permalink to this headline">¶</a></h2>
+<p>Language extensions can be very useful, but only if you know you can depend on
+them. In order to allow fine-grain features checks, we support three builtin
+function-like macros. This allows you to directly test for a feature in your
+code without having to resort to something like autoconf or fragile âcompiler
+version checksâ.</p>
+<div class="section" id="has-builtin">
+<h3><code class="docutils literal notranslate"><span class="pre">__has_builtin</span></code><a class="headerlink" href="#has-builtin" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro takes a single identifier argument that is the name of
+a builtin function. It evaluates to 1 if the builtin is supported or 0 if not.
+It can be used like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifndef __has_builtin </span><span class="c1">// Optional of course.</span>
+ <span class="cp">#define __has_builtin(x) 0 </span><span class="c1">// Compatibility with non-clang compilers.</span>
+<span class="cp">#endif</span>
+
+<span class="p">...</span>
+<span class="cp">#if __has_builtin(__builtin_trap)</span>
+ <span class="n">__builtin_trap</span><span class="p">();</span>
+<span class="cp">#else</span>
+ <span class="n">abort</span><span class="p">();</span>
+<span class="cp">#endif</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-feature-and-has-extension">
+<span id="langext-has-feature-has-extension"></span><h3><code class="docutils literal notranslate"><span class="pre">__has_feature</span></code> and <code class="docutils literal notranslate"><span class="pre">__has_extension</span></code><a class="headerlink" href="#has-feature-and-has-extension" title="Permalink to this headline">¶</a></h3>
+<p>These function-like macros take a single identifier argument that is the name
+of a feature. <code class="docutils literal notranslate"><span class="pre">__has_feature</span></code> evaluates to 1 if the feature is both
+supported by Clang and standardized in the current language standard or 0 if
+not (but see <a class="reference internal" href="#langext-has-feature-back-compat"><span class="std std-ref">below</span></a>), while
+<code class="docutils literal notranslate"><span class="pre">__has_extension</span></code> evaluates to 1 if the feature is supported by Clang in the
+current language (either as a language extension or a standard language
+feature) or 0 if not. They can be used like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifndef __has_feature </span><span class="c1">// Optional of course.</span>
+ <span class="cp">#define __has_feature(x) 0 </span><span class="c1">// Compatibility with non-clang compilers.</span>
+<span class="cp">#endif</span>
+<span class="cp">#ifndef __has_extension</span>
+ <span class="cp">#define __has_extension __has_feature </span><span class="c1">// Compatibility with pre-3.0 compilers.</span>
+<span class="cp">#endif</span>
+
+<span class="p">...</span>
+<span class="cp">#if __has_feature(cxx_rvalue_references)</span>
+<span class="c1">// This code will only be compiled with the -std=c++11 and -std=gnu++11</span>
+<span class="c1">// options, because rvalue references are only standardized in C++11.</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if __has_extension(cxx_rvalue_references)</span>
+<span class="c1">// This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98</span>
+<span class="c1">// and -std=gnu++98 options, because rvalue references are supported as a</span>
+<span class="c1">// language extension in C++98.</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p id="langext-has-feature-back-compat">For backward compatibility, <code class="docutils literal notranslate"><span class="pre">__has_feature</span></code> can also be used to test
+for support for non-standardized features, i.e. features not prefixed <code class="docutils literal notranslate"><span class="pre">c_</span></code>,
+<code class="docutils literal notranslate"><span class="pre">cxx_</span></code> or <code class="docutils literal notranslate"><span class="pre">objc_</span></code>.</p>
+<p>Another use of <code class="docutils literal notranslate"><span class="pre">__has_feature</span></code> is to check for compiler features not related
+to the language standard, such as e.g. <a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>.</p>
+<p>If the <code class="docutils literal notranslate"><span class="pre">-pedantic-errors</span></code> option is given, <code class="docutils literal notranslate"><span class="pre">__has_extension</span></code> is equivalent
+to <code class="docutils literal notranslate"><span class="pre">__has_feature</span></code>.</p>
+<p>The feature tag is described along with the language feature below.</p>
+<p>The feature name or extension name can also be specified with a preceding and
+following <code class="docutils literal notranslate"><span class="pre">__</span></code> (double underscore) to avoid interference from a macro with
+the same name. For instance, <code class="docutils literal notranslate"><span class="pre">__cxx_rvalue_references__</span></code> can be used instead
+of <code class="docutils literal notranslate"><span class="pre">cxx_rvalue_references</span></code>.</p>
+</div>
+<div class="section" id="has-cpp-attribute">
+<h3><code class="docutils literal notranslate"><span class="pre">__has_cpp_attribute</span></code><a class="headerlink" href="#has-cpp-attribute" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro is available in C++2a by default, and is provided as an
+extension in earlier language standards. It takes a single argument that is the
+name of a double-square-bracket-style attribute. The argument can either be a
+single identifier or a scoped identifier. If the attribute is supported, a
+nonzero value is returned. If the attribute is a standards-based attribute, this
+macro returns a nonzero value based on the year and month in which the attribute
+was voted into the working draft. See <a class="reference external" href="https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations">WG21 SD-6</a>
+for the list of values returned for standards-based attributes. If the attribute
+is not supported by the current compliation target, this macro evaluates to 0.
+It can be used like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifndef __has_cpp_attribute </span><span class="c1">// For backwards compatibility</span>
+ <span class="cp">#define __has_cpp_attribute(x) 0</span>
+<span class="cp">#endif</span>
+
+<span class="p">...</span>
+<span class="cp">#if __has_cpp_attribute(clang::fallthrough)</span>
+<span class="cp">#define FALLTHROUGH [[clang::fallthrough]]</span>
+<span class="cp">#else</span>
+<span class="cp">#define FALLTHROUGH</span>
+<span class="cp">#endif</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>The attribute scope tokens <code class="docutils literal notranslate"><span class="pre">clang</span></code> and <code class="docutils literal notranslate"><span class="pre">_Clang</span></code> are interchangeable, as are
+the attribute scope tokens <code class="docutils literal notranslate"><span class="pre">gnu</span></code> and <code class="docutils literal notranslate"><span class="pre">__gnu__</span></code>. Attribute tokens in either
+of these namespaces can be specified with a preceding and following <code class="docutils literal notranslate"><span class="pre">__</span></code>
+(double underscore) to avoid interference from a macro with the same name. For
+instance, <code class="docutils literal notranslate"><span class="pre">gnu::__const__</span></code> can be used instead of <code class="docutils literal notranslate"><span class="pre">gnu::const</span></code>.</p>
+</div>
+<div class="section" id="has-c-attribute">
+<h3><code class="docutils literal notranslate"><span class="pre">__has_c_attribute</span></code><a class="headerlink" href="#has-c-attribute" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro takes a single argument that is the name of an
+attribute exposed with the double square-bracket syntax in C mode. The argument
+can either be a single identifier or a scoped identifier. If the attribute is
+supported, a nonzero value is returned. If the attribute is not supported by the
+current compilation target, this macro evaluates to 0. It can be used like this:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifndef __has_c_attribute </span><span class="c1">// Optional of course.</span>
+ <span class="cp">#define __has_c_attribute(x) 0 </span><span class="c1">// Compatibility with non-clang compilers.</span>
+<span class="cp">#endif</span>
+
+<span class="p">...</span>
+<span class="cp">#if __has_c_attribute(fallthrough)</span>
+ <span class="cp">#define FALLTHROUGH [[fallthrough]]</span>
+<span class="cp">#else</span>
+ <span class="cp">#define FALLTHROUGH</span>
+<span class="cp">#endif</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>The attribute scope tokens <code class="docutils literal notranslate"><span class="pre">clang</span></code> and <code class="docutils literal notranslate"><span class="pre">_Clang</span></code> are interchangeable, as are
+the attribute scope tokens <code class="docutils literal notranslate"><span class="pre">gnu</span></code> and <code class="docutils literal notranslate"><span class="pre">__gnu__</span></code>. Attribute tokens in either
+of these namespaces can be specified with a preceding and following <code class="docutils literal notranslate"><span class="pre">__</span></code>
+(double underscore) to avoid interference from a macro with the same name. For
+instance, <code class="docutils literal notranslate"><span class="pre">gnu::__const__</span></code> can be used instead of <code class="docutils literal notranslate"><span class="pre">gnu::const</span></code>.</p>
+</div>
+<div class="section" id="has-attribute">
+<h3><code class="docutils literal notranslate"><span class="pre">__has_attribute</span></code><a class="headerlink" href="#has-attribute" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro takes a single identifier argument that is the name of
+a GNU-style attribute. It evaluates to 1 if the attribute is supported by the
+current compilation target, or 0 if not. It can be used like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifndef __has_attribute </span><span class="c1">// Optional of course.</span>
+ <span class="cp">#define __has_attribute(x) 0 </span><span class="c1">// Compatibility with non-clang compilers.</span>
+<span class="cp">#endif</span>
+
+<span class="p">...</span>
+<span class="cp">#if __has_attribute(always_inline)</span>
+<span class="cp">#define ALWAYS_INLINE __attribute__((always_inline))</span>
+<span class="cp">#else</span>
+<span class="cp">#define ALWAYS_INLINE</span>
+<span class="cp">#endif</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>The attribute name can also be specified with a preceding and following <code class="docutils literal notranslate"><span class="pre">__</span></code>
+(double underscore) to avoid interference from a macro with the same name. For
+instance, <code class="docutils literal notranslate"><span class="pre">__always_inline__</span></code> can be used instead of <code class="docutils literal notranslate"><span class="pre">always_inline</span></code>.</p>
+</div>
+<div class="section" id="has-declspec-attribute">
+<h3><code class="docutils literal notranslate"><span class="pre">__has_declspec_attribute</span></code><a class="headerlink" href="#has-declspec-attribute" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro takes a single identifier argument that is the name of
+an attribute implemented as a Microsoft-style <code class="docutils literal notranslate"><span class="pre">__declspec</span></code> attribute. It
+evaluates to 1 if the attribute is supported by the current compilation target,
+or 0 if not. It can be used like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifndef __has_declspec_attribute </span><span class="c1">// Optional of course.</span>
+ <span class="cp">#define __has_declspec_attribute(x) 0 </span><span class="c1">// Compatibility with non-clang compilers.</span>
+<span class="cp">#endif</span>
+
+<span class="p">...</span>
+<span class="cp">#if __has_declspec_attribute(dllexport)</span>
+<span class="cp">#define DLLEXPORT __declspec(dllexport)</span>
+<span class="cp">#else</span>
+<span class="cp">#define DLLEXPORT</span>
+<span class="cp">#endif</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>The attribute name can also be specified with a preceding and following <code class="docutils literal notranslate"><span class="pre">__</span></code>
+(double underscore) to avoid interference from a macro with the same name. For
+instance, <code class="docutils literal notranslate"><span class="pre">__dllexport__</span></code> can be used instead of <code class="docutils literal notranslate"><span class="pre">dllexport</span></code>.</p>
+</div>
+<div class="section" id="is-identifier">
+<h3><code class="docutils literal notranslate"><span class="pre">__is_identifier</span></code><a class="headerlink" href="#is-identifier" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro takes a single identifier argument that might be either
+a reserved word or a regular identifier. It evaluates to 1 if the argument is just
+a regular identifier and not a reserved word, in the sense that it can then be
+used as the name of a user-defined function or variable. Otherwise it evaluates
+to 0. It can be used like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="p">...</span>
+<span class="cp">#ifdef __is_identifier </span><span class="c1">// Compatibility with non-clang compilers.</span>
+ <span class="cp">#if __is_identifier(__wchar_t)</span>
+ <span class="k">typedef</span> <span class="kt">wchar_t</span> <span class="kr">__wchar_t</span><span class="p">;</span>
+ <span class="cp">#endif</span>
+<span class="cp">#endif</span>
+
+<span class="kr">__wchar_t</span> <span class="n">WideCharacter</span><span class="p">;</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="include-file-checking-macros">
+<h2><a class="toc-backref" href="#id7">Include File Checking Macros</a><a class="headerlink" href="#include-file-checking-macros" title="Permalink to this headline">¶</a></h2>
+<p>Not all developments systems have the same include files. The
+<a class="reference internal" href="#langext-has-include"><span class="std std-ref">__has_include</span></a> and <a class="reference internal" href="#langext-has-include-next"><span class="std std-ref">__has_include_next</span></a> macros allow
+you to check for the existence of an include file before doing a possibly
+failing <code class="docutils literal notranslate"><span class="pre">#include</span></code> directive. Include file checking macros must be used
+as expressions in <code class="docutils literal notranslate"><span class="pre">#if</span></code> or <code class="docutils literal notranslate"><span class="pre">#elif</span></code> preprocessing directives.</p>
+<div class="section" id="has-include">
+<span id="langext-has-include"></span><h3><code class="docutils literal notranslate"><span class="pre">__has_include</span></code><a class="headerlink" href="#has-include" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro takes a single file name string argument that is the
+name of an include file. It evaluates to 1 if the file can be found using the
+include paths, or 0 otherwise:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Note the two possible file name string formats.</span>
+<span class="cp">#if __has_include("myinclude.h") && __has_include(<stdint.h>)</span>
+<span class="cp"># include "myinclude.h"</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>To test for this feature, use <code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">defined(__has_include)</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// To avoid problem with non-clang compilers not having this macro.</span>
+<span class="cp">#if defined(__has_include)</span>
+<span class="cp">#if __has_include("myinclude.h")</span>
+<span class="cp"># include "myinclude.h"</span>
+<span class="cp">#endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-include-next">
+<span id="langext-has-include-next"></span><h3><code class="docutils literal notranslate"><span class="pre">__has_include_next</span></code><a class="headerlink" href="#has-include-next" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro takes a single file name string argument that is the
+name of an include file. It is like <code class="docutils literal notranslate"><span class="pre">__has_include</span></code> except that it looks for
+the second instance of the given file found in the include paths. It evaluates
+to 1 if the second instance of the file can be found using the include paths,
+or 0 otherwise:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Note the two possible file name string formats.</span>
+<span class="cp">#if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)</span>
+<span class="cp"># include_next "myinclude.h"</span>
+<span class="cp">#endif</span>
+
+<span class="c1">// To avoid problem with non-clang compilers not having this macro.</span>
+<span class="cp">#if defined(__has_include_next)</span>
+<span class="cp">#if __has_include_next("myinclude.h")</span>
+<span class="cp"># include_next "myinclude.h"</span>
+<span class="cp">#endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>Note that <code class="docutils literal notranslate"><span class="pre">__has_include_next</span></code>, like the GNU extension <code class="docutils literal notranslate"><span class="pre">#include_next</span></code>
+directive, is intended for use in headers only, and will issue a warning if
+used in the top-level compilation file. A warning will also be issued if an
+absolute path is used in the file argument.</p>
+</div>
+<div class="section" id="has-warning">
+<h3><code class="docutils literal notranslate"><span class="pre">__has_warning</span></code><a class="headerlink" href="#has-warning" title="Permalink to this headline">¶</a></h3>
+<p>This function-like macro takes a string literal that represents a command line
+option for a warning and returns true if that is a valid warning option.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#if __has_warning("-Wformat")</span>
+<span class="p">...</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="builtin-macros">
+<span id="languageextensions-builtin-macros"></span><h2><a class="toc-backref" href="#id8">Builtin Macros</a><a class="headerlink" href="#builtin-macros" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt><code class="docutils literal notranslate"><span class="pre">__BASE_FILE__</span></code></dt>
+<dd>Defined to a string that contains the name of the main input file passed to
+Clang.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__FILE_NAME__</span></code></dt>
+<dd>Clang-specific extension that functions similar to <code class="docutils literal notranslate"><span class="pre">__FILE__</span></code> but only
+renders the last path component (the filename) instead of an invocation
+dependent full path to that file.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__COUNTER__</span></code></dt>
+<dd>Defined to an integer value that starts at zero and is incremented each time
+the <code class="docutils literal notranslate"><span class="pre">__COUNTER__</span></code> macro is expanded.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__INCLUDE_LEVEL__</span></code></dt>
+<dd>Defined to an integral value that is the include depth of the file currently
+being translated. For the main file, this value is zero.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__TIMESTAMP__</span></code></dt>
+<dd>Defined to the date and time of the last modification of the current source
+file.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__clang__</span></code></dt>
+<dd>Defined when compiling with Clang</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__clang_major__</span></code></dt>
+<dd>Defined to the major marketing version number of Clang (e.g., the 2 in
+2.0.1). Note that marketing version numbers should not be used to check for
+language features, as different vendors use different numbering schemes.
+Instead, use the <a class="reference internal" href="#langext-feature-check"><span class="std std-ref">Feature Checking Macros</span></a>.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__clang_minor__</span></code></dt>
+<dd>Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note
+that marketing version numbers should not be used to check for language
+features, as different vendors use different numbering schemes. Instead, use
+the <a class="reference internal" href="#langext-feature-check"><span class="std std-ref">Feature Checking Macros</span></a>.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__clang_patchlevel__</span></code></dt>
+<dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">__clang_version__</span></code></dt>
+<dd>Defined to a string that captures the Clang marketing version, including the
+Subversion tag or revision number, e.g., â<code class="docutils literal notranslate"><span class="pre">1.5</span> <span class="pre">(trunk</span> <span class="pre">102332)</span></code>â.</dd>
+</dl>
+</div>
+<div class="section" id="vectors-and-extended-vectors">
+<span id="langext-vectors"></span><h2><a class="toc-backref" href="#id9">Vectors and Extended Vectors</a><a class="headerlink" href="#vectors-and-extended-vectors" title="Permalink to this headline">¶</a></h2>
+<p>Supports the GCC, OpenCL, AltiVec and NEON vector extensions.</p>
+<p>OpenCL vector types are created using <code class="docutils literal notranslate"><span class="pre">ext_vector_type</span></code> attribute. It
+support for <code class="docutils literal notranslate"><span class="pre">V.xyzw</span></code> syntax and other tidbits as seen in OpenCL. An example
+is:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="kt">float</span> <span class="n">float4</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">ext_vector_type</span><span class="p">(</span><span class="mi">4</span><span class="p">)));</span>
+<span class="k">typedef</span> <span class="kt">float</span> <span class="n">float2</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">ext_vector_type</span><span class="p">(</span><span class="mi">2</span><span class="p">)));</span>
+
+<span class="n">float4</span> <span class="nf">foo</span><span class="p">(</span><span class="n">float2</span> <span class="n">a</span><span class="p">,</span> <span class="n">float2</span> <span class="n">b</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">float4</span> <span class="n">c</span><span class="p">;</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">xz</span> <span class="o">=</span> <span class="n">a</span><span class="p">;</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">yw</span> <span class="o">=</span> <span class="n">b</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">c</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_extension(attribute_ext_vector_type)</span></code>.</p>
+<p>Giving <code class="docutils literal notranslate"><span class="pre">-maltivec</span></code> option to clang enables support for AltiVec vector syntax
+and functions. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">vector</span> <span class="kt">float</span> <span class="nf">foo</span><span class="p">(</span><span class="n">vector</span> <span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">vector</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span>
+ <span class="n">b</span> <span class="o">=</span> <span class="n">vec_add</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">a</span><span class="p">)</span> <span class="o">+</span> <span class="n">a</span><span class="p">;</span>
+ <span class="k">return</span> <span class="p">(</span><span class="n">vector</span> <span class="kt">float</span><span class="p">)</span><span class="n">b</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>NEON vector types are created using <code class="docutils literal notranslate"><span class="pre">neon_vector_type</span></code> and
+<code class="docutils literal notranslate"><span class="pre">neon_polyvector_type</span></code> attributes. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">neon_vector_type</span><span class="p">(</span><span class="mi">8</span><span class="p">)))</span> <span class="kt">int8_t</span> <span class="n">int8x8_t</span><span class="p">;</span>
+<span class="k">typedef</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">neon_polyvector_type</span><span class="p">(</span><span class="mi">16</span><span class="p">)))</span> <span class="n">poly8_t</span> <span class="n">poly8x16_t</span><span class="p">;</span>
+
+<span class="n">int8x8_t</span> <span class="nf">foo</span><span class="p">(</span><span class="n">int8x8_t</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">int8x8_t</span> <span class="n">v</span><span class="p">;</span>
+ <span class="n">v</span> <span class="o">=</span> <span class="n">a</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">v</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="section" id="vector-literals">
+<h3>Vector Literals<a class="headerlink" href="#vector-literals" title="Permalink to this headline">¶</a></h3>
+<p>Vector literals can be used to create vectors from a set of scalars, or
+vectors. Either parentheses or braces form can be used. In the parentheses
+form the number of literal values specified must be one, i.e. referring to a
+scalar value, or must match the size of the vector type being created. If a
+single scalar literal value is specified, the scalar literal value will be
+replicated to all the components of the vector type. In the brackets form any
+number of literals can be specified. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="kt">int</span> <span class="n">v4si</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">__vector_size__</span><span class="p">(</span><span class="mi">16</span><span class="p">)));</span>
+<span class="k">typedef</span> <span class="kt">float</span> <span class="n">float4</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">ext_vector_type</span><span class="p">(</span><span class="mi">4</span><span class="p">)));</span>
+<span class="k">typedef</span> <span class="kt">float</span> <span class="n">float2</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">ext_vector_type</span><span class="p">(</span><span class="mi">2</span><span class="p">)));</span>
+
+<span class="n">v4si</span> <span class="n">vsi</span> <span class="o">=</span> <span class="p">(</span><span class="n">v4si</span><span class="p">){</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">};</span>
+<span class="n">float4</span> <span class="n">vf</span> <span class="o">=</span> <span class="p">(</span><span class="n">float4</span><span class="p">)(</span><span class="mf">1.0f</span><span class="p">,</span> <span class="mf">2.0f</span><span class="p">,</span> <span class="mf">3.0f</span><span class="p">,</span> <span class="mf">4.0f</span><span class="p">);</span>
+<span class="n">vector</span> <span class="kt">int</span> <span class="n">vi1</span> <span class="o">=</span> <span class="p">(</span><span class="n">vector</span> <span class="kt">int</span><span class="p">)(</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// vi1 will be (1, 1, 1, 1).</span>
+<span class="n">vector</span> <span class="kt">int</span> <span class="n">vi2</span> <span class="o">=</span> <span class="p">(</span><span class="n">vector</span> <span class="kt">int</span><span class="p">){</span><span class="mi">1</span><span class="p">};</span> <span class="c1">// vi2 will be (1, 0, 0, 0).</span>
+<span class="n">vector</span> <span class="kt">int</span> <span class="n">vi3</span> <span class="o">=</span> <span class="p">(</span><span class="n">vector</span> <span class="kt">int</span><span class="p">)(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span> <span class="c1">// error</span>
+<span class="n">vector</span> <span class="kt">int</span> <span class="n">vi4</span> <span class="o">=</span> <span class="p">(</span><span class="n">vector</span> <span class="kt">int</span><span class="p">){</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">};</span> <span class="c1">// vi4 will be (1, 2, 0, 0).</span>
+<span class="n">vector</span> <span class="kt">int</span> <span class="n">vi5</span> <span class="o">=</span> <span class="p">(</span><span class="n">vector</span> <span class="kt">int</span><span class="p">)(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">);</span>
+<span class="n">float4</span> <span class="n">vf</span> <span class="o">=</span> <span class="p">(</span><span class="n">float4</span><span class="p">)((</span><span class="n">float2</span><span class="p">)(</span><span class="mf">1.0f</span><span class="p">,</span> <span class="mf">2.0f</span><span class="p">),</span> <span class="p">(</span><span class="n">float2</span><span class="p">)(</span><span class="mf">3.0f</span><span class="p">,</span> <span class="mf">4.0f</span><span class="p">));</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="vector-operations">
+<h3>Vector Operations<a class="headerlink" href="#vector-operations" title="Permalink to this headline">¶</a></h3>
+<p>The table below shows the support for each operation by vector extension. A
+dash indicates that an operation is not accepted according to a corresponding
+specification.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="52%" />
+<col width="12%" />
+<col width="12%" />
+<col width="12%" />
+<col width="12%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Operator</th>
+<th class="head">OpenCL</th>
+<th class="head">AltiVec</th>
+<th class="head">GCC</th>
+<th class="head">NEON</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>[]</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td>unary operators +, â</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>++, â â</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td>+,â,*,/,%</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>bitwise operators &,|,^,~</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td>>>,<<</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>!, &&, ||</td>
+<td>yes</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td>==, !=, >, <, >=, <=</td>
+<td>yes</td>
+<td>yes</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>=</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+</tr>
+<tr class="row-odd"><td>:?</td>
+<td>yes</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>sizeof</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+</tr>
+<tr class="row-odd"><td>C-style cast</td>
+<td>yes</td>
+<td>yes</td>
+<td>yes</td>
+<td>no</td>
+</tr>
+<tr class="row-even"><td>reinterpret_cast</td>
+<td>yes</td>
+<td>no</td>
+<td>yes</td>
+<td>no</td>
+</tr>
+<tr class="row-odd"><td>static_cast</td>
+<td>yes</td>
+<td>no</td>
+<td>yes</td>
+<td>no</td>
+</tr>
+<tr class="row-even"><td>const_cast</td>
+<td>no</td>
+<td>no</td>
+<td>no</td>
+<td>no</td>
+</tr>
+</tbody>
+</table>
+<p>See also <a class="reference internal" href="#langext-builtin-shufflevector"><span class="std std-ref">__builtin_shufflevector</span></a>, <a class="reference internal" href="#langext-builtin-convertvector"><span class="std std-ref">__builtin_convertvector</span></a>.</p>
+</div>
+</div>
+<div class="section" id="half-precision-floating-point">
+<h2><a class="toc-backref" href="#id10">Half-Precision Floating Point</a><a class="headerlink" href="#half-precision-floating-point" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports two half-precision (16-bit) floating point types: <code class="docutils literal notranslate"><span class="pre">__fp16</span></code> and
+<code class="docutils literal notranslate"><span class="pre">_Float16</span></code>. These types are supported in all language modes.</p>
+<p><code class="docutils literal notranslate"><span class="pre">__fp16</span></code> is supported on every target, as it is purely a storage format; see below.
+<code class="docutils literal notranslate"><span class="pre">_Float16</span></code> is currently only supported on the following targets, with further
+targets pending ABI standardization:
+- 32-bit ARM
+- 64-bit ARM (AArch64)
+- SPIR
+<code class="docutils literal notranslate"><span class="pre">_Float16</span></code> will be supported on more targets as they define ABIs for it.</p>
+<p><code class="docutils literal notranslate"><span class="pre">__fp16</span></code> is a storage and interchange format only. This means that values of
+<code class="docutils literal notranslate"><span class="pre">__fp16</span></code> are immediately promoted to (at least) <code class="docutils literal notranslate"><span class="pre">float</span></code> when used in arithmetic
+operations, so that e.g. the result of adding two <code class="docutils literal notranslate"><span class="pre">__fp16</span></code> values has type <code class="docutils literal notranslate"><span class="pre">float</span></code>.
+The behavior of <code class="docutils literal notranslate"><span class="pre">__fp16</span></code> is specified by the ARM C Language Extensions (<a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053d/IHI0053D_acle_2_1.pdf">ACLE</a>).
+Clang uses the <code class="docutils literal notranslate"><span class="pre">binary16</span></code> format from IEEE 754-2008 for <code class="docutils literal notranslate"><span class="pre">__fp16</span></code>, not the ARM
+alternative format.</p>
+<p><code class="docutils literal notranslate"><span class="pre">_Float16</span></code> is an extended floating-point type. This means that, just like arithmetic on
+<code class="docutils literal notranslate"><span class="pre">float</span></code> or <code class="docutils literal notranslate"><span class="pre">double</span></code>, arithmetic on <code class="docutils literal notranslate"><span class="pre">_Float16</span></code> operands is formally performed in the
+<code class="docutils literal notranslate"><span class="pre">_Float16</span></code> type, so that e.g. the result of adding two <code class="docutils literal notranslate"><span class="pre">_Float16</span></code> values has type
+<code class="docutils literal notranslate"><span class="pre">_Float16</span></code>. The behavior of <code class="docutils literal notranslate"><span class="pre">_Float16</span></code> is specified by ISO/IEC TS 18661-3:2015
+(âFloating-point extensions for Câ). As with <code class="docutils literal notranslate"><span class="pre">__fp16</span></code>, Clang uses the <code class="docutils literal notranslate"><span class="pre">binary16</span></code>
+format from IEEE 754-2008 for <code class="docutils literal notranslate"><span class="pre">_Float16</span></code>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">_Float16</span></code> arithmetic will be performed using native half-precision support
+when available on the target (e.g. on ARMv8.2a); otherwise it will be performed
+at a higher precision (currently always <code class="docutils literal notranslate"><span class="pre">float</span></code>) and then truncated down to
+<code class="docutils literal notranslate"><span class="pre">_Float16</span></code>. Note that C and C++ allow intermediate floating-point operands
+of an expression to be computed with greater precision than is expressible in
+their type, so Clang may avoid intermediate truncations in certain cases; this may
+lead to results that are inconsistent with native arithmetic.</p>
+<p>It is recommended that portable code use <code class="docutils literal notranslate"><span class="pre">_Float16</span></code> instead of <code class="docutils literal notranslate"><span class="pre">__fp16</span></code>,
+as it has been defined by the C standards committee and has behavior that is
+more familiar to most programmers.</p>
+<p>Because <code class="docutils literal notranslate"><span class="pre">__fp16</span></code> operands are always immediately promoted to <code class="docutils literal notranslate"><span class="pre">float</span></code>, the
+common real type of <code class="docutils literal notranslate"><span class="pre">__fp16</span></code> and <code class="docutils literal notranslate"><span class="pre">_Float16</span></code> for the purposes of the usual
+arithmetic conversions is <code class="docutils literal notranslate"><span class="pre">float</span></code>.</p>
+<p>A literal can be given <code class="docutils literal notranslate"><span class="pre">_Float16</span></code> type using the suffix <code class="docutils literal notranslate"><span class="pre">f16</span></code>; for example:
+<code class="docutils literal notranslate"><span class="pre">`</span>
+<span class="pre">3.14f16</span>
+<span class="pre">`</span></code></p>
+<p>Because default argument promotion only applies to the standard floating-point
+types, <code class="docutils literal notranslate"><span class="pre">_Float16</span></code> values are not promoted to <code class="docutils literal notranslate"><span class="pre">double</span></code> when passed as variadic
+or untyped arguments. As a consequence, some caution must be taken when using
+certain library facilities with <code class="docutils literal notranslate"><span class="pre">_Float16</span></code>; for example, there is no <code class="docutils literal notranslate"><span class="pre">printf</span></code> format
+specifier for <code class="docutils literal notranslate"><span class="pre">_Float16</span></code>, and (unlike <code class="docutils literal notranslate"><span class="pre">float</span></code>) it will not be implicitly promoted to
+<code class="docutils literal notranslate"><span class="pre">double</span></code> when passed to <code class="docutils literal notranslate"><span class="pre">printf</span></code>, so the programmer must explicitly cast it to
+<code class="docutils literal notranslate"><span class="pre">double</span></code> before using it with an <code class="docutils literal notranslate"><span class="pre">%f</span></code> or similar specifier.</p>
+</div>
+<div class="section" id="messages-on-deprecated-and-unavailable-attributes">
+<h2><a class="toc-backref" href="#id11">Messages on <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> and <code class="docutils literal notranslate"><span class="pre">unavailable</span></code> Attributes</a><a class="headerlink" href="#messages-on-deprecated-and-unavailable-attributes" title="Permalink to this headline">¶</a></h2>
+<p>An optional string message can be added to the <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> and
+<code class="docutils literal notranslate"><span class="pre">unavailable</span></code> attributes. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">explode</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">deprecated</span><span class="p">(</span><span class="s">"extremely unsafe, use 'combust' instead!!!"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>If the deprecated or unavailable declaration is used, the message will be
+incorporated into the appropriate diagnostic:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
+ [-Wdeprecated-declarations]
+ explode();
+ ^
+</pre></div>
+</div>
+<p>Query for this feature with
+<code class="docutils literal notranslate"><span class="pre">__has_extension(attribute_deprecated_with_message)</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__has_extension(attribute_unavailable_with_message)</span></code>.</p>
+</div>
+<div class="section" id="attributes-on-enumerators">
+<h2><a class="toc-backref" href="#id12">Attributes on Enumerators</a><a class="headerlink" href="#attributes-on-enumerators" title="Permalink to this headline">¶</a></h2>
+<p>Clang allows attributes to be written on individual enumerators. This allows
+enumerators to be deprecated, made unavailable, etc. The attribute must appear
+after the enumerator name and before any initializer, like so:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="n">OperationMode</span> <span class="p">{</span>
+ <span class="n">OM_Invalid</span><span class="p">,</span>
+ <span class="n">OM_Normal</span><span class="p">,</span>
+ <span class="n">OM_Terrified</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">deprecated</span><span class="p">)),</span>
+ <span class="n">OM_AbortOnError</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">deprecated</span><span class="p">))</span> <span class="o">=</span> <span class="mi">4</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Attributes on the <code class="docutils literal notranslate"><span class="pre">enum</span></code> declaration do not apply to individual enumerators.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_extension(enumerator_attributes)</span></code>.</p>
+</div>
+<div class="section" id="user-specified-system-frameworks">
+<h2><a class="toc-backref" href="#id13">âUser-Specifiedâ System Frameworks</a><a class="headerlink" href="#user-specified-system-frameworks" title="Permalink to this headline">¶</a></h2>
+<p>Clang provides a mechanism by which frameworks can be built in such a way that
+they will always be treated as being âsystem frameworksâ, even if they are not
+present in a system framework directory. This can be useful to system
+framework developers who want to be able to test building other applications
+with development builds of their framework, including the manner in which the
+compiler changes warning behavior for system headers.</p>
+<p>Framework developers can opt-in to this mechanism by creating a
+â<code class="docutils literal notranslate"><span class="pre">.system_framework</span></code>â file at the top-level of their framework. That is, the
+framework should have contents like:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>.../TestFramework.framework
+.../TestFramework.framework/.system_framework
+.../TestFramework.framework/Headers
+.../TestFramework.framework/Headers/TestFramework.h
+...
+</pre></div>
+</div>
+<p>Clang will treat the presence of this file as an indicator that the framework
+should be treated as a system framework, regardless of how it was found in the
+framework search path. For consistency, we recommend that such files never be
+included in installed versions of the framework.</p>
+</div>
+<div class="section" id="checks-for-standard-language-features">
+<h2><a class="toc-backref" href="#id14">Checks for Standard Language Features</a><a class="headerlink" href="#checks-for-standard-language-features" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">__has_feature</span></code> macro can be used to query if certain standard language
+features are enabled. The <code class="docutils literal notranslate"><span class="pre">__has_extension</span></code> macro can be used to query if
+language features are available as an extension when compiling for a standard
+which does not provide them. The features which can be tested are listed here.</p>
+<p>Since Clang 3.4, the C++ SD-6 feature test macros are also supported.
+These are macros with names of the form <code class="docutils literal notranslate"><span class="pre">__cpp_<feature_name></span></code>, and are
+intended to be a portable way to query the supported features of the compiler.
+See <a class="reference external" href="https://clang.llvm.org/cxx_status.html#ts">the C++ status page</a> for
+information on the version of SD-6 supported by each Clang release, and the
+macros provided by that revision of the recommendations.</p>
+<div class="section" id="c-98">
+<h3>C++98<a class="headerlink" href="#c-98" title="Permalink to this headline">¶</a></h3>
+<p>The features listed below are part of the C++98 standard. These features are
+enabled by default when compiling C++ code.</p>
+<div class="section" id="c-exceptions">
+<h4>C++ exceptions<a class="headerlink" href="#c-exceptions" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_exceptions)</span></code> to determine if C++ exceptions have been
+enabled. For example, compiling code with <code class="docutils literal notranslate"><span class="pre">-fno-exceptions</span></code> disables C++
+exceptions.</p>
+</div>
+<div class="section" id="c-rtti">
+<h4>C++ RTTI<a class="headerlink" href="#c-rtti" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_rtti)</span></code> to determine if C++ RTTI has been enabled. For
+example, compiling code with <code class="docutils literal notranslate"><span class="pre">-fno-rtti</span></code> disables the use of RTTI.</p>
+</div>
+</div>
+<div class="section" id="c-11">
+<h3>C++11<a class="headerlink" href="#c-11" title="Permalink to this headline">¶</a></h3>
+<p>The features listed below are part of the C++11 standard. As a result, all
+these features are enabled with the <code class="docutils literal notranslate"><span class="pre">-std=c++11</span></code> or <code class="docutils literal notranslate"><span class="pre">-std=gnu++11</span></code> option
+when compiling C++ code.</p>
+<div class="section" id="c-11-sfinae-includes-access-control">
+<h4>C++11 SFINAE includes access control<a class="headerlink" href="#c-11-sfinae-includes-access-control" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_access_control_sfinae)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_access_control_sfinae)</span></code> to determine whether
+access-control errors (e.g., calling a private constructor) are considered to
+be template argument deduction errors (aka SFINAE errors), per <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170">C++ DR1170</a>.</p>
+</div>
+<div class="section" id="c-11-alias-templates">
+<h4>C++11 alias templates<a class="headerlink" href="#c-11-alias-templates" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_alias_templates)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_alias_templates)</span></code> to determine if support for C++11âs
+alias declarations and alias templates is enabled.</p>
+</div>
+<div class="section" id="c-11-alignment-specifiers">
+<h4>C++11 alignment specifiers<a class="headerlink" href="#c-11-alignment-specifiers" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_alignas)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_alignas)</span></code> to
+determine if support for alignment specifiers using <code class="docutils literal notranslate"><span class="pre">alignas</span></code> is enabled.</p>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_alignof)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_alignof)</span></code> to
+determine if support for the <code class="docutils literal notranslate"><span class="pre">alignof</span></code> keyword is enabled.</p>
+</div>
+<div class="section" id="c-11-attributes">
+<h4>C++11 attributes<a class="headerlink" href="#c-11-attributes" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_attributes)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_attributes)</span></code> to
+determine if support for attribute parsing with C++11âs square bracket notation
+is enabled.</p>
+</div>
+<div class="section" id="c-11-generalized-constant-expressions">
+<h4>C++11 generalized constant expressions<a class="headerlink" href="#c-11-generalized-constant-expressions" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_constexpr)</span></code> to determine if support for generalized
+constant expressions (e.g., <code class="docutils literal notranslate"><span class="pre">constexpr</span></code>) is enabled.</p>
+</div>
+<div class="section" id="c-11-decltype">
+<h4>C++11 <code class="docutils literal notranslate"><span class="pre">decltype()</span></code><a class="headerlink" href="#c-11-decltype" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_decltype)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_decltype)</span></code> to
+determine if support for the <code class="docutils literal notranslate"><span class="pre">decltype()</span></code> specifier is enabled. C++11âs
+<code class="docutils literal notranslate"><span class="pre">decltype</span></code> does not require type-completeness of a function call expression.
+Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_decltype_incomplete_return_types)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_decltype_incomplete_return_types)</span></code> to determine if
+support for this feature is enabled.</p>
+</div>
+<div class="section" id="c-11-default-template-arguments-in-function-templates">
+<h4>C++11 default template arguments in function templates<a class="headerlink" href="#c-11-default-template-arguments-in-function-templates" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_default_function_template_args)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_default_function_template_args)</span></code> to determine if support
+for default template arguments in function templates is enabled.</p>
+</div>
+<div class="section" id="c-11-defaulted-functions">
+<h4>C++11 <code class="docutils literal notranslate"><span class="pre">default</span></code>ed functions<a class="headerlink" href="#c-11-defaulted-functions" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_defaulted_functions)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_defaulted_functions)</span></code> to determine if support for
+defaulted function definitions (with <code class="docutils literal notranslate"><span class="pre">=</span> <span class="pre">default</span></code>) is enabled.</p>
+</div>
+<div class="section" id="c-11-delegating-constructors">
+<h4>C++11 delegating constructors<a class="headerlink" href="#c-11-delegating-constructors" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_delegating_constructors)</span></code> to determine if support for
+delegating constructors is enabled.</p>
+</div>
+<div class="section" id="c-11-deleted-functions">
+<h4>C++11 <code class="docutils literal notranslate"><span class="pre">deleted</span></code> functions<a class="headerlink" href="#c-11-deleted-functions" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_deleted_functions)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_deleted_functions)</span></code> to determine if support for deleted
+function definitions (with <code class="docutils literal notranslate"><span class="pre">=</span> <span class="pre">delete</span></code>) is enabled.</p>
+</div>
+<div class="section" id="c-11-explicit-conversion-functions">
+<h4>C++11 explicit conversion functions<a class="headerlink" href="#c-11-explicit-conversion-functions" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_explicit_conversions)</span></code> to determine if support for
+<code class="docutils literal notranslate"><span class="pre">explicit</span></code> conversion functions is enabled.</p>
+</div>
+<div class="section" id="c-11-generalized-initializers">
+<h4>C++11 generalized initializers<a class="headerlink" href="#c-11-generalized-initializers" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_generalized_initializers)</span></code> to determine if support for
+generalized initializers (using braced lists and <code class="docutils literal notranslate"><span class="pre">std::initializer_list</span></code>) is
+enabled.</p>
+</div>
+<div class="section" id="c-11-implicit-move-constructors-assignment-operators">
+<h4>C++11 implicit move constructors/assignment operators<a class="headerlink" href="#c-11-implicit-move-constructors-assignment-operators" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_implicit_moves)</span></code> to determine if Clang will implicitly
+generate move constructors and move assignment operators where needed.</p>
+</div>
+<div class="section" id="c-11-inheriting-constructors">
+<h4>C++11 inheriting constructors<a class="headerlink" href="#c-11-inheriting-constructors" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_inheriting_constructors)</span></code> to determine if support for
+inheriting constructors is enabled.</p>
+</div>
+<div class="section" id="c-11-inline-namespaces">
+<h4>C++11 inline namespaces<a class="headerlink" href="#c-11-inline-namespaces" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_inline_namespaces)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_inline_namespaces)</span></code> to determine if support for inline
+namespaces is enabled.</p>
+</div>
+<div class="section" id="c-11-lambdas">
+<h4>C++11 lambdas<a class="headerlink" href="#c-11-lambdas" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_lambdas)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_lambdas)</span></code> to
+determine if support for lambdas is enabled.</p>
+</div>
+<div class="section" id="c-11-local-and-unnamed-types-as-template-arguments">
+<h4>C++11 local and unnamed types as template arguments<a class="headerlink" href="#c-11-local-and-unnamed-types-as-template-arguments" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_local_type_template_args)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_local_type_template_args)</span></code> to determine if support for
+local and unnamed types as template arguments is enabled.</p>
+</div>
+<div class="section" id="c-11-noexcept">
+<h4>C++11 noexcept<a class="headerlink" href="#c-11-noexcept" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_noexcept)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_noexcept)</span></code> to
+determine if support for noexcept exception specifications is enabled.</p>
+</div>
+<div class="section" id="c-11-in-class-non-static-data-member-initialization">
+<h4>C++11 in-class non-static data member initialization<a class="headerlink" href="#c-11-in-class-non-static-data-member-initialization" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_nonstatic_member_init)</span></code> to determine whether in-class
+initialization of non-static data members is enabled.</p>
+</div>
+<div class="section" id="c-11-nullptr">
+<h4>C++11 <code class="docutils literal notranslate"><span class="pre">nullptr</span></code><a class="headerlink" href="#c-11-nullptr" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_nullptr)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_nullptr)</span></code> to
+determine if support for <code class="docutils literal notranslate"><span class="pre">nullptr</span></code> is enabled.</p>
+</div>
+<div class="section" id="c-11-override-control">
+<h4>C++11 <code class="docutils literal notranslate"><span class="pre">override</span> <span class="pre">control</span></code><a class="headerlink" href="#c-11-override-control" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_override_control)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_override_control)</span></code> to determine if support for the
+override control keywords is enabled.</p>
+</div>
+<div class="section" id="c-11-reference-qualified-functions">
+<h4>C++11 reference-qualified functions<a class="headerlink" href="#c-11-reference-qualified-functions" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_reference_qualified_functions)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_reference_qualified_functions)</span></code> to determine if support
+for reference-qualified functions (e.g., member functions with <code class="docutils literal notranslate"><span class="pre">&</span></code> or <code class="docutils literal notranslate"><span class="pre">&&</span></code>
+applied to <code class="docutils literal notranslate"><span class="pre">*this</span></code>) is enabled.</p>
+</div>
+<div class="section" id="c-11-range-based-for-loop">
+<h4>C++11 range-based <code class="docutils literal notranslate"><span class="pre">for</span></code> loop<a class="headerlink" href="#c-11-range-based-for-loop" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_range_for)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_range_for)</span></code> to
+determine if support for the range-based for loop is enabled.</p>
+</div>
+<div class="section" id="c-11-raw-string-literals">
+<h4>C++11 raw string literals<a class="headerlink" href="#c-11-raw-string-literals" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_raw_string_literals)</span></code> to determine if support for raw
+string literals (e.g., <code class="docutils literal notranslate"><span class="pre">R"x(foo\bar)x"</span></code>) is enabled.</p>
+</div>
+<div class="section" id="c-11-rvalue-references">
+<h4>C++11 rvalue references<a class="headerlink" href="#c-11-rvalue-references" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_rvalue_references)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_rvalue_references)</span></code> to determine if support for rvalue
+references is enabled.</p>
+</div>
+<div class="section" id="c-11-static-assert">
+<h4>C++11 <code class="docutils literal notranslate"><span class="pre">static_assert()</span></code><a class="headerlink" href="#c-11-static-assert" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_static_assert)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_static_assert)</span></code> to determine if support for compile-time
+assertions using <code class="docutils literal notranslate"><span class="pre">static_assert</span></code> is enabled.</p>
+</div>
+<div class="section" id="c-11-thread-local">
+<h4>C++11 <code class="docutils literal notranslate"><span class="pre">thread_local</span></code><a class="headerlink" href="#c-11-thread-local" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_thread_local)</span></code> to determine if support for
+<code class="docutils literal notranslate"><span class="pre">thread_local</span></code> variables is enabled.</p>
+</div>
+<div class="section" id="c-11-type-inference">
+<h4>C++11 type inference<a class="headerlink" href="#c-11-type-inference" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_auto_type)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_auto_type)</span></code> to
+determine C++11 type inference is supported using the <code class="docutils literal notranslate"><span class="pre">auto</span></code> specifier. If
+this is disabled, <code class="docutils literal notranslate"><span class="pre">auto</span></code> will instead be a storage class specifier, as in C
+or C++98.</p>
+</div>
+<div class="section" id="c-11-strongly-typed-enumerations">
+<h4>C++11 strongly typed enumerations<a class="headerlink" href="#c-11-strongly-typed-enumerations" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_strong_enums)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_strong_enums)</span></code> to determine if support for strongly
+typed, scoped enumerations is enabled.</p>
+</div>
+<div class="section" id="c-11-trailing-return-type">
+<h4>C++11 trailing return type<a class="headerlink" href="#c-11-trailing-return-type" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_trailing_return)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_trailing_return)</span></code> to determine if support for the
+alternate function declaration syntax with trailing return type is enabled.</p>
+</div>
+<div class="section" id="c-11-unicode-string-literals">
+<h4>C++11 Unicode string literals<a class="headerlink" href="#c-11-unicode-string-literals" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_unicode_literals)</span></code> to determine if support for Unicode
+string literals is enabled.</p>
+</div>
+<div class="section" id="c-11-unrestricted-unions">
+<h4>C++11 unrestricted unions<a class="headerlink" href="#c-11-unrestricted-unions" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_unrestricted_unions)</span></code> to determine if support for
+unrestricted unions is enabled.</p>
+</div>
+<div class="section" id="c-11-user-defined-literals">
+<h4>C++11 user-defined literals<a class="headerlink" href="#c-11-user-defined-literals" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_user_literals)</span></code> to determine if support for
+user-defined literals is enabled.</p>
+</div>
+<div class="section" id="c-11-variadic-templates">
+<h4>C++11 variadic templates<a class="headerlink" href="#c-11-variadic-templates" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_variadic_templates)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_variadic_templates)</span></code> to determine if support for
+variadic templates is enabled.</p>
+</div>
+</div>
+<div class="section" id="c-14">
+<h3>C++14<a class="headerlink" href="#c-14" title="Permalink to this headline">¶</a></h3>
+<p>The features listed below are part of the C++14 standard. As a result, all
+these features are enabled with the <code class="docutils literal notranslate"><span class="pre">-std=C++14</span></code> or <code class="docutils literal notranslate"><span class="pre">-std=gnu++14</span></code> option
+when compiling C++ code.</p>
+<div class="section" id="c-14-binary-literals">
+<h4>C++14 binary literals<a class="headerlink" href="#c-14-binary-literals" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_binary_literals)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_binary_literals)</span></code> to determine whether
+binary literals (for instance, <code class="docutils literal notranslate"><span class="pre">0b10010</span></code>) are recognized. Clang supports this
+feature as an extension in all language modes.</p>
+</div>
+<div class="section" id="c-14-contextual-conversions">
+<h4>C++14 contextual conversions<a class="headerlink" href="#c-14-contextual-conversions" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_contextual_conversions)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_contextual_conversions)</span></code> to determine if the C++14 rules
+are used when performing an implicit conversion for an array bound in a
+<em>new-expression</em>, the operand of a <em>delete-expression</em>, an integral constant
+expression, or a condition in a <code class="docutils literal notranslate"><span class="pre">switch</span></code> statement.</p>
+</div>
+<div class="section" id="c-14-decltype-auto">
+<h4>C++14 decltype(auto)<a class="headerlink" href="#c-14-decltype-auto" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_decltype_auto)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_decltype_auto)</span></code> to determine if support
+for the <code class="docutils literal notranslate"><span class="pre">decltype(auto)</span></code> placeholder type is enabled.</p>
+</div>
+<div class="section" id="c-14-default-initializers-for-aggregates">
+<h4>C++14 default initializers for aggregates<a class="headerlink" href="#c-14-default-initializers-for-aggregates" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_aggregate_nsdmi)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_aggregate_nsdmi)</span></code> to determine if support
+for default initializers in aggregate members is enabled.</p>
+</div>
+<div class="section" id="c-14-digit-separators">
+<h4>C++14 digit separators<a class="headerlink" href="#c-14-digit-separators" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__cpp_digit_separators</span></code> to determine if support for digit separators
+using single quotes (for instance, <code class="docutils literal notranslate"><span class="pre">10'000</span></code>) is enabled. At this time, there
+is no corresponding <code class="docutils literal notranslate"><span class="pre">__has_feature</span></code> name</p>
+</div>
+<div class="section" id="c-14-generalized-lambda-capture">
+<h4>C++14 generalized lambda capture<a class="headerlink" href="#c-14-generalized-lambda-capture" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_init_captures)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_init_captures)</span></code> to determine if support for
+lambda captures with explicit initializers is enabled
+(for instance, <code class="docutils literal notranslate"><span class="pre">[n(0)]</span> <span class="pre">{</span> <span class="pre">return</span> <span class="pre">++n;</span> <span class="pre">}</span></code>).</p>
+</div>
+<div class="section" id="c-14-generic-lambdas">
+<h4>C++14 generic lambdas<a class="headerlink" href="#c-14-generic-lambdas" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_generic_lambdas)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_generic_lambdas)</span></code> to determine if support for generic
+(polymorphic) lambdas is enabled
+(for instance, <code class="docutils literal notranslate"><span class="pre">[]</span> <span class="pre">(auto</span> <span class="pre">x)</span> <span class="pre">{</span> <span class="pre">return</span> <span class="pre">x</span> <span class="pre">+</span> <span class="pre">1;</span> <span class="pre">}</span></code>).</p>
+</div>
+<div class="section" id="c-14-relaxed-constexpr">
+<h4>C++14 relaxed constexpr<a class="headerlink" href="#c-14-relaxed-constexpr" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_relaxed_constexpr)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_relaxed_constexpr)</span></code> to determine if variable
+declarations, local variable modification, and control flow constructs
+are permitted in <code class="docutils literal notranslate"><span class="pre">constexpr</span></code> functions.</p>
+</div>
+<div class="section" id="c-14-return-type-deduction">
+<h4>C++14 return type deduction<a class="headerlink" href="#c-14-return-type-deduction" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_return_type_deduction)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_return_type_deduction)</span></code> to determine if support
+for return type deduction for functions (using <code class="docutils literal notranslate"><span class="pre">auto</span></code> as a return type)
+is enabled.</p>
+</div>
+<div class="section" id="c-14-runtime-sized-arrays">
+<h4>C++14 runtime-sized arrays<a class="headerlink" href="#c-14-runtime-sized-arrays" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_runtime_array)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_runtime_array)</span></code> to determine if support
+for arrays of runtime bound (a restricted form of variable-length arrays)
+is enabled.
+Clangâs implementation of this feature is incomplete.</p>
+</div>
+<div class="section" id="c-14-variable-templates">
+<h4>C++14 variable templates<a class="headerlink" href="#c-14-variable-templates" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_variable_templates)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(cxx_variable_templates)</span></code> to determine if support for
+templated variable declarations is enabled.</p>
+</div>
+</div>
+<div class="section" id="c11">
+<h3>C11<a class="headerlink" href="#c11" title="Permalink to this headline">¶</a></h3>
+<p>The features listed below are part of the C11 standard. As a result, all these
+features are enabled with the <code class="docutils literal notranslate"><span class="pre">-std=c11</span></code> or <code class="docutils literal notranslate"><span class="pre">-std=gnu11</span></code> option when
+compiling C code. Additionally, because these features are all
+backward-compatible, they are available as extensions in all language modes.</p>
+<div class="section" id="c11-alignment-specifiers">
+<h4>C11 alignment specifiers<a class="headerlink" href="#c11-alignment-specifiers" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(c_alignas)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(c_alignas)</span></code> to determine
+if support for alignment specifiers using <code class="docutils literal notranslate"><span class="pre">_Alignas</span></code> is enabled.</p>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(c_alignof)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(c_alignof)</span></code> to determine
+if support for the <code class="docutils literal notranslate"><span class="pre">_Alignof</span></code> keyword is enabled.</p>
+</div>
+<div class="section" id="c11-atomic-operations">
+<h4>C11 atomic operations<a class="headerlink" href="#c11-atomic-operations" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(c_atomic)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(c_atomic)</span></code> to determine
+if support for atomic types using <code class="docutils literal notranslate"><span class="pre">_Atomic</span></code> is enabled. Clang also provides
+<a class="reference internal" href="#langext-c11-atomic"><span class="std std-ref">a set of builtins</span></a> which can be used to implement
+the <code class="docutils literal notranslate"><span class="pre"><stdatomic.h></span></code> operations on <code class="docutils literal notranslate"><span class="pre">_Atomic</span></code> types. Use
+<code class="docutils literal notranslate"><span class="pre">__has_include(<stdatomic.h>)</span></code> to determine if C11âs <code class="docutils literal notranslate"><span class="pre"><stdatomic.h></span></code> header
+is available.</p>
+<p>Clang will use the systemâs <code class="docutils literal notranslate"><span class="pre"><stdatomic.h></span></code> header when one is available, and
+will otherwise use its own. When using its own, implementations of the atomic
+operations are provided as macros. In the cases where C11 also requires a real
+function, this header provides only the declaration of that function (along
+with a shadowing macro implementation), and you must link to a library which
+provides a definition of the function if you use it instead of the macro.</p>
+</div>
+<div class="section" id="c11-generic-selections">
+<h4>C11 generic selections<a class="headerlink" href="#c11-generic-selections" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(c_generic_selections)</span></code> or
+<code class="docutils literal notranslate"><span class="pre">__has_extension(c_generic_selections)</span></code> to determine if support for generic
+selections is enabled.</p>
+<p>As an extension, the C11 generic selection expression is available in all
+languages supported by Clang. The syntax is the same as that given in the C11
+standard.</p>
+<p>In C, type compatibility is decided according to the rules given in the
+appropriate standard, but in C++, which lacks the type compatibility rules used
+in C, types are considered compatible only if they are equivalent.</p>
+</div>
+<div class="section" id="c11-static-assert">
+<h4>C11 <code class="docutils literal notranslate"><span class="pre">_Static_assert()</span></code><a class="headerlink" href="#c11-static-assert" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(c_static_assert)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(c_static_assert)</span></code>
+to determine if support for compile-time assertions using <code class="docutils literal notranslate"><span class="pre">_Static_assert</span></code> is
+enabled.</p>
+</div>
+<div class="section" id="c11-thread-local">
+<h4>C11 <code class="docutils literal notranslate"><span class="pre">_Thread_local</span></code><a class="headerlink" href="#c11-thread-local" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(c_thread_local)</span></code> or <code class="docutils literal notranslate"><span class="pre">__has_extension(c_thread_local)</span></code>
+to determine if support for <code class="docutils literal notranslate"><span class="pre">_Thread_local</span></code> variables is enabled.</p>
+</div>
+</div>
+<div class="section" id="modules">
+<h3>Modules<a class="headerlink" href="#modules" title="Permalink to this headline">¶</a></h3>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(modules)</span></code> to determine if Modules have been enabled.
+For example, compiling code with <code class="docutils literal notranslate"><span class="pre">-fmodules</span></code> enables the use of Modules.</p>
+<p>More information could be found <a class="reference external" href="https://clang.llvm.org/docs/Modules.html">here</a>.</p>
+</div>
+</div>
+<div class="section" id="checks-for-type-trait-primitives">
+<h2><a class="toc-backref" href="#id15">Checks for Type Trait Primitives</a><a class="headerlink" href="#checks-for-type-trait-primitives" title="Permalink to this headline">¶</a></h2>
+<p>Type trait primitives are special builtin constant expressions that can be used
+by the standard C++ library to facilitate or simplify the implementation of
+user-facing type traits in the <type_traits> header.</p>
+<p>They are not intended to be used directly by user code because they are
+implementation-defined and subject to change â as such theyâre tied closely to
+the supported set of system headers, currently:</p>
+<ul class="simple">
+<li>LLVMâs own libc++</li>
+<li>GNU libstdc++</li>
+<li>The Microsoft standard C++ library</li>
+</ul>
+<p>Clang supports the <a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html">GNU C++ type traits</a> and a subset of the
+<a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx">Microsoft Visual C++ Type traits</a>.</p>
+<p>Feature detection is supported only for some of the primitives at present. User
+code should not use these checks because they bear no direct relation to the
+actual set of type traits supported by the C++ standard library.</p>
+<p>For type trait <code class="docutils literal notranslate"><span class="pre">__X</span></code>, <code class="docutils literal notranslate"><span class="pre">__has_extension(X)</span></code> indicates the presence of the
+type trait primitive in the compiler. A simplistic usage example as might be
+seen in standard C++ headers follows:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#if __has_extension(is_convertible_to)</span>
+<span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">From</span><span class="p">,</span> <span class="k">typename</span> <span class="n">To</span><span class="o">></span>
+<span class="k">struct</span> <span class="n">is_convertible_to</span> <span class="p">{</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="kt">bool</span> <span class="n">value</span> <span class="o">=</span> <span class="n">__is_convertible_to</span><span class="p">(</span><span class="n">From</span><span class="p">,</span> <span class="n">To</span><span class="p">);</span>
+<span class="p">};</span>
+<span class="cp">#else</span>
+<span class="c1">// Emulate type trait for compatibility with other compilers.</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>The following type trait primitives are supported by Clang:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__has_nothrow_assign</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__has_nothrow_copy</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__has_nothrow_constructor</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__has_trivial_assign</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__has_trivial_copy</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__has_trivial_constructor</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__has_trivial_destructor</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__has_virtual_destructor</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_abstract</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_aggregate</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_base_of</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_class</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_convertible_to</span></code> (Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_empty</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_enum</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_interface_class</span></code> (Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_pod</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_polymorphic</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_union</span></code> (GNU, Microsoft)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_literal(type)</span></code>: Determines whether the given type is a literal type</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_final</span></code>: Determines whether the given type is declared with a
+<code class="docutils literal notranslate"><span class="pre">final</span></code> class-virt-specifier.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__underlying_type(type)</span></code>: Retrieves the underlying type for a given
+<code class="docutils literal notranslate"><span class="pre">enum</span></code> type. This trait is required to implement the C++11 standard
+library.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_trivially_assignable(totype,</span> <span class="pre">fromtype)</span></code>: Determines whether a value
+of type <code class="docutils literal notranslate"><span class="pre">totype</span></code> can be assigned to from a value of type <code class="docutils literal notranslate"><span class="pre">fromtype</span></code> such
+that no non-trivial functions are called as part of that assignment. This
+trait is required to implement the C++11 standard library.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_trivially_constructible(type,</span> <span class="pre">argtypes...)</span></code>: Determines whether a
+value of type <code class="docutils literal notranslate"><span class="pre">type</span></code> can be direct-initialized with arguments of types
+<code class="docutils literal notranslate"><span class="pre">argtypes...</span></code> such that no non-trivial functions are called as part of
+that initialization. This trait is required to implement the C++11 standard
+library.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_destructible</span></code> (MSVC 2013)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_nothrow_destructible</span></code> (MSVC 2013)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_nothrow_assignable</span></code> (MSVC 2013, clang)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_constructible</span></code> (MSVC 2013, clang)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_nothrow_constructible</span></code> (MSVC 2013, clang)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__is_assignable</span></code> (MSVC 2015, clang)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__reference_binds_to_temporary(T,</span> <span class="pre">U)</span></code> (Clang): Determines whether a
+reference of type <code class="docutils literal notranslate"><span class="pre">T</span></code> bound to an expression of type <code class="docutils literal notranslate"><span class="pre">U</span></code> would bind to a
+materialized temporary object. If <code class="docutils literal notranslate"><span class="pre">T</span></code> is not a reference type the result
+is false. Note this trait will also return false when the initialization of
+<code class="docutils literal notranslate"><span class="pre">T</span></code> from <code class="docutils literal notranslate"><span class="pre">U</span></code> is ill-formed.</li>
+</ul>
+</div>
+<div class="section" id="blocks">
+<h2><a class="toc-backref" href="#id16">Blocks</a><a class="headerlink" href="#blocks" title="Permalink to this headline">¶</a></h2>
+<p>The syntax and high level language feature description is in
+<a class="reference internal" href="BlockLanguageSpec.html"><span class="doc">BlockLanguageSpec</span></a>. Implementation and ABI details for
+the clang implementation are in <a class="reference internal" href="Block-ABI-Apple.html"><span class="doc">Block-ABI-Apple</span></a>.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_extension(blocks)</span></code>.</p>
+</div>
+<div class="section" id="objective-c-features">
+<h2><a class="toc-backref" href="#id17">Objective-C Features</a><a class="headerlink" href="#objective-c-features" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="related-result-types">
+<h3>Related result types<a class="headerlink" href="#related-result-types" title="Permalink to this headline">¶</a></h3>
+<p>According to Cocoa conventions, Objective-C methods with certain names
+(â<code class="docutils literal notranslate"><span class="pre">init</span></code>â, â<code class="docutils literal notranslate"><span class="pre">alloc</span></code>â, etc.) always return objects that are an instance of
+the receiving classâs type. Such methods are said to have a ârelated result
+typeâ, meaning that a message send to one of these methods will have the same
+static type as an instance of the receiver class. For example, given the
+following classes:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">@interface</span> <span class="bp">NSObject</span>
+<span class="p">+</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">alloc</span><span class="p">;</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">init</span><span class="p">;</span>
+<span class="k">@end</span>
+
+<span class="k">@interface</span> <span class="bp">NSArray</span> : <span class="bp">NSObject</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>and this common initialization pattern</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="bp">NSArray</span> <span class="o">*</span><span class="n">array</span> <span class="o">=</span> <span class="p">[[</span><span class="bp">NSArray</span> <span class="n">alloc</span><span class="p">]</span> <span class="n">init</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>the type of the expression <code class="docutils literal notranslate"><span class="pre">[NSArray</span> <span class="pre">alloc]</span></code> is <code class="docutils literal notranslate"><span class="pre">NSArray*</span></code> because
+<code class="docutils literal notranslate"><span class="pre">alloc</span></code> implicitly has a related result type. Similarly, the type of the
+expression <code class="docutils literal notranslate"><span class="pre">[[NSArray</span> <span class="pre">alloc]</span> <span class="pre">init]</span></code> is <code class="docutils literal notranslate"><span class="pre">NSArray*</span></code>, since <code class="docutils literal notranslate"><span class="pre">init</span></code> has a
+related result type and its receiver is known to have the type <code class="docutils literal notranslate"><span class="pre">NSArray</span> <span class="pre">*</span></code>.
+If neither <code class="docutils literal notranslate"><span class="pre">alloc</span></code> nor <code class="docutils literal notranslate"><span class="pre">init</span></code> had a related result type, the expressions
+would have had type <code class="docutils literal notranslate"><span class="pre">id</span></code>, as declared in the method signature.</p>
+<p>A method with a related result type can be declared by using the type
+<code class="docutils literal notranslate"><span class="pre">instancetype</span></code> as its result type. <code class="docutils literal notranslate"><span class="pre">instancetype</span></code> is a contextual keyword
+that is only permitted in the result type of an Objective-C method, e.g.</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">@interface</span> <span class="nc">A</span>
+<span class="p">+</span> <span class="p">(</span><span class="kt">instancetype</span><span class="p">)</span><span class="nf">constructAnA</span><span class="p">;</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>The related result type can also be inferred for some methods. To determine
+whether a method has an inferred related result type, the first word in the
+camel-case selector (e.g., â<code class="docutils literal notranslate"><span class="pre">init</span></code>â in â<code class="docutils literal notranslate"><span class="pre">initWithObjects</span></code>â) is considered,
+and the method will have a related result type if its return type is compatible
+with the type of its class and if:</p>
+<ul class="simple">
+<li>the first word is â<code class="docutils literal notranslate"><span class="pre">alloc</span></code>â or â<code class="docutils literal notranslate"><span class="pre">new</span></code>â, and the method is a class method,
+or</li>
+<li>the first word is â<code class="docutils literal notranslate"><span class="pre">autorelease</span></code>â, â<code class="docutils literal notranslate"><span class="pre">init</span></code>â, â<code class="docutils literal notranslate"><span class="pre">retain</span></code>â, or â<code class="docutils literal notranslate"><span class="pre">self</span></code>â,
+and the method is an instance method.</li>
+</ul>
+<p>If a method with a related result type is overridden by a subclass method, the
+subclass method must also return a type that is compatible with the subclass
+type. For example:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">@interface</span> <span class="bp">NSString</span> : <span class="bp">NSObject</span>
+<span class="p">-</span> <span class="p">(</span><span class="n">NSUnrelated</span> <span class="o">*</span><span class="p">)</span><span class="nf">init</span><span class="p">;</span> <span class="c1">// incorrect usage: NSUnrelated is not NSString or a superclass of NSString</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>Related result types only affect the type of a message send or property access
+via the given method. In all other respects, a method with a related result
+type is treated the same way as method that returns <code class="docutils literal notranslate"><span class="pre">id</span></code>.</p>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(objc_instancetype)</span></code> to determine whether the
+<code class="docutils literal notranslate"><span class="pre">instancetype</span></code> contextual keyword is available.</p>
+</div>
+<div class="section" id="automatic-reference-counting">
+<h3>Automatic reference counting<a class="headerlink" href="#automatic-reference-counting" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides support for <a class="reference internal" href="AutomaticReferenceCounting.html"><span class="doc">automated reference counting</span></a> in Objective-C, which eliminates the need
+for manual <code class="docutils literal notranslate"><span class="pre">retain</span></code>/<code class="docutils literal notranslate"><span class="pre">release</span></code>/<code class="docutils literal notranslate"><span class="pre">autorelease</span></code> message sends. There are three
+feature macros associated with automatic reference counting:
+<code class="docutils literal notranslate"><span class="pre">__has_feature(objc_arc)</span></code> indicates the availability of automated reference
+counting in general, while <code class="docutils literal notranslate"><span class="pre">__has_feature(objc_arc_weak)</span></code> indicates that
+automated reference counting also includes support for <code class="docutils literal notranslate"><span class="pre">__weak</span></code> pointers to
+Objective-C objects. <code class="docutils literal notranslate"><span class="pre">__has_feature(objc_arc_fields)</span></code> indicates that C structs
+are allowed to have fields that are pointers to Objective-C objects managed by
+automatic reference counting.</p>
+</div>
+<div class="section" id="weak-references">
+<span id="objc-weak"></span><h3>Weak references<a class="headerlink" href="#weak-references" title="Permalink to this headline">¶</a></h3>
+<p>Clang supports ARC-style weak and unsafe references in Objective-C even
+outside of ARC mode. Weak references must be explicitly enabled with
+the <code class="docutils literal notranslate"><span class="pre">-fobjc-weak</span></code> option; use <code class="docutils literal notranslate"><span class="pre">__has_feature((objc_arc_weak))</span></code>
+to test whether they are enabled. Unsafe references are enabled
+unconditionally. ARC-style weak and unsafe references cannot be used
+when Objective-C garbage collection is enabled.</p>
+<p>Except as noted below, the language rules for the <code class="docutils literal notranslate"><span class="pre">__weak</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code> qualifiers (and the <code class="docutils literal notranslate"><span class="pre">weak</span></code> and
+<code class="docutils literal notranslate"><span class="pre">unsafe_unretained</span></code> property attributes) are just as laid out
+in the <a class="reference internal" href="AutomaticReferenceCounting.html"><span class="doc">ARC specification</span></a>.
+In particular, note that some classes do not support forming weak
+references to their instances, and note that special care must be
+taken when storing weak references in memory where initialization
+and deinitialization are outside the responsibility of the compiler
+(such as in <code class="docutils literal notranslate"><span class="pre">malloc</span></code>-ed memory).</p>
+<p>Loading from a <code class="docutils literal notranslate"><span class="pre">__weak</span></code> variable always implicitly retains the
+loaded value. In non-ARC modes, this retain is normally balanced
+by an implicit autorelease. This autorelease can be suppressed
+by performing the load in the receiver position of a <code class="docutils literal notranslate"><span class="pre">-retain</span></code>
+message send (e.g. <code class="docutils literal notranslate"><span class="pre">[weakReference</span> <span class="pre">retain]</span></code>); note that this performs
+only a single retain (the retain done when primitively loading from
+the weak reference).</p>
+<p>For the most part, <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code> in non-ARC modes is just the
+default behavior of variables and therefore is not needed. However,
+it does have an effect on the semantics of block captures: normally,
+copying a block which captures an Objective-C object or block pointer
+causes the captured pointer to be retained or copied, respectively,
+but that behavior is suppressed when the captured variable is qualified
+with <code class="docutils literal notranslate"><span class="pre">__unsafe_unretained</span></code>.</p>
+<p>Note that the <code class="docutils literal notranslate"><span class="pre">__weak</span></code> qualifier formerly meant the GC qualifier in
+all non-ARC modes and was silently ignored outside of GC modes. It now
+means the ARC-style qualifier in all non-GC modes and is no longer
+allowed if not enabled by either <code class="docutils literal notranslate"><span class="pre">-fobjc-arc</span></code> or <code class="docutils literal notranslate"><span class="pre">-fobjc-weak</span></code>.
+It is expected that <code class="docutils literal notranslate"><span class="pre">-fobjc-weak</span></code> will eventually be enabled by default
+in all non-GC Objective-C modes.</p>
+</div>
+<div class="section" id="enumerations-with-a-fixed-underlying-type">
+<span id="objc-fixed-enum"></span><h3>Enumerations with a fixed underlying type<a class="headerlink" href="#enumerations-with-a-fixed-underlying-type" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides support for C++11 enumerations with a fixed underlying type
+within Objective-C. For example, one can write an enumeration type as:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">enum</span> <span class="o">:</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="p">{</span> <span class="n">Red</span><span class="p">,</span> <span class="n">Green</span><span class="p">,</span> <span class="n">Blue</span> <span class="p">}</span> <span class="n">Color</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This specifies that the underlying type, which is used to store the enumeration
+value, is <code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code>.</p>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(objc_fixed_enum)</span></code> to determine whether support for fixed
+underlying types is available in Objective-C.</p>
+</div>
+<div class="section" id="interoperability-with-c-11-lambdas">
+<h3>Interoperability with C++11 lambdas<a class="headerlink" href="#interoperability-with-c-11-lambdas" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides interoperability between C++11 lambdas and blocks-based APIs, by
+permitting a lambda to be implicitly converted to a block pointer with the
+corresponding signature. For example, consider an API such as <code class="docutils literal notranslate"><span class="pre">NSArray</span></code>âs
+array-sorting method:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="p">-</span> <span class="p">(</span><span class="bp">NSArray</span> <span class="o">*</span><span class="p">)</span><span class="nf">sortedArrayUsingComparator:</span><span class="p">(</span><span class="n">NSComparator</span><span class="p">)</span><span class="nv">cmptr</span><span class="p">;</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">NSComparator</span></code> is simply a typedef for the block pointer <code class="docutils literal notranslate"><span class="pre">NSComparisonResult</span>
+<span class="pre">(^)(id,</span> <span class="pre">id)</span></code>, and parameters of this type are generally provided with block
+literals as arguments. However, one can also use a C++11 lambda so long as it
+provides the same signature (in this case, accepting two parameters of type
+<code class="docutils literal notranslate"><span class="pre">id</span></code> and returning an <code class="docutils literal notranslate"><span class="pre">NSComparisonResult</span></code>):</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="bp">NSArray</span> <span class="o">*</span><span class="n">array</span> <span class="o">=</span> <span class="l">@[</span><span class="s">@"string 1"</span><span class="p">,</span> <span class="s">@"string 21"</span><span class="p">,</span> <span class="s">@"string 12"</span><span class="p">,</span> <span class="s">@"String 11"</span><span class="p">,</span>
+ <span class="s">@"String 02"</span><span class="l">]</span><span class="p">;</span>
+<span class="k">const</span> <span class="n">NSStringCompareOptions</span> <span class="n">comparisonOptions</span>
+ <span class="o">=</span> <span class="n">NSCaseInsensitiveSearch</span> <span class="o">|</span> <span class="n">NSNumericSearch</span> <span class="o">|</span>
+ <span class="n">NSWidthInsensitiveSearch</span> <span class="o">|</span> <span class="n">NSForcedOrderingSearch</span><span class="p">;</span>
+<span class="bp">NSLocale</span> <span class="o">*</span><span class="n">currentLocale</span> <span class="o">=</span> <span class="p">[</span><span class="bp">NSLocale</span> <span class="n">currentLocale</span><span class="p">];</span>
+<span class="bp">NSArray</span> <span class="o">*</span><span class="n">sorted</span>
+ <span class="o">=</span> <span class="p">[</span><span class="n">array</span> <span class="nl">sortedArrayUsingComparator</span><span class="p">:[</span><span class="o">=</span><span class="p">](</span><span class="kt">id</span> <span class="n">s1</span><span class="p">,</span> <span class="kt">id</span> <span class="n">s2</span><span class="p">)</span> <span class="o">-></span> <span class="n">NSComparisonResult</span> <span class="p">{</span>
+ <span class="n">NSRange</span> <span class="n">string1Range</span> <span class="o">=</span> <span class="n">NSMakeRange</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="p">[</span><span class="n">s1</span> <span class="n">length</span><span class="p">]);</span>
+ <span class="k">return</span> <span class="p">[</span><span class="n">s1</span> <span class="nl">compare</span><span class="p">:</span><span class="n">s2</span> <span class="nl">options</span><span class="p">:</span><span class="n">comparisonOptions</span>
+ <span class="nl">range</span><span class="p">:</span><span class="n">string1Range</span> <span class="nl">locale</span><span class="p">:</span><span class="n">currentLocale</span><span class="p">];</span>
+ <span class="p">}];</span>
+<span class="n">NSLog</span><span class="p">(</span><span class="s">@"sorted: %@"</span><span class="p">,</span> <span class="n">sorted</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This code relies on an implicit conversion from the type of the lambda
+expression (an unnamed, local class type called the <em>closure type</em>) to the
+corresponding block pointer type. The conversion itself is expressed by a
+conversion operator in that closure type that produces a block pointer with the
+same signature as the lambda itself, e.g.,</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="n">operator</span> <span class="nf">NSComparisonResult</span> <span class="p">(</span><span class="o">^</span><span class="p">)(</span><span class="kt">id</span><span class="p">,</span> <span class="kt">id</span><span class="p">)()</span> <span class="k">const</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This conversion function returns a new block that simply forwards the two
+parameters to the lambda object (which it captures by copy), then returns the
+result. The returned block is first copied (with <code class="docutils literal notranslate"><span class="pre">Block_copy</span></code>) and then
+autoreleased. As an optimization, if a lambda expression is immediately
+converted to a block pointer (as in the first example, above), then the block
+is not copied and autoreleased: rather, it is given the same lifetime as a
+block literal written at that point in the program, which avoids the overhead
+of copying a block to the heap in the common case.</p>
+<p>The conversion from a lambda to a block pointer is only available in
+Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory
+management (autorelease).</p>
+</div>
+<div class="section" id="object-literals-and-subscripting">
+<h3>Object Literals and Subscripting<a class="headerlink" href="#object-literals-and-subscripting" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides support for <a class="reference internal" href="ObjectiveCLiterals.html"><span class="doc">Object Literals and Subscripting</span></a> in Objective-C, which simplifies common Objective-C
+programming patterns, makes programs more concise, and improves the safety of
+container creation. There are several feature macros associated with object
+literals and subscripting: <code class="docutils literal notranslate"><span class="pre">__has_feature(objc_array_literals)</span></code> tests the
+availability of array literals; <code class="docutils literal notranslate"><span class="pre">__has_feature(objc_dictionary_literals)</span></code>
+tests the availability of dictionary literals;
+<code class="docutils literal notranslate"><span class="pre">__has_feature(objc_subscripting)</span></code> tests the availability of object
+subscripting.</p>
+</div>
+<div class="section" id="objective-c-autosynthesis-of-properties">
+<h3>Objective-C Autosynthesis of Properties<a class="headerlink" href="#objective-c-autosynthesis-of-properties" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides support for autosynthesis of declared properties. Using this
+feature, clang provides default synthesis of those properties not declared
+@dynamic and not having user provided backing getter and setter methods.
+<code class="docutils literal notranslate"><span class="pre">__has_feature(objc_default_synthesize_properties)</span></code> checks for availability
+of this feature in version of clang being used.</p>
+</div>
+<div class="section" id="objective-c-retaining-behavior-attributes">
+<span id="langext-objc-retain-release"></span><h3>Objective-C retaining behavior attributes<a class="headerlink" href="#objective-c-retaining-behavior-attributes" title="Permalink to this headline">¶</a></h3>
+<p>In Objective-C, functions and methods are generally assumed to follow the
+<a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html">Cocoa Memory Management</a>
+conventions for ownership of object arguments and
+return values. However, there are exceptions, and so Clang provides attributes
+to allow these exceptions to be documented. This are used by ARC and the
+<a class="reference external" href="https://clang-analyzer.llvm.org">static analyzer</a> Some exceptions may be
+better described using the <code class="docutils literal notranslate"><span class="pre">objc_method_family</span></code> attribute instead.</p>
+<p><strong>Usage</strong>: The <code class="docutils literal notranslate"><span class="pre">ns_returns_retained</span></code>, <code class="docutils literal notranslate"><span class="pre">ns_returns_not_retained</span></code>,
+<code class="docutils literal notranslate"><span class="pre">ns_returns_autoreleased</span></code>, <code class="docutils literal notranslate"><span class="pre">cf_returns_retained</span></code>, and
+<code class="docutils literal notranslate"><span class="pre">cf_returns_not_retained</span></code> attributes can be placed on methods and functions
+that return Objective-C or CoreFoundation objects. They are commonly placed at
+the end of a function prototype or method declaration:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">id</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+
+<span class="p">-</span> <span class="p">(</span><span class="bp">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">bar:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">x</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">*_returns_retained</span></code> attributes specify that the returned object has a +1
+retain count. The <code class="docutils literal notranslate"><span class="pre">*_returns_not_retained</span></code> attributes specify that the return
+object has a +0 retain count, even if the normal convention for its selector
+would be +1. <code class="docutils literal notranslate"><span class="pre">ns_returns_autoreleased</span></code> specifies that the returned object is
++0, but is guaranteed to live at least as long as the next flush of an
+autorelease pool.</p>
+<p><strong>Usage</strong>: The <code class="docutils literal notranslate"><span class="pre">ns_consumed</span></code> and <code class="docutils literal notranslate"><span class="pre">cf_consumed</span></code> attributes can be placed on
+an parameter declaration; they specify that the argument is expected to have a
++1 retain count, which will be balanced in some way by the function or method.
+The <code class="docutils literal notranslate"><span class="pre">ns_consumes_self</span></code> attribute can only be placed on an Objective-C
+method; it specifies that the method expects its <code class="docutils literal notranslate"><span class="pre">self</span></code> parameter to have a
++1 retain count, which it will balance in some way.</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="bp">NSString</span> <span class="o">*</span><span class="n">string</span><span class="p">);</span>
+
+<span class="p">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="nf">bar</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">ns_consumes_self</span><span class="p">));</span>
+<span class="p">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="nf">baz:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="nv">__attribute__</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="nv">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Further examples of these attributes are available in the static analyzerâs <a class="reference external" href="https://clang-analyzer.llvm.org/annotations.html#cocoa_mem">list of annotations for analysis</a>.</p>
+<p>Query for these features with <code class="docutils literal notranslate"><span class="pre">__has_attribute(ns_consumed)</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__has_attribute(ns_returns_retained)</span></code>, etc.</p>
+</div>
+<div class="section" id="objective-c-available">
+<h3>Objective-C @available<a class="headerlink" href="#objective-c-available" title="Permalink to this headline">¶</a></h3>
+<p>It is possible to use the newest SDK but still build a program that can run on
+older versions of macOS and iOS by passing <code class="docutils literal notranslate"><span class="pre">-mmacosx-version-min=</span></code> /
+<code class="docutils literal notranslate"><span class="pre">-miphoneos-version-min=</span></code>.</p>
+<p>Before LLVM 5.0, when calling a function that exists only in the OS thatâs
+newer than the target OS (as determined by the minimum deployment version),
+programmers had to carefully check if the function exists at runtime, using
+null checks for weakly-linked C functions, <code class="docutils literal notranslate"><span class="pre">+class</span></code> for Objective-C classes,
+and <code class="docutils literal notranslate"><span class="pre">-respondsToSelector:</span></code> or <code class="docutils literal notranslate"><span class="pre">+instancesRespondToSelector:</span></code> for
+Objective-C methods. If such a check was missed, the program would compile
+fine, run fine on newer systems, but crash on older systems.</p>
+<p>As of LLVM 5.0, <code class="docutils literal notranslate"><span class="pre">-Wunguarded-availability</span></code> uses the <a class="reference external" href="https://clang.llvm.org/docs/AttributeReference.html#availability">availability attributes</a> together
+with the new <code class="docutils literal notranslate"><span class="pre">@available()</span></code> keyword to assist with this issue.
+When a method thatâs introduced in the OS newer than the target OS is called, a
+-Wunguarded-availability warning is emitted if that call is not guarded:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">my_fun</span><span class="p">(</span><span class="n">NSSomeClass</span><span class="o">*</span> <span class="n">var</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// If fancyNewMethod was added in e.g. macOS 10.12, but the code is</span>
+ <span class="c1">// built with -mmacosx-version-min=10.11, then this unconditional call</span>
+ <span class="c1">// will emit a -Wunguarded-availability warning:</span>
+ <span class="p">[</span><span class="n">var</span> <span class="n">fancyNewMethod</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>To fix the warning and to avoid the crash on macOS 10.11, wrap it in
+<code class="docutils literal notranslate"><span class="pre">if(@available())</span></code>:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">my_fun</span><span class="p">(</span><span class="n">NSSomeClass</span><span class="o">*</span> <span class="n">var</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(@</span><span class="n">available</span><span class="p">(</span><span class="n">macOS</span> <span class="mf">10.12</span><span class="p">,</span> <span class="o">*</span><span class="p">))</span> <span class="p">{</span>
+ <span class="p">[</span><span class="n">var</span> <span class="n">fancyNewMethod</span><span class="p">];</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="c1">// Put fallback behavior for old macOS versions (and for non-mac</span>
+ <span class="c1">// platforms) here.</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">*</span></code> is required and means that platforms not explicitly listed will take
+the true branch, and the compiler will emit <code class="docutils literal notranslate"><span class="pre">-Wunguarded-availability</span></code>
+warnings for unlisted platforms based on those platformâs deployment target.
+More than one platform can be listed in <code class="docutils literal notranslate"><span class="pre">@available()</span></code>:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">my_fun</span><span class="p">(</span><span class="n">NSSomeClass</span><span class="o">*</span> <span class="n">var</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(@</span><span class="n">available</span><span class="p">(</span><span class="n">macOS</span> <span class="mf">10.12</span><span class="p">,</span> <span class="n">iOS</span> <span class="mi">10</span><span class="p">,</span> <span class="o">*</span><span class="p">))</span> <span class="p">{</span>
+ <span class="p">[</span><span class="n">var</span> <span class="n">fancyNewMethod</span><span class="p">];</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the caller of <code class="docutils literal notranslate"><span class="pre">my_fun()</span></code> already checks that <code class="docutils literal notranslate"><span class="pre">my_fun()</span></code> is only called
+on 10.12, then add an <a class="reference external" href="https://clang.llvm.org/docs/AttributeReference.html#availability">availability attribute</a> to it,
+which will also suppress the warning and require that calls to my_fun() are
+checked:</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="n">API_AVAILABLE</span><span class="p">(</span><span class="n">macos</span><span class="p">(</span><span class="mf">10.12</span><span class="p">))</span> <span class="kt">void</span> <span class="n">my_fun</span><span class="p">(</span><span class="n">NSSomeClass</span><span class="o">*</span> <span class="n">var</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">[</span><span class="n">var</span> <span class="n">fancyNewMethod</span><span class="p">];</span> <span class="c1">// Now ok.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">@available()</span></code> is only available in Objective-C code. To use the feature
+in C and C++ code, use the <code class="docutils literal notranslate"><span class="pre">__builtin_available()</span></code> spelling instead.</p>
+<p>If existing code uses null checks or <code class="docutils literal notranslate"><span class="pre">-respondsToSelector:</span></code>, it should
+be changed to use <code class="docutils literal notranslate"><span class="pre">@available()</span></code> (or <code class="docutils literal notranslate"><span class="pre">__builtin_available</span></code>) instead.</p>
+<p><code class="docutils literal notranslate"><span class="pre">-Wunguarded-availability</span></code> is disabled by default, but
+<code class="docutils literal notranslate"><span class="pre">-Wunguarded-availability-new</span></code>, which only emits this warning for APIs
+that have been introduced in macOS >= 10.13, iOS >= 11, watchOS >= 4 and
+tvOS >= 11, is enabled by default.</p>
+</div>
+<div class="section" id="objective-c-abi-protocol-qualifier-mangling-of-parameters">
+<span id="langext-overloading"></span><h3>Objective-C++ ABI: protocol-qualifier mangling of parameters<a class="headerlink" href="#objective-c-abi-protocol-qualifier-mangling-of-parameters" title="Permalink to this headline">¶</a></h3>
+<p>Starting with LLVM 3.4, Clang produces a new mangling for parameters whose
+type is a qualified-<code class="docutils literal notranslate"><span class="pre">id</span></code> (e.g., <code class="docutils literal notranslate"><span class="pre">id<Foo></span></code>). This mangling allows such
+parameters to be differentiated from those with the regular unqualified <code class="docutils literal notranslate"><span class="pre">id</span></code>
+type.</p>
+<p>This was a non-backward compatible mangling change to the ABI. This change
+allows proper overloading, and also prevents mangling conflicts with template
+parameters of protocol-qualified type.</p>
+<p>Query the presence of this new mangling with
+<code class="docutils literal notranslate"><span class="pre">__has_feature(objc_protocol_qualifier_mangling)</span></code>.</p>
+</div>
+</div>
+<div class="section" id="opencl-features">
+<h2><a class="toc-backref" href="#id18">OpenCL Features</a><a class="headerlink" href="#opencl-features" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="c-for-opencl">
+<h3>C++ for OpenCL<a class="headerlink" href="#c-for-opencl" title="Permalink to this headline">¶</a></h3>
+<p>This functionality is built on top of OpenCL C v2.0 and C++17 enabling most of
+regular C++ features in OpenCL kernel code. Most functionality from OpenCL C
+is inherited. This section describes minor differences to OpenCL C and any
+limitations related to C++ support as well as interactions between OpenCL and
+C++ features that are not documented elsewhere.</p>
+<div class="section" id="restrictions-to-c-17">
+<h4>Restrictions to C++17<a class="headerlink" href="#restrictions-to-c-17" title="Permalink to this headline">¶</a></h4>
+<p>The following features are not supported:</p>
+<ul class="simple">
+<li>Virtual functions</li>
+<li>Exceptions</li>
+<li><code class="docutils literal notranslate"><span class="pre">dynamic_cast</span></code> operator</li>
+<li>Non-placement <code class="docutils literal notranslate"><span class="pre">new</span></code>/<code class="docutils literal notranslate"><span class="pre">delete</span></code> operators</li>
+<li>Standard C++ libraries. Currently there is no solution for alternative C++
+libraries provided. Future release will feature library support.</li>
+</ul>
+</div>
+<div class="section" id="interplay-of-opencl-and-c-features">
+<h4>Interplay of OpenCL and C++ features<a class="headerlink" href="#interplay-of-opencl-and-c-features" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="address-space-behavior">
+<h5>Address space behavior<a class="headerlink" href="#address-space-behavior" title="Permalink to this headline">¶</a></h5>
+<p>Address spaces are part of the type qualifiers; many rules are just inherited
+from the qualifier behavior documented in OpenCL C v2.0 s6.5 and Embedded C
+extension ISO/IEC JTC1 SC22 WG14 N1021 s3.1. Note that since the address space
+behavior in C++ is not documented formally, Clang extends the existing concept
+from C and OpenCL. For example conversion rules are extended from qualification
+conversion but the compatibility is determined using notation of sets and
+overlapping of address spaces from Embedded C (ISO/IEC JTC1 SC22 WG14 N1021
+s3.1.3). For OpenCL it means that implicit conversions are allowed from
+a named address space (except for <code class="docutils literal notranslate"><span class="pre">__constant</span></code>) to <code class="docutils literal notranslate"><span class="pre">__generic</span></code> (OpenCL C
+v2.0 6.5.5). Reverse conversion is only allowed explicitly. The <code class="docutils literal notranslate"><span class="pre">__constant</span></code>
+address space does not overlap with any other and therefore no valid conversion
+between <code class="docutils literal notranslate"><span class="pre">__constant</span></code> and other address spaces exists. Most of the rules
+follow this logic.</p>
+<p><strong>Casts</strong></p>
+<p>C-style casts follow OpenCL C v2.0 rules (s6.5.5). All cast operators
+permit conversion to <code class="docutils literal notranslate"><span class="pre">__generic</span></code> implicitly. However converting from
+<code class="docutils literal notranslate"><span class="pre">__generic</span></code> to named address spaces can only be done using <code class="docutils literal notranslate"><span class="pre">addrspace_cast</span></code>.
+Note that conversions between <code class="docutils literal notranslate"><span class="pre">__constant</span></code> and any other address space
+are disallowed.</p>
+<p id="opencl-cpp-addrsp-deduction"><strong>Deduction</strong></p>
+<p>Address spaces are not deduced for:</p>
+<ul class="simple">
+<li>non-pointer/non-reference template parameters or any dependent types except
+for template specializations.</li>
+<li>non-pointer/non-reference class members except for static data members that are
+deduced to <code class="docutils literal notranslate"><span class="pre">__global</span></code> address space.</li>
+<li>non-pointer/non-reference alias declarations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">decltype</span></code> expressions.</li>
+</ul>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">T</span> <span class="n">m</span><span class="p">;</span> <span class="c1">// address space of m will be known at template instantiation time.</span>
+ <span class="n">T</span> <span class="o">*</span> <span class="n">ptr</span><span class="p">;</span> <span class="c1">// ptr points to __generic address space object.</span>
+ <span class="n">T</span> <span class="o">&</span> <span class="n">ref</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// ref references an object in __generic address space.</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><</span><span class="kt">int</span> <span class="n">N</span><span class="o">></span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="c1">// i has no address space</span>
+ <span class="k">static</span> <span class="kt">int</span> <span class="n">ii</span><span class="p">;</span> <span class="c1">// ii is in global address space</span>
+ <span class="kt">int</span> <span class="o">*</span> <span class="n">ptr</span><span class="p">;</span> <span class="c1">// ptr points to __generic address space int.</span>
+ <span class="kt">int</span> <span class="o">&</span> <span class="n">ref</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// ref references int in __generic address space.</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><</span><span class="kt">int</span> <span class="n">N</span><span class="o">></span>
+<span class="kt">void</span> <span class="n">bar</span><span class="p">()</span>
+<span class="p">{</span>
+ <span class="n">S</span><span class="o"><</span><span class="n">N</span><span class="o">></span> <span class="n">s</span><span class="p">;</span> <span class="c1">// s is in __private address space</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>TODO: Add example for type alias and decltype!</p>
+<p><strong>References</strong></p>
+<p>Reference types can be qualified with an address space.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__private</span> <span class="kt">int</span> <span class="o">&</span> <span class="n">ref</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// references int in __private address space</span>
+</pre></div>
+</div>
+<p>By default references will refer to <code class="docutils literal notranslate"><span class="pre">__generic</span></code> address space objects, except
+for dependent types that are not template specializations
+(see <a class="reference internal" href="#opencl-cpp-addrsp-deduction"><span class="std std-ref">Deduction</span></a>). Address space compatibility
+checks are performed when references are bound to values. The logic follows the
+rules from address space pointer conversion (OpenCL v2.0 s6.5.5).</p>
+<p><strong>Default address space</strong></p>
+<p>All non-static member functions take an implicit object parameter <code class="docutils literal notranslate"><span class="pre">this</span></code> that
+is a pointer type. By default this pointer parameter is in the <code class="docutils literal notranslate"><span class="pre">__generic</span></code>
+address space. All concrete objects passed as an argument to <code class="docutils literal notranslate"><span class="pre">this</span></code> parameter
+will be converted to the <code class="docutils literal notranslate"><span class="pre">__generic</span></code> address space first if such conversion is
+valid. Therefore programs using objects in the <code class="docutils literal notranslate"><span class="pre">__constant</span></code> address space will
+not be compiled unless the address space is explicitly specified using address
+space qualifiers on member functions
+(see <a class="reference internal" href="#opencl-cpp-addrspace-method-qual"><span class="std std-ref">Member function qualifier</span></a>) as the
+conversion between <code class="docutils literal notranslate"><span class="pre">__constant</span></code> and <code class="docutils literal notranslate"><span class="pre">__generic</span></code> is disallowed. Member function
+qualifiers can also be used in case conversion to the <code class="docutils literal notranslate"><span class="pre">__generic</span></code> address space
+is undesirable (even if it is legal). For example, a method can be implemented to
+exploit memory access coalescing for segments with memory bank. This not only
+applies to regular member functions but to constructors and destructors too.</p>
+<p id="opencl-cpp-addrspace-method-qual"><strong>Member function qualifier</strong></p>
+<p>Clang allows specifying an address space qualifier on member functions to signal
+that they are to be used with objects constructed in some specific address space.
+This works just the same as qualifying member functions with <code class="docutils literal notranslate"><span class="pre">const</span></code> or any
+other qualifiers. The overloading resolution will select the candidate with the
+most specific address space if multiple candidates are provided. If there is no
+conversion to an address space among candidates, compilation will fail with a
+diagnostic.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">C</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="n">__local</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="nf">foo</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="n">__kernel</span> <span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">__local</span> <span class="n">C</span> <span class="n">c1</span><span class="p">;</span>
+ <span class="n">C</span> <span class="n">c2</span><span class="p">;</span>
+ <span class="n">__constant</span> <span class="n">C</span> <span class="n">c3</span><span class="p">;</span>
+ <span class="n">c1</span><span class="p">.</span><span class="n">foo</span><span class="p">();</span> <span class="c1">// will resolve to the first foo</span>
+ <span class="n">c2</span><span class="p">.</span><span class="n">foo</span><span class="p">();</span> <span class="c1">// will resolve to the second foo</span>
+ <span class="n">c3</span><span class="p">.</span><span class="n">foo</span><span class="p">();</span> <span class="c1">// error due to mismatching address spaces - can't convert to</span>
+ <span class="c1">// __local or __generic</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><strong>Implicit special members</strong></p>
+<p>All implicit special members (default, copy, or move constructor, copy or move
+assignment, destructor) will be generated with the <code class="docutils literal notranslate"><span class="pre">__generic</span></code> address space.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">C</span> <span class="p">{</span>
+ <span class="c1">// Has the following implicit definition</span>
+ <span class="c1">// void C() __generic;</span>
+ <span class="c1">// void C(const __generic C &) __generic;</span>
+ <span class="c1">// void C(__generic C &&) __generic;</span>
+ <span class="c1">// operator= '__generic C &(__generic C &&)'</span>
+ <span class="c1">// operator= '__generic C &(const __generic C &) __generic</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><strong>Builtin operators</strong></p>
+<p>All builtin operators are available in the specific address spaces, thus no
+conversion to <code class="docutils literal notranslate"><span class="pre">__generic</span></code> is performed.</p>
+<p><strong>Templates</strong></p>
+<p>There is no deduction of address spaces in non-pointer/non-reference template
+parameters and dependent types (see <a class="reference internal" href="#opencl-cpp-addrsp-deduction"><span class="std std-ref">Deduction</span></a>).
+The address space of a template parameter is deduced during type deduction if
+it is not explicitly provided in the instantiation.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span> <span class="mi">1</span> <span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+ <span class="mi">2</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">T</span><span class="o">*</span> <span class="n">i</span><span class="p">){</span>
+ <span class="mi">3</span> <span class="n">T</span> <span class="n">var</span><span class="p">;</span>
+ <span class="mi">4</span> <span class="p">}</span>
+ <span class="mi">5</span>
+ <span class="mi">6</span> <span class="n">__global</span> <span class="kt">int</span> <span class="n">g</span><span class="p">;</span>
+ <span class="mi">7</span> <span class="kt">void</span> <span class="nf">bar</span><span class="p">(){</span>
+ <span class="mi">8</span> <span class="n">foo</span><span class="p">(</span><span class="o">&</span><span class="n">g</span><span class="p">);</span> <span class="c1">// error: template instantiation failed as function scope variable</span>
+ <span class="mi">9</span> <span class="c1">// appears to be declared in __global address space (see line 3)</span>
+<span class="mi">10</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>It is not legal to specify multiple different address spaces between template
+definition and instantiation. If multiple different address spaces are specified in
+template definition and instantiation, compilation of such a program will fail with
+a diagnostic.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">__private</span> <span class="n">T</span> <span class="n">var</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="o"><</span><span class="n">__global</span> <span class="kt">int</span><span class="o">></span><span class="p">();</span> <span class="c1">// error: conflicting address space qualifiers are provided</span>
+ <span class="c1">// __global and __private</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Once a template has been instantiated, regular restrictions for address spaces will
+apply.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(){</span>
+ <span class="n">T</span> <span class="n">var</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="n">bar</span><span class="p">(){</span>
+ <span class="n">foo</span><span class="o"><</span><span class="n">__global</span> <span class="kt">int</span><span class="o">></span><span class="p">();</span> <span class="c1">// error: function scope variable cannot be declared in</span>
+ <span class="c1">// __global address space</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><strong>Temporary materialization</strong></p>
+<p>All temporaries are materialized in the <code class="docutils literal notranslate"><span class="pre">__private</span></code> address space. If a
+reference with another address space is bound to them, the conversion will be
+generated in case it is valid, otherwise compilation will fail with a diagnostic.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">bar</span><span class="p">(</span><span class="k">const</span> <span class="kt">unsigned</span> <span class="kt">int</span> <span class="o">&</span><span class="n">i</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">bar</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// temporary is created in __private address space but converted</span>
+ <span class="c1">// to __generic address space of parameter reference</span>
+<span class="p">}</span>
+
+<span class="n">__global</span> <span class="k">const</span> <span class="kt">int</span><span class="o">&</span> <span class="n">f</span><span class="p">(</span><span class="n">__global</span> <span class="kt">float</span> <span class="o">&</span><span class="n">ref</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">ref</span><span class="p">;</span> <span class="c1">// error: address space mismatch between temporary object</span>
+ <span class="c1">// created to hold value converted float->int and return</span>
+ <span class="c1">// value type (can't convert from __private to __global)</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><strong>Initialization of local and constant address space objects</strong></p>
+<p>TODO</p>
+</div>
+</div>
+<div class="section" id="constructing-and-destroying-global-objects">
+<h4>Constructing and destroying global objects<a class="headerlink" href="#constructing-and-destroying-global-objects" title="Permalink to this headline">¶</a></h4>
+<p>Global objects must be constructed before the first kernel using the global
+objects is executed and destroyed just after the last kernel using the
+program objects is executed. In OpenCL v2.0 drivers there is no specific
+API for invoking global constructors. However, an easy workaround would be
+to enqueue a constructor initialization kernel that has a name
+<code class="docutils literal notranslate"><span class="pre">@_GLOBAL__sub_I_<compiled</span> <span class="pre">file</span> <span class="pre">name></span></code>. This kernel is only present if there
+are any global objects to be initialized in the compiled binary. One way to
+check this is by passing <code class="docutils literal notranslate"><span class="pre">CL_PROGRAM_KERNEL_NAMES</span></code> to <code class="docutils literal notranslate"><span class="pre">clGetProgramInfo</span></code>
+(OpenCL v2.0 s5.8.7).</p>
+<p>Note that if multiple files are compiled and linked into libraries, multiple
+kernels that initialize global objects for multiple modules would have to be
+invoked.</p>
+<p>Applications are currently required to run initialization of global objects
+manually before running any kernels in which the objects are used.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">clang -cl-std=clc++ test.cl</span>
+</pre></div>
+</div>
+<p>If there are any global objects to be initialized, the final binary will
+contain the <code class="docutils literal notranslate"><span class="pre">@_GLOBAL__sub_I_test.cl</span></code> kernel to be enqueued.</p>
+<p>Global destructors can not be invoked in OpenCL v2.0 drivers. However, all
+memory used for program scope objects is released on <code class="docutils literal notranslate"><span class="pre">clReleaseProgram</span></code>.</p>
+</div>
+</div>
+</div>
+<div class="section" id="initializer-lists-for-complex-numbers-in-c">
+<h2><a class="toc-backref" href="#id19">Initializer lists for complex numbers in C</a><a class="headerlink" href="#initializer-lists-for-complex-numbers-in-c" title="Permalink to this headline">¶</a></h2>
+<p>clang supports an extension which allows the following in C:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><math.h></span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf"><complex.h></span><span class="cp"></span>
+<span class="n">complex</span> <span class="kt">float</span> <span class="n">x</span> <span class="o">=</span> <span class="p">{</span> <span class="mf">1.0f</span><span class="p">,</span> <span class="n">INFINITY</span> <span class="p">};</span> <span class="c1">// Init to (1, Inf)</span>
+</pre></div>
+</div>
+<p>This construct is useful because there is no way to separately initialize the
+real and imaginary parts of a complex variable in standard C, given that clang
+does not support <code class="docutils literal notranslate"><span class="pre">_Imaginary</span></code>. (Clang also supports the <code class="docutils literal notranslate"><span class="pre">__real__</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__imag__</span></code> extensions from gcc, which help in some cases, but are not usable
+in static initializers.)</p>
+<p>Note that this extension does not allow eliding the braces; the meaning of the
+following two lines is different:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">complex</span> <span class="kt">float</span> <span class="n">x</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="p">{</span> <span class="mf">1.0f</span><span class="p">,</span> <span class="mf">1.0f</span> <span class="p">}</span> <span class="p">};</span> <span class="c1">// [0] = (1, 1)</span>
+<span class="n">complex</span> <span class="kt">float</span> <span class="n">x</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="mf">1.0f</span><span class="p">,</span> <span class="mf">1.0f</span> <span class="p">};</span> <span class="c1">// [0] = (1, 0), [1] = (1, 0)</span>
+</pre></div>
+</div>
+<p>This extension also works in C++ mode, as far as that goes, but does not apply
+to the C++ <code class="docutils literal notranslate"><span class="pre">std::complex</span></code>. (In C++11, list initialization allows the same
+syntax to be used with <code class="docutils literal notranslate"><span class="pre">std::complex</span></code> with the same meaning.)</p>
+</div>
+<div class="section" id="builtin-functions">
+<h2><a class="toc-backref" href="#id20">Builtin Functions</a><a class="headerlink" href="#builtin-functions" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports a number of builtin library functions with the same syntax as
+GCC, including things like <code class="docutils literal notranslate"><span class="pre">__builtin_nan</span></code>, <code class="docutils literal notranslate"><span class="pre">__builtin_constant_p</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__builtin_choose_expr</span></code>, <code class="docutils literal notranslate"><span class="pre">__builtin_types_compatible_p</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__builtin_assume_aligned</span></code>, <code class="docutils literal notranslate"><span class="pre">__sync_fetch_and_add</span></code>, etc. In addition to
+the GCC builtins, Clang supports a number of builtins that GCC does not, which
+are listed here.</p>
+<p>Please note that Clang does not and will not support all of the GCC builtins
+for vector operations. Instead of using builtins, you should use the functions
+defined in target-specific header files like <code class="docutils literal notranslate"><span class="pre"><xmmintrin.h></span></code>, which define
+portable wrappers for these. Many of the Clang versions of these functions are
+implemented directly in terms of <a class="reference internal" href="#langext-vectors"><span class="std std-ref">extended vector support</span></a> instead of builtins, in order to reduce the number of
+builtins that we need to implement.</p>
+<div class="section" id="builtin-assume">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_assume</span></code><a class="headerlink" href="#builtin-assume" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_assume</span></code> is used to provide the optimizer with a boolean
+invariant that is defined to be true.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_assume</span><span class="p">(</span><span class="kt">bool</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Example of Use</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">__builtin_assume</span><span class="p">(</span><span class="n">x</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">);</span>
+
+ <span class="c1">// The optimizer may short-circuit this check using the invariant.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">do_something</span><span class="p">();</span>
+
+ <span class="k">return</span> <span class="n">do_something_else</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The boolean argument to this function is defined to be true. The optimizer may
+analyze the form of the expression provided as the argument and deduce from
+that information used to optimize the program. If the condition is violated
+during execution, the behavior is undefined. The argument itself is never
+evaluated, so any side effects of the expression will be discarded.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_builtin(__builtin_assume)</span></code>.</p>
+</div>
+<div class="section" id="builtin-readcyclecounter">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_readcyclecounter</span></code><a class="headerlink" href="#builtin-readcyclecounter" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_readcyclecounter</span></code> is used to access the cycle counter register (or
+a similar low-latency, high-accuracy clock) on those targets that support it.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_readcyclecounter</span><span class="p">()</span>
+</pre></div>
+</div>
+<p><strong>Example of Use</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">t0</span> <span class="o">=</span> <span class="n">__builtin_readcyclecounter</span><span class="p">();</span>
+<span class="n">do_something</span><span class="p">();</span>
+<span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">t1</span> <span class="o">=</span> <span class="n">__builtin_readcyclecounter</span><span class="p">();</span>
+<span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">cycles_to_do_something</span> <span class="o">=</span> <span class="n">t1</span> <span class="o">-</span> <span class="n">t0</span><span class="p">;</span> <span class="c1">// assuming no overflow</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">__builtin_readcyclecounter()</span></code> builtin returns the cycle counter value,
+which may be either global or process/thread-specific depending on the target.
+As the backing counters often overflow quickly (on the order of seconds) this
+should only be used for timing small intervals. When not supported by the
+target, the return value is always zero. This builtin takes no arguments and
+produces an unsigned long long result.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_builtin(__builtin_readcyclecounter)</span></code>. Note
+that even if present, its use may depend on run-time privilege or other OS
+controlled state.</p>
+</div>
+<div class="section" id="builtin-shufflevector">
+<span id="langext-builtin-shufflevector"></span><h3><code class="docutils literal notranslate"><span class="pre">__builtin_shufflevector</span></code><a class="headerlink" href="#builtin-shufflevector" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_shufflevector</span></code> is used to express generic vector
+permutation/shuffle/swizzle operations. This builtin is also very important
+for the implementation of various target-specific header files like
+<code class="docutils literal notranslate"><span class="pre"><xmmintrin.h></span></code>.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_shufflevector</span><span class="p">(</span><span class="n">vec1</span><span class="p">,</span> <span class="n">vec2</span><span class="p">,</span> <span class="n">index1</span><span class="p">,</span> <span class="n">index2</span><span class="p">,</span> <span class="p">...)</span>
+</pre></div>
+</div>
+<p><strong>Examples</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// identity operation - return 4-element vector v1.</span>
+<span class="n">__builtin_shufflevector</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
+
+<span class="c1">// "Splat" element 0 of V1 into a 4-element result.</span>
+<span class="n">__builtin_shufflevector</span><span class="p">(</span><span class="n">V1</span><span class="p">,</span> <span class="n">V1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
+
+<span class="c1">// Reverse 4-element vector V1.</span>
+<span class="n">__builtin_shufflevector</span><span class="p">(</span><span class="n">V1</span><span class="p">,</span> <span class="n">V1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
+
+<span class="c1">// Concatenate every other element of 4-element vectors V1 and V2.</span>
+<span class="n">__builtin_shufflevector</span><span class="p">(</span><span class="n">V1</span><span class="p">,</span> <span class="n">V2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">6</span><span class="p">)</span>
+
+<span class="c1">// Concatenate every other element of 8-element vectors V1 and V2.</span>
+<span class="n">__builtin_shufflevector</span><span class="p">(</span><span class="n">V1</span><span class="p">,</span> <span class="n">V2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">14</span><span class="p">)</span>
+
+<span class="c1">// Shuffle v1 with some elements being undefined</span>
+<span class="n">__builtin_shufflevector</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The first two arguments to <code class="docutils literal notranslate"><span class="pre">__builtin_shufflevector</span></code> are vectors that have
+the same element type. The remaining arguments are a list of integers that
+specify the elements indices of the first two vectors that should be extracted
+and returned in a new vector. These element indices are numbered sequentially
+starting with the first vector, continuing into the second vector. Thus, if
+<code class="docutils literal notranslate"><span class="pre">vec1</span></code> is a 4-element vector, index 5 would refer to the second element of
+<code class="docutils literal notranslate"><span class="pre">vec2</span></code>. An index of -1 can be used to indicate that the corresponding element
+in the returned vector is a donât care and can be optimized by the backend.</p>
+<p>The result of <code class="docutils literal notranslate"><span class="pre">__builtin_shufflevector</span></code> is a vector with the same element
+type as <code class="docutils literal notranslate"><span class="pre">vec1</span></code>/<code class="docutils literal notranslate"><span class="pre">vec2</span></code> but that has an element count equal to the number of
+indices specified.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_builtin(__builtin_shufflevector)</span></code>.</p>
+</div>
+<div class="section" id="builtin-convertvector">
+<span id="langext-builtin-convertvector"></span><h3><code class="docutils literal notranslate"><span class="pre">__builtin_convertvector</span></code><a class="headerlink" href="#builtin-convertvector" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_convertvector</span></code> is used to express generic vector
+type-conversion operations. The input vector and the output vector
+type must have the same number of elements.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_convertvector</span><span class="p">(</span><span class="n">src_vec</span><span class="p">,</span> <span class="n">dst_vec_type</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Examples</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="kt">double</span> <span class="n">vector4double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">__vector_size__</span><span class="p">(</span><span class="mi">32</span><span class="p">)));</span>
+<span class="k">typedef</span> <span class="kt">float</span> <span class="n">vector4float</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">__vector_size__</span><span class="p">(</span><span class="mi">16</span><span class="p">)));</span>
+<span class="k">typedef</span> <span class="kt">short</span> <span class="n">vector4short</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">__vector_size__</span><span class="p">(</span><span class="mi">8</span><span class="p">)));</span>
+<span class="n">vector4float</span> <span class="n">vf</span><span class="p">;</span> <span class="n">vector4short</span> <span class="n">vs</span><span class="p">;</span>
+
+<span class="c1">// convert from a vector of 4 floats to a vector of 4 doubles.</span>
+<span class="n">__builtin_convertvector</span><span class="p">(</span><span class="n">vf</span><span class="p">,</span> <span class="n">vector4double</span><span class="p">)</span>
+<span class="c1">// equivalent to:</span>
+<span class="p">(</span><span class="n">vector4double</span><span class="p">)</span> <span class="p">{</span> <span class="p">(</span><span class="kt">double</span><span class="p">)</span> <span class="n">vf</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="p">(</span><span class="kt">double</span><span class="p">)</span> <span class="n">vf</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="p">(</span><span class="kt">double</span><span class="p">)</span> <span class="n">vf</span><span class="p">[</span><span class="mi">2</span><span class="p">],</span> <span class="p">(</span><span class="kt">double</span><span class="p">)</span> <span class="n">vf</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="p">}</span>
+
+<span class="c1">// convert from a vector of 4 shorts to a vector of 4 floats.</span>
+<span class="n">__builtin_convertvector</span><span class="p">(</span><span class="n">vs</span><span class="p">,</span> <span class="n">vector4float</span><span class="p">)</span>
+<span class="c1">// equivalent to:</span>
+<span class="p">(</span><span class="n">vector4float</span><span class="p">)</span> <span class="p">{</span> <span class="p">(</span><span class="kt">float</span><span class="p">)</span> <span class="n">vs</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="p">(</span><span class="kt">float</span><span class="p">)</span> <span class="n">vs</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="p">(</span><span class="kt">float</span><span class="p">)</span> <span class="n">vs</span><span class="p">[</span><span class="mi">2</span><span class="p">],</span> <span class="p">(</span><span class="kt">float</span><span class="p">)</span> <span class="n">vs</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The first argument to <code class="docutils literal notranslate"><span class="pre">__builtin_convertvector</span></code> is a vector, and the second
+argument is a vector type with the same number of elements as the first
+argument.</p>
+<p>The result of <code class="docutils literal notranslate"><span class="pre">__builtin_convertvector</span></code> is a vector with the same element
+type as the second argument, with a value defined in terms of the action of a
+C-style cast applied to each element of the first argument.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_builtin(__builtin_convertvector)</span></code>.</p>
+</div>
+<div class="section" id="builtin-bitreverse">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_bitreverse</span></code><a class="headerlink" href="#builtin-bitreverse" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_bitreverse8</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_bitreverse16</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_bitreverse32</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_bitreverse64</span></code></li>
+</ul>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_bitreverse32</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Examples</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">uint8_t</span> <span class="n">rev_x</span> <span class="o">=</span> <span class="n">__builtin_bitreverse8</span><span class="p">(</span><span class="n">x</span><span class="p">);</span>
+<span class="kt">uint16_t</span> <span class="n">rev_x</span> <span class="o">=</span> <span class="n">__builtin_bitreverse16</span><span class="p">(</span><span class="n">x</span><span class="p">);</span>
+<span class="kt">uint32_t</span> <span class="n">rev_y</span> <span class="o">=</span> <span class="n">__builtin_bitreverse32</span><span class="p">(</span><span class="n">y</span><span class="p">);</span>
+<span class="kt">uint64_t</span> <span class="n">rev_z</span> <span class="o">=</span> <span class="n">__builtin_bitreverse64</span><span class="p">(</span><span class="n">z</span><span class="p">);</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The â<code class="docutils literal notranslate"><span class="pre">__builtin_bitreverse</span></code>â family of builtins is used to reverse
+the bitpattern of an integer value; for example <code class="docutils literal notranslate"><span class="pre">0b10110110</span></code> becomes
+<code class="docutils literal notranslate"><span class="pre">0b01101101</span></code>.</p>
+</div>
+<div class="section" id="builtin-rotateleft">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_rotateleft</span></code><a class="headerlink" href="#builtin-rotateleft" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_rotateleft8</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_rotateleft16</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_rotateleft32</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_rotateleft64</span></code></li>
+</ul>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_rotateleft32</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Examples</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">uint8_t</span> <span class="n">rot_x</span> <span class="o">=</span> <span class="n">__builtin_rotateleft8</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+<span class="kt">uint16_t</span> <span class="n">rot_x</span> <span class="o">=</span> <span class="n">__builtin_rotateleft16</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+<span class="kt">uint32_t</span> <span class="n">rot_x</span> <span class="o">=</span> <span class="n">__builtin_rotateleft32</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+<span class="kt">uint64_t</span> <span class="n">rot_x</span> <span class="o">=</span> <span class="n">__builtin_rotateleft64</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The â<code class="docutils literal notranslate"><span class="pre">__builtin_rotateleft</span></code>â family of builtins is used to rotate
+the bits in the first argument by the amount in the second argument.
+For example, <code class="docutils literal notranslate"><span class="pre">0b10000110</span></code> rotated left by 11 becomes <code class="docutils literal notranslate"><span class="pre">0b00110100</span></code>.
+The shift value is treated as an unsigned amount modulo the size of
+the arguments. Both arguments and the result have the bitwidth specified
+by the name of the builtin.</p>
+</div>
+<div class="section" id="builtin-rotateright">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_rotateright</span></code><a class="headerlink" href="#builtin-rotateright" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_rotateright8</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_rotateright16</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_rotateright32</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__builtin_rotateright64</span></code></li>
+</ul>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_rotateright32</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Examples</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">uint8_t</span> <span class="n">rot_x</span> <span class="o">=</span> <span class="n">__builtin_rotateright8</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+<span class="kt">uint16_t</span> <span class="n">rot_x</span> <span class="o">=</span> <span class="n">__builtin_rotateright16</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+<span class="kt">uint32_t</span> <span class="n">rot_x</span> <span class="o">=</span> <span class="n">__builtin_rotateright32</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+<span class="kt">uint64_t</span> <span class="n">rot_x</span> <span class="o">=</span> <span class="n">__builtin_rotateright64</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The â<code class="docutils literal notranslate"><span class="pre">__builtin_rotateright</span></code>â family of builtins is used to rotate
+the bits in the first argument by the amount in the second argument.
+For example, <code class="docutils literal notranslate"><span class="pre">0b10000110</span></code> rotated right by 3 becomes <code class="docutils literal notranslate"><span class="pre">0b11010000</span></code>.
+The shift value is treated as an unsigned amount modulo the size of
+the arguments. Both arguments and the result have the bitwidth specified
+by the name of the builtin.</p>
+</div>
+<div class="section" id="builtin-unreachable">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_unreachable</span></code><a class="headerlink" href="#builtin-unreachable" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_unreachable</span></code> is used to indicate that a specific point in the
+program cannot be reached, even if the compiler might otherwise think it can.
+This is useful to improve optimization and eliminates certain warnings. For
+example, without the <code class="docutils literal notranslate"><span class="pre">__builtin_unreachable</span></code> in the example below, the
+compiler assumes that the inline asm can fall through and prints a âfunction
+declared â<code class="docutils literal notranslate"><span class="pre">noreturn</span></code>â should not returnâ warning.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_unreachable</span><span class="p">()</span>
+</pre></div>
+</div>
+<p><strong>Example of use</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">myabort</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">noreturn</span><span class="p">));</span>
+<span class="kt">void</span> <span class="nf">myabort</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">asm</span><span class="p">(</span><span class="s">"int3"</span><span class="p">);</span>
+ <span class="n">__builtin_unreachable</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">__builtin_unreachable()</span></code> builtin has completely undefined behavior.
+Since it has undefined behavior, it is a statement that it is never reached and
+the optimizer can take advantage of this to produce better code. This builtin
+takes no arguments and produces a void result.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_builtin(__builtin_unreachable)</span></code>.</p>
+</div>
+<div class="section" id="builtin-unpredictable">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_unpredictable</span></code><a class="headerlink" href="#builtin-unpredictable" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_unpredictable</span></code> is used to indicate that a branch condition is
+unpredictable by hardware mechanisms such as branch prediction logic.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">__builtin_unpredictable</span><span class="p">(</span><span class="kt">long</span> <span class="kt">long</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Example of use</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">__builtin_unpredictable</span><span class="p">(</span><span class="n">x</span> <span class="o">></span> <span class="mi">0</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">__builtin_unpredictable()</span></code> builtin is expected to be used with control
+flow conditions such as in <code class="docutils literal notranslate"><span class="pre">if</span></code> and <code class="docutils literal notranslate"><span class="pre">switch</span></code> statements.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_builtin(__builtin_unpredictable)</span></code>.</p>
+</div>
+<div class="section" id="sync-swap">
+<h3><code class="docutils literal notranslate"><span class="pre">__sync_swap</span></code><a class="headerlink" href="#sync-swap" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__sync_swap</span></code> is used to atomically swap integers or pointers in memory.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">type</span> <span class="n">__sync_swap</span><span class="p">(</span><span class="n">type</span> <span class="o">*</span><span class="n">ptr</span><span class="p">,</span> <span class="n">type</span> <span class="n">value</span><span class="p">,</span> <span class="p">...)</span>
+</pre></div>
+</div>
+<p><strong>Example of Use</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">old_value</span> <span class="o">=</span> <span class="n">__sync_swap</span><span class="p">(</span><span class="o">&</span><span class="n">value</span><span class="p">,</span> <span class="n">new_value</span><span class="p">);</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">__sync_swap()</span></code> builtin extends the existing <code class="docutils literal notranslate"><span class="pre">__sync_*()</span></code> family of
+atomic intrinsics to allow code to atomically swap the current value with the
+new value. More importantly, it helps developers write more efficient and
+correct code by avoiding expensive loops around
+<code class="docutils literal notranslate"><span class="pre">__sync_bool_compare_and_swap()</span></code> or relying on the platform specific
+implementation details of <code class="docutils literal notranslate"><span class="pre">__sync_lock_test_and_set()</span></code>. The
+<code class="docutils literal notranslate"><span class="pre">__sync_swap()</span></code> builtin is a full barrier.</p>
+</div>
+<div class="section" id="builtin-addressof">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_addressof</span></code><a class="headerlink" href="#builtin-addressof" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_addressof</span></code> performs the functionality of the built-in <code class="docutils literal notranslate"><span class="pre">&</span></code>
+operator, ignoring any <code class="docutils literal notranslate"><span class="pre">operator&</span></code> overload. This is useful in constant
+expressions in C++11, where there is no other way to take the address of an
+object that overloads <code class="docutils literal notranslate"><span class="pre">operator&</span></code>.</p>
+<p><strong>Example of use</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="k">constexpr</span> <span class="n">T</span> <span class="o">*</span><span class="n">addressof</span><span class="p">(</span><span class="n">T</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">__builtin_addressof</span><span class="p">(</span><span class="n">value</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="builtin-operator-new-and-builtin-operator-delete">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_operator_new</span></code> and <code class="docutils literal notranslate"><span class="pre">__builtin_operator_delete</span></code><a class="headerlink" href="#builtin-operator-new-and-builtin-operator-delete" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_operator_new</span></code> allocates memory just like a non-placement non-class
+<em>new-expression</em>. This is exactly like directly calling the normal
+non-placement <code class="docutils literal notranslate"><span class="pre">::operator</span> <span class="pre">new</span></code>, except that it allows certain optimizations
+that the C++ standard does not permit for a direct function call to
+<code class="docutils literal notranslate"><span class="pre">::operator</span> <span class="pre">new</span></code> (in particular, removing <code class="docutils literal notranslate"><span class="pre">new</span></code> / <code class="docutils literal notranslate"><span class="pre">delete</span></code> pairs and
+merging allocations).</p>
+<p>Likewise, <code class="docutils literal notranslate"><span class="pre">__builtin_operator_delete</span></code> deallocates memory just like a
+non-class <em>delete-expression</em>, and is exactly like directly calling the normal
+<code class="docutils literal notranslate"><span class="pre">::operator</span> <span class="pre">delete</span></code>, except that it permits optimizations. Only the unsized
+form of <code class="docutils literal notranslate"><span class="pre">__builtin_operator_delete</span></code> is currently available.</p>
+<p>These builtins are intended for use in the implementation of <code class="docutils literal notranslate"><span class="pre">std::allocator</span></code>
+and other similar allocation libraries, and are only available in C++.</p>
+</div>
+<div class="section" id="builtin-preserve-access-index">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_preserve_access_index</span></code><a class="headerlink" href="#builtin-preserve-access-index" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_preserve_access_index</span></code> specifies a code section where
+array subscript access and structure/union member access are relocatable
+under bpf compile-once run-everywhere framework. Debuginfo (typically
+with <code class="docutils literal notranslate"><span class="pre">-g</span></code>) is needed, otherwise, the compiler will exit with an error.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">const</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">__builtin_preserve_access_index</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">ptr</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Example of Use</strong>:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">t</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">j</span><span class="p">;</span>
+ <span class="k">union</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">a</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">b</span><span class="p">;</span>
+ <span class="p">}</span> <span class="n">c</span><span class="p">[</span><span class="mi">4</span><span class="p">];</span>
+<span class="p">};</span>
+<span class="k">struct</span> <span class="n">t</span> <span class="o">*</span><span class="n">v</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">pb</span> <span class="o">=</span><span class="n">__builtin_preserve_access_index</span><span class="p">(</span><span class="o">&</span><span class="n">v</span><span class="o">-></span><span class="n">c</span><span class="p">[</span><span class="mi">3</span><span class="p">].</span><span class="n">b</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="multiprecision-arithmetic-builtins">
+<h3>Multiprecision Arithmetic Builtins<a class="headerlink" href="#multiprecision-arithmetic-builtins" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides a set of builtins which expose multiprecision arithmetic in a
+manner amenable to C. They all have the following form:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">unsigned</span> <span class="n">x</span> <span class="o">=</span> <span class="p">...,</span> <span class="n">y</span> <span class="o">=</span> <span class="p">...,</span> <span class="n">carryin</span> <span class="o">=</span> <span class="p">...,</span> <span class="n">carryout</span><span class="p">;</span>
+<span class="kt">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="n">__builtin_addc</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">carryin</span><span class="p">,</span> <span class="o">&</span><span class="n">carryout</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Thus one can form a multiprecision addition chain in the following manner:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">unsigned</span> <span class="o">*</span><span class="n">x</span><span class="p">,</span> <span class="o">*</span><span class="n">y</span><span class="p">,</span> <span class="o">*</span><span class="n">z</span><span class="p">,</span> <span class="n">carryin</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">carryout</span><span class="p">;</span>
+<span class="n">z</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">__builtin_addc</span><span class="p">(</span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">y</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">carryin</span><span class="p">,</span> <span class="o">&</span><span class="n">carryout</span><span class="p">);</span>
+<span class="n">carryin</span> <span class="o">=</span> <span class="n">carryout</span><span class="p">;</span>
+<span class="n">z</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">__builtin_addc</span><span class="p">(</span><span class="n">x</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">y</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">carryin</span><span class="p">,</span> <span class="o">&</span><span class="n">carryout</span><span class="p">);</span>
+<span class="n">carryin</span> <span class="o">=</span> <span class="n">carryout</span><span class="p">;</span>
+<span class="n">z</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="n">__builtin_addc</span><span class="p">(</span><span class="n">x</span><span class="p">[</span><span class="mi">2</span><span class="p">],</span> <span class="n">y</span><span class="p">[</span><span class="mi">2</span><span class="p">],</span> <span class="n">carryin</span><span class="p">,</span> <span class="o">&</span><span class="n">carryout</span><span class="p">);</span>
+<span class="n">carryin</span> <span class="o">=</span> <span class="n">carryout</span><span class="p">;</span>
+<span class="n">z</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="o">=</span> <span class="n">__builtin_addc</span><span class="p">(</span><span class="n">x</span><span class="p">[</span><span class="mi">3</span><span class="p">],</span> <span class="n">y</span><span class="p">[</span><span class="mi">3</span><span class="p">],</span> <span class="n">carryin</span><span class="p">,</span> <span class="o">&</span><span class="n">carryout</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The complete list of builtins are:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">unsigned</span> <span class="kt">char</span> <span class="nf">__builtin_addcb</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="kt">short</span> <span class="nf">__builtin_addcs</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">short</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">short</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">short</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">short</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="nf">__builtin_addc</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">__builtin_addcl</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="nf">__builtin_addcll</span><span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="kt">char</span> <span class="nf">__builtin_subcb</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="kt">short</span> <span class="nf">__builtin_subcs</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">short</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">short</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">short</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">short</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="nf">__builtin_subc</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">__builtin_subcl</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+<span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="nf">__builtin_subcll</span><span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">carryin</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="o">*</span><span class="n">carryout</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="checked-arithmetic-builtins">
+<h3>Checked Arithmetic Builtins<a class="headerlink" href="#checked-arithmetic-builtins" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides a set of builtins that implement checked arithmetic for security
+critical applications in a manner that is fast and easily expressable in C. As
+an example of their usage:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">errorcode_t</span> <span class="nf">security_critical_application</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">result</span><span class="p">;</span>
+ <span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">__builtin_mul_overflow</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="o">&</span><span class="n">result</span><span class="p">))</span>
+ <span class="k">return</span> <span class="n">kErrorCodeHackers</span><span class="p">;</span>
+ <span class="p">...</span>
+ <span class="n">use_multiply</span><span class="p">(</span><span class="n">result</span><span class="p">);</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Clang provides the following checked arithmetic builtins:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">bool</span> <span class="nf">__builtin_add_overflow</span> <span class="p">(</span><span class="n">type1</span> <span class="n">x</span><span class="p">,</span> <span class="n">type2</span> <span class="n">y</span><span class="p">,</span> <span class="n">type3</span> <span class="o">*</span><span class="n">sum</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_sub_overflow</span> <span class="p">(</span><span class="n">type1</span> <span class="n">x</span><span class="p">,</span> <span class="n">type2</span> <span class="n">y</span><span class="p">,</span> <span class="n">type3</span> <span class="o">*</span><span class="n">diff</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_mul_overflow</span> <span class="p">(</span><span class="n">type1</span> <span class="n">x</span><span class="p">,</span> <span class="n">type2</span> <span class="n">y</span><span class="p">,</span> <span class="n">type3</span> <span class="o">*</span><span class="n">prod</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_uadd_overflow</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">sum</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_uaddl_overflow</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="o">*</span><span class="n">sum</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_uaddll_overflow</span><span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="o">*</span><span class="n">sum</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_usub_overflow</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">diff</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_usubl_overflow</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="o">*</span><span class="n">diff</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_usubll_overflow</span><span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="o">*</span><span class="n">diff</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_umul_overflow</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">prod</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_umull_overflow</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="o">*</span><span class="n">prod</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_umulll_overflow</span><span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">long</span> <span class="o">*</span><span class="n">prod</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_sadd_overflow</span> <span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="kt">int</span> <span class="n">y</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">sum</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_saddl_overflow</span> <span class="p">(</span><span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">long</span> <span class="o">*</span><span class="n">sum</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_saddll_overflow</span><span class="p">(</span><span class="kt">long</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">long</span> <span class="kt">long</span> <span class="o">*</span><span class="n">sum</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_ssub_overflow</span> <span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="kt">int</span> <span class="n">y</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">diff</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_ssubl_overflow</span> <span class="p">(</span><span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">long</span> <span class="o">*</span><span class="n">diff</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_ssubll_overflow</span><span class="p">(</span><span class="kt">long</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">long</span> <span class="kt">long</span> <span class="o">*</span><span class="n">diff</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_smul_overflow</span> <span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="kt">int</span> <span class="n">y</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">prod</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_smull_overflow</span> <span class="p">(</span><span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">long</span> <span class="o">*</span><span class="n">prod</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_smulll_overflow</span><span class="p">(</span><span class="kt">long</span> <span class="kt">long</span> <span class="n">x</span><span class="p">,</span> <span class="kt">long</span> <span class="kt">long</span> <span class="n">y</span><span class="p">,</span> <span class="kt">long</span> <span class="kt">long</span> <span class="o">*</span><span class="n">prod</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Each builtin performs the specified mathematical operation on the
+first two arguments and stores the result in the third argument. If
+possible, the result will be equal to mathematically-correct result
+and the builtin will return 0. Otherwise, the builtin will return
+1 and the result will be equal to the unique value that is equivalent
+to the mathematically-correct result modulo two raised to the <em>k</em>
+power, where <em>k</em> is the number of bits in the result type. The
+behavior of these builtins is well-defined for all argument values.</p>
+<p>The first three builtins work generically for operands of any integer type,
+including boolean types. The operands need not have the same type as each
+other, or as the result. The other builtins may implicitly promote or
+convert their operands before performing the operation.</p>
+<p>Query for this feature with <code class="docutils literal notranslate"><span class="pre">__has_builtin(__builtin_add_overflow)</span></code>, etc.</p>
+</div>
+<div class="section" id="floating-point-builtins">
+<h3>Floating point builtins<a class="headerlink" href="#floating-point-builtins" title="Permalink to this headline">¶</a></h3>
+</div>
+<div class="section" id="builtin-canonicalize">
+<h3><code class="docutils literal notranslate"><span class="pre">__builtin_canonicalize</span></code><a class="headerlink" href="#builtin-canonicalize" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">double</span> <span class="nf">__builtin_canonicalize</span><span class="p">(</span><span class="kt">double</span><span class="p">);</span>
+<span class="kt">float</span> <span class="nf">__builtin_canonicalizef</span><span class="p">(</span><span class="kt">float</span><span class="p">);</span>
+<span class="kt">long</span> <span class="nf">double__builtin_canonicalizel</span><span class="p">(</span><span class="kt">long</span> <span class="kt">double</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Returns the platform specific canonical encoding of a floating point
+number. This canonicalization is useful for implementing certain
+numeric primitives such as frexp. See <a class="reference external" href="https://llvm.org/docs/LangRef.html#llvm-canonicalize-intrinsic">LLVM canonicalize intrinsic</a> for
+more information on the semantics.</p>
+</div>
+<div class="section" id="string-builtins">
+<h3>String builtins<a class="headerlink" href="#string-builtins" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides constant expression evaluation support for builtins forms of
+the following functions from the C standard library <code class="docutils literal notranslate"><span class="pre"><string.h></span></code> header:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">memchr</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">memcmp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">strchr</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">strcmp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">strlen</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">strncmp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">wcschr</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">wcscmp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">wcslen</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">wcsncmp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">wmemchr</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">wmemcmp</span></code></li>
+</ul>
+<p>In each case, the builtin form has the name of the C library function prefixed
+by <code class="docutils literal notranslate"><span class="pre">__builtin_</span></code>. Example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="o">*</span><span class="n">p</span> <span class="o">=</span> <span class="n">__builtin_memchr</span><span class="p">(</span><span class="s">"foobar"</span><span class="p">,</span> <span class="sc">'b'</span><span class="p">,</span> <span class="mi">5</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In addition to the above, one further builtin is provided:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">char</span> <span class="o">*</span><span class="nf">__builtin_char_memchr</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">haystack</span><span class="p">,</span> <span class="kt">int</span> <span class="n">needle</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_char_memchr(a,</span> <span class="pre">b,</span> <span class="pre">c)</span></code> is identical to
+<code class="docutils literal notranslate"><span class="pre">(char*)__builtin_memchr(a,</span> <span class="pre">b,</span> <span class="pre">c)</span></code> except that its use is permitted within
+constant expressions in C++11 onwards (where a cast from <code class="docutils literal notranslate"><span class="pre">void*</span></code> to <code class="docutils literal notranslate"><span class="pre">char*</span></code>
+is disallowed in general).</p>
+<p>Support for constant expression evaluation for the above builtins be detected
+with <code class="docutils literal notranslate"><span class="pre">__has_feature(cxx_constexpr_string_builtins)</span></code>.</p>
+</div>
+<div class="section" id="atomic-min-max-builtins-with-memory-ordering">
+<h3>Atomic Min/Max builtins with memory ordering<a class="headerlink" href="#atomic-min-max-builtins-with-memory-ordering" title="Permalink to this headline">¶</a></h3>
+<p>There are two atomic builtins with min/max in-memory comparison and swap.
+The syntax and semantics are similar to GCC-compatible __atomic_* builtins.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__atomic_fetch_min</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__atomic_fetch_max</span></code></li>
+</ul>
+<p>The builtins work with signed and unsigned integers and require to specify memory ordering.
+The return value is the original value that was stored in memory before comparison.</p>
+<p>Example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">val</span> <span class="o">=</span> <span class="n">__atomic_fetch_min</span><span class="p">(</span><span class="kt">unsigned</span> <span class="kt">int</span> <span class="o">*</span><span class="n">pi</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">ui</span><span class="p">,</span> <span class="n">__ATOMIC_RELAXED</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The third argument is one of the memory ordering specifiers <code class="docutils literal notranslate"><span class="pre">__ATOMIC_RELAXED</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__ATOMIC_CONSUME</span></code>, <code class="docutils literal notranslate"><span class="pre">__ATOMIC_ACQUIRE</span></code>, <code class="docutils literal notranslate"><span class="pre">__ATOMIC_RELEASE</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__ATOMIC_ACQ_REL</span></code>, or <code class="docutils literal notranslate"><span class="pre">__ATOMIC_SEQ_CST</span></code> following C++11 memory model semantics.</p>
+<p>In terms or aquire-release ordering barriers these two operations are always
+considered as operations with <em>load-store</em> semantics, even when the original value
+is not actually modified after comparison.</p>
+</div>
+<div class="section" id="c11-atomic-builtins">
+<span id="langext-c11-atomic"></span><h3>__c11_atomic builtins<a class="headerlink" href="#c11-atomic-builtins" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides a set of builtins which are intended to be used to implement
+C11âs <code class="docutils literal notranslate"><span class="pre"><stdatomic.h></span></code> header. These builtins provide the semantics of the
+<code class="docutils literal notranslate"><span class="pre">_explicit</span></code> form of the corresponding C11 operation, and are named with a
+<code class="docutils literal notranslate"><span class="pre">__c11_</span></code> prefix. The supported operations, and the differences from
+the corresponding C11 operations, are:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_init</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_thread_fence</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_signal_fence</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_is_lock_free</span></code> (The argument is the size of the
+<code class="docutils literal notranslate"><span class="pre">_Atomic(...)</span></code> object, instead of its address)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_store</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_load</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_exchange</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_compare_exchange_strong</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_compare_exchange_weak</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_fetch_add</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_fetch_sub</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_fetch_and</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_fetch_or</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">__c11_atomic_fetch_xor</span></code></li>
+</ul>
+<p>The macros <code class="docutils literal notranslate"><span class="pre">__ATOMIC_RELAXED</span></code>, <code class="docutils literal notranslate"><span class="pre">__ATOMIC_CONSUME</span></code>, <code class="docutils literal notranslate"><span class="pre">__ATOMIC_ACQUIRE</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__ATOMIC_RELEASE</span></code>, <code class="docutils literal notranslate"><span class="pre">__ATOMIC_ACQ_REL</span></code>, and <code class="docutils literal notranslate"><span class="pre">__ATOMIC_SEQ_CST</span></code> are
+provided, with values corresponding to the enumerators of C11âs
+<code class="docutils literal notranslate"><span class="pre">memory_order</span></code> enumeration.</p>
+<p>(Note that Clang additionally provides GCC-compatible <code class="docutils literal notranslate"><span class="pre">__atomic_*</span></code>
+builtins and OpenCL 2.0 <code class="docutils literal notranslate"><span class="pre">__opencl_atomic_*</span></code> builtins. The OpenCL 2.0
+atomic builtins are an explicit form of the corresponding OpenCL 2.0
+builtin function, and are named with a <code class="docutils literal notranslate"><span class="pre">__opencl_</span></code> prefix. The macros
+<code class="docutils literal notranslate"><span class="pre">__OPENCL_MEMORY_SCOPE_WORK_ITEM</span></code>, <code class="docutils literal notranslate"><span class="pre">__OPENCL_MEMORY_SCOPE_WORK_GROUP</span></code>,
+<code class="docutils literal notranslate"><span class="pre">__OPENCL_MEMORY_SCOPE_DEVICE</span></code>, <code class="docutils literal notranslate"><span class="pre">__OPENCL_MEMORY_SCOPE_ALL_SVM_DEVICES</span></code>,
+and <code class="docutils literal notranslate"><span class="pre">__OPENCL_MEMORY_SCOPE_SUB_GROUP</span></code> are provided, with values
+corresponding to the enumerators of OpenCLâs <code class="docutils literal notranslate"><span class="pre">memory_scope</span></code> enumeration.)</p>
+</div>
+<div class="section" id="low-level-arm-exclusive-memory-builtins">
+<h3>Low-level ARM exclusive memory builtins<a class="headerlink" href="#low-level-arm-exclusive-memory-builtins" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides overloaded builtins giving direct access to the three key ARM
+instructions for implementing atomic operations.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">T</span> <span class="nf">__builtin_arm_ldrex</span><span class="p">(</span><span class="k">const</span> <span class="k">volatile</span> <span class="n">T</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+<span class="n">T</span> <span class="nf">__builtin_arm_ldaex</span><span class="p">(</span><span class="k">const</span> <span class="k">volatile</span> <span class="n">T</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">__builtin_arm_strex</span><span class="p">(</span><span class="n">T</span> <span class="n">val</span><span class="p">,</span> <span class="k">volatile</span> <span class="n">T</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">__builtin_arm_stlex</span><span class="p">(</span><span class="n">T</span> <span class="n">val</span><span class="p">,</span> <span class="k">volatile</span> <span class="n">T</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__builtin_arm_clrex</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The types <code class="docutils literal notranslate"><span class="pre">T</span></code> currently supported are:</p>
+<ul class="simple">
+<li>Integer types with width at most 64 bits (or 128 bits on AArch64).</li>
+<li>Floating-point types</li>
+<li>Pointer types.</li>
+</ul>
+<p>Note that the compiler does not guarantee it will not insert stores which clear
+the exclusive monitor in between an <code class="docutils literal notranslate"><span class="pre">ldrex</span></code> type operation and its paired
+<code class="docutils literal notranslate"><span class="pre">strex</span></code>. In practice this is only usually a risk when the extra store is on
+the same cache line as the variable being modified and Clang will only insert
+stack stores on its own, so it is best not to use these operations on variables
+with automatic storage duration.</p>
+<p>Also, loads and stores may be implicit in code written between the <code class="docutils literal notranslate"><span class="pre">ldrex</span></code> and
+<code class="docutils literal notranslate"><span class="pre">strex</span></code>. Clang will not necessarily mitigate the effects of these either, so
+care should be exercised.</p>
+<p>For these reasons the higher level atomic primitives should be preferred where
+possible.</p>
+</div>
+<div class="section" id="non-temporal-load-store-builtins">
+<h3>Non-temporal load/store builtins<a class="headerlink" href="#non-temporal-load-store-builtins" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides overloaded builtins allowing generation of non-temporal memory
+accesses.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">T</span> <span class="nf">__builtin_nontemporal_load</span><span class="p">(</span><span class="n">T</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__builtin_nontemporal_store</span><span class="p">(</span><span class="n">T</span> <span class="n">value</span><span class="p">,</span> <span class="n">T</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The types <code class="docutils literal notranslate"><span class="pre">T</span></code> currently supported are:</p>
+<ul class="simple">
+<li>Integer types.</li>
+<li>Floating-point types.</li>
+<li>Vector types.</li>
+</ul>
+<p>Note that the compiler does not guarantee that non-temporal loads or stores
+will be used.</p>
+</div>
+<div class="section" id="c-coroutines-support-builtins">
+<h3>C++ Coroutines support builtins<a class="headerlink" href="#c-coroutines-support-builtins" title="Permalink to this headline">¶</a></h3>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This is a work in progress. Compatibility across Clang/LLVM releases is not
+guaranteed.</p>
+</div>
+<p>Clang provides experimental builtins to support C++ Coroutines as defined by
+<a class="reference external" href="https://wg21.link/P0057">https://wg21.link/P0057</a>. The following four are intended to be used by the
+standard library to implement <cite>std::experimental::coroutine_handle</cite> type.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">__builtin_coro_resume</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__builtin_coro_destroy</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="nf">__builtin_coro_done</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">addr</span><span class="p">);</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">__builtin_coro_promise</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">addr</span><span class="p">,</span> <span class="kt">int</span> <span class="n">alignment</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">from_promise</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Example of use</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span> <span class="o"><></span> <span class="k">struct</span> <span class="n">coroutine_handle</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">resume</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="n">__builtin_coro_resume</span><span class="p">(</span><span class="n">ptr</span><span class="p">);</span> <span class="p">}</span>
+ <span class="kt">void</span> <span class="n">destroy</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="n">__builtin_coro_destroy</span><span class="p">(</span><span class="n">ptr</span><span class="p">);</span> <span class="p">}</span>
+ <span class="kt">bool</span> <span class="n">done</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">__builtin_coro_done</span><span class="p">(</span><span class="n">ptr</span><span class="p">);</span> <span class="p">}</span>
+ <span class="c1">// ...</span>
+<span class="k">protected</span><span class="o">:</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">ptr</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">Promise</span><span class="o">></span> <span class="k">struct</span> <span class="nl">coroutine_handle</span> <span class="p">:</span> <span class="n">coroutine_handle</span><span class="o"><></span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+ <span class="n">Promise</span> <span class="o">&</span><span class="n">promise</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="o">*</span><span class="k">reinterpret_cast</span><span class="o"><</span><span class="n">Promise</span> <span class="o">*></span><span class="p">(</span>
+ <span class="n">__builtin_coro_promise</span><span class="p">(</span><span class="n">ptr</span><span class="p">,</span> <span class="k">alignof</span><span class="p">(</span><span class="n">Promise</span><span class="p">),</span> <span class="cm">/*from-promise=*/</span><span class="nb">false</span><span class="p">));</span>
+ <span class="p">}</span>
+ <span class="k">static</span> <span class="n">coroutine_handle</span> <span class="n">from_promise</span><span class="p">(</span><span class="n">Promise</span> <span class="o">&</span><span class="n">promise</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">coroutine_handle</span> <span class="n">p</span><span class="p">;</span>
+ <span class="n">p</span><span class="p">.</span><span class="n">ptr</span> <span class="o">=</span> <span class="n">__builtin_coro_promise</span><span class="p">(</span><span class="o">&</span><span class="n">promise</span><span class="p">,</span> <span class="k">alignof</span><span class="p">(</span><span class="n">Promise</span><span class="p">),</span>
+ <span class="cm">/*from-promise=*/</span><span class="nb">true</span><span class="p">);</span>
+ <span class="k">return</span> <span class="n">p</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Other coroutine builtins are either for internal clang use or for use during
+development of the coroutine feature. See <a class="reference external" href="https://llvm.org/docs/Coroutines.html#intrinsics">Coroutines in LLVM</a> for
+more information on their semantics. Note that builtins matching the intrinsics
+that take token as the first parameter (llvm.coro.begin, llvm.coro.alloc,
+llvm.coro.free and llvm.coro.suspend) omit the token parameter and fill it to
+an appropriate value during the emission.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">size_t</span> <span class="n">__builtin_coro_size</span><span class="p">()</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">__builtin_coro_frame</span><span class="p">()</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">__builtin_coro_free</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">coro_frame</span><span class="p">)</span>
+
+<span class="kt">void</span> <span class="o">*</span><span class="n">__builtin_coro_id</span><span class="p">(</span><span class="kt">int</span> <span class="n">align</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">promise</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">fnaddr</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">parts</span><span class="p">)</span>
+<span class="kt">bool</span> <span class="n">__builtin_coro_alloc</span><span class="p">()</span>
+<span class="kt">void</span> <span class="o">*</span><span class="n">__builtin_coro_begin</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">memory</span><span class="p">)</span>
+<span class="kt">void</span> <span class="n">__builtin_coro_end</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">coro_frame</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">unwind</span><span class="p">)</span>
+<span class="kt">char</span> <span class="n">__builtin_coro_suspend</span><span class="p">(</span><span class="kt">bool</span> <span class="n">final</span><span class="p">)</span>
+<span class="kt">bool</span> <span class="n">__builtin_coro_param</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">original</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">copy</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Note that there is no builtin matching the <cite>llvm.coro.save</cite> intrinsic. LLVM
+automatically will insert one if the first argument to <cite>llvm.coro.suspend</cite> is
+token <cite>none</cite>. If a user calls <cite>__builin_suspend</cite>, clang will insert <cite>token none</cite>
+as the first argument to the intrinsic.</p>
+</div>
+<div class="section" id="source-location-builtins">
+<h3>Source location builtins<a class="headerlink" href="#source-location-builtins" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides experimental builtins to support C++ standard library implementation
+of <code class="docutils literal notranslate"><span class="pre">std::experimental::source_location</span></code> as specified in <a class="reference external" href="http://wg21.link/N4600">http://wg21.link/N4600</a>.
+With the exception of <code class="docutils literal notranslate"><span class="pre">__builtin_COLUMN</span></code>, these builtins are also implemented by
+GCC.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="nf">__builtin_FILE</span><span class="p">();</span>
+<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="nf">__builtin_FUNCTION</span><span class="p">();</span>
+<span class="kt">unsigned</span> <span class="nf">__builtin_LINE</span><span class="p">();</span>
+<span class="kt">unsigned</span> <span class="nf">__builtin_COLUMN</span><span class="p">();</span> <span class="c1">// Clang only</span>
+</pre></div>
+</div>
+<p><strong>Example of use</strong>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">my_assert</span><span class="p">(</span><span class="kt">bool</span> <span class="n">pred</span><span class="p">,</span> <span class="kt">int</span> <span class="n">line</span> <span class="o">=</span> <span class="n">__builtin_LINE</span><span class="p">(),</span> <span class="c1">// Captures line of caller</span>
+ <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">file</span> <span class="o">=</span> <span class="n">__builtin_FILE</span><span class="p">(),</span>
+ <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">function</span> <span class="o">=</span> <span class="n">__builtin_FUNCTION</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">pred</span><span class="p">)</span> <span class="k">return</span><span class="p">;</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"%s:%d assertion failed in function %s</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">file</span><span class="p">,</span> <span class="n">line</span><span class="p">,</span> <span class="n">function</span><span class="p">);</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">abort</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="k">struct</span> <span class="n">MyAggregateType</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">x</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">line</span> <span class="o">=</span> <span class="n">__builtin_LINE</span><span class="p">();</span> <span class="c1">// captures line where aggregate initialization occurs</span>
+<span class="p">};</span>
+<span class="k">static_assert</span><span class="p">(</span><span class="n">MyAggregateType</span><span class="p">{</span><span class="mi">42</span><span class="p">}.</span><span class="n">line</span> <span class="o">==</span> <span class="n">__LINE__</span><span class="p">);</span>
+
+<span class="k">struct</span> <span class="n">MyClassType</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">line</span> <span class="o">=</span> <span class="n">__builtin_LINE</span><span class="p">();</span> <span class="c1">// captures line of the constructor used during initialization</span>
+ <span class="k">constexpr</span> <span class="nf">MyClassType</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{</span> <span class="n">assert</span><span class="p">(</span><span class="n">line</span> <span class="o">==</span> <span class="n">__LINE__</span><span class="p">);</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><strong>Description</strong>:</p>
+<p>The builtins <code class="docutils literal notranslate"><span class="pre">__builtin_LINE</span></code>, <code class="docutils literal notranslate"><span class="pre">__builtin_FUNCTION</span></code>, and <code class="docutils literal notranslate"><span class="pre">__builtin_FILE</span></code> return
+the values, at the âinvocation pointâ, for <code class="docutils literal notranslate"><span class="pre">__LINE__</span></code>, <code class="docutils literal notranslate"><span class="pre">__FUNCTION__</span></code>, and
+<code class="docutils literal notranslate"><span class="pre">__FILE__</span></code> respectively. These builtins are constant expressions.</p>
+<p>When the builtins appear as part of a default function argument the invocation
+point is the location of the caller. When the builtins appear as part of a
+default member initializer, the invocation point is the location of the
+constructor or aggregate initialization used to create the object. Otherwise
+the invocation point is the same as the location of the builtin.</p>
+<p>When the invocation point of <code class="docutils literal notranslate"><span class="pre">__builtin_FUNCTION</span></code> is not a function scope the
+empty string is returned.</p>
+</div>
+</div>
+<div class="section" id="non-standard-c-11-attributes">
+<h2><a class="toc-backref" href="#id21">Non-standard C++11 Attributes</a><a class="headerlink" href="#non-standard-c-11-attributes" title="Permalink to this headline">¶</a></h2>
+<p>Clangâs non-standard C++11 attributes live in the <code class="docutils literal notranslate"><span class="pre">clang</span></code> attribute
+namespace.</p>
+<p>Clang supports GCCâs <code class="docutils literal notranslate"><span class="pre">gnu</span></code> attribute namespace. All GCC attributes which
+are accepted with the <code class="docutils literal notranslate"><span class="pre">__attribute__((foo))</span></code> syntax are also accepted as
+<code class="docutils literal notranslate"><span class="pre">[[gnu::foo]]</span></code>. This only extends to attributes which are specified by GCC
+(see the list of <a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">GCC function attributes</a>, <a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html">GCC variable
+attributes</a>, and
+<a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html">GCC type attributes</a>). As with the GCC
+implementation, these attributes must appertain to the <em>declarator-id</em> in a
+declaration, which means they must go either at the start of the declaration or
+immediately after the name being declared.</p>
+<p>For example, this applies the GNU <code class="docutils literal notranslate"><span class="pre">unused</span></code> attribute to <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">f</span></code>, and
+also applies the GNU <code class="docutils literal notranslate"><span class="pre">noreturn</span></code> attribute to <code class="docutils literal notranslate"><span class="pre">f</span></code>.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">gnu</span><span class="o">::</span><span class="n">unused</span><span class="p">]]</span> <span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="n">f</span> <span class="p">[[</span><span class="n">gnu</span><span class="o">::</span><span class="n">noreturn</span><span class="p">]]</span> <span class="p">();</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="target-specific-extensions">
+<h2><a class="toc-backref" href="#id22">Target-Specific Extensions</a><a class="headerlink" href="#target-specific-extensions" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports some language features conditionally on some targets.</p>
+<div class="section" id="arm-aarch64-language-extensions">
+<h3>ARM/AArch64 Language Extensions<a class="headerlink" href="#arm-aarch64-language-extensions" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="memory-barrier-intrinsics">
+<h4>Memory Barrier Intrinsics<a class="headerlink" href="#memory-barrier-intrinsics" title="Permalink to this headline">¶</a></h4>
+<p>Clang implements the <code class="docutils literal notranslate"><span class="pre">__dmb</span></code>, <code class="docutils literal notranslate"><span class="pre">__dsb</span></code> and <code class="docutils literal notranslate"><span class="pre">__isb</span></code> intrinsics as defined
+in the <a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf">ARM C Language Extensions Release 2.0</a>.
+Note that these intrinsics are implemented as motion barriers that block
+reordering of memory accesses and side effect instructions. Other instructions
+like simple arithmetic may be reordered around the intrinsic. If you expect to
+have no reordering at all, use inline assembly instead.</p>
+</div>
+</div>
+<div class="section" id="x86-x86-64-language-extensions">
+<h3>X86/X86-64 Language Extensions<a class="headerlink" href="#x86-x86-64-language-extensions" title="Permalink to this headline">¶</a></h3>
+<p>The X86 backend has these language extensions:</p>
+<div class="section" id="memory-references-to-specified-segments">
+<h4>Memory references to specified segments<a class="headerlink" href="#memory-references-to-specified-segments" title="Permalink to this headline">¶</a></h4>
+<p>Annotating a pointer with address space #256 causes it to be code generated
+relative to the X86 GS segment register, address space #257 causes it to be
+relative to the X86 FS segment, and address space #258 causes it to be
+relative to the X86 SS segment. Note that this is a very very low-level
+feature that should only be used if you know what youâre doing (for example in
+an OS kernel).</p>
+<p>Here is an example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#define GS_RELATIVE __attribute__((address_space(256)))</span>
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">GS_RELATIVE</span> <span class="o">*</span><span class="n">P</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="o">*</span><span class="n">P</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Which compiles to (on X86-32):</p>
+<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nl">_foo:</span>
+ <span class="nf">movl</span> <span class="mi">4</span><span class="p">(</span><span class="nv">%esp</span><span class="p">),</span> <span class="nv">%eax</span>
+ <span class="nf">movl</span> <span class="nv">%gs</span><span class="p">:(</span><span class="nv">%eax</span><span class="p">),</span> <span class="nv">%eax</span>
+ <span class="nf">ret</span>
+</pre></div>
+</div>
+<p>You can also use the GCC compatibility macros <code class="docutils literal notranslate"><span class="pre">__seg_fs</span></code> and <code class="docutils literal notranslate"><span class="pre">__seg_gs</span></code> for
+the same purpose. The preprocessor symbols <code class="docutils literal notranslate"><span class="pre">__SEG_FS</span></code> and <code class="docutils literal notranslate"><span class="pre">__SEG_GS</span></code>
+indicate their support.</p>
+</div>
+</div>
+<div class="section" id="powerpc-language-extensions">
+<h3>PowerPC Language Extensions<a class="headerlink" href="#powerpc-language-extensions" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="set-the-floating-point-rounding-mode">
+<h4>Set the Floating Point Rounding Mode<a class="headerlink" href="#set-the-floating-point-rounding-mode" title="Permalink to this headline">¶</a></h4>
+<p>PowerPC64/PowerPC64le supports the builtin function <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd</span></code> to set
+the floating point rounding mode. This function will use the least significant
+two bits of integer argument to set the floating point rounding mode.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">double</span> <span class="nf">__builtin_setrnd</span><span class="p">(</span><span class="kt">int</span> <span class="n">mode</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The effective values for mode are:</p>
+<blockquote>
+<div><ul class="simple">
+<li>0 - round to nearest</li>
+<li>1 - round to zero</li>
+<li>2 - round to +infinity</li>
+<li>3 - round to -infinity</li>
+</ul>
+</div></blockquote>
+<p>Note that the mode argument will modulo 4, so if the int argument is greater
+than 3, it will only use the least significant two bits of the mode.
+Namely, <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd(102))</span></code> is equal to <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd(2)</span></code>.</p>
+</div>
+</div>
+<div class="section" id="id1">
+<h3>PowerPC Language Extensions<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id2">
+<h4>Set the Floating Point Rounding Mode<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>PowerPC64/PowerPC64le supports the builtin function <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd</span></code> to set
+the floating point rounding mode. This function will use the least significant
+two bits of integer argument to set the floating point rounding mode.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">double</span> <span class="nf">__builtin_setrnd</span><span class="p">(</span><span class="kt">int</span> <span class="n">mode</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The effective values for mode are:</p>
+<blockquote>
+<div><ul class="simple">
+<li>0 - round to nearest</li>
+<li>1 - round to zero</li>
+<li>2 - round to +infinity</li>
+<li>3 - round to -infinity</li>
+</ul>
+</div></blockquote>
+<p>Note that the mode argument will modulo 4, so if the integer argument is greater
+than 3, it will only use the least significant two bits of the mode.
+Namely, <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd(102))</span></code> is equal to <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd(2)</span></code>.</p>
+</div>
+</div>
+<div class="section" id="id3">
+<h3>PowerPC Language Extensions<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id4">
+<h4>Set the Floating Point Rounding Mode<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>PowerPC64/PowerPC64le supports the builtin function <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd</span></code> to set
+the floating point rounding mode. This function will use the least significant
+two bits of integer argument to set the floating point rounding mode.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">double</span> <span class="nf">__builtin_setrnd</span><span class="p">(</span><span class="kt">int</span> <span class="n">mode</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The effective values for mode are:</p>
+<blockquote>
+<div><ul class="simple">
+<li>0 - round to nearest</li>
+<li>1 - round to zero</li>
+<li>2 - round to +infinity</li>
+<li>3 - round to -infinity</li>
+</ul>
+</div></blockquote>
+<p>Note that the mode argument will modulo 4, so if the integer argument is greater
+than 3, it will only use the least significant two bits of the mode.
+Namely, <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd(102))</span></code> is equal to <code class="docutils literal notranslate"><span class="pre">__builtin_setrnd(2)</span></code>.</p>
+</div>
+<div class="section" id="powerpc-cache-builtins">
+<h4>PowerPC cache builtins<a class="headerlink" href="#powerpc-cache-builtins" title="Permalink to this headline">¶</a></h4>
+<p>The PowerPC architecture specifies instructions implementing cache operations.
+Clang provides builtins that give direct programmer access to these cache
+instructions.</p>
+<p>Currently the following builtins are implemented in clang:</p>
+<p><code class="docutils literal notranslate"><span class="pre">__builtin_dcbf</span></code> copies the contents of a modified block from the data cache
+to main memory and flushes the copy from the data cache.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">__dcbf</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">addr</span><span class="p">);</span> <span class="cm">/* Data Cache Block Flush */</span>
+</pre></div>
+</div>
+<p><strong>Example of Use</strong>:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">a</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="n">__builtin_dcbf</span> <span class="p">(</span><span class="o">&</span><span class="n">a</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="extensions-for-static-analysis">
+<h2><a class="toc-backref" href="#id23">Extensions for Static Analysis</a><a class="headerlink" href="#extensions-for-static-analysis" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes that are useful for documenting program
+invariants and rules for static analysis tools, such as the <a class="reference external" href="https://clang-analyzer.llvm.org/">Clang Static
+Analyzer</a>. These attributes are documented
+in the analyzerâs <a class="reference external" href="https://clang-analyzer.llvm.org/annotations.html">list of source-level annotations</a>.</p>
+</div>
+<div class="section" id="extensions-for-dynamic-analysis">
+<h2><a class="toc-backref" href="#id24">Extensions for Dynamic Analysis</a><a class="headerlink" href="#extensions-for-dynamic-analysis" title="Permalink to this headline">¶</a></h2>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(address_sanitizer)</span></code> to check if the code is being built
+with <a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>.</p>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(thread_sanitizer)</span></code> to check if the code is being built
+with <a class="reference internal" href="ThreadSanitizer.html"><span class="doc">ThreadSanitizer</span></a>.</p>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(memory_sanitizer)</span></code> to check if the code is being built
+with <a class="reference internal" href="MemorySanitizer.html"><span class="doc">MemorySanitizer</span></a>.</p>
+<p>Use <code class="docutils literal notranslate"><span class="pre">__has_feature(safe_stack)</span></code> to check if the code is being built
+with <a class="reference internal" href="SafeStack.html"><span class="doc">SafeStack</span></a>.</p>
+</div>
+<div class="section" id="extensions-for-selectively-disabling-optimization">
+<h2><a class="toc-backref" href="#id25">Extensions for selectively disabling optimization</a><a class="headerlink" href="#extensions-for-selectively-disabling-optimization" title="Permalink to this headline">¶</a></h2>
+<p>Clang provides a mechanism for selectively disabling optimizations in functions
+and methods.</p>
+<p>To disable optimizations in a single function definition, the GNU-style or C++11
+non-standard attribute <code class="docutils literal notranslate"><span class="pre">optnone</span></code> can be used.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// The following functions will not be optimized.</span>
+<span class="c1">// GNU-style attribute</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">optnone</span><span class="p">))</span> <span class="kt">int</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="c1">// ... code</span>
+<span class="p">}</span>
+<span class="c1">// C++11 attribute</span>
+<span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">optnone</span><span class="p">]]</span> <span class="kt">int</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="c1">// ... code</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>To facilitate disabling optimization for a range of function definitions, a
+range-based pragma is provided. Its syntax is <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">optimize</span></code>
+followed by <code class="docutils literal notranslate"><span class="pre">off</span></code> or <code class="docutils literal notranslate"><span class="pre">on</span></code>.</p>
+<p>All function definitions in the region between an <code class="docutils literal notranslate"><span class="pre">off</span></code> and the following
+<code class="docutils literal notranslate"><span class="pre">on</span></code> will be decorated with the <code class="docutils literal notranslate"><span class="pre">optnone</span></code> attribute unless doing so would
+conflict with explicit attributes already present on the function (e.g. the
+ones that control inlining).</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang optimize off</span>
+<span class="c1">// This function will be decorated with optnone.</span>
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="c1">// ... code</span>
+<span class="p">}</span>
+
+<span class="c1">// optnone conflicts with always_inline, so bar() will not be decorated.</span>
+<span class="n">__attribute__</span><span class="p">((</span><span class="n">always_inline</span><span class="p">))</span> <span class="kt">int</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="c1">// ... code</span>
+<span class="p">}</span>
+<span class="cp">#pragma clang optimize on</span>
+</pre></div>
+</div>
+<p>If no <code class="docutils literal notranslate"><span class="pre">on</span></code> is found to close an <code class="docutils literal notranslate"><span class="pre">off</span></code> region, the end of the region is the
+end of the compilation unit.</p>
+<p>Note that a stray <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">optimize</span> <span class="pre">on</span></code> does not selectively enable
+additional optimizations when compiling at low optimization levels. This feature
+can only be used to selectively disable optimizations.</p>
+<p>The pragma has an effect on functions only at the point of their definition; for
+function templates, this means that the state of the pragma at the point of an
+instantiation is not necessarily relevant. Consider the following example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">T</span> <span class="n">twice</span><span class="p">(</span><span class="n">T</span> <span class="n">t</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">2</span> <span class="o">*</span> <span class="n">t</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="cp">#pragma clang optimize off</span>
+<span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">T</span> <span class="n">thrice</span><span class="p">(</span><span class="n">T</span> <span class="n">t</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">3</span> <span class="o">*</span> <span class="n">t</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="n">container</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">twice</span><span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="o">+</span> <span class="n">thrice</span><span class="p">(</span><span class="n">b</span><span class="p">);</span>
+<span class="p">}</span>
+<span class="cp">#pragma clang optimize on</span>
+</pre></div>
+</div>
+<p>In this example, the definition of the template function <code class="docutils literal notranslate"><span class="pre">twice</span></code> is outside
+the pragma region, whereas the definition of <code class="docutils literal notranslate"><span class="pre">thrice</span></code> is inside the region.
+The <code class="docutils literal notranslate"><span class="pre">container</span></code> function is also in the region and will not be optimized, but
+it causes the instantiation of <code class="docutils literal notranslate"><span class="pre">twice</span></code> and <code class="docutils literal notranslate"><span class="pre">thrice</span></code> with an <code class="docutils literal notranslate"><span class="pre">int</span></code> type; of
+these two instantiations, <code class="docutils literal notranslate"><span class="pre">twice</span></code> will be optimized (because its definition
+was outside the region) and <code class="docutils literal notranslate"><span class="pre">thrice</span></code> will not be optimized.</p>
+</div>
+<div class="section" id="extensions-for-loop-hint-optimizations">
+<h2><a class="toc-backref" href="#id26">Extensions for loop hint optimizations</a><a class="headerlink" href="#extensions-for-loop-hint-optimizations" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span></code> directive is used to specify hints for optimizing the
+subsequent for, while, do-while, or c++11 range-based for loop. The directive
+provides options for vectorization, interleaving, unrolling and
+distribution. Loop hints can be specified before any loop and will be ignored if
+the optimization is not safe to apply.</p>
+<div class="section" id="vectorization-and-interleaving">
+<h3>Vectorization and Interleaving<a class="headerlink" href="#vectorization-and-interleaving" title="Permalink to this headline">¶</a></h3>
+<p>A vectorized loop performs multiple iterations of the original loop
+in parallel using vector instructions. The instruction set of the target
+processor determines which vector instructions are available and their vector
+widths. This restricts the types of loops that can be vectorized. The vectorizer
+automatically determines if the loop is safe and profitable to vectorize. A
+vector instruction cost model is used to select the vector width.</p>
+<p>Interleaving multiple loop iterations allows modern processors to further
+improve instruction-level parallelism (ILP) using advanced hardware features,
+such as multiple execution units and out-of-order execution. The vectorizer uses
+a cost model that depends on the register pressure and generated code size to
+select the interleaving count.</p>
+<p>Vectorization is enabled by <code class="docutils literal notranslate"><span class="pre">vectorize(enable)</span></code> and interleaving is enabled
+by <code class="docutils literal notranslate"><span class="pre">interleave(enable)</span></code>. This is useful when compiling with <code class="docutils literal notranslate"><span class="pre">-Os</span></code> to
+manually enable vectorization or interleaving.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang loop vectorize(enable)</span>
+<span class="cp">#pragma clang loop interleave(enable)</span>
+<span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The vector width is specified by <code class="docutils literal notranslate"><span class="pre">vectorize_width(_value_)</span></code> and the interleave
+count is specified by <code class="docutils literal notranslate"><span class="pre">interleave_count(_value_)</span></code>, where
+_value_ is a positive integer. This is useful for specifying the optimal
+width/count of the set of target architectures supported by your application.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang loop vectorize_width(2)</span>
+<span class="cp">#pragma clang loop interleave_count(2)</span>
+<span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Specifying a width/count of 1 disables the optimization, and is equivalent to
+<code class="docutils literal notranslate"><span class="pre">vectorize(disable)</span></code> or <code class="docutils literal notranslate"><span class="pre">interleave(disable)</span></code>.</p>
+</div>
+<div class="section" id="loop-unrolling">
+<h3>Loop Unrolling<a class="headerlink" href="#loop-unrolling" title="Permalink to this headline">¶</a></h3>
+<p>Unrolling a loop reduces the loop control overhead and exposes more
+opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling
+eliminates the loop and replaces it with an enumerated sequence of loop
+iterations. Full unrolling is only possible if the loop trip count is known at
+compile time. Partial unrolling replicates the loop body within the loop and
+reduces the trip count.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">unroll(enable)</span></code> is specified the unroller will attempt to fully unroll the
+loop if the trip count is known at compile time. If the fully unrolled code size
+is greater than an internal limit the loop will be partially unrolled up to this
+limit. If the trip count is not known at compile time the loop will be partially
+unrolled with a heuristically chosen unroll factor.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang loop unroll(enable)</span>
+<span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If <code class="docutils literal notranslate"><span class="pre">unroll(full)</span></code> is specified the unroller will attempt to fully unroll the
+loop if the trip count is known at compile time identically to
+<code class="docutils literal notranslate"><span class="pre">unroll(enable)</span></code>. However, with <code class="docutils literal notranslate"><span class="pre">unroll(full)</span></code> the loop will not be unrolled
+if the loop count is not known at compile time.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang loop unroll(full)</span>
+<span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The unroll count can be specified explicitly with <code class="docutils literal notranslate"><span class="pre">unroll_count(_value_)</span></code> where
+_value_ is a positive integer. If this value is greater than the trip count the
+loop will be fully unrolled. Otherwise the loop is partially unrolled subject
+to the same code size limit as with <code class="docutils literal notranslate"><span class="pre">unroll(enable)</span></code>.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang loop unroll_count(8)</span>
+<span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Unrolling of a loop can be prevented by specifying <code class="docutils literal notranslate"><span class="pre">unroll(disable)</span></code>.</p>
+</div>
+<div class="section" id="loop-distribution">
+<h3>Loop Distribution<a class="headerlink" href="#loop-distribution" title="Permalink to this headline">¶</a></h3>
+<p>Loop Distribution allows splitting a loop into multiple loops. This is
+beneficial for example when the entire loop cannot be vectorized but some of the
+resulting loops can.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">distribute(enable))</span></code> is specified and the loop has memory dependencies
+that inhibit vectorization, the compiler will attempt to isolate the offending
+operations into a new loop. This optimization is not enabled by default, only
+loops marked with the pragma are considered.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang loop distribute(enable)</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">N</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nl">S1</span><span class="p">:</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+ <span class="nl">S2</span><span class="p">:</span> <span class="n">C</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">D</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*</span> <span class="n">E</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This loop will be split into two loops between statements S1 and S2. The
+second loop containing S2 will be vectorized.</p>
+<p>Loop Distribution is currently not enabled by default in the optimizer because
+it can hurt performance in some cases. For example, instruction-level
+parallelism could be reduced by sequentializing the execution of the
+statements S1 and S2 above.</p>
+<p>If Loop Distribution is turned on globally with
+<code class="docutils literal notranslate"><span class="pre">-mllvm</span> <span class="pre">-enable-loop-distribution</span></code>, specifying <code class="docutils literal notranslate"><span class="pre">distribute(disable)</span></code> can
+be used the disable it on a per-loop basis.</p>
+</div>
+<div class="section" id="additional-information">
+<h3>Additional Information<a class="headerlink" href="#additional-information" title="Permalink to this headline">¶</a></h3>
+<p>For convenience multiple loop hints can be specified on a single line.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang loop vectorize_width(4) interleave_count(8)</span>
+<span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If an optimization cannot be applied any hints that apply to it will be ignored.
+For example, the hint <code class="docutils literal notranslate"><span class="pre">vectorize_width(4)</span></code> is ignored if the loop is not
+proven safe to vectorize. To identify and diagnose optimization issues use
+<cite>-Rpass</cite>, <cite>-Rpass-missed</cite>, and <cite>-Rpass-analysis</cite> command line options. See the
+user guide for details.</p>
+</div>
+</div>
+<div class="section" id="extensions-to-specify-floating-point-flags">
+<h2><a class="toc-backref" href="#id27">Extensions to specify floating-point flags</a><a class="headerlink" href="#extensions-to-specify-floating-point-flags" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">fp</span></code> pragma allows floating-point options to be specified
+for a section of the source code. This pragma can only appear at file scope or
+at the start of a compound statement (excluding comments). When using within a
+compound statement, the pragma is active within the scope of the compound
+statement.</p>
+<p>Currently, only FP contraction can be controlled with the pragma. <code class="docutils literal notranslate"><span class="pre">#pragma</span>
+<span class="pre">clang</span> <span class="pre">fp</span> <span class="pre">contract</span></code> specifies whether the compiler should contract a multiply
+and an addition (or subtraction) into a fused FMA operation when supported by
+the target.</p>
+<p>The pragma can take three values: <code class="docutils literal notranslate"><span class="pre">on</span></code>, <code class="docutils literal notranslate"><span class="pre">fast</span></code> and <code class="docutils literal notranslate"><span class="pre">off</span></code>. The <code class="docutils literal notranslate"><span class="pre">on</span></code>
+option is identical to using <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">STDC</span> <span class="pre">FP_CONTRACT(ON)</span></code> and it allows
+fusion as specified the language standard. The <code class="docutils literal notranslate"><span class="pre">fast</span></code> option allows fusiong
+in cases when the language standard does not make this possible (e.g. across
+statements in C)</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">for</span><span class="p">(...)</span> <span class="p">{</span>
+ <span class="cp">#pragma clang fp contract(fast)</span>
+ <span class="n">a</span> <span class="o">=</span> <span class="n">b</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*</span> <span class="n">c</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+ <span class="n">d</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span> <span class="n">a</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The pragma can also be used with <code class="docutils literal notranslate"><span class="pre">off</span></code> which turns FP contraction off for a
+section of the code. This can be useful when fast contraction is otherwise
+enabled for the translation unit with the <code class="docutils literal notranslate"><span class="pre">-ffp-contract=fast</span></code> flag.</p>
+</div>
+<div class="section" id="specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute">
+<h2><a class="toc-backref" href="#id28">Specifying an attribute for multiple declarations (#pragma clang attribute)</a><a class="headerlink" href="#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code> directive can be used to apply an attribute to
+multiple declarations. The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span> <span class="pre">push</span></code> variation of the
+directive pushes a new âscopeâ of <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code> that attributes
+can be added to. The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span> <span class="pre">(...)</span></code> variation adds an
+attribute to that scope, and the <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span> <span class="pre">pop</span></code> variation pops
+the scope. You can also use <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span> <span class="pre">push</span> <span class="pre">(...)</span></code>, which is a
+shorthand for when you want to add one attribute to a new scope. Multiple push
+directives can be nested inside each other.</p>
+<p>The attributes that are used in the <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code> directives
+can be written using the GNU-style syntax:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang attribute push (__attribute__((annotate("custom"))), apply_to = function)</span>
+
+<span class="kt">void</span> <span class="nf">function</span><span class="p">();</span> <span class="c1">// The function now has the annotate("custom") attribute</span>
+
+<span class="cp">#pragma clang attribute pop</span>
+</pre></div>
+</div>
+<p>The attributes can also be written using the C++11 style syntax:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang attribute push ([[noreturn]], apply_to = function)</span>
+
+<span class="kt">void</span> <span class="nf">function</span><span class="p">();</span> <span class="c1">// The function now has the [[noreturn]] attribute</span>
+
+<span class="cp">#pragma clang attribute pop</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">__declspec</span></code> style syntax is also supported:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang attribute push (__declspec(dllexport), apply_to = function)</span>
+
+<span class="kt">void</span> <span class="nf">function</span><span class="p">();</span> <span class="c1">// The function now has the __declspec(dllexport) attribute</span>
+
+<span class="cp">#pragma clang attribute pop</span>
+</pre></div>
+</div>
+<p>A single push directive accepts only one attribute regardless of the syntax
+used.</p>
+<p>Because multiple push directives can be nested, if youâre writing a macro that
+expands to <code class="docutils literal notranslate"><span class="pre">_Pragma("clang</span> <span class="pre">attribute")</span></code> itâs good hygiene (though not
+required) to add a namespace to your push/pop directives. A pop directive with a
+namespace will pop the innermost push that has that same namespace. This will
+ensure that another macroâs <code class="docutils literal notranslate"><span class="pre">pop</span></code> wonât inadvertently pop your attribute. Note
+that an <code class="docutils literal notranslate"><span class="pre">pop</span></code> without a namespace will pop the innermost <code class="docutils literal notranslate"><span class="pre">push</span></code> without a
+namespace. <code class="docutils literal notranslate"><span class="pre">push``es</span> <span class="pre">with</span> <span class="pre">a</span> <span class="pre">namespace</span> <span class="pre">can</span> <span class="pre">only</span> <span class="pre">be</span> <span class="pre">popped</span> <span class="pre">by</span> <span class="pre">``pop</span></code> with the
+same namespace. For instance:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#define ASSUME_NORETURN_BEGIN _Pragma("clang attribute AssumeNoreturn.push ([[noreturn]], apply_to = function)")</span>
+<span class="cp">#define ASSUME_NORETURN_END _Pragma("clang attribute AssumeNoreturn.pop")</span>
+
+<span class="cp">#define ASSUME_UNAVAILABLE_BEGIN _Pragma("clang attribute Unavailable.push (__attribute__((unavailable)), apply_to=function)")</span>
+<span class="cp">#define ASSUME_UNAVAILABLE_END _Pragma("clang attribute Unavailable.pop")</span>
+
+
+<span class="n">ASSUME_NORETURN_BEGIN</span>
+<span class="n">ASSUME_UNAVAILABLE_BEGIN</span>
+<span class="kt">void</span> <span class="nf">function</span><span class="p">();</span> <span class="c1">// function has [[noreturn]] and __attribute__((unavailable))</span>
+<span class="n">ASSUME_NORETURN_END</span>
+<span class="kt">void</span> <span class="nf">other_function</span><span class="p">();</span> <span class="c1">// function has __attribute__((unavailable))</span>
+<span class="n">ASSUME_UNAVAILABLE_END</span>
+</pre></div>
+</div>
+<p>Without the namespaces on the macros, <code class="docutils literal notranslate"><span class="pre">other_function</span></code> will be annotated with
+<code class="docutils literal notranslate"><span class="pre">[[noreturn]]</span></code> instead of <code class="docutils literal notranslate"><span class="pre">__attribute__((unavailable))</span></code>. This may seem like
+a contrived example, but its very possible for this kind of situation to appear
+in real code if the pragmas are spread out across a large file. You can test if
+your version of clang supports namespaces on <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code> with
+<code class="docutils literal notranslate"><span class="pre">__has_extension(pragma_clang_attribute_namespaces)</span></code>.</p>
+<div class="section" id="subject-match-rules">
+<h3>Subject Match Rules<a class="headerlink" href="#subject-match-rules" title="Permalink to this headline">¶</a></h3>
+<p>The set of declarations that receive a single attribute from the attribute stack
+depends on the subject match rules that were specified in the pragma. Subject
+match rules are specified after the attribute. The compiler expects an
+identifier that corresponds to the subject set specifier. The <code class="docutils literal notranslate"><span class="pre">apply_to</span></code>
+specifier is currently the only supported subject set specifier. It allows you
+to specify match rules that form a subset of the attributeâs allowed subject
+set, i.e. the compiler doesnât require all of the attributeâs subjects. For
+example, an attribute like <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> whose subject set includes
+<code class="docutils literal notranslate"><span class="pre">enum</span></code>, <code class="docutils literal notranslate"><span class="pre">record</span></code> and <code class="docutils literal notranslate"><span class="pre">hasType(functionType)</span></code>, requires the presence of at
+least one of these rules after <code class="docutils literal notranslate"><span class="pre">apply_to</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang attribute push([[nodiscard]], apply_to = enum)</span>
+
+<span class="k">enum</span> <span class="n">Enum1</span> <span class="p">{</span> <span class="n">A1</span><span class="p">,</span> <span class="n">B1</span> <span class="p">};</span> <span class="c1">// The enum will receive [[nodiscard]]</span>
+
+<span class="k">struct</span> <span class="n">Record1</span> <span class="p">{</span> <span class="p">};</span> <span class="c1">// The struct will *not* receive [[nodiscard]]</span>
+
+<span class="cp">#pragma clang attribute pop</span>
+
+<span class="cp">#pragma clang attribute push([[nodiscard]], apply_to = any(record, enum))</span>
+
+<span class="k">enum</span> <span class="n">Enum2</span> <span class="p">{</span> <span class="n">A2</span><span class="p">,</span> <span class="n">B2</span> <span class="p">};</span> <span class="c1">// The enum will receive [[nodiscard]]</span>
+
+<span class="k">struct</span> <span class="n">Record2</span> <span class="p">{</span> <span class="p">};</span> <span class="c1">// The struct *will* receive [[nodiscard]]</span>
+
+<span class="cp">#pragma clang attribute pop</span>
+
+<span class="c1">// This is an error, since [[nodiscard]] can't be applied to namespaces:</span>
+<span class="cp">#pragma clang attribute push([[nodiscard]], apply_to = any(record, namespace))</span>
+
+<span class="cp">#pragma clang attribute pop</span>
+</pre></div>
+</div>
+<p>Multiple match rules can be specified using the <code class="docutils literal notranslate"><span class="pre">any</span></code> match rule, as shown
+in the example above. The <code class="docutils literal notranslate"><span class="pre">any</span></code> rule applies attributes to all declarations
+that are matched by at least one of the rules in the <code class="docutils literal notranslate"><span class="pre">any</span></code>. It doesnât nest
+and canât be used inside the other match rules. Redundant match rules or rules
+that conflict with one another should not be used inside of <code class="docutils literal notranslate"><span class="pre">any</span></code>.</p>
+<p>Clang supports the following match rules:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">function</span></code>: Can be used to apply attributes to functions. This includes C++
+member functions, static functions, operators, and constructors/destructors.</li>
+<li><code class="docutils literal notranslate"><span class="pre">function(is_member)</span></code>: Can be used to apply attributes to C++ member
+functions. This includes members like static functions, operators, and
+constructors/destructors.</li>
+<li><code class="docutils literal notranslate"><span class="pre">hasType(functionType)</span></code>: Can be used to apply attributes to functions, C++
+member functions, and variables/fields whose type is a function pointer. It
+does not apply attributes to Objective-C methods or blocks.</li>
+<li><code class="docutils literal notranslate"><span class="pre">type_alias</span></code>: Can be used to apply attributes to <code class="docutils literal notranslate"><span class="pre">typedef</span></code> declarations
+and C++11 type aliases.</li>
+<li><code class="docutils literal notranslate"><span class="pre">record</span></code>: Can be used to apply attributes to <code class="docutils literal notranslate"><span class="pre">struct</span></code>, <code class="docutils literal notranslate"><span class="pre">class</span></code>, and
+<code class="docutils literal notranslate"><span class="pre">union</span></code> declarations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">record(unless(is_union))</span></code>: Can be used to apply attributes only to
+<code class="docutils literal notranslate"><span class="pre">struct</span></code> and <code class="docutils literal notranslate"><span class="pre">class</span></code> declarations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">enum</span></code>: Can be be used to apply attributes to enumeration declarations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">enum_constant</span></code>: Can be used to apply attributes to enumerators.</li>
+<li><code class="docutils literal notranslate"><span class="pre">variable</span></code>: Can be used to apply attributes to variables, including
+local variables, parameters, global variables, and static member variables.
+It does not apply attributes to instance member variables or Objective-C
+ivars.</li>
+<li><code class="docutils literal notranslate"><span class="pre">variable(is_thread_local)</span></code>: Can be used to apply attributes to thread-local
+variables only.</li>
+<li><code class="docutils literal notranslate"><span class="pre">variable(is_global)</span></code>: Can be used to apply attributes to global variables
+only.</li>
+<li><code class="docutils literal notranslate"><span class="pre">variable(is_parameter)</span></code>: Can be used to apply attributes to parameters
+only.</li>
+<li><code class="docutils literal notranslate"><span class="pre">variable(unless(is_parameter))</span></code>: Can be used to apply attributes to all
+the variables that are not parameters.</li>
+<li><code class="docutils literal notranslate"><span class="pre">field</span></code>: Can be used to apply attributes to non-static member variables
+in a record. This includes Objective-C ivars.</li>
+<li><code class="docutils literal notranslate"><span class="pre">namespace</span></code>: Can be used to apply attributes to <code class="docutils literal notranslate"><span class="pre">namespace</span></code> declarations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">objc_interface</span></code>: Can be used to apply attributes to <code class="docutils literal notranslate"><span class="pre">@interface</span></code>
+declarations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">objc_protocol</span></code>: Can be used to apply attributes to <code class="docutils literal notranslate"><span class="pre">@protocol</span></code>
+declarations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">objc_category</span></code>: Can be used to apply attributes to category declarations,
+including class extensions.</li>
+<li><code class="docutils literal notranslate"><span class="pre">objc_method</span></code>: Can be used to apply attributes to Objective-C methods,
+including instance and class methods. Implicit methods like implicit property
+getters and setters do not receive the attribute.</li>
+<li><code class="docutils literal notranslate"><span class="pre">objc_method(is_instance)</span></code>: Can be used to apply attributes to Objective-C
+instance methods.</li>
+<li><code class="docutils literal notranslate"><span class="pre">objc_property</span></code>: Can be used to apply attributes to <code class="docutils literal notranslate"><span class="pre">@property</span></code>
+declarations.</li>
+<li><code class="docutils literal notranslate"><span class="pre">block</span></code>: Can be used to apply attributes to block declarations. This does
+not include variables/fields of block pointer type.</li>
+</ul>
+<p>The use of <code class="docutils literal notranslate"><span class="pre">unless</span></code> in match rules is currently restricted to a strict set of
+sub-rules that are used by the supported attributes. That means that even though
+<code class="docutils literal notranslate"><span class="pre">variable(unless(is_parameter))</span></code> is a valid match rule,
+<code class="docutils literal notranslate"><span class="pre">variable(unless(is_thread_local))</span></code> is not.</p>
+</div>
+<div class="section" id="supported-attributes">
+<h3>Supported Attributes<a class="headerlink" href="#supported-attributes" title="Permalink to this headline">¶</a></h3>
+<p>Not all attributes can be used with the <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">attribute</span></code> directive.
+Notably, statement attributes like <code class="docutils literal notranslate"><span class="pre">[[fallthrough]]</span></code> or type attributes
+like <code class="docutils literal notranslate"><span class="pre">address_space</span></code> arenât supported by this directive. You can determine
+whether or not an attribute is supported by the pragma by referring to the
+<a class="reference internal" href="AttributeReference.html"><span class="doc">individual documentation for that attribute</span></a>.</p>
+<p>The attributes are applied to all matching declarations individually, even when
+the attribute is semantically incorrect. The attributes that arenât applied to
+any declaration are not verified semantically.</p>
+</div>
+</div>
+<div class="section" id="specifying-section-names-for-global-objects-pragma-clang-section">
+<h2><a class="toc-backref" href="#id29">Specifying section names for global objects (#pragma clang section)</a><a class="headerlink" href="#specifying-section-names-for-global-objects-pragma-clang-section" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">section</span></code> directive provides a means to assign section-names
+to global variables, functions and static variables.</p>
+<p>The section names can be specified as:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang section bss="myBSS" data="myData" rodata="myRodata" text="myText"</span>
+</pre></div>
+</div>
+<p>The section names can be reverted back to default name by supplying an empty
+string to the section kind, for example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma clang section bss="" data="" text="" rodata=""</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">section</span></code> directive obeys the following rules:</p>
+<ul class="simple">
+<li>The pragma applies to all global variable, statics and function declarations
+from the pragma to the end of the translation unit.</li>
+<li>The pragma clang section is enabled automatically, without need of any flags.</li>
+<li>This feature is only defined to work sensibly for ELF targets.</li>
+<li>If section name is specified through _attribute_((section(âmynameâ))), then
+the attribute name gains precedence.</li>
+<li>Global variables that are initialized to zero will be placed in the named
+bss section, if one is present.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">section</span></code> directive does not does try to infer section-kind
+from the name. For example, naming a section â<code class="docutils literal notranslate"><span class="pre">.bss.mySec</span></code>â does NOT mean
+it will be a bss section name.</li>
+<li>The decision about which section-kind applies to each global is taken in the back-end.
+Once the section-kind is known, appropriate section name, as specified by the user using
+<code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">section</span></code> directive, is applied to that global.</li>
+</ul>
+</div>
+<div class="section" id="specifying-linker-options-on-elf-targets">
+<h2><a class="toc-backref" href="#id30">Specifying Linker Options on ELF Targets</a><a class="headerlink" href="#specifying-linker-options-on-elf-targets" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">comment(lib,</span> <span class="pre">...)</span></code> directive is supported on all ELF targets.
+The second parameter is the library name (without the traditional Unix prefix of
+<code class="docutils literal notranslate"><span class="pre">lib</span></code>). This allows you to provide an implicit link of dependent libraries.</p>
+</div>
+<div class="section" id="evaluating-object-size-dynamically">
+<h2><a class="toc-backref" href="#id31">Evaluating Object Size Dynamically</a><a class="headerlink" href="#evaluating-object-size-dynamically" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports the builtin <code class="docutils literal notranslate"><span class="pre">__builtin_dynamic_object_size</span></code>, the semantics are
+the same as GCCâs <code class="docutils literal notranslate"><span class="pre">__builtin_object_size</span></code> (which Clang also supports), but
+<code class="docutils literal notranslate"><span class="pre">__builtin_dynamic_object_size</span></code> can evaluate the objectâs size at runtime.
+<code class="docutils literal notranslate"><span class="pre">__builtin_dynamic_object_size</span></code> is meant to be used as a drop-in replacement
+for <code class="docutils literal notranslate"><span class="pre">__builtin_object_size</span></code> in libraries that support it.</p>
+<p>For instance, here is a program that <code class="docutils literal notranslate"><span class="pre">__builtin_dynamic_object_size</span></code> will make
+safer:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">copy_into_buffer</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">char</span><span class="o">*</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">malloc</span><span class="p">(</span><span class="n">size</span><span class="p">);</span>
+ <span class="n">strlcpy</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="s">"some string"</span><span class="p">,</span> <span class="n">strlen</span><span class="p">(</span><span class="s">"some string"</span><span class="p">));</span>
+ <span class="c1">// Previous line preprocesses to:</span>
+ <span class="c1">// __builtin___strlcpy_chk(buffer, "some string", strlen("some string"), __builtin_object_size(buffer, 0))</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Since the size of <code class="docutils literal notranslate"><span class="pre">buffer</span></code> canât be known at compile time, Clang will fold
+<code class="docutils literal notranslate"><span class="pre">__builtin_object_size(buffer,</span> <span class="pre">0)</span></code> into <code class="docutils literal notranslate"><span class="pre">-1</span></code>. However, if this was written
+as <code class="docutils literal notranslate"><span class="pre">__builtin_dynamic_object_size(buffer,</span> <span class="pre">0)</span></code>, Clang will fold it into
+<code class="docutils literal notranslate"><span class="pre">size</span></code>, providing some extra runtime safety.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="Toolchain.html">Assembling a Complete Toolchain</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ObjectiveCLiterals.html">Objective-C Literals</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/LeakSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/LeakSanitizer.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/LeakSanitizer.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/LeakSanitizer.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,108 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>LeakSanitizer — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="SanitizerCoverage" href="SanitizerCoverage.html" />
+ <link rel="prev" title="DataFlowSanitizer Design Document" href="DataFlowSanitizerDesign.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>LeakSanitizer</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="DataFlowSanitizerDesign.html">DataFlowSanitizer Design Document</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerCoverage.html">SanitizerCoverage</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="leaksanitizer">
+<h1>LeakSanitizer<a class="headerlink" href="#leaksanitizer" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#usage" id="id2">Usage</a></li>
+<li><a class="reference internal" href="#more-information" id="id3">More Information</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>LeakSanitizer is a run-time memory leak detector. It can be combined with
+<a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a> to get both memory error and leak detection, or
+used in a stand-alone mode. LSan adds almost no performance overhead
+until the very end of the process, at which point there is an extra leak
+detection phase.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id2">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>LeakSanitizer is supported on x86_64 Linux and macOS. In order to use it,
+simply build your program with <a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> cat memory-leak.c
+<span class="gp">#</span>include <stdlib.h>
+<span class="go">void *p;</span>
+<span class="go">int main() {</span>
+<span class="go"> p = malloc(7);</span>
+<span class="go"> p = 0; // The memory is leaked here.</span>
+<span class="go"> return 0;</span>
+<span class="go">}</span>
+<span class="gp">%</span> clang -fsanitize<span class="o">=</span>address -g memory-leak.c <span class="p">;</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">detect_leaks</span><span class="o">=</span><span class="m">1</span> ./a.out
+<span class="go">==23646==ERROR: LeakSanitizer: detected memory leaks</span>
+<span class="go">Direct leak of 7 byte(s) in 1 object(s) allocated from:</span>
+<span class="gp"> #</span><span class="m">0</span> 0x4af01b in __interceptor_malloc /projects/compiler-rt/lib/asan/asan_malloc_linux.cc:52:3
+<span class="gp"> #</span><span class="m">1</span> 0x4da26a in main memory-leak.c:4:7
+<span class="gp"> #</span><span class="m">2</span> 0x7f076fd9cec4 in __libc_start_main libc-start.c:287
+<span class="go">SUMMARY: AddressSanitizer: 7 byte(s) leaked in 1 allocation(s).</span>
+</pre></div>
+</div>
+<p>To use LeakSanitizer in stand-alone mode, link your program with
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=leak</span></code> flag. Make sure to use <code class="docutils literal notranslate"><span class="pre">clang</span></code> (not <code class="docutils literal notranslate"><span class="pre">ld</span></code>) for the
+link step, so that it would link in proper LeakSanitizer run-time library
+into the final executable.</p>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id3">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer</a></p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="DataFlowSanitizerDesign.html">DataFlowSanitizer Design Document</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerCoverage.html">SanitizerCoverage</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/LibASTMatchers.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/LibASTMatchers.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/LibASTMatchers.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/LibASTMatchers.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,157 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Matching the Clang AST — Clang 9 documentation</title>
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="How To Setup Clang Tooling For LLVM" href="HowToSetupToolingForLLVM.html" />
+ <link rel="prev" title="Tutorial for building tools using LibTooling and LibASTMatchers" href="LibASTMatchersTutorial.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Matching the Clang AST</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="matching-the-clang-ast">
+<h1>Matching the Clang AST<a class="headerlink" href="#matching-the-clang-ast" title="Permalink to this headline">¶</a></h1>
+<p>This document explains how to use Clangâs LibASTMatchers to match interesting
+nodes of the AST and execute code that uses the matched nodes. Combined with
+<a class="reference internal" href="LibTooling.html"><span class="doc">LibTooling</span></a>, LibASTMatchers helps to write code-to-code transformation
+tools or query tools.</p>
+<p>We assume basic knowledge about the Clang AST. See the <a class="reference internal" href="IntroductionToTheClangAST.html"><span class="doc">Introduction
+to the Clang AST</span></a> if you want to learn more
+about how the AST is structured.</p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>LibASTMatchers provides a domain specific language to create predicates on
+Clangâs AST. This DSL is written in and can be used from C++, allowing users
+to write a single program to both match AST nodes and access the nodeâs C++
+interface to extract attributes, source locations, or any other information
+provided on the AST level.</p>
+<p>AST matchers are predicates on nodes in the AST. Matchers are created by
+calling creator functions that allow building up a tree of matchers, where
+inner matchers are used to make the match more specific.</p>
+<p>For example, to create a matcher that matches all class or union declarations
+in the AST of a translation unit, you can call <a class="reference external" href="LibASTMatchersReference.html#recordDecl0Anchor">recordDecl()</a>. To narrow the match down,
+for example to find all class or union declarations with the name â<code class="docutils literal notranslate"><span class="pre">Foo</span></code>â,
+insert a <a class="reference external" href="LibASTMatchersReference.html#hasName0Anchor">hasName</a> matcher: the
+call <code class="docutils literal notranslate"><span class="pre">recordDecl(hasName("Foo"))</span></code> returns a matcher that matches classes or
+unions that are named â<code class="docutils literal notranslate"><span class="pre">Foo</span></code>â, in any namespace. By default, matchers that
+accept multiple inner matchers use an implicit <a class="reference external" href="LibASTMatchersReference.html#allOf0Anchor">allOf()</a>. This allows further narrowing
+down the match, for example to match all classes that are derived from
+â<code class="docutils literal notranslate"><span class="pre">Bar</span></code>â: <code class="docutils literal notranslate"><span class="pre">recordDecl(hasName("Foo"),</span> <span class="pre">isDerivedFrom("Bar"))</span></code>.</p>
+</div>
+<div class="section" id="how-to-create-a-matcher">
+<h2>How to create a matcher<a class="headerlink" href="#how-to-create-a-matcher" title="Permalink to this headline">¶</a></h2>
+<p>With more than a thousand classes in the Clang AST, one can quickly get lost
+when trying to figure out how to create a matcher for a specific pattern. This
+section will teach you how to use a rigorous step-by-step pattern to build the
+matcher you are interested in. Note that there will always be matchers missing
+for some part of the AST. See the section about <a class="reference internal" href="#astmatchers-writing"><span class="std std-ref">how to write your own
+AST matchers</span></a> later in this document.</p>
+<p>The precondition to using the matchers is to understand how the AST for what you
+want to match looks like. The
+<a class="reference internal" href="IntroductionToTheClangAST.html"><span class="doc">Introduction to the Clang AST</span></a> teaches you
+how to dump a translation unitâs AST into a human readable format.</p>
+<p>In general, the strategy to create the right matchers is:</p>
+<ol class="arabic simple">
+<li>Find the outermost class in Clangâs AST you want to match.</li>
+<li>Look at the <a class="reference external" href="LibASTMatchersReference.html">AST Matcher Reference</a> for
+matchers that either match the node youâre interested in or narrow down
+attributes on the node.</li>
+<li>Create your outer match expression. Verify that it works as expected.</li>
+<li>Examine the matchers for what the next inner node you want to match is.</li>
+<li>Repeat until the matcher is finished.</li>
+</ol>
+</div>
+<div class="section" id="binding-nodes-in-match-expressions">
+<span id="astmatchers-bind"></span><h2>Binding nodes in match expressions<a class="headerlink" href="#binding-nodes-in-match-expressions" title="Permalink to this headline">¶</a></h2>
+<p>Matcher expressions allow you to specify which parts of the AST are interesting
+for a certain task. Often you will want to then do something with the nodes
+that were matched, like building source code transformations.</p>
+<p>To that end, matchers that match specific AST nodes (so called node matchers)
+are bindable; for example, <code class="docutils literal notranslate"><span class="pre">recordDecl(hasName("MyClass")).bind("id")</span></code> will
+bind the matched <code class="docutils literal notranslate"><span class="pre">recordDecl</span></code> node to the string â<code class="docutils literal notranslate"><span class="pre">id</span></code>â, to be later
+retrieved in the <a class="reference external" href="https://clang.llvm.org/doxygen/classclang_1_1ast__matchers_1_1MatchFinder_1_1MatchCallback.html">match callback</a>.</p>
+</div>
+<div class="section" id="writing-your-own-matchers">
+<h2>Writing your own matchers<a class="headerlink" href="#writing-your-own-matchers" title="Permalink to this headline">¶</a></h2>
+<p>There are multiple different ways to define a matcher, depending on its type
+and flexibility.</p>
+<div class="section" id="variadicdyncastallofmatcher-base-derived">
+<h3><code class="docutils literal notranslate"><span class="pre">VariadicDynCastAllOfMatcher<Base,</span> <span class="pre">Derived></span></code><a class="headerlink" href="#variadicdyncastallofmatcher-base-derived" title="Permalink to this headline">¶</a></h3>
+<p>Those match all nodes of type <em>Base</em> if they can be dynamically casted to
+<em>Derived</em>. The names of those matchers are nouns, which closely resemble
+<em>Derived</em>. <code class="docutils literal notranslate"><span class="pre">VariadicDynCastAllOfMatchers</span></code> are the backbone of the matcher
+hierarchy. Most often, your match expression will start with one of them, and
+you can <a class="reference internal" href="#astmatchers-bind"><span class="std std-ref">bind</span></a> the node they represent to ids for later
+processing.</p>
+<p><code class="docutils literal notranslate"><span class="pre">VariadicDynCastAllOfMatchers</span></code> are callable classes that model variadic
+template functions in C++03. They take an arbitrary number of
+<code class="docutils literal notranslate"><span class="pre">Matcher<Derived></span></code> and return a <code class="docutils literal notranslate"><span class="pre">Matcher<Base></span></code>.</p>
+</div>
+<div class="section" id="ast-matcher-p-type-name-paramtype-param">
+<h3><code class="docutils literal notranslate"><span class="pre">AST_MATCHER_P(Type,</span> <span class="pre">Name,</span> <span class="pre">ParamType,</span> <span class="pre">Param)</span></code><a class="headerlink" href="#ast-matcher-p-type-name-paramtype-param" title="Permalink to this headline">¶</a></h3>
+<p>Most matcher definitions use the matcher creation macros. Those define both
+the matcher of type <code class="docutils literal notranslate"><span class="pre">Matcher<Type></span></code> itself, and a matcher-creation function
+named <em>Name</em> that takes a parameter of type <em>ParamType</em> and returns the
+corresponding matcher.</p>
+<p>There are multiple matcher definition macros that deal with polymorphic return
+values and different parameter counts. See <a class="reference external" href="https://clang.llvm.org/doxygen/ASTMatchersMacros_8h.html">ASTMatchersMacros.h</a>.</p>
+</div>
+<div class="section" id="matcher-creation-functions">
+<span id="astmatchers-writing"></span><h3>Matcher creation functions<a class="headerlink" href="#matcher-creation-functions" title="Permalink to this headline">¶</a></h3>
+<p>Matchers are generated by nesting calls to matcher creation functions. Most of
+the time those functions are either created by using
+<code class="docutils literal notranslate"><span class="pre">VariadicDynCastAllOfMatcher</span></code> or the matcher creation macros (see below).
+The free-standing functions are an indication that this matcher is just a
+combination of other matchers, as is for example the case with <a class="reference external" href="LibASTMatchersReference.html#callee1Anchor">callee</a>.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list