[www-releases] r246586 - Commit 3.7.0

Tue Sep 1 13:55:36 PDT 2015

Added: www-releases/trunk/3.7.0/tools/clang/docs/LanguageExtensions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/LanguageExtensions.html?rev=246586&view=auto
==============================================================================

--- www-releases/trunk/3.7.0/tools/clang/docs/LanguageExtensions.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/LanguageExtensions.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,1868 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Clang Language Extensions — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Objective-C Literals" href="ObjectiveCLiterals.html" />
+    <link rel="prev" title="Clang Compiler Userâs Manual" href="UsersManual.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang Language Extensions</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="UsersManual.html">Clang Compiler User’s Manual</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="id1">Introduction</a></li>
+<li><a class="reference internal" href="#feature-checking-macros" id="id2">Feature Checking Macros</a></li>
+<li><a class="reference internal" href="#include-file-checking-macros" id="id3">Include File Checking Macros</a></li>
+<li><a class="reference internal" href="#builtin-macros" id="id4">Builtin Macros</a></li>
+<li><a class="reference internal" href="#vectors-and-extended-vectors" id="id5">Vectors and Extended Vectors</a></li>
+<li><a class="reference internal" href="#messages-on-deprecated-and-unavailable-attributes" id="id6">Messages on <tt class="docutils literal"><span class="pre">deprecated</span></tt> and <tt class="docutils literal"><span class="pre">unavailable</span></tt> Attributes</a></li>
+<li><a class="reference internal" href="#attributes-on-enumerators" id="id7">Attributes on Enumerators</a></li>
+<li><a class="reference internal" href="#user-specified-system-frameworks" id="id8">‘User-Specified’ System Frameworks</a></li>
+<li><a class="reference internal" href="#checks-for-standard-language-features" id="id9">Checks for Standard Language Features</a></li>
+<li><a class="reference internal" href="#checks-for-type-trait-primitives" id="id10">Checks for Type Trait Primitives</a></li>
+<li><a class="reference internal" href="#blocks" id="id11">Blocks</a></li>
+<li><a class="reference internal" href="#objective-c-features" id="id12">Objective-C Features</a></li>
+<li><a class="reference internal" href="#initializer-lists-for-complex-numbers-in-c" id="id13">Initializer lists for complex numbers in C</a></li>
+<li><a class="reference internal" href="#builtin-functions" id="id14">Builtin Functions</a></li>
+<li><a class="reference internal" href="#non-standard-c-11-attributes" id="id15">Non-standard C++11 Attributes</a></li>
+<li><a class="reference internal" href="#target-specific-extensions" id="id16">Target-Specific Extensions</a></li>
+<li><a class="reference internal" href="#extensions-for-static-analysis" id="id17">Extensions for Static Analysis</a></li>
+<li><a class="reference internal" href="#extensions-for-dynamic-analysis" id="id18">Extensions for Dynamic Analysis</a></li>
+<li><a class="reference internal" href="#extensions-for-selectively-disabling-optimization" id="id19">Extensions for selectively disabling optimization</a></li>
+<li><a class="reference internal" href="#extensions-for-loop-hint-optimizations" id="id20">Extensions for loop hint optimizations</a></li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</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>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="http://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="#id2">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><tt class="docutils literal"><span class="pre">__has_builtin</span></tt><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++"><div class="highlight"><pre>#ifndef __has_builtin         // Optional of course.
+  #define __has_builtin(x) 0  // Compatibility with non-clang compilers.
+#endif
+
+...
+#if __has_builtin(__builtin_trap)
+  __builtin_trap();
+#else
+  abort();
+#endif
+...
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-feature-and-has-extension">
+<span id="langext-has-feature-has-extension"></span><h3><tt class="docutils literal"><span class="pre">__has_feature</span></tt> and <tt class="docutils literal"><span class="pre">__has_extension</span></tt><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.  <tt class="docutils literal"><span class="pre">__has_feature</span></tt> 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"><em>below</em></a>), while
+<tt class="docutils literal"><span class="pre">__has_extension</span></tt> 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++"><div class="highlight"><pre>#ifndef __has_feature         // Optional of course.
+  #define __has_feature(x) 0  // Compatibility with non-clang compilers.
+#endif
+#ifndef __has_extension
+  #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
+#endif
+
+...
+#if __has_feature(cxx_rvalue_references)
+// This code will only be compiled with the -std=c++11 and -std=gnu++11
+// options, because rvalue references are only standardized in C++11.
+#endif
+
+#if __has_extension(cxx_rvalue_references)
+// This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
+// and -std=gnu++98 options, because rvalue references are supported as a
+// language extension in C++98.
+#endif
+</pre></div>
+</div>
+<p id="langext-has-feature-back-compat">For backward compatibility, <tt class="docutils literal"><span class="pre">__has_feature</span></tt> can also be used to test
+for support for non-standardized features, i.e. features not prefixed <tt class="docutils literal"><span class="pre">c_</span></tt>,
+<tt class="docutils literal"><span class="pre">cxx_</span></tt> or <tt class="docutils literal"><span class="pre">objc_</span></tt>.</p>
+<p>Another use of <tt class="docutils literal"><span class="pre">__has_feature</span></tt> is to check for compiler features not related
+to the language standard, such as e.g. <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>.</p>
+<p>If the <tt class="docutils literal"><span class="pre">-pedantic-errors</span></tt> option is given, <tt class="docutils literal"><span class="pre">__has_extension</span></tt> is equivalent
+to <tt class="docutils literal"><span class="pre">__has_feature</span></tt>.</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 <tt class="docutils literal"><span class="pre">__</span></tt> (double underscore) to avoid interference from a macro with
+the same name.  For instance, <tt class="docutils literal"><span class="pre">__cxx_rvalue_references__</span></tt> can be used instead
+of <tt class="docutils literal"><span class="pre">cxx_rvalue_references</span></tt>.</p>
+</div>
+<div class="section" id="has-cpp-attribute">
+<h3><tt class="docutils literal"><span class="pre">__has_cpp_attribute</span></tt><a class="headerlink" href="#has-cpp-attribute" title="Permalink to this headline">Â¶</a></h3>
+<p>This function-like macro takes a single argument that is the name of a
+C++11-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. 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++"><div class="highlight"><pre>#ifndef __has_cpp_attribute         // Optional of course.
+  #define __has_cpp_attribute(x) 0  // Compatibility with non-clang compilers.
+#endif
+
+...
+#if __has_cpp_attribute(clang::fallthrough)
+#define FALLTHROUGH [[clang::fallthrough]]
+#else
+#define FALLTHROUGH
+#endif
+...
+</pre></div>
+</div>
+<p>The attribute identifier (but not scope) can also be specified with a preceding
+and following <tt class="docutils literal"><span class="pre">__</span></tt> (double underscore) to avoid interference from a macro with
+the same name.  For instance, <tt class="docutils literal"><span class="pre">gnu::__const__</span></tt> can be used instead of
+<tt class="docutils literal"><span class="pre">gnu::const</span></tt>.</p>
+</div>
+<div class="section" id="has-attribute">
+<h3><tt class="docutils literal"><span class="pre">__has_attribute</span></tt><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++"><div class="highlight"><pre>#ifndef __has_attribute         // Optional of course.
+  #define __has_attribute(x) 0  // Compatibility with non-clang compilers.
+#endif
+
+...
+#if __has_attribute(always_inline)
+#define ALWAYS_INLINE __attribute__((always_inline))
+#else
+#define ALWAYS_INLINE
+#endif
+...
+</pre></div>
+</div>
+<p>The attribute name can also be specified with a preceding and following <tt class="docutils literal"><span class="pre">__</span></tt>
+(double underscore) to avoid interference from a macro with the same name.  For
+instance, <tt class="docutils literal"><span class="pre">__always_inline__</span></tt> can be used instead of <tt class="docutils literal"><span class="pre">always_inline</span></tt>.</p>
+</div>
+<div class="section" id="has-declspec-attribute">
+<h3><tt class="docutils literal"><span class="pre">__has_declspec_attribute</span></tt><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 <tt class="docutils literal"><span class="pre">__declspec</span></tt> 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++"><div class="highlight"><pre>#ifndef __has_declspec_attribute         // Optional of course.
+  #define __has_declspec_attribute(x) 0  // Compatibility with non-clang compilers.
+#endif
+
+...
+#if __has_declspec_attribute(dllexport)
+#define DLLEXPORT __declspec(dllexport)
+#else
+#define DLLEXPORT
+#endif
+...
+</pre></div>
+</div>
+<p>The attribute name can also be specified with a preceding and following <tt class="docutils literal"><span class="pre">__</span></tt>
+(double underscore) to avoid interference from a macro with the same name.  For
+instance, <tt class="docutils literal"><span class="pre">__dllexport__</span></tt> can be used instead of <tt class="docutils literal"><span class="pre">dllexport</span></tt>.</p>
+</div>
+<div class="section" id="is-identifier">
+<h3><tt class="docutils literal"><span class="pre">__is_identifier</span></tt><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++"><div class="highlight"><pre>...
+#ifdef __is_identifier          // Compatibility with non-clang compilers.
+  #if __is_identifier(__wchar_t)
+    typedef wchar_t __wchar_t;
+  #endif
+#endif
+
+__wchar_t WideCharacter;
+...
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="include-file-checking-macros">
+<h2><a class="toc-backref" href="#id3">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"><em>__has_include</em></a> and <a class="reference internal" href="#langext-has-include-next"><em>__has_include_next</em></a> macros allow
+you to check for the existence of an include file before doing a possibly
+failing <tt class="docutils literal"><span class="pre">#include</span></tt> directive.  Include file checking macros must be used
+as expressions in <tt class="docutils literal"><span class="pre">#if</span></tt> or <tt class="docutils literal"><span class="pre">#elif</span></tt> preprocessing directives.</p>
+<div class="section" id="has-include">
+<span id="langext-has-include"></span><h3><tt class="docutils literal"><span class="pre">__has_include</span></tt><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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">#if</span> <span class="pre">defined(__has_include)</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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><tt class="docutils literal"><span class="pre">__has_include_next</span></tt><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 <tt class="docutils literal"><span class="pre">__has_include</span></tt> 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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">__has_include_next</span></tt>, like the GNU extension <tt class="docutils literal"><span class="pre">#include_next</span></tt>
+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><tt class="docutils literal"><span class="pre">__has_warning</span></tt><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++"><div class="highlight"><pre><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">
+<h2><a class="toc-backref" href="#id4">Builtin Macros</a><a class="headerlink" href="#builtin-macros" title="Permalink to this headline">Â¶</a></h2>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">__BASE_FILE__</span></tt></dt>
+<dd>Defined to a string that contains the name of the main input file passed to
+Clang.</dd>
+<dt><tt class="docutils literal"><span class="pre">__COUNTER__</span></tt></dt>
+<dd>Defined to an integer value that starts at zero and is incremented each time
+the <tt class="docutils literal"><span class="pre">__COUNTER__</span></tt> macro is expanded.</dd>
+<dt><tt class="docutils literal"><span class="pre">__INCLUDE_LEVEL__</span></tt></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><tt class="docutils literal"><span class="pre">__TIMESTAMP__</span></tt></dt>
+<dd>Defined to the date and time of the last modification of the current source
+file.</dd>
+<dt><tt class="docutils literal"><span class="pre">__clang__</span></tt></dt>
+<dd>Defined when compiling with Clang</dd>
+<dt><tt class="docutils literal"><span class="pre">__clang_major__</span></tt></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"><em>Feature Checking Macros</em></a>.</dd>
+<dt><tt class="docutils literal"><span class="pre">__clang_minor__</span></tt></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"><em>Feature Checking Macros</em></a>.</dd>
+<dt><tt class="docutils literal"><span class="pre">__clang_patchlevel__</span></tt></dt>
+<dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd>
+<dt><tt class="docutils literal"><span class="pre">__clang_version__</span></tt></dt>
+<dd>Defined to a string that captures the Clang marketing version, including the
+Subversion tag or revision number, e.g., “<tt class="docutils literal"><span class="pre">1.5</span> <span class="pre">(trunk</span> <span class="pre">102332)</span></tt>”.</dd>
+</dl>
+</div>
+<div class="section" id="vectors-and-extended-vectors">
+<span id="langext-vectors"></span><h2><a class="toc-backref" href="#id5">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 <tt class="docutils literal"><span class="pre">ext_vector_type</span></tt> attribute.  It
+support for <tt class="docutils literal"><span class="pre">V.xyzw</span></tt> syntax and other tidbits as seen in OpenCL.  An example
+is:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">__has_extension(attribute_ext_vector_type)</span></tt>.</p>
+<p>Giving <tt class="docutils literal"><span class="pre">-faltivec</span></tt> option to clang enables support for AltiVec vector syntax
+and functions.  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">neon_vector_type</span></tt> and
+<tt class="docutils literal"><span class="pre">neon_polyvector_type</span></tt> attributes.  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="n">__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="kt">int8x8_t</span><span class="p">;</span>
+<span class="k">typedef</span> <span class="n">__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="kt">poly8_t</span> <span class="kt">poly8x16_t</span><span class="p">;</span>
+
+<span class="kt">int8x8_t</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int8x8_t</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kt">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++"><div class="highlight"><pre><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">Opeator</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"><em>__builtin_shufflevector</em></a>, <a class="reference internal" href="#langext-builtin-convertvector"><em>__builtin_convertvector</em></a>.</p>
+</div>
+</div>
+<div class="section" id="messages-on-deprecated-and-unavailable-attributes">
+<h2><a class="toc-backref" href="#id6">Messages on <tt class="docutils literal"><span class="pre">deprecated</span></tt> and <tt class="docutils literal"><span class="pre">unavailable</span></tt> 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 <tt class="docutils literal"><span class="pre">deprecated</span></tt> and
+<tt class="docutils literal"><span class="pre">unavailable</span></tt> attributes.  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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-c++"><div class="highlight"><pre>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
+<tt class="docutils literal"><span class="pre">__has_extension(attribute_deprecated_with_message)</span></tt> and
+<tt class="docutils literal"><span class="pre">__has_extension(attribute_unavailable_with_message)</span></tt>.</p>
+</div>
+<div class="section" id="attributes-on-enumerators">
+<h2><a class="toc-backref" href="#id7">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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">enum</span></tt> declaration do not apply to individual enumerators.</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_extension(enumerator_attributes)</span></tt>.</p>
+</div>
+<div class="section" id="user-specified-system-frameworks">
+<h2><a class="toc-backref" href="#id8">‘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
+“<tt class="docutils literal"><span class="pre">.system_framework</span></tt>” file at the top-level of their framework.  That is, the
+framework should have contents like:</p>
+<div class="highlight-none"><div class="highlight"><pre>.../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="#id9">Checks for Standard Language Features</a><a class="headerlink" href="#checks-for-standard-language-features" title="Permalink to this headline">Â¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">__has_feature</span></tt> macro can be used to query if certain standard language
+features are enabled.  The <tt class="docutils literal"><span class="pre">__has_extension</span></tt> 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 <tt class="docutils literal"><span class="pre">__cpp_<feature_name></span></tt>, and are
+intended to be a portable way to query the supported features of the compiler.
+See <a class="reference external" href="http://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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_exceptions)</span></tt> to determine if C++ exceptions have been
+enabled.  For example, compiling code with <tt class="docutils literal"><span class="pre">-fno-exceptions</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_rtti)</span></tt> to determine if C++ RTTI has been enabled.  For
+example, compiling code with <tt class="docutils literal"><span class="pre">-fno-rtti</span></tt> 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 <tt class="docutils literal"><span class="pre">-std=c++11</span></tt> or <tt class="docutils literal"><span class="pre">-std=gnu++11</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_access_control_sfinae)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_access_control_sfinae)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_alias_templates)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_alias_templates)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_alignas)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_alignas)</span></tt> to
+determine if support for alignment specifiers using <tt class="docutils literal"><span class="pre">alignas</span></tt> is enabled.</p>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_alignof)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_alignof)</span></tt> to
+determine if support for the <tt class="docutils literal"><span class="pre">alignof</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_attributes)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_attributes)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_constexpr)</span></tt> to determine if support for generalized
+constant expressions (e.g., <tt class="docutils literal"><span class="pre">constexpr</span></tt>) is enabled.</p>
+</div>
+<div class="section" id="c-11-decltype">
+<h4>C++11 <tt class="docutils literal"><span class="pre">decltype()</span></tt><a class="headerlink" href="#c-11-decltype" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_decltype)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_decltype)</span></tt> to
+determine if support for the <tt class="docutils literal"><span class="pre">decltype()</span></tt> specifier is enabled.  C++11’s
+<tt class="docutils literal"><span class="pre">decltype</span></tt> does not require type-completeness of a function call expression.
+Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_decltype_incomplete_return_types)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_decltype_incomplete_return_types)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_default_function_template_args)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_default_function_template_args)</span></tt> 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 <tt class="docutils literal"><span class="pre">default</span></tt>ed functions<a class="headerlink" href="#c-11-defaulted-functions" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_defaulted_functions)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_defaulted_functions)</span></tt> to determine if support for
+defaulted function definitions (with <tt class="docutils literal"><span class="pre">=</span> <span class="pre">default</span></tt>) 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_delegating_constructors)</span></tt> to determine if support for
+delegating constructors is enabled.</p>
+</div>
+<div class="section" id="c-11-deleted-functions">
+<h4>C++11 <tt class="docutils literal"><span class="pre">deleted</span></tt> functions<a class="headerlink" href="#c-11-deleted-functions" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_deleted_functions)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_deleted_functions)</span></tt> to determine if support for deleted
+function definitions (with <tt class="docutils literal"><span class="pre">=</span> <span class="pre">delete</span></tt>) 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_explicit_conversions)</span></tt> to determine if support for
+<tt class="docutils literal"><span class="pre">explicit</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_generalized_initializers)</span></tt> to determine if support for
+generalized initializers (using braced lists and <tt class="docutils literal"><span class="pre">std::initializer_list</span></tt>) 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_implicit_moves)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_inheriting_constructors)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_inline_namespaces)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_inline_namespaces)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_lambdas)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_lambdas)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_local_type_template_args)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_local_type_template_args)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_noexcept)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_noexcept)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_nonstatic_member_init)</span></tt> 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 <tt class="docutils literal"><span class="pre">nullptr</span></tt><a class="headerlink" href="#c-11-nullptr" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_nullptr)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_nullptr)</span></tt> to
+determine if support for <tt class="docutils literal"><span class="pre">nullptr</span></tt> is enabled.</p>
+</div>
+<div class="section" id="c-11-override-control">
+<h4>C++11 <tt class="docutils literal"><span class="pre">override</span> <span class="pre">control</span></tt><a class="headerlink" href="#c-11-override-control" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_override_control)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_override_control)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_reference_qualified_functions)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_reference_qualified_functions)</span></tt> to determine if support
+for reference-qualified functions (e.g., member functions with <tt class="docutils literal"><span class="pre">&</span></tt> or <tt class="docutils literal"><span class="pre">&&</span></tt>
+applied to <tt class="docutils literal"><span class="pre">*this</span></tt>) is enabled.</p>
+</div>
+<div class="section" id="c-11-range-based-for-loop">
+<h4>C++11 range-based <tt class="docutils literal"><span class="pre">for</span></tt> loop<a class="headerlink" href="#c-11-range-based-for-loop" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_range_for)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_range_for)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_raw_string_literals)</span></tt> to determine if support for raw
+string literals (e.g., <tt class="docutils literal"><span class="pre">R"x(foo\bar)x"</span></tt>) 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_rvalue_references)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_rvalue_references)</span></tt> to determine if support for rvalue
+references is enabled.</p>
+</div>
+<div class="section" id="c-11-static-assert">
+<h4>C++11 <tt class="docutils literal"><span class="pre">static_assert()</span></tt><a class="headerlink" href="#c-11-static-assert" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_static_assert)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_static_assert)</span></tt> to determine if support for compile-time
+assertions using <tt class="docutils literal"><span class="pre">static_assert</span></tt> is enabled.</p>
+</div>
+<div class="section" id="c-11-thread-local">
+<h4>C++11 <tt class="docutils literal"><span class="pre">thread_local</span></tt><a class="headerlink" href="#c-11-thread-local" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_thread_local)</span></tt> to determine if support for
+<tt class="docutils literal"><span class="pre">thread_local</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_auto_type)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(cxx_auto_type)</span></tt> to
+determine C++11 type inference is supported using the <tt class="docutils literal"><span class="pre">auto</span></tt> specifier.  If
+this is disabled, <tt class="docutils literal"><span class="pre">auto</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_strong_enums)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_strong_enums)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_trailing_return)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_trailing_return)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_unicode_literals)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_unrestricted_unions)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_user_literals)</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(cxx_variadic_templates)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_variadic_templates)</span></tt> to determine if support for
+variadic templates is enabled.</p>
+</div>
+</div>
+<div class="section" id="c-1y">
+<h3>C++1y<a class="headerlink" href="#c-1y" title="Permalink to this headline">Â¶</a></h3>
+<p>The features listed below are part of the committee draft for the C++1y
+standard.  As a result, all these features are enabled with the <tt class="docutils literal"><span class="pre">-std=c++1y</span></tt>
+or <tt class="docutils literal"><span class="pre">-std=gnu++1y</span></tt> option when compiling C++ code.</p>
+<div class="section" id="c-1y-binary-literals">
+<h4>C++1y binary literals<a class="headerlink" href="#c-1y-binary-literals" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_binary_literals)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_binary_literals)</span></tt> to determine whether
+binary literals (for instance, <tt class="docutils literal"><span class="pre">0b10010</span></tt>) are recognized. Clang supports this
+feature as an extension in all language modes.</p>
+</div>
+<div class="section" id="c-1y-contextual-conversions">
+<h4>C++1y contextual conversions<a class="headerlink" href="#c-1y-contextual-conversions" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_contextual_conversions)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_contextual_conversions)</span></tt> to determine if the C++1y 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 <tt class="docutils literal"><span class="pre">switch</span></tt> statement.</p>
+</div>
+<div class="section" id="c-1y-decltype-auto">
+<h4>C++1y decltype(auto)<a class="headerlink" href="#c-1y-decltype-auto" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_decltype_auto)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_decltype_auto)</span></tt> to determine if support
+for the <tt class="docutils literal"><span class="pre">decltype(auto)</span></tt> placeholder type is enabled.</p>
+</div>
+<div class="section" id="c-1y-default-initializers-for-aggregates">
+<h4>C++1y default initializers for aggregates<a class="headerlink" href="#c-1y-default-initializers-for-aggregates" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_aggregate_nsdmi)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_aggregate_nsdmi)</span></tt> to determine if support
+for default initializers in aggregate members is enabled.</p>
+</div>
+<div class="section" id="c-1y-digit-separators">
+<h4>C++1y digit separators<a class="headerlink" href="#c-1y-digit-separators" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__cpp_digit_separators</span></tt> to determine if support for digit separators
+using single quotes (for instance, <tt class="docutils literal"><span class="pre">10'000</span></tt>) is enabled. At this time, there
+is no corresponding <tt class="docutils literal"><span class="pre">__has_feature</span></tt> name</p>
+</div>
+<div class="section" id="c-1y-generalized-lambda-capture">
+<h4>C++1y generalized lambda capture<a class="headerlink" href="#c-1y-generalized-lambda-capture" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_init_captures)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_init_captures)</span></tt> to determine if support for
+lambda captures with explicit initializers is enabled
+(for instance, <tt class="docutils literal"><span class="pre">[n(0)]</span> <span class="pre">{</span> <span class="pre">return</span> <span class="pre">++n;</span> <span class="pre">}</span></tt>).</p>
+</div>
+<div class="section" id="c-1y-generic-lambdas">
+<h4>C++1y generic lambdas<a class="headerlink" href="#c-1y-generic-lambdas" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_generic_lambdas)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_generic_lambdas)</span></tt> to determine if support for generic
+(polymorphic) lambdas is enabled
+(for instance, <tt class="docutils literal"><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></tt>).</p>
+</div>
+<div class="section" id="c-1y-relaxed-constexpr">
+<h4>C++1y relaxed constexpr<a class="headerlink" href="#c-1y-relaxed-constexpr" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_relaxed_constexpr)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_relaxed_constexpr)</span></tt> to determine if variable
+declarations, local variable modification, and control flow constructs
+are permitted in <tt class="docutils literal"><span class="pre">constexpr</span></tt> functions.</p>
+</div>
+<div class="section" id="c-1y-return-type-deduction">
+<h4>C++1y return type deduction<a class="headerlink" href="#c-1y-return-type-deduction" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_return_type_deduction)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_return_type_deduction)</span></tt> to determine if support
+for return type deduction for functions (using <tt class="docutils literal"><span class="pre">auto</span></tt> as a return type)
+is enabled.</p>
+</div>
+<div class="section" id="c-1y-runtime-sized-arrays">
+<h4>C++1y runtime-sized arrays<a class="headerlink" href="#c-1y-runtime-sized-arrays" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_runtime_array)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_runtime_array)</span></tt> 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-1y-variable-templates">
+<h4>C++1y variable templates<a class="headerlink" href="#c-1y-variable-templates" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(cxx_variable_templates)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(cxx_variable_templates)</span></tt> 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 <tt class="docutils literal"><span class="pre">-std=c11</span></tt> or <tt class="docutils literal"><span class="pre">-std=gnu11</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(c_alignas)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(c_alignas)</span></tt> to determine
+if support for alignment specifiers using <tt class="docutils literal"><span class="pre">_Alignas</span></tt> is enabled.</p>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(c_alignof)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(c_alignof)</span></tt> to determine
+if support for the <tt class="docutils literal"><span class="pre">_Alignof</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(c_atomic)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(c_atomic)</span></tt> to determine
+if support for atomic types using <tt class="docutils literal"><span class="pre">_Atomic</span></tt> is enabled.  Clang also provides
+<a class="reference internal" href="#langext-c11-atomic"><em>a set of builtins</em></a> which can be used to implement
+the <tt class="docutils literal"><span class="pre"><stdatomic.h></span></tt> operations on <tt class="docutils literal"><span class="pre">_Atomic</span></tt> types. Use
+<tt class="docutils literal"><span class="pre">__has_include(<stdatomic.h>)</span></tt> to determine if C11’s <tt class="docutils literal"><span class="pre"><stdatomic.h></span></tt> header
+is available.</p>
+<p>Clang will use the system’s <tt class="docutils literal"><span class="pre"><stdatomic.h></span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(c_generic_selections)</span></tt> or
+<tt class="docutils literal"><span class="pre">__has_extension(c_generic_selections)</span></tt> 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 <tt class="docutils literal"><span class="pre">_Static_assert()</span></tt><a class="headerlink" href="#c11-static-assert" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(c_static_assert)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(c_static_assert)</span></tt>
+to determine if support for compile-time assertions using <tt class="docutils literal"><span class="pre">_Static_assert</span></tt> is
+enabled.</p>
+</div>
+<div class="section" id="c11-thread-local">
+<h4>C11 <tt class="docutils literal"><span class="pre">_Thread_local</span></tt><a class="headerlink" href="#c11-thread-local" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(c_thread_local)</span></tt> or <tt class="docutils literal"><span class="pre">__has_extension(c_thread_local)</span></tt>
+to determine if support for <tt class="docutils literal"><span class="pre">_Thread_local</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_feature(modules)</span></tt> to determine if Modules have been enabled.
+For example, compiling code with <tt class="docutils literal"><span class="pre">-fmodules</span></tt> enables the use of Modules.</p>
+<p>More information could be found <a class="reference external" href="http://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="#id10">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="http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html">GNU C++ type traits</a> and a subset of the
+<a class="reference external" href="http://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 <tt class="docutils literal"><span class="pre">__X</span></tt>, <tt class="docutils literal"><span class="pre">__has_extension(X)</span></tt> 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++"><div class="highlight"><pre><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><tt class="docutils literal"><span class="pre">__has_nothrow_assign</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__has_nothrow_copy</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__has_nothrow_constructor</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__has_trivial_assign</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__has_trivial_copy</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__has_trivial_constructor</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__has_trivial_destructor</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__has_virtual_destructor</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_abstract</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_base_of</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_class</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_convertible_to</span></tt> (Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_empty</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_enum</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_interface_class</span></tt> (Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_pod</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_polymorphic</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_union</span></tt> (GNU, Microsoft)</li>
+<li><tt class="docutils literal"><span class="pre">__is_literal(type)</span></tt>: Determines whether the given type is a literal type</li>
+<li><tt class="docutils literal"><span class="pre">__is_final</span></tt>: Determines whether the given type is declared with a
+<tt class="docutils literal"><span class="pre">final</span></tt> class-virt-specifier.</li>
+<li><tt class="docutils literal"><span class="pre">__underlying_type(type)</span></tt>: Retrieves the underlying type for a given
+<tt class="docutils literal"><span class="pre">enum</span></tt> type.  This trait is required to implement the C++11 standard
+library.</li>
+<li><tt class="docutils literal"><span class="pre">__is_trivially_assignable(totype,</span> <span class="pre">fromtype)</span></tt>: Determines whether a value
+of type <tt class="docutils literal"><span class="pre">totype</span></tt> can be assigned to from a value of type <tt class="docutils literal"><span class="pre">fromtype</span></tt> 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><tt class="docutils literal"><span class="pre">__is_trivially_constructible(type,</span> <span class="pre">argtypes...)</span></tt>: Determines whether a
+value of type <tt class="docutils literal"><span class="pre">type</span></tt> can be direct-initialized with arguments of types
+<tt class="docutils literal"><span class="pre">argtypes...</span></tt> 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><tt class="docutils literal"><span class="pre">__is_destructible</span></tt> (MSVC 2013): partially implemented</li>
+<li><tt class="docutils literal"><span class="pre">__is_nothrow_destructible</span></tt> (MSVC 2013): partially implemented</li>
+<li><tt class="docutils literal"><span class="pre">__is_nothrow_assignable</span></tt> (MSVC 2013, clang)</li>
+<li><tt class="docutils literal"><span class="pre">__is_constructible</span></tt> (MSVC 2013, clang)</li>
+<li><tt class="docutils literal"><span class="pre">__is_nothrow_constructible</span></tt> (MSVC 2013, clang)</li>
+</ul>
+</div>
+<div class="section" id="blocks">
+<h2><a class="toc-backref" href="#id11">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"><em>BlockLanguageSpec</em></a>. Implementation and ABI details for
+the clang implementation are in <a class="reference internal" href="Block-ABI-Apple.html"><em>Block-ABI-Apple</em></a>.</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_extension(blocks)</span></tt>.</p>
+</div>
+<div class="section" id="objective-c-features">
+<h2><a class="toc-backref" href="#id12">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
+(“<tt class="docutils literal"><span class="pre">init</span></tt>”, “<tt class="docutils literal"><span class="pre">alloc</span></tt>”, 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"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">NSObject</span>
+<span class="k">+</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="k">-</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="nc">NSArray</span> : <span class="nc">NSObject</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>and this common initialization pattern</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">NSArray</span> <span class="o">*</span><span class="n">array</span> <span class="o">=</span> <span class="p">[[</span><span class="n">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 <tt class="docutils literal"><span class="pre">[NSArray</span> <span class="pre">alloc]</span></tt> is <tt class="docutils literal"><span class="pre">NSArray*</span></tt> because
+<tt class="docutils literal"><span class="pre">alloc</span></tt> implicitly has a related result type.  Similarly, the type of the
+expression <tt class="docutils literal"><span class="pre">[[NSArray</span> <span class="pre">alloc]</span> <span class="pre">init]</span></tt> is <tt class="docutils literal"><span class="pre">NSArray*</span></tt>, since <tt class="docutils literal"><span class="pre">init</span></tt> has a
+related result type and its receiver is known to have the type <tt class="docutils literal"><span class="pre">NSArray</span> <span class="pre">*</span></tt>.
+If neither <tt class="docutils literal"><span class="pre">alloc</span></tt> nor <tt class="docutils literal"><span class="pre">init</span></tt> had a related result type, the expressions
+would have had type <tt class="docutils literal"><span class="pre">id</span></tt>, as declared in the method signature.</p>
+<p>A method with a related result type can be declared by using the type
+<tt class="docutils literal"><span class="pre">instancetype</span></tt> as its result type.  <tt class="docutils literal"><span class="pre">instancetype</span></tt> is a contextual keyword
+that is only permitted in the result type of an Objective-C method, e.g.</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">A</span>
+<span class="k">+</span> <span class="p">(</span><span class="n">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., “<tt class="docutils literal"><span class="pre">init</span></tt>” in “<tt class="docutils literal"><span class="pre">initWithObjects</span></tt>”) 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 “<tt class="docutils literal"><span class="pre">alloc</span></tt>” or “<tt class="docutils literal"><span class="pre">new</span></tt>”, and the method is a class method,
+or</li>
+<li>the first word is “<tt class="docutils literal"><span class="pre">autorelease</span></tt>”, “<tt class="docutils literal"><span class="pre">init</span></tt>”, “<tt class="docutils literal"><span class="pre">retain</span></tt>”, or “<tt class="docutils literal"><span class="pre">self</span></tt>”,
+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"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">NSString</span> : <span class="nc">NSObject</span>
+<span class="k">-</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 <tt class="docutils literal"><span class="pre">id</span></tt>.</p>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(objc_instancetype)</span></tt> to determine whether the
+<tt class="docutils literal"><span class="pre">instancetype</span></tt> 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"><em>automated reference counting</em></a> in Objective-C, which eliminates the need
+for manual <tt class="docutils literal"><span class="pre">retain</span></tt>/<tt class="docutils literal"><span class="pre">release</span></tt>/<tt class="docutils literal"><span class="pre">autorelease</span></tt> message sends.  There are two
+feature macros associated with automatic reference counting:
+<tt class="docutils literal"><span class="pre">__has_feature(objc_arc)</span></tt> indicates the availability of automated reference
+counting in general, while <tt class="docutils literal"><span class="pre">__has_feature(objc_arc_weak)</span></tt> indicates that
+automated reference counting also includes support for <tt class="docutils literal"><span class="pre">__weak</span></tt> pointers to
+Objective-C objects.</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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span></tt>.</p>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(objc_fixed_enum)</span></tt> 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 <tt class="docutils literal"><span class="pre">NSArray</span></tt>‘s
+array-sorting method:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">-</span> <span class="p">(</span><span class="n">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><tt class="docutils literal"><span class="pre">NSComparator</span></tt> is simply a typedef for the block pointer <tt class="docutils literal"><span class="pre">NSComparisonResult</span>
+<span class="pre">(^)(id,</span> <span class="pre">id)</span></tt>, 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
+<tt class="docutils literal"><span class="pre">id</span></tt> and returning an <tt class="docutils literal"><span class="pre">NSComparisonResult</span></tt>):</p>
+<div class="highlight-objc"><div class="highlight"><pre>NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
+                   @"String 02"];
+const NSStringCompareOptions comparisonOptions
+  = NSCaseInsensitiveSearch | NSNumericSearch |
+    NSWidthInsensitiveSearch | NSForcedOrderingSearch;
+NSLocale *currentLocale = [NSLocale currentLocale];
+NSArray *sorted
+  = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult {
+             NSRange string1Range = NSMakeRange(0, [s1 length]);
+             return [s1 compare:s2 options:comparisonOptions
+             range:string1Range locale:currentLocale];
+     }];
+NSLog(@"sorted: %@", sorted);
+</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"><div class="highlight"><pre><span class="n">operator</span> <span class="n">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 <tt class="docutils literal"><span class="pre">Block_copy</span></tt>) 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"><em>Object Literals and Subscripting</em></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: <tt class="docutils literal"><span class="pre">__has_feature(objc_array_literals)</span></tt> tests the
+availability of array literals; <tt class="docutils literal"><span class="pre">__has_feature(objc_dictionary_literals)</span></tt>
+tests the availability of dictionary literals;
+<tt class="docutils literal"><span class="pre">__has_feature(objc_subscripting)</span></tt> 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.
+<tt class="docutils literal"><span class="pre">__has_feature(objc_default_synthesize_properties)</span></tt> 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="http://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="http://clang-analyzer.llvm.org">static analyzer</a> Some exceptions may be
+better described using the <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute instead.</p>
+<p><strong>Usage</strong>: The <tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt>, <tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt>,
+<tt class="docutils literal"><span class="pre">ns_returns_autoreleased</span></tt>, <tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt>, and
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> 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"><div class="highlight"><pre><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="k">-</span> <span class="p">(</span><span class="n">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 <tt class="docutils literal"><span class="pre">*_returns_retained</span></tt> attributes specify that the returned object has a +1
+retain count.  The <tt class="docutils literal"><span class="pre">*_returns_not_retained</span></tt> attributes specify that the return
+object has a +0 retain count, even if the normal convention for its selector
+would be +1.  <tt class="docutils literal"><span class="pre">ns_returns_autoreleased</span></tt> 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 <tt class="docutils literal"><span class="pre">ns_consumed</span></tt> and <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> 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 <tt class="docutils literal"><span class="pre">ns_consumes_self</span></tt> attribute can only be placed on an Objective-C
+method; it specifies that the method expects its <tt class="docutils literal"><span class="pre">self</span></tt> parameter to have a
++1 retain count, which it will balance in some way.</p>
+<div class="highlight-objc"><div class="highlight"><pre><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="n">NSString</span> <span class="o">*</span><span class="n">string</span><span class="p">);</span>
+
+<span class="k">-</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="k">-</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="n">__attribute__</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="n">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="http://clang-analyzer.llvm.org/annotations.html#cocoa_mem">list of annotations for analysis</a>.</p>
+<p>Query for these features with <tt class="docutils literal"><span class="pre">__has_attribute(ns_consumed)</span></tt>,
+<tt class="docutils literal"><span class="pre">__has_attribute(ns_returns_retained)</span></tt>, etc.</p>
+</div>
+<div class="section" id="objective-c-abi-protocol-qualifier-mangling-of-parameters">
+<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-<tt class="docutils literal"><span class="pre">id</span></tt> (e.g., <tt class="docutils literal"><span class="pre">id<Foo></span></tt>).  This mangling allows such
+parameters to be differentiated from those with the regular unqualified <tt class="docutils literal"><span class="pre">id</span></tt>
+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
+<tt class="docutils literal"><span class="pre">__has_feature(objc_protocol_qualifier_mangling)</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="initializer-lists-for-complex-numbers-in-c">
+<span id="langext-overloading"></span><h2><a class="toc-backref" href="#id13">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++"><div class="highlight"><pre><span class="cp">#include <math.h></span>
+<span class="cp">#include <complex.h></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 <tt class="docutils literal"><span class="pre">_Imaginary</span></tt>.  (Clang also supports the <tt class="docutils literal"><span class="pre">__real__</span></tt> and
+<tt class="docutils literal"><span class="pre">__imag__</span></tt> 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++"><div class="highlight"><pre><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++ <tt class="docutils literal"><span class="pre">std::complex</span></tt>.  (In C++11, list initialization allows the same
+syntax to be used with <tt class="docutils literal"><span class="pre">std::complex</span></tt> with the same meaning.)</p>
+</div>
+<div class="section" id="builtin-functions">
+<h2><a class="toc-backref" href="#id14">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 <tt class="docutils literal"><span class="pre">__builtin_nan</span></tt>, <tt class="docutils literal"><span class="pre">__builtin_constant_p</span></tt>,
+<tt class="docutils literal"><span class="pre">__builtin_choose_expr</span></tt>, <tt class="docutils literal"><span class="pre">__builtin_types_compatible_p</span></tt>,
+<tt class="docutils literal"><span class="pre">__builtin_assume_aligned</span></tt>, <tt class="docutils literal"><span class="pre">__sync_fetch_and_add</span></tt>, 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 <tt class="docutils literal"><span class="pre"><xmmintrin.h></span></tt>, 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"><em>extended vector support</em></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><tt class="docutils literal"><span class="pre">__builtin_assume</span></tt><a class="headerlink" href="#builtin-assume" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">__builtin_assume</span></tt> 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++"><div class="highlight"><pre><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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">__has_builtin(__builtin_assume)</span></tt>.</p>
+</div>
+<div class="section" id="builtin-readcyclecounter">
+<h3><tt class="docutils literal"><span class="pre">__builtin_readcyclecounter</span></tt><a class="headerlink" href="#builtin-readcyclecounter" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">__builtin_readcyclecounter</span></tt> 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++"><div class="highlight"><pre><span class="n">__builtin_readcyclecounter</span><span class="p">()</span>
+</pre></div>
+</div>
+<p><strong>Example of Use</strong>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">__builtin_readcyclecounter()</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_builtin(__builtin_readcyclecounter)</span></tt>. 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><tt class="docutils literal"><span class="pre">__builtin_shufflevector</span></tt><a class="headerlink" href="#builtin-shufflevector" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">__builtin_shufflevector</span></tt> 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
+<tt class="docutils literal"><span class="pre"><xmmintrin.h></span></tt>.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">__builtin_shufflevector</span></tt> 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
+<tt class="docutils literal"><span class="pre">vec1</span></tt> is a 4-element vector, index 5 would refer to the second element of
+<tt class="docutils literal"><span class="pre">vec2</span></tt>. 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 <tt class="docutils literal"><span class="pre">__builtin_shufflevector</span></tt> is a vector with the same element
+type as <tt class="docutils literal"><span class="pre">vec1</span></tt>/<tt class="docutils literal"><span class="pre">vec2</span></tt> but that has an element count equal to the number of
+indices specified.</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_builtin(__builtin_shufflevector)</span></tt>.</p>
+</div>
+<div class="section" id="builtin-convertvector">
+<span id="langext-builtin-convertvector"></span><h3><tt class="docutils literal"><span class="pre">__builtin_convertvector</span></tt><a class="headerlink" href="#builtin-convertvector" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">__builtin_convertvector</span></tt> 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++"><div class="highlight"><pre><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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">__builtin_convertvector</span></tt> 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 <tt class="docutils literal"><span class="pre">__builtin_convertvector</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_builtin(__builtin_convertvector)</span></tt>.</p>
+</div>
+<div class="section" id="builtin-unreachable">
+<h3><tt class="docutils literal"><span class="pre">__builtin_unreachable</span></tt><a class="headerlink" href="#builtin-unreachable" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">__builtin_unreachable</span></tt> 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 <tt class="docutils literal"><span class="pre">__builtin_unreachable</span></tt> in the example below, the
+compiler assumes that the inline asm can fall through and prints a “function
+declared ‘<tt class="docutils literal"><span class="pre">noreturn</span></tt>‘ should not return” warning.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__builtin_unreachable</span><span class="p">()</span>
+</pre></div>
+</div>
+<p><strong>Example of use</strong>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">__builtin_unreachable()</span></tt> 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 <tt class="docutils literal"><span class="pre">__has_builtin(__builtin_unreachable)</span></tt>.</p>
+</div>
+<div class="section" id="sync-swap">
+<h3><tt class="docutils literal"><span class="pre">__sync_swap</span></tt><a class="headerlink" href="#sync-swap" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">__sync_swap</span></tt> is used to atomically swap integers or pointers in memory.</p>
+<p><strong>Syntax</strong>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">__sync_swap()</span></tt> builtin extends the existing <tt class="docutils literal"><span class="pre">__sync_*()</span></tt> 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
+<tt class="docutils literal"><span class="pre">__sync_bool_compare_and_swap()</span></tt> or relying on the platform specific
+implementation details of <tt class="docutils literal"><span class="pre">__sync_lock_test_and_set()</span></tt>.  The
+<tt class="docutils literal"><span class="pre">__sync_swap()</span></tt> builtin is a full barrier.</p>
+</div>
+<div class="section" id="builtin-addressof">
+<h3><tt class="docutils literal"><span class="pre">__builtin_addressof</span></tt><a class="headerlink" href="#builtin-addressof" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">__builtin_addressof</span></tt> performs the functionality of the built-in <tt class="docutils literal"><span class="pre">&</span></tt>
+operator, ignoring any <tt class="docutils literal"><span class="pre">operator&</span></tt> 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 <tt class="docutils literal"><span class="pre">operator&</span></tt>.</p>
+<p><strong>Example of use</strong>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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">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><tt class="docutils literal"><span class="pre">__builtin_operator_new</span></tt> and <tt class="docutils literal"><span class="pre">__builtin_operator_delete</span></tt><a class="headerlink" href="#builtin-operator-new-and-builtin-operator-delete" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">__builtin_operator_new</span></tt> allocates memory just like a non-placement non-class
+<em>new-expression</em>. This is exactly like directly calling the normal
+non-placement <tt class="docutils literal"><span class="pre">::operator</span> <span class="pre">new</span></tt>, except that it allows certain optimizations
+that the C++ standard does not permit for a direct function call to
+<tt class="docutils literal"><span class="pre">::operator</span> <span class="pre">new</span></tt> (in particular, removing <tt class="docutils literal"><span class="pre">new</span></tt> / <tt class="docutils literal"><span class="pre">delete</span></tt> pairs and
+merging allocations).</p>
+<p>Likewise, <tt class="docutils literal"><span class="pre">__builtin_operator_delete</span></tt> deallocates memory just like a
+non-class <em>delete-expression</em>, and is exactly like directly calling the normal
+<tt class="docutils literal"><span class="pre">::operator</span> <span class="pre">delete</span></tt>, except that it permits optimizations. Only the unsized
+form of <tt class="docutils literal"><span class="pre">__builtin_operator_delete</span></tt> is currently available.</p>
+<p>These builtins are intended for use in the implementation of <tt class="docutils literal"><span class="pre">std::allocator</span></tt>
+and other similar allocation libraries, and are only available in C++.</p>
+</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"><div class="highlight"><pre><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"><div class="highlight"><pre><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"><div class="highlight"><pre><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"><div class="highlight"><pre><span class="kt">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_umul_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>A complete enumeration of the builtins are:</p>
+<div class="highlight-c"><div class="highlight"><pre><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>
+</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 <tt class="docutils literal"><span class="pre"><stdatomic.h></span></tt> header.  These builtins provide the semantics of the
+<tt class="docutils literal"><span class="pre">_explicit</span></tt> form of the corresponding C11 operation, and are named with a
+<tt class="docutils literal"><span class="pre">__c11_</span></tt> prefix.  The supported operations, and the differences from
+the corresponding C11 operations, are:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_init</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_thread_fence</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_signal_fence</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_is_lock_free</span></tt> (The argument is the size of the
+<tt class="docutils literal"><span class="pre">_Atomic(...)</span></tt> object, instead of its address)</li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_store</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_load</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_exchange</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_compare_exchange_strong</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_compare_exchange_weak</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_fetch_add</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_fetch_sub</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_fetch_and</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_fetch_or</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__c11_atomic_fetch_xor</span></tt></li>
+</ul>
+<p>The macros <tt class="docutils literal"><span class="pre">__ATOMIC_RELAXED</span></tt>, <tt class="docutils literal"><span class="pre">__ATOMIC_CONSUME</span></tt>, <tt class="docutils literal"><span class="pre">__ATOMIC_ACQUIRE</span></tt>,
+<tt class="docutils literal"><span class="pre">__ATOMIC_RELEASE</span></tt>, <tt class="docutils literal"><span class="pre">__ATOMIC_ACQ_REL</span></tt>, and <tt class="docutils literal"><span class="pre">__ATOMIC_SEQ_CST</span></tt> are
+provided, with values corresponding to the enumerators of C11’s
+<tt class="docutils literal"><span class="pre">memory_order</span></tt> 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"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">T</span></tt> currently supported are:
+* Integer types with width at most 64 bits (or 128 bits on AArch64).
+* Floating-point types
+* Pointer types.</p>
+<p>Note that the compiler does not guarantee it will not insert stores which clear
+the exclusive monitor in between an <tt class="docutils literal"><span class="pre">ldrex</span></tt> type operation and its paired
+<tt class="docutils literal"><span class="pre">strex</span></tt>. 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 <tt class="docutils literal"><span class="pre">ldrex</span></tt> and
+<tt class="docutils literal"><span class="pre">strex</span></tt>. 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>
+<div class="section" id="non-standard-c-11-attributes">
+<h2><a class="toc-backref" href="#id15">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 <tt class="docutils literal"><span class="pre">clang</span></tt> attribute
+namespace.</p>
+<p>Clang supports GCC’s <tt class="docutils literal"><span class="pre">gnu</span></tt> attribute namespace. All GCC attributes which
+are accepted with the <tt class="docutils literal"><span class="pre">__attribute__((foo))</span></tt> syntax are also accepted as
+<tt class="docutils literal"><span class="pre">[[gnu::foo]]</span></tt>. This only extends to attributes which are specified by GCC
+(see the list of <a class="reference external" href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">GCC function attributes</a>, <a class="reference external" href="http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html">GCC variable
+attributes</a>, and
+<a class="reference external" href="http://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 <tt class="docutils literal"><span class="pre">unused</span></tt> attribute to <tt class="docutils literal"><span class="pre">a</span></tt> and <tt class="docutils literal"><span class="pre">f</span></tt>, and
+also applies the GNU <tt class="docutils literal"><span class="pre">noreturn</span></tt> attribute to <tt class="docutils literal"><span class="pre">f</span></tt>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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="#id16">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 <tt class="docutils literal"><span class="pre">__dmb</span></tt>, <tt class="docutils literal"><span class="pre">__dsb</span></tt> and <tt class="docutils literal"><span class="pre">__isb</span></tt> 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 arithmatic 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-off-the-gs-segment">
+<h4>Memory references off the GS segment<a class="headerlink" href="#memory-references-off-the-gs-segment" 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, and address space #257 causes it to be
+relative to the X86 FS 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++"><div class="highlight"><pre><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"><div class="highlight"><pre><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>
+</div>
+</div>
+</div>
+<div class="section" id="extensions-for-static-analysis">
+<h2><a class="toc-backref" href="#id17">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="http://clang-analyzer.llvm.org/">Clang Static
+Analyzer</a>. These attributes are documented
+in the analyzer’s <a class="reference external" href="http://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="#id18">Extensions for Dynamic Analysis</a><a class="headerlink" href="#extensions-for-dynamic-analysis" title="Permalink to this headline">Â¶</a></h2>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt> to check if the code is being built
+with <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>.</p>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt> to check if the code is being built
+with <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>.</p>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(memory_sanitizer)</span></tt> to check if the code is being built
+with <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a>.</p>
+<p>Use <tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt> to check if the code is being built
+with <a class="reference internal" href="SafeStack.html"><em>SafeStack</em></a>.</p>
+</div>
+<div class="section" id="extensions-for-selectively-disabling-optimization">
+<h2><a class="toc-backref" href="#id19">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 <tt class="docutils literal"><span class="pre">optnone</span></tt> can be used.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">optimize</span></tt>
+followed by <tt class="docutils literal"><span class="pre">off</span></tt> or <tt class="docutils literal"><span class="pre">on</span></tt>.</p>
+<p>All function definitions in the region between an <tt class="docutils literal"><span class="pre">off</span></tt> and the following
+<tt class="docutils literal"><span class="pre">on</span></tt> will be decorated with the <tt class="docutils literal"><span class="pre">optnone</span></tt> 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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">on</span></tt> is found to close an <tt class="docutils literal"><span class="pre">off</span></tt> region, the end of the region is the
+end of the compilation unit.</p>
+<p>Note that a stray <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">optimize</span> <span class="pre">on</span></tt> 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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">twice</span></tt> is outside
+the pragma region, whereas the definition of <tt class="docutils literal"><span class="pre">thrice</span></tt> is inside the region.
+The <tt class="docutils literal"><span class="pre">container</span></tt> function is also in the region and will not be optimized, but
+it causes the instantiation of <tt class="docutils literal"><span class="pre">twice</span></tt> and <tt class="docutils literal"><span class="pre">thrice</span></tt> with an <tt class="docutils literal"><span class="pre">int</span></tt> type; of
+these two instantiations, <tt class="docutils literal"><span class="pre">twice</span></tt> will be optimized (because its definition
+was outside the region) and <tt class="docutils literal"><span class="pre">thrice</span></tt> will not be optimized.</p>
+</div>
+<div class="section" id="extensions-for-loop-hint-optimizations">
+<h2><a class="toc-backref" href="#id20">Extensions for loop hint optimizations</a><a class="headerlink" href="#extensions-for-loop-hint-optimizations" title="Permalink to this headline">Â¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span></tt> 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, and unrolling. 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 <tt class="docutils literal"><span class="pre">vectorize(enable)</span></tt> and interleaving is enabled
+by <tt class="docutils literal"><span class="pre">interleave(enable)</span></tt>. This is useful when compiling with <tt class="docutils literal"><span class="pre">-Os</span></tt> to
+manually enable vectorization or interleaving.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">vectorize_width(_value_)</span></tt> and the interleave
+count is specified by <tt class="docutils literal"><span class="pre">interleave_count(_value_)</span></tt>, 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++"><div class="highlight"><pre><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
+<tt class="docutils literal"><span class="pre">vectorize(disable)</span></tt> or <tt class="docutils literal"><span class="pre">interleave(disable)</span></tt>.</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 <tt class="docutils literal"><span class="pre">unroll(full)</span></tt> 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 loop count is not known at compile time the loop will not be
+unrolled.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">unroll_count(_value_)</span></tt> 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 <tt class="docutils literal"><span class="pre">unroll(full)</span></tt>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">unroll(disable)</span></tt>.</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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">vectorize_width(4)</span></tt> 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>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="UsersManual.html">Clang Compiler User’s Manual</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ObjectiveCLiterals.html">Objective-C Literals</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/LeakSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/LeakSanitizer.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/LeakSanitizer.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/LeakSanitizer.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,100 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>LeakSanitizer — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="SanitizerCoverage" href="SanitizerCoverage.html" />
+    <link rel="prev" title="DataFlowSanitizer Design Document" href="DataFlowSanitizerDesign.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>LeakSanitizer</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <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="#current-status" id="id2">Current status</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"><em>AddressSanitizer</em></a> to get both memory error and leak detection.
+LeakSanitizer does not introduce any additional slowdown when used in this mode.
+The LeakSanitizer runtime can also be linked in separately to get leak detection
+only, at a minimal performance cost.</p>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id2">Current status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">Â¶</a></h2>
+<p>LeakSanitizer is turned on by default, but it is only supported on x86_64
+Linux.</p>
+<p>The combined mode has been tested on fairly large software projects. The
+stand-alone mode has received much less testing.</p>
+<p>There are plans to support LeakSanitizer in <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a> builds.</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://code.google.com/p/address-sanitizer/wiki/LeakSanitizer">https://code.google.com/p/address-sanitizer/wiki/LeakSanitizer</a></p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <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">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/LibASTMatchers.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/LibASTMatchers.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/LibASTMatchers.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/LibASTMatchers.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,167 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Matching the Clang AST — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.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"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Matching the Clang AST</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <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"><em>LibTooling</em></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"><em>Introduction
+to the Clang AST</em></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 “<tt class="docutils literal"><span class="pre">Foo</span></tt>”,
+insert a <a class="reference external" href="LibASTMatchersReference.html#hasName0Anchor">hasName</a> matcher: the
+call <tt class="docutils literal"><span class="pre">recordDecl(hasName("Foo"))</span></tt> returns a matcher that matches classes or
+unions that are named “<tt class="docutils literal"><span class="pre">Foo</span></tt>”, 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
+“<tt class="docutils literal"><span class="pre">Bar</span></tt>”: <tt class="docutils literal"><span class="pre">recordDecl(hasName("Foo"),</span> <span class="pre">isDerivedFrom("Bar"))</span></tt>.</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"><em>how to write your own
+AST matchers</em></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"><em>Introduction to the Clang AST</em></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, <tt class="docutils literal"><span class="pre">recordDecl(hasName("MyClass")).bind("id")</span></tt> will
+bind the matched <tt class="docutils literal"><span class="pre">recordDecl</span></tt> node to the string “<tt class="docutils literal"><span class="pre">id</span></tt>”, to be later
+retrieved in the <a class="reference external" href="http://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><tt class="docutils literal"><span class="pre">VariadicDynCastAllOfMatcher<Base,</span> <span class="pre">Derived></span></tt><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>.  <tt class="docutils literal"><span class="pre">VariadicDynCastAllOfMatchers</span></tt> 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"><em>bind</em></a> the node they represent to ids for later
+processing.</p>
+<p><tt class="docutils literal"><span class="pre">VariadicDynCastAllOfMatchers</span></tt> are callable classes that model variadic
+template functions in C++03.  They take an aribtrary number of
+<tt class="docutils literal"><span class="pre">Matcher<Derived></span></tt> and return a <tt class="docutils literal"><span class="pre">Matcher<Base></span></tt>.</p>
+</div>
+<div class="section" id="ast-matcher-p-type-name-paramtype-param">
+<h3><tt class="docutils literal"><span class="pre">AST_MATCHER_P(Type,</span> <span class="pre">Name,</span> <span class="pre">ParamType,</span> <span class="pre">Param)</span></tt><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 <tt class="docutils literal"><span class="pre">Matcher<Type></span></tt> 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="http://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
+<tt class="docutils literal"><span class="pre">VariadicDynCastAllOfMatcher</span></tt> 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">
+      
+        <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">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/LibASTMatchersTutorial.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/LibASTMatchersTutorial.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/LibASTMatchersTutorial.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/LibASTMatchersTutorial.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,543 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Tutorial for building tools using LibTooling and LibASTMatchers — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Matching the Clang AST" href="LibASTMatchers.html" />
+    <link rel="prev" title="How to write RecursiveASTVisitor based ASTFrontendActions." href="RAVFrontendAction.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Tutorial for building tools using LibTooling and LibASTMatchers</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="RAVFrontendAction.html">How to write RecursiveASTVisitor based ASTFrontendActions.</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibASTMatchers.html">Matching the Clang AST</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="tutorial-for-building-tools-using-libtooling-and-libastmatchers">
+<h1>Tutorial for building tools using LibTooling and LibASTMatchers<a class="headerlink" href="#tutorial-for-building-tools-using-libtooling-and-libastmatchers" title="Permalink to this headline">Â¶</a></h1>
+<p>This document is intended to show how to build a useful source-to-source
+translation tool based on Clang’s <a class="reference external" href="LibTooling.html">LibTooling</a>. It is
+explicitly aimed at people who are new to Clang, so all you should need
+is a working knowledge of C++ and the command line.</p>
+<p>In order to work on the compiler, you need some basic knowledge of the
+abstract syntax tree (AST). To this end, the reader is incouraged to
+skim the <a class="reference internal" href="IntroductionToTheClangAST.html"><em>Introduction to the Clang
+AST</em></a></p>
+<div class="section" id="step-0-obtaining-clang">
+<h2>Step 0: Obtaining Clang<a class="headerlink" href="#step-0-obtaining-clang" title="Permalink to this headline">Â¶</a></h2>
+<p>As Clang is part of the LLVM project, you’ll need to download LLVM’s
+source code first. Both Clang and LLVM are maintained as Subversion
+repositories, but we’ll be accessing them through the git mirror. For
+further information, see the <a class="reference external" href="http://llvm.org/docs/GettingStarted.html">getting started
+guide</a>.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">mkdir ~/clang-llvm && cd ~/clang-llvm</span>
+<span class="go">git clone http://llvm.org/git/llvm.git</span>
+<span class="go">cd llvm/tools</span>
+<span class="go">git clone http://llvm.org/git/clang.git</span>
+<span class="go">cd clang/tools</span>
+<span class="go">git clone http://llvm.org/git/clang-tools-extra.git extra</span>
+</pre></div>
+</div>
+<p>Next you need to obtain the CMake build system and Ninja build tool. You
+may already have CMake installed, but current binary versions of CMake
+aren’t built with Ninja support.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">cd ~/clang-llvm</span>
+<span class="go">git clone https://github.com/martine/ninja.git</span>
+<span class="go">cd ninja</span>
+<span class="go">git checkout release</span>
+<span class="go">./bootstrap.py</span>
+<span class="go">sudo cp ninja /usr/bin/</span>
+
+<span class="go">cd ~/clang-llvm</span>
+<span class="go">git clone git://cmake.org/stage/cmake.git</span>
+<span class="go">cd cmake</span>
+<span class="go">git checkout next</span>
+<span class="go">./bootstrap</span>
+<span class="go">make</span>
+<span class="go">sudo make install</span>
+</pre></div>
+</div>
+<p>Okay. Now we’ll build Clang!</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">cd ~/clang-llvm</span>
+<span class="go">mkdir build && cd build</span>
+<span class="go">cmake -G Ninja ../llvm -DLLVM_BUILD_TESTS=ON  # Enable tests; default is off.</span>
+<span class="go">ninja</span>
+<span class="go">ninja check       # Test LLVM only.</span>
+<span class="go">ninja clang-test  # Test Clang only.</span>
+<span class="go">ninja install</span>
+</pre></div>
+</div>
+<p>And we’re live.</p>
+<p>All of the tests should pass, though there is a (very) small chance that
+you can catch LLVM and Clang out of sync. Running <tt class="docutils literal"><span class="pre">'git</span> <span class="pre">svn</span> <span class="pre">rebase'</span></tt>
+in both the llvm and clang directories should fix any problems.</p>
+<p>Finally, we want to set Clang as its own compiler.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">cd ~/clang-llvm/build</span>
+<span class="go">ccmake ../llvm</span>
+</pre></div>
+</div>
+<p>The second command will bring up a GUI for configuring Clang. You need
+to set the entry for <tt class="docutils literal"><span class="pre">CMAKE_CXX_COMPILER</span></tt>. Press <tt class="docutils literal"><span class="pre">'t'</span></tt> to turn on
+advanced mode. Scroll down to <tt class="docutils literal"><span class="pre">CMAKE_CXX_COMPILER</span></tt>, and set it to
+<tt class="docutils literal"><span class="pre">/usr/bin/clang++</span></tt>, or wherever you installed it. Press <tt class="docutils literal"><span class="pre">'c'</span></tt> to
+configure, then <tt class="docutils literal"><span class="pre">'g'</span></tt> to generate CMake’s files.</p>
+<p>Finally, run ninja one last time, and you’re done.</p>
+</div>
+<div class="section" id="step-1-create-a-clangtool">
+<h2>Step 1: Create a ClangTool<a class="headerlink" href="#step-1-create-a-clangtool" title="Permalink to this headline">Â¶</a></h2>
+<p>Now that we have enough background knowledge, it’s time to create the
+simplest productive ClangTool in existence: a syntax checker. While this
+already exists as <tt class="docutils literal"><span class="pre">clang-check</span></tt>, it’s important to understand what’s
+going on.</p>
+<p>First, we’ll need to create a new directory for our tool and tell CMake
+that it exists. As this is not going to be a core clang tool, it will
+live in the <tt class="docutils literal"><span class="pre">tools/extra</span></tt> repository.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">cd ~/clang-llvm/llvm/tools/clang</span>
+<span class="go">mkdir tools/extra/loop-convert</span>
+<span class="go">echo 'add_subdirectory(loop-convert)' >> tools/extra/CMakeLists.txt</span>
+<span class="go">vim tools/extra/loop-convert/CMakeLists.txt</span>
+</pre></div>
+</div>
+<p>CMakeLists.txt should have the following contents:</p>
+<div class="highlight-python"><div class="highlight"><pre>set(LLVM_LINK_COMPONENTS support)
+set(LLVM_USED_LIBS clangTooling clangBasic clangAST)
+
+add_clang_executable(loop-convert
+  LoopConvert.cpp
+  )
+target_link_libraries(loop-convert
+  clangTooling
+  clangBasic
+  clangASTMatchers
+  )
+</pre></div>
+</div>
+<p>With that done, Ninja will be able to compile our tool. Let’s give it
+something to compile! Put the following into
+<tt class="docutils literal"><span class="pre">tools/extra/loop-convert/LoopConvert.cpp</span></tt>. A detailed explanation of
+why the different parts are needed can be found in the <a class="reference external" href="LibTooling.html">LibTooling
+documentation</a>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Declares clang::SyntaxOnlyAction.</span>
+<span class="cp">#include "clang/Frontend/FrontendActions.h"</span>
+<span class="cp">#include "clang/Tooling/CommonOptionsParser.h"</span>
+<span class="cp">#include "clang/Tooling/Tooling.h"</span>
+<span class="c1">// Declares llvm::cl::extrahelp.</span>
+<span class="cp">#include "llvm/Support/CommandLine.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">clang</span><span class="o">::</span><span class="n">tooling</span><span class="p">;</span>
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="c1">// Apply a custom category to all command-line options so that they are the</span>
+<span class="c1">// only ones displayed.</span>
+<span class="k">static</span> <span class="n">llvm</span><span class="o">::</span><span class="n">cl</span><span class="o">::</span><span class="n">OptionCategory</span> <span class="n">MyToolCategory</span><span class="p">(</span><span class="s">"my-tool options"</span><span class="p">);</span>
+
+<span class="c1">// CommonOptionsParser declares HelpMessage with a description of the common</span>
+<span class="c1">// command-line options related to the compilation database and input files.</span>
+<span class="c1">// It's nice to have this help message in all tools.</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">extrahelp</span> <span class="n">CommonHelp</span><span class="p">(</span><span class="n">CommonOptionsParser</span><span class="o">::</span><span class="n">HelpMessage</span><span class="p">);</span>
+
+<span class="c1">// A help message for this specific tool can be added afterwards.</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">extrahelp</span> <span class="n">MoreHelp</span><span class="p">(</span><span class="s">"</span><span class="se">\n</span><span class="s">More help text..."</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">CommonOptionsParser</span> <span class="n">OptionsParser</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">,</span> <span class="n">MyToolCategory</span><span class="p">);</span>
+  <span class="n">ClangTool</span> <span class="n">Tool</span><span class="p">(</span><span class="n">OptionsParser</span><span class="p">.</span><span class="n">getCompilations</span><span class="p">(),</span>
+                 <span class="n">OptionsParser</span><span class="p">.</span><span class="n">getSourcePathList</span><span class="p">());</span>
+  <span class="k">return</span> <span class="n">Tool</span><span class="p">.</span><span class="n">run</span><span class="p">(</span><span class="n">newFrontendActionFactory</span><span class="o"><</span><span class="n">clang</span><span class="o">::</span><span class="n">SyntaxOnlyAction</span><span class="o">></span><span class="p">().</span><span class="n">get</span><span class="p">());</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>And that’s it! You can compile our new tool by running ninja from the
+<tt class="docutils literal"><span class="pre">build</span></tt> directory.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">cd ~/clang-llvm/build</span>
+<span class="go">ninja</span>
+</pre></div>
+</div>
+<p>You should now be able to run the syntax checker, which is located in
+<tt class="docutils literal"><span class="pre">~/clang-llvm/build/bin</span></tt>, on any source file. Try it!</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">echo "int main() { return 0; }" > test.cpp</span>
+<span class="go">bin/loop-convert test.cpp --</span>
+</pre></div>
+</div>
+<p>Note the two dashes after we specify the source file. The additional
+options for the compiler are passed after the dashes rather than loading
+them from a compilation database - there just aren’t any options needed
+right now.</p>
+</div>
+<div class="section" id="intermezzo-learn-ast-matcher-basics">
+<h2>Intermezzo: Learn AST matcher basics<a class="headerlink" href="#intermezzo-learn-ast-matcher-basics" title="Permalink to this headline">Â¶</a></h2>
+<p>Clang recently introduced the <a class="reference internal" href="LibASTMatchers.html"><em>ASTMatcher
+library</em></a> to provide a simple, powerful, and
+concise way to describe specific patterns in the AST. Implemented as a
+DSL powered by macros and templates (see
+<a class="reference external" href="../doxygen/ASTMatchers_8h_source.html">ASTMatchers.h</a> if you’re
+curious), matchers offer the feel of algebraic data types common to
+functional programming languages.</p>
+<p>For example, suppose you wanted to examine only binary operators. There
+is a matcher to do exactly that, conveniently named <tt class="docutils literal"><span class="pre">binaryOperator</span></tt>.
+I’ll give you one guess what this matcher does:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">binaryOperator</span><span class="p">(</span><span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"+"</span><span class="p">),</span> <span class="n">hasLHS</span><span class="p">(</span><span class="n">integerLiteral</span><span class="p">(</span><span class="n">equals</span><span class="p">(</span><span class="mi">0</span><span class="p">))))</span>
+</pre></div>
+</div>
+<p>Shockingly, it will match against addition expressions whose left hand
+side is exactly the literal 0. It will not match against other forms of
+0, such as <tt class="docutils literal"><span class="pre">'\0'</span></tt> or <tt class="docutils literal"><span class="pre">NULL</span></tt>, but it will match against macros that
+expand to 0. The matcher will also not match against calls to the
+overloaded operator <tt class="docutils literal"><span class="pre">'+'</span></tt>, as there is a separate <tt class="docutils literal"><span class="pre">operatorCallExpr</span></tt>
+matcher to handle overloaded operators.</p>
+<p>There are AST matchers to match all the different nodes of the AST,
+narrowing matchers to only match AST nodes fulfilling specific criteria,
+and traversal matchers to get from one kind of AST node to another. For
+a complete list of AST matchers, take a look at the <a class="reference external" href="LibASTMatchersReference.html">AST Matcher
+References</a></p>
+<p>All matcher that are nouns describe entities in the AST and can be
+bound, so that they can be referred to whenever a match is found. To do
+so, simply call the method <tt class="docutils literal"><span class="pre">bind</span></tt> on these matchers, e.g.:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">variable</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())).</span><span class="n">bind</span><span class="p">(</span><span class="s">"intvar"</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="step-2-using-ast-matchers">
+<h2>Step 2: Using AST matchers<a class="headerlink" href="#step-2-using-ast-matchers" title="Permalink to this headline">Â¶</a></h2>
+<p>Okay, on to using matchers for real. Let’s start by defining a matcher
+which will capture all <tt class="docutils literal"><span class="pre">for</span></tt> statements that define a new variable
+initialized to zero. Let’s start with matching all <tt class="docutils literal"><span class="pre">for</span></tt> loops:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">forStmt</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>Next, we want to specify that a single variable is declared in the first
+portion of the loop, so we can extend the matcher to</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">forStmt</span><span class="p">(</span><span class="n">hasLoopInit</span><span class="p">(</span><span class="n">declStmt</span><span class="p">(</span><span class="n">hasSingleDecl</span><span class="p">(</span><span class="n">varDecl</span><span class="p">()))))</span>
+</pre></div>
+</div>
+<p>Finally, we can add the condition that the variable is initialized to
+zero.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">forStmt</span><span class="p">(</span><span class="n">hasLoopInit</span><span class="p">(</span><span class="n">declStmt</span><span class="p">(</span><span class="n">hasSingleDecl</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span>
+  <span class="n">hasInitializer</span><span class="p">(</span><span class="n">integerLiteral</span><span class="p">(</span><span class="n">equals</span><span class="p">(</span><span class="mi">0</span><span class="p">))))))))</span>
+</pre></div>
+</div>
+<p>It is fairly easy to read and understand the matcher definition (“match
+loops whose init portion declares a single variable which is initialized
+to the integer literal 0”), but deciding that every piece is necessary
+is more difficult. Note that this matcher will not match loops whose
+variables are initialized to <tt class="docutils literal"><span class="pre">'\0'</span></tt>, <tt class="docutils literal"><span class="pre">0.0</span></tt>, <tt class="docutils literal"><span class="pre">NULL</span></tt>, or any form of
+zero besides the integer 0.</p>
+<p>The last step is giving the matcher a name and binding the <tt class="docutils literal"><span class="pre">ForStmt</span></tt>
+as we will want to do something with it:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">StatementMatcher</span> <span class="n">LoopMatcher</span> <span class="o">=</span>
+  <span class="n">forStmt</span><span class="p">(</span><span class="n">hasLoopInit</span><span class="p">(</span><span class="n">declStmt</span><span class="p">(</span><span class="n">hasSingleDecl</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span>
+    <span class="n">hasInitializer</span><span class="p">(</span><span class="n">integerLiteral</span><span class="p">(</span><span class="n">equals</span><span class="p">(</span><span class="mi">0</span><span class="p">)))))))).</span><span class="n">bind</span><span class="p">(</span><span class="s">"forLoop"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Once you have defined your matchers, you will need to add a little more
+scaffolding in order to run them. Matchers are paired with a
+<tt class="docutils literal"><span class="pre">MatchCallback</span></tt> and registered with a <tt class="docutils literal"><span class="pre">MatchFinder</span></tt> object, then run
+from a <tt class="docutils literal"><span class="pre">ClangTool</span></tt>. More code!</p>
+<p>Add the following to <tt class="docutils literal"><span class="pre">LoopConvert.cpp</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "clang/ASTMatchers/ASTMatchers.h"</span>
+<span class="cp">#include "clang/ASTMatchers/ASTMatchFinder.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">clang</span><span class="p">;</span>
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">clang</span><span class="o">::</span><span class="n">ast_matchers</span><span class="p">;</span>
+
+<span class="n">StatementMatcher</span> <span class="n">LoopMatcher</span> <span class="o">=</span>
+  <span class="n">forStmt</span><span class="p">(</span><span class="n">hasLoopInit</span><span class="p">(</span><span class="n">declStmt</span><span class="p">(</span><span class="n">hasSingleDecl</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span>
+    <span class="n">hasInitializer</span><span class="p">(</span><span class="n">integerLiteral</span><span class="p">(</span><span class="n">equals</span><span class="p">(</span><span class="mi">0</span><span class="p">)))))))).</span><span class="n">bind</span><span class="p">(</span><span class="s">"forLoop"</span><span class="p">);</span>
+
+<span class="k">class</span> <span class="nc">LoopPrinter</span> <span class="o">:</span> <span class="k">public</span> <span class="n">MatchFinder</span><span class="o">::</span><span class="n">MatchCallback</span> <span class="p">{</span>
+<span class="k">public</span> <span class="o">:</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="n">run</span><span class="p">(</span><span class="k">const</span> <span class="n">MatchFinder</span><span class="o">::</span><span class="n">MatchResult</span> <span class="o">&</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="k">const</span> <span class="n">ForStmt</span> <span class="o">*</span><span class="n">FS</span> <span class="o">=</span> <span class="n">Result</span><span class="p">.</span><span class="n">Nodes</span><span class="p">.</span><span class="n">getNodeAs</span><span class="o"><</span><span class="n">clang</span><span class="o">::</span><span class="n">ForStmt</span><span class="o">></span><span class="p">(</span><span class="s">"forLoop"</span><span class="p">))</span>
+      <span class="n">FS</span><span class="o">-></span><span class="n">dump</span><span class="p">();</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>And change <tt class="docutils literal"><span class="pre">main()</span></tt> to:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">CommonOptionsParser</span> <span class="n">OptionsParser</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">,</span> <span class="n">MyToolCategory</span><span class="p">);</span>
+  <span class="n">ClangTool</span> <span class="n">Tool</span><span class="p">(</span><span class="n">OptionsParser</span><span class="p">.</span><span class="n">getCompilations</span><span class="p">(),</span>
+                 <span class="n">OptionsParser</span><span class="p">.</span><span class="n">getSourcePathList</span><span class="p">());</span>
+
+  <span class="n">LoopPrinter</span> <span class="n">Printer</span><span class="p">;</span>
+  <span class="n">MatchFinder</span> <span class="n">Finder</span><span class="p">;</span>
+  <span class="n">Finder</span><span class="p">.</span><span class="n">addMatcher</span><span class="p">(</span><span class="n">LoopMatcher</span><span class="p">,</span> <span class="o">&</span><span class="n">Printer</span><span class="p">);</span>
+
+  <span class="k">return</span> <span class="n">Tool</span><span class="p">.</span><span class="n">run</span><span class="p">(</span><span class="n">newFrontendActionFactory</span><span class="p">(</span><span class="o">&</span><span class="n">Finder</span><span class="p">).</span><span class="n">get</span><span class="p">());</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Now, you should be able to recompile and run the code to discover for
+loops. Create a new file with a few examples, and test out our new
+handiwork:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">cd ~/clang-llvm/llvm/llvm_build/</span>
+<span class="go">ninja loop-convert</span>
+<span class="go">vim ~/test-files/simple-loops.cc</span>
+<span class="go">bin/loop-convert ~/test-files/simple-loops.cc</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="step-3-5-more-complicated-matchers">
+<h2>Step 3.5: More Complicated Matchers<a class="headerlink" href="#step-3-5-more-complicated-matchers" title="Permalink to this headline">Â¶</a></h2>
+<p>Our simple matcher is capable of discovering for loops, but we would
+still need to filter out many more ourselves. We can do a good portion
+of the remaining work with some cleverly chosen matchers, but first we
+need to decide exactly which properties we want to allow.</p>
+<p>How can we characterize for loops over arrays which would be eligible
+for translation to range-based syntax? Range based loops over arrays of
+size <tt class="docutils literal"><span class="pre">N</span></tt> that:</p>
+<ul class="simple">
+<li>start at index <tt class="docutils literal"><span class="pre">0</span></tt></li>
+<li>iterate consecutively</li>
+<li>end at index <tt class="docutils literal"><span class="pre">N-1</span></tt></li>
+</ul>
+<p>We already check for (1), so all we need to add is a check to the loop’s
+condition to ensure that the loop’s index variable is compared against
+<tt class="docutils literal"><span class="pre">N</span></tt> and another check to ensure that the increment step just
+increments this same variable. The matcher for (2) is straightforward:
+require a pre- or post-increment of the same variable declared in the
+init portion.</p>
+<p>Unfortunately, such a matcher is impossible to write. Matchers contain
+no logic for comparing two arbitrary AST nodes and determining whether
+or not they are equal, so the best we can do is matching more than we
+would like to allow, and punting extra comparisons to the callback.</p>
+<p>In any case, we can start building this sub-matcher. We can require that
+the increment step be a unary increment like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">hasIncrement</span><span class="p">(</span><span class="n">unaryOperator</span><span class="p">(</span><span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"++"</span><span class="p">)))</span>
+</pre></div>
+</div>
+<p>Specifying what is incremented introduces another quirk of Clang’s AST:
+Usages of variables are represented as <tt class="docutils literal"><span class="pre">DeclRefExpr</span></tt>‘s (“declaration
+reference expressions”) because they are expressions which refer to
+variable declarations. To find a <tt class="docutils literal"><span class="pre">unaryOperator</span></tt> that refers to a
+specific declaration, we can simply add a second condition to it:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">hasIncrement</span><span class="p">(</span><span class="n">unaryOperator</span><span class="p">(</span>
+  <span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"++"</span><span class="p">),</span>
+  <span class="n">hasUnaryOperand</span><span class="p">(</span><span class="n">declRefExpr</span><span class="p">())))</span>
+</pre></div>
+</div>
+<p>Furthermore, we can restrict our matcher to only match if the
+incremented variable is an integer:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">hasIncrement</span><span class="p">(</span><span class="n">unaryOperator</span><span class="p">(</span>
+  <span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"++"</span><span class="p">),</span>
+  <span class="n">hasUnaryOperand</span><span class="p">(</span><span class="n">declRefExpr</span><span class="p">(</span><span class="n">to</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())))))))</span>
+</pre></div>
+</div>
+<p>And the last step will be to attach an identifier to this variable, so
+that we can retrieve it in the callback:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">hasIncrement</span><span class="p">(</span><span class="n">unaryOperator</span><span class="p">(</span>
+  <span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"++"</span><span class="p">),</span>
+  <span class="n">hasUnaryOperand</span><span class="p">(</span><span class="n">declRefExpr</span><span class="p">(</span><span class="n">to</span><span class="p">(</span>
+    <span class="n">varDecl</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())).</span><span class="n">bind</span><span class="p">(</span><span class="s">"incrementVariable"</span><span class="p">))))))</span>
+</pre></div>
+</div>
+<p>We can add this code to the definition of <tt class="docutils literal"><span class="pre">LoopMatcher</span></tt> and make sure
+that our program, outfitted with the new matcher, only prints out loops
+that declare a single variable initialized to zero and have an increment
+step consisting of a unary increment of some variable.</p>
+<p>Now, we just need to add a matcher to check if the condition part of the
+<tt class="docutils literal"><span class="pre">for</span></tt> loop compares a variable against the size of the array. There is
+only one problem - we don’t know which array we’re iterating over
+without looking at the body of the loop! We are again restricted to
+approximating the result we want with matchers, filling in the details
+in the callback. So we start with:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">hasCondition</span><span class="p">(</span><span class="n">binaryOperator</span><span class="p">(</span><span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"<"</span><span class="p">))</span>
+</pre></div>
+</div>
+<p>It makes sense to ensure that the left-hand side is a reference to a
+variable, and that the right-hand side has integer type.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">hasCondition</span><span class="p">(</span><span class="n">binaryOperator</span><span class="p">(</span>
+  <span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"<"</span><span class="p">),</span>
+  <span class="n">hasLHS</span><span class="p">(</span><span class="n">declRefExpr</span><span class="p">(</span><span class="n">to</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">()))))),</span>
+  <span class="n">hasRHS</span><span class="p">(</span><span class="n">expr</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())))))</span>
+</pre></div>
+</div>
+<p>Why? Because it doesn’t work. Of the three loops provided in
+<tt class="docutils literal"><span class="pre">test-files/simple.cpp</span></tt>, zero of them have a matching condition. A
+quick look at the AST dump of the first for loop, produced by the
+previous iteration of loop-convert, shows us the answer:</p>
+<div class="highlight-python"><div class="highlight"><pre>(ForStmt 0x173b240
+  (DeclStmt 0x173afc8
+    0x173af50 "int i =
+      (IntegerLiteral 0x173afa8 'int' 0)")
+  <<>>
+  (BinaryOperator 0x173b060 '_Bool' '<'
+    (ImplicitCastExpr 0x173b030 'int'
+      (DeclRefExpr 0x173afe0 'int' lvalue Var 0x173af50 'i' 'int'))
+    (ImplicitCastExpr 0x173b048 'int'
+      (DeclRefExpr 0x173b008 'const int' lvalue Var 0x170fa80 'N' 'const int')))
+  (UnaryOperator 0x173b0b0 'int' lvalue prefix '++'
+    (DeclRefExpr 0x173b088 'int' lvalue Var 0x173af50 'i' 'int'))
+  (CompoundStatement ...
+</pre></div>
+</div>
+<p>We already know that the declaration and increments both match, or this
+loop wouldn’t have been dumped. The culprit lies in the implicit cast
+applied to the first operand (i.e. the LHS) of the less-than operator,
+an L-value to R-value conversion applied to the expression referencing
+<tt class="docutils literal"><span class="pre">i</span></tt>. Thankfully, the matcher library offers a solution to this problem
+in the form of <tt class="docutils literal"><span class="pre">ignoringParenImpCasts</span></tt>, which instructs the matcher to
+ignore implicit casts and parentheses before continuing to match.
+Adjusting the condition operator will restore the desired match.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">hasCondition</span><span class="p">(</span><span class="n">binaryOperator</span><span class="p">(</span>
+  <span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"<"</span><span class="p">),</span>
+  <span class="n">hasLHS</span><span class="p">(</span><span class="n">ignoringParenImpCasts</span><span class="p">(</span><span class="n">declRefExpr</span><span class="p">(</span>
+    <span class="n">to</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())))))),</span>
+  <span class="n">hasRHS</span><span class="p">(</span><span class="n">expr</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())))))</span>
+</pre></div>
+</div>
+<p>After adding binds to the expressions we wished to capture and
+extracting the identifier strings into variables, we have array-step-2
+completed.</p>
+</div>
+<div class="section" id="step-4-retrieving-matched-nodes">
+<h2>Step 4: Retrieving Matched Nodes<a class="headerlink" href="#step-4-retrieving-matched-nodes" title="Permalink to this headline">Â¶</a></h2>
+<p>So far, the matcher callback isn’t very interesting: it just dumps the
+loop’s AST. At some point, we will need to make changes to the input
+source code. Next, we’ll work on using the nodes we bound in the
+previous step.</p>
+<p>The <tt class="docutils literal"><span class="pre">MatchFinder::run()</span></tt> callback takes a
+<tt class="docutils literal"><span class="pre">MatchFinder::MatchResult&</span></tt> as its parameter. We’re most interested in
+its <tt class="docutils literal"><span class="pre">Context</span></tt> and <tt class="docutils literal"><span class="pre">Nodes</span></tt> members. Clang uses the <tt class="docutils literal"><span class="pre">ASTContext</span></tt>
+class to represent contextual information about the AST, as the name
+implies, though the most functionally important detail is that several
+operations require an <tt class="docutils literal"><span class="pre">ASTContext*</span></tt> parameter. More immediately useful
+is the set of matched nodes, and how we retrieve them.</p>
+<p>Since we bind three variables (identified by ConditionVarName,
+InitVarName, and IncrementVarName), we can obtain the matched nodes by
+using the <tt class="docutils literal"><span class="pre">getNodeAs()</span></tt> member function.</p>
+<p>In <tt class="docutils literal"><span class="pre">LoopConvert.cpp</span></tt> add</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "clang/AST/ASTContext.h"</span>
+</pre></div>
+</div>
+<p>Change <tt class="docutils literal"><span class="pre">LoopMatcher</span></tt> to</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">StatementMatcher</span> <span class="n">LoopMatcher</span> <span class="o">=</span>
+    <span class="n">forStmt</span><span class="p">(</span><span class="n">hasLoopInit</span><span class="p">(</span><span class="n">declStmt</span><span class="p">(</span>
+                <span class="n">hasSingleDecl</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span><span class="n">hasInitializer</span><span class="p">(</span><span class="n">integerLiteral</span><span class="p">(</span><span class="n">equals</span><span class="p">(</span><span class="mi">0</span><span class="p">))))</span>
+                                  <span class="p">.</span><span class="n">bind</span><span class="p">(</span><span class="s">"initVarName"</span><span class="p">)))),</span>
+            <span class="n">hasIncrement</span><span class="p">(</span><span class="n">unaryOperator</span><span class="p">(</span>
+                <span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"++"</span><span class="p">),</span>
+                <span class="n">hasUnaryOperand</span><span class="p">(</span><span class="n">declRefExpr</span><span class="p">(</span>
+                    <span class="n">to</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())).</span><span class="n">bind</span><span class="p">(</span><span class="s">"incVarName"</span><span class="p">)))))),</span>
+            <span class="n">hasCondition</span><span class="p">(</span><span class="n">binaryOperator</span><span class="p">(</span>
+                <span class="n">hasOperatorName</span><span class="p">(</span><span class="s">"<"</span><span class="p">),</span>
+                <span class="n">hasLHS</span><span class="p">(</span><span class="n">ignoringParenImpCasts</span><span class="p">(</span><span class="n">declRefExpr</span><span class="p">(</span>
+                    <span class="n">to</span><span class="p">(</span><span class="n">varDecl</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())).</span><span class="n">bind</span><span class="p">(</span><span class="s">"condVarName"</span><span class="p">))))),</span>
+                <span class="n">hasRHS</span><span class="p">(</span><span class="n">expr</span><span class="p">(</span><span class="n">hasType</span><span class="p">(</span><span class="n">isInteger</span><span class="p">())))))).</span><span class="n">bind</span><span class="p">(</span><span class="s">"forLoop"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>And change <tt class="docutils literal"><span class="pre">LoopPrinter::run</span></tt> to</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">LoopPrinter</span><span class="o">::</span><span class="n">run</span><span class="p">(</span><span class="k">const</span> <span class="n">MatchFinder</span><span class="o">::</span><span class="n">MatchResult</span> <span class="o">&</span><span class="n">Result</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">ASTContext</span> <span class="o">*</span><span class="n">Context</span> <span class="o">=</span> <span class="n">Result</span><span class="p">.</span><span class="n">Context</span><span class="p">;</span>
+  <span class="k">const</span> <span class="n">ForStmt</span> <span class="o">*</span><span class="n">FS</span> <span class="o">=</span> <span class="n">Result</span><span class="p">.</span><span class="n">Nodes</span><span class="p">.</span><span class="n">getStmtAs</span><span class="o"><</span><span class="n">ForStmt</span><span class="o">></span><span class="p">(</span><span class="s">"forLoop"</span><span class="p">);</span>
+  <span class="c1">// We do not want to convert header files!</span>
+  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">FS</span> <span class="o">||</span> <span class="o">!</span><span class="n">Context</span><span class="o">-></span><span class="n">getSourceManager</span><span class="p">().</span><span class="n">isFromMainFile</span><span class="p">(</span><span class="n">FS</span><span class="o">-></span><span class="n">getForLoc</span><span class="p">()))</span>
+    <span class="k">return</span><span class="p">;</span>
+  <span class="k">const</span> <span class="n">VarDecl</span> <span class="o">*</span><span class="n">IncVar</span> <span class="o">=</span> <span class="n">Result</span><span class="p">.</span><span class="n">Nodes</span><span class="p">.</span><span class="n">getNodeAs</span><span class="o"><</span><span class="n">VarDecl</span><span class="o">></span><span class="p">(</span><span class="s">"incVarName"</span><span class="p">);</span>
+  <span class="k">const</span> <span class="n">VarDecl</span> <span class="o">*</span><span class="n">CondVar</span> <span class="o">=</span> <span class="n">Result</span><span class="p">.</span><span class="n">Nodes</span><span class="p">.</span><span class="n">getNodeAs</span><span class="o"><</span><span class="n">VarDecl</span><span class="o">></span><span class="p">(</span><span class="s">"condVarName"</span><span class="p">);</span>
+  <span class="k">const</span> <span class="n">VarDecl</span> <span class="o">*</span><span class="n">InitVar</span> <span class="o">=</span> <span class="n">Result</span><span class="p">.</span><span class="n">Nodes</span><span class="p">.</span><span class="n">getNodeAs</span><span class="o"><</span><span class="n">VarDecl</span><span class="o">></span><span class="p">(</span><span class="s">"initVarName"</span><span class="p">);</span>
+
+  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">areSameVariable</span><span class="p">(</span><span class="n">IncVar</span><span class="p">,</span> <span class="n">CondVar</span><span class="p">)</span> <span class="o">||</span> <span class="o">!</span><span class="n">areSameVariable</span><span class="p">(</span><span class="n">IncVar</span><span class="p">,</span> <span class="n">InitVar</span><span class="p">))</span>
+    <span class="k">return</span><span class="p">;</span>
+  <span class="n">llvm</span><span class="o">::</span><span class="n">outs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"Potential array-based loop discovered.</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Clang associates a <tt class="docutils literal"><span class="pre">VarDecl</span></tt> with each variable to represent the variable’s
+declaration. Since the “canonical” form of each declaration is unique by
+address, all we need to do is make sure neither <tt class="docutils literal"><span class="pre">ValueDecl</span></tt> (base class of
+<tt class="docutils literal"><span class="pre">VarDecl</span></tt>) is <tt class="docutils literal"><span class="pre">NULL</span></tt> and compare the canonical Decls.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="kt">bool</span> <span class="nf">areSameVariable</span><span class="p">(</span><span class="k">const</span> <span class="n">ValueDecl</span> <span class="o">*</span><span class="n">First</span><span class="p">,</span> <span class="k">const</span> <span class="n">ValueDecl</span> <span class="o">*</span><span class="n">Second</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">First</span> <span class="o">&&</span> <span class="n">Second</span> <span class="o">&&</span>
+         <span class="n">First</span><span class="o">-></span><span class="n">getCanonicalDecl</span><span class="p">()</span> <span class="o">==</span> <span class="n">Second</span><span class="o">-></span><span class="n">getCanonicalDecl</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If execution reaches the end of <tt class="docutils literal"><span class="pre">LoopPrinter::run()</span></tt>, we know that the
+loop shell that looks like</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="kt">int</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">expr</span><span class="p">();</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>For now, we will just print a message explaining that we found a loop.
+The next section will deal with recursively traversing the AST to
+discover all changes needed.</p>
+<p>As a side note, it’s not as trivial to test if two expressions are the same,
+though Clang has already done the hard work for us by providing a way to
+canonicalize expressions:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="kt">bool</span> <span class="nf">areSameExpr</span><span class="p">(</span><span class="n">ASTContext</span> <span class="o">*</span><span class="n">Context</span><span class="p">,</span> <span class="k">const</span> <span class="n">Expr</span> <span class="o">*</span><span class="n">First</span><span class="p">,</span>
+                        <span class="k">const</span> <span class="n">Expr</span> <span class="o">*</span><span class="n">Second</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">First</span> <span class="o">||</span> <span class="o">!</span><span class="n">Second</span><span class="p">)</span>
+    <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+  <span class="n">llvm</span><span class="o">::</span><span class="n">FoldingSetNodeID</span> <span class="n">FirstID</span><span class="p">,</span> <span class="n">SecondID</span><span class="p">;</span>
+  <span class="n">First</span><span class="o">-></span><span class="n">Profile</span><span class="p">(</span><span class="n">FirstID</span><span class="p">,</span> <span class="o">*</span><span class="n">Context</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span>
+  <span class="n">Second</span><span class="o">-></span><span class="n">Profile</span><span class="p">(</span><span class="n">SecondID</span><span class="p">,</span> <span class="o">*</span><span class="n">Context</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span>
+  <span class="k">return</span> <span class="n">FirstID</span> <span class="o">==</span> <span class="n">SecondID</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This code relies on the comparison between two
+<tt class="docutils literal"><span class="pre">llvm::FoldingSetNodeIDs</span></tt>. As the documentation for
+<tt class="docutils literal"><span class="pre">Stmt::Profile()</span></tt> indicates, the <tt class="docutils literal"><span class="pre">Profile()</span></tt> member function builds
+a description of a node in the AST, based on its properties, along with
+those of its children. <tt class="docutils literal"><span class="pre">FoldingSetNodeID</span></tt> then serves as a hash we can
+use to compare expressions. We will need <tt class="docutils literal"><span class="pre">areSameExpr</span></tt> later. Before
+you run the new code on the additional loops added to
+test-files/simple.cpp, try to figure out which ones will be considered
+potentially convertible.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="RAVFrontendAction.html">How to write RecursiveASTVisitor based ASTFrontendActions.</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibASTMatchers.html">Matching the Clang AST</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/LibFormat.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/LibFormat.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/LibFormat.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/LibFormat.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,112 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>LibFormat — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Clang Plugins" href="ClangPlugins.html" />
+    <link rel="prev" title="LibTooling" href="LibTooling.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>LibFormat</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="LibTooling.html">LibTooling</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangPlugins.html">Clang Plugins</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="libformat">
+<h1>LibFormat<a class="headerlink" href="#libformat" title="Permalink to this headline">Â¶</a></h1>
+<p>LibFormat is a library that implements automatic source code formatting based
+on Clang. This documents describes the LibFormat interface and design as well
+as some basic style discussions.</p>
+<p>If you just want to use <cite>clang-format</cite> as a tool or integrated into an editor,
+checkout <a class="reference internal" href="ClangFormat.html"><em>ClangFormat</em></a>.</p>
+<div class="section" id="design">
+<h2>Design<a class="headerlink" href="#design" title="Permalink to this headline">Â¶</a></h2>
+<p>FIXME: Write up design.</p>
+</div>
+<div class="section" id="interface">
+<h2>Interface<a class="headerlink" href="#interface" title="Permalink to this headline">Â¶</a></h2>
+<p>The core routine of LibFormat is <tt class="docutils literal"><span class="pre">reformat()</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">tooling</span><span class="o">::</span><span class="n">Replacements</span> <span class="n">reformat</span><span class="p">(</span><span class="k">const</span> <span class="n">FormatStyle</span> <span class="o">&</span><span class="n">Style</span><span class="p">,</span> <span class="n">Lexer</span> <span class="o">&</span><span class="n">Lex</span><span class="p">,</span>
+                               <span class="n">SourceManager</span> <span class="o">&</span><span class="n">SourceMgr</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">CharSourceRange</span><span class="o">></span> <span class="n">Ranges</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This reads a token stream out of the lexer <tt class="docutils literal"><span class="pre">Lex</span></tt> and reformats all the code
+ranges in <tt class="docutils literal"><span class="pre">Ranges</span></tt>. The <tt class="docutils literal"><span class="pre">FormatStyle</span></tt> controls basic decisions made during
+formatting. A list of options can be found under <a class="reference internal" href="#style-options"><em>Style Options</em></a>.</p>
+</div>
+<div class="section" id="style-options">
+<span id="id1"></span><h2>Style Options<a class="headerlink" href="#style-options" title="Permalink to this headline">Â¶</a></h2>
+<p>The style options describe specific formatting options that can be used in
+order to make <cite>ClangFormat</cite> comply with different style guides. Currently,
+two style guides are hard-coded:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">/// \brief Returns a format style complying with the LLVM coding standards:</span>
+<span class="c1">/// http://llvm.org/docs/CodingStandards.html.</span>
+<span class="n">FormatStyle</span> <span class="nf">getLLVMStyle</span><span class="p">();</span>
+
+<span class="c1">/// \brief Returns a format style complying with Google's C++ style guide:</span>
+<span class="c1">/// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.</span>
+<span class="n">FormatStyle</span> <span class="nf">getGoogleStyle</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>These options are also exposed in the <a class="reference internal" href="ClangFormat.html"><em>standalone tools</em></a>
+through the <cite>-style</cite> option.</p>
+<p>In the future, we plan on making this configurable.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="LibTooling.html">LibTooling</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangPlugins.html">Clang Plugins</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/LibTooling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/LibTooling.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/LibTooling.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/LibTooling.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,242 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>LibTooling — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="LibFormat" href="LibFormat.html" />
+    <link rel="prev" title="Introduction to the Clang AST" href="IntroductionToTheClangAST.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>LibTooling</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibFormat.html">LibFormat</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="libtooling">
+<h1>LibTooling<a class="headerlink" href="#libtooling" title="Permalink to this headline">Â¶</a></h1>
+<p>LibTooling is a library to support writing standalone tools based on Clang.
+This document will provide a basic walkthrough of how to write a tool using
+LibTooling.</p>
+<p>For the information on how to setup Clang Tooling for LLVM see
+<a class="reference internal" href="HowToSetupToolingForLLVM.html"><em>How To Setup Clang Tooling For LLVM</em></a></p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>Tools built with LibTooling, like Clang Plugins, run <tt class="docutils literal"><span class="pre">FrontendActions</span></tt> over
+code.</p>
+<p>In this tutorial, we’ll demonstrate the different ways of running Clang’s
+<tt class="docutils literal"><span class="pre">SyntaxOnlyAction</span></tt>, which runs a quick syntax check, over a bunch of code.</p>
+</div>
+<div class="section" id="parsing-a-code-snippet-in-memory">
+<h2>Parsing a code snippet in memory<a class="headerlink" href="#parsing-a-code-snippet-in-memory" title="Permalink to this headline">Â¶</a></h2>
+<p>If you ever wanted to run a <tt class="docutils literal"><span class="pre">FrontendAction</span></tt> over some sample code, for
+example to unit test parts of the Clang AST, <tt class="docutils literal"><span class="pre">runToolOnCode</span></tt> is what you
+looked for.  Let me give you an example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "clang/Tooling/Tooling.h"</span>
+
+<span class="n">TEST</span><span class="p">(</span><span class="n">runToolOnCode</span><span class="p">,</span> <span class="n">CanSyntaxCheckCode</span><span class="p">)</span> <span class="p">{</span>
+  <span class="c1">// runToolOnCode returns whether the action was correctly run over the</span>
+  <span class="c1">// given code.</span>
+  <span class="n">EXPECT_TRUE</span><span class="p">(</span><span class="n">runToolOnCode</span><span class="p">(</span><span class="k">new</span> <span class="n">clang</span><span class="o">::</span><span class="n">SyntaxOnlyAction</span><span class="p">,</span> <span class="s">"class X {};"</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="writing-a-standalone-tool">
+<h2>Writing a standalone tool<a class="headerlink" href="#writing-a-standalone-tool" title="Permalink to this headline">Â¶</a></h2>
+<p>Once you unit tested your <tt class="docutils literal"><span class="pre">FrontendAction</span></tt> to the point where it cannot
+possibly break, it’s time to create a standalone tool.  For a standalone tool
+to run clang, it first needs to figure out what command line arguments to use
+for a specified file.  To that end we create a <tt class="docutils literal"><span class="pre">CompilationDatabase</span></tt>.  There
+are different ways to create a compilation database, and we need to support all
+of them depending on command-line options.  There’s the <tt class="docutils literal"><span class="pre">CommonOptionsParser</span></tt>
+class that takes the responsibility to parse command-line parameters related to
+compilation databases and inputs, so that all tools share the implementation.</p>
+<div class="section" id="parsing-common-tools-options">
+<h3>Parsing common tools options<a class="headerlink" href="#parsing-common-tools-options" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">CompilationDatabase</span></tt> can be read from a build directory or the command line.
+Using <tt class="docutils literal"><span class="pre">CommonOptionsParser</span></tt> allows for explicit specification of a compile
+command line, specification of build path using the <tt class="docutils literal"><span class="pre">-p</span></tt> command-line option,
+and automatic location of the compilation database using source files paths.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "clang/Tooling/CommonOptionsParser.h"</span>
+<span class="cp">#include "llvm/Support/CommandLine.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">clang</span><span class="o">::</span><span class="n">tooling</span><span class="p">;</span>
+
+<span class="c1">// Apply a custom category to all command-line options so that they are the</span>
+<span class="c1">// only ones displayed.</span>
+<span class="k">static</span> <span class="n">llvm</span><span class="o">::</span><span class="n">cl</span><span class="o">::</span><span class="n">OptionCategory</span> <span class="n">MyToolCategory</span><span class="p">(</span><span class="s">"my-tool options"</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+  <span class="c1">// CommonOptionsParser constructor will parse arguments and create a</span>
+  <span class="c1">// CompilationDatabase.  In case of error it will terminate the program.</span>
+  <span class="n">CommonOptionsParser</span> <span class="n">OptionsParser</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">,</span> <span class="n">MyToolCategory</span><span class="p">);</span>
+
+  <span class="c1">// Use OptionsParser.getCompilations() and OptionsParser.getSourcePathList()</span>
+  <span class="c1">// to retrieve CompilationDatabase and the list of input file paths.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="creating-and-running-a-clangtool">
+<h3>Creating and running a ClangTool<a class="headerlink" href="#creating-and-running-a-clangtool" title="Permalink to this headline">Â¶</a></h3>
+<p>Once we have a <tt class="docutils literal"><span class="pre">CompilationDatabase</span></tt>, we can create a <tt class="docutils literal"><span class="pre">ClangTool</span></tt> and run
+our <tt class="docutils literal"><span class="pre">FrontendAction</span></tt> over some code.  For example, to run the
+<tt class="docutils literal"><span class="pre">SyntaxOnlyAction</span></tt> over the files “a.cc” and “b.cc” one would write:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// A clang tool can run over a number of sources in the same process...</span>
+<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="n">Sources</span><span class="p">;</span>
+<span class="n">Sources</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="s">"a.cc"</span><span class="p">);</span>
+<span class="n">Sources</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="s">"b.cc"</span><span class="p">);</span>
+
+<span class="c1">// We hand the CompilationDatabase we created and the sources to run over into</span>
+<span class="c1">// the tool constructor.</span>
+<span class="n">ClangTool</span> <span class="nf">Tool</span><span class="p">(</span><span class="n">OptionsParser</span><span class="p">.</span><span class="n">getCompilations</span><span class="p">(),</span> <span class="n">Sources</span><span class="p">);</span>
+
+<span class="c1">// The ClangTool needs a new FrontendAction for each translation unit we run</span>
+<span class="c1">// on.  Thus, it takes a FrontendActionFactory as parameter.  To create a</span>
+<span class="c1">// FrontendActionFactory from a given FrontendAction type, we call</span>
+<span class="c1">// newFrontendActionFactory<clang::SyntaxOnlyAction>().</span>
+<span class="kt">int</span> <span class="n">result</span> <span class="o">=</span> <span class="n">Tool</span><span class="p">.</span><span class="n">run</span><span class="p">(</span><span class="n">newFrontendActionFactory</span><span class="o"><</span><span class="n">clang</span><span class="o">::</span><span class="n">SyntaxOnlyAction</span><span class="o">></span><span class="p">().</span><span class="n">get</span><span class="p">());</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="putting-it-together-the-first-tool">
+<h3>Putting it together — the first tool<a class="headerlink" href="#putting-it-together-the-first-tool" title="Permalink to this headline">Â¶</a></h3>
+<p>Now we combine the two previous steps into our first real tool.  A more advanced
+version of this example tool is also checked into the clang tree at
+<tt class="docutils literal"><span class="pre">tools/clang-check/ClangCheck.cpp</span></tt>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Declares clang::SyntaxOnlyAction.</span>
+<span class="cp">#include "clang/Frontend/FrontendActions.h"</span>
+<span class="cp">#include "clang/Tooling/CommonOptionsParser.h"</span>
+<span class="cp">#include "clang/Tooling/Tooling.h"</span>
+<span class="c1">// Declares llvm::cl::extrahelp.</span>
+<span class="cp">#include "llvm/Support/CommandLine.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">clang</span><span class="o">::</span><span class="n">tooling</span><span class="p">;</span>
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="c1">// Apply a custom category to all command-line options so that they are the</span>
+<span class="c1">// only ones displayed.</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">OptionCategory</span> <span class="n">MyToolCategory</span><span class="p">(</span><span class="s">"my-tool options"</span><span class="p">);</span>
+
+<span class="c1">// CommonOptionsParser declares HelpMessage with a description of the common</span>
+<span class="c1">// command-line options related to the compilation database and input files.</span>
+<span class="c1">// It's nice to have this help message in all tools.</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">extrahelp</span> <span class="n">CommonHelp</span><span class="p">(</span><span class="n">CommonOptionsParser</span><span class="o">::</span><span class="n">HelpMessage</span><span class="p">);</span>
+
+<span class="c1">// A help message for this specific tool can be added afterwards.</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">extrahelp</span> <span class="n">MoreHelp</span><span class="p">(</span><span class="s">"</span><span class="se">\n</span><span class="s">More help text..."</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">CommonOptionsParser</span> <span class="n">OptionsParser</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">,</span> <span class="n">MyToolCategory</span><span class="p">);</span>
+  <span class="n">ClangTool</span> <span class="n">Tool</span><span class="p">(</span><span class="n">OptionsParser</span><span class="p">.</span><span class="n">getCompilations</span><span class="p">(),</span>
+                 <span class="n">OptionsParser</span><span class="p">.</span><span class="n">getSourcePathList</span><span class="p">());</span>
+  <span class="k">return</span> <span class="n">Tool</span><span class="p">.</span><span class="n">run</span><span class="p">(</span><span class="n">newFrontendActionFactory</span><span class="o"><</span><span class="n">clang</span><span class="o">::</span><span class="n">SyntaxOnlyAction</span><span class="o">></span><span class="p">().</span><span class="n">get</span><span class="p">());</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="running-the-tool-on-some-code">
+<h3>Running the tool on some code<a class="headerlink" href="#running-the-tool-on-some-code" title="Permalink to this headline">Â¶</a></h3>
+<p>When you check out and build clang, clang-check is already built and available
+to you in bin/clang-check inside your build directory.</p>
+<p>You can run clang-check on a file in the llvm repository by specifying all the
+needed parameters after a “<tt class="docutils literal"><span class="pre">--</span></tt>” separator:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span><span class="nb">cd</span> /path/to/source/llvm
+<span class="nv">$ </span><span class="nb">export </span><span class="nv">BD</span><span class="o">=</span>/path/to/build/llvm
+<span class="nv">$ $BD</span>/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- <span class="se">\</span>
+      clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS <span class="se">\</span>
+      -Itools/clang/include -I<span class="nv">$BD</span>/include -Iinclude <span class="se">\</span>
+      -Itools/clang/lib/Headers -c
+</pre></div>
+</div>
+<p>As an alternative, you can also configure cmake to output a compile command
+database into its build directory:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Alternatively to calling cmake, use ccmake, toggle to advanced mode and</span>
+<span class="c"># set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.</span>
+<span class="nv">$ </span>cmake -DCMAKE_EXPORT_COMPILE_COMMANDS<span class="o">=</span>ON .
+</pre></div>
+</div>
+<p>This creates a file called <tt class="docutils literal"><span class="pre">compile_commands.json</span></tt> in the build directory.
+Now you can run <strong class="program">clang-check</strong> over files in the project by specifying
+the build path as first argument and some source files as further positional
+arguments:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span><span class="nb">cd</span> /path/to/source/llvm
+<span class="nv">$ </span><span class="nb">export </span><span class="nv">BD</span><span class="o">=</span>/path/to/build/llvm
+<span class="nv">$ $BD</span>/bin/clang-check -p <span class="nv">$BD</span> tools/clang/tools/clang-check/ClangCheck.cpp
+</pre></div>
+</div>
+</div>
+<div class="section" id="builtin-includes">
+<span id="libtooling-builtin-includes"></span><h3>Builtin includes<a class="headerlink" href="#builtin-includes" title="Permalink to this headline">Â¶</a></h3>
+<p>Clang tools need their builtin headers and search for them the same way Clang
+does.  Thus, the default location to look for builtin headers is in a path
+<tt class="docutils literal"><span class="pre">$(dirname</span> <span class="pre">/path/to/tool)/../lib/clang/3.3/include</span></tt> relative to the tool
+binary.  This works out-of-the-box for tools running from llvm’s toplevel
+binary directory after building clang-headers, or if the tool is running from
+the binary directory of a clang install next to the clang binary.</p>
+<p>Tips: if your tool fails to find <tt class="docutils literal"><span class="pre">stddef.h</span></tt> or similar headers, call the tool
+with <tt class="docutils literal"><span class="pre">-v</span></tt> and look at the search paths it looks through.</p>
+</div>
+<div class="section" id="linking">
+<h3>Linking<a class="headerlink" href="#linking" title="Permalink to this headline">Â¶</a></h3>
+<p>For a list of libraries to link, look at one of the tools’ Makefiles (for
+example <a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup">clang-check/Makefile</a>).</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibFormat.html">LibFormat</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/MSVCCompatibility.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/MSVCCompatibility.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/MSVCCompatibility.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/MSVCCompatibility.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,190 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>MSVC compatibility — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Clang âmanâ pages" href="CommandGuide/index.html" />
+    <link rel="prev" title="Modules" href="Modules.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>MSVC compatibility</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="Modules.html">Modules</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="CommandGuide/index.html">Clang “man” pages</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <style type="text/css">
+  .none { background-color: #FFCCCC }
+  .partial { background-color: #FFFF99 }
+  .good { background-color: #CCFF99 }
+</style><div class="section" id="msvc-compatibility">
+<h1>MSVC compatibility<a class="headerlink" href="#msvc-compatibility" title="Permalink to this headline">Â¶</a></h1>
+<p>When Clang compiles C++ code for Windows, it attempts to be compatible with
+MSVC.  There are multiple dimensions to compatibility.</p>
+<p>First, Clang attempts to be ABI-compatible, meaning that Clang-compiled code
+should be able to link against MSVC-compiled code successfully.  However, C++
+ABIs are particularly large and complicated, and Clang’s support for MSVC’s C++
+ABI is a work in progress.  If you don’t require MSVC ABI compatibility or don’t
+want to use Microsoft’s C and C++ runtimes, the mingw32 toolchain might be a
+better fit for your project.</p>
+<p>Second, Clang implements many MSVC language extensions, such as
+<tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> and a handful of pragmas.  These are typically
+controlled by <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt>.</p>
+<p>Third, MSVC accepts some C++ code that Clang will typically diagnose as
+invalid.  When these constructs are present in widely included system headers,
+Clang attempts to recover and continue compiling the user’s program.  Most
+parsing and semantic compatibility tweaks are controlled by
+<tt class="docutils literal"><span class="pre">-fms-compatibility</span></tt> and <tt class="docutils literal"><span class="pre">-fdelayed-template-parsing</span></tt>, and they are a work
+in progress.</p>
+<p>Finally, there is <a class="reference internal" href="UsersManual.html#clang-cl"><em>clang-cl</em></a>, a driver program for clang that attempts to
+be compatible with MSVC’s cl.exe.</p>
+<div class="section" id="abi-features">
+<h2>ABI features<a class="headerlink" href="#abi-features" title="Permalink to this headline">Â¶</a></h2>
+<p>The status of major ABI-impacting C++ features:</p>
+<ul class="simple">
+<li>Record layout: <span class="good">Complete</span>.  We’ve tested this with a fuzzer and have
+fixed all known bugs.</li>
+<li>Class inheritance: <span class="good">Mostly complete</span>.  This covers all of the standard
+OO features you would expect: virtual method inheritance, multiple
+inheritance, and virtual inheritance.  Every so often we uncover a bug where
+our tables are incompatible, but this is pretty well in hand.  This feature
+has also been fuzz tested.</li>
+<li>Name mangling: <span class="good">Ongoing</span>.  Every new C++ feature generally needs its own
+mangling.  For example, member pointer template arguments have an interesting
+and distinct mangling.  Fortunately, incorrect manglings usually do not result
+in runtime errors.  Non-inline functions with incorrect manglings usually
+result in link errors, which are relatively easy to diagnose.  Incorrect
+manglings for inline functions and templates result in multiple copies in the
+final image.  The C++ standard requires that those addresses be equal, but few
+programs rely on this.</li>
+<li>Member pointers: <span class="good">Mostly complete</span>.  Standard C++ member pointers are
+fully implemented and should be ABI compatible.  Both <a class="reference external" href="http://msdn.microsoft.com/en-us/library/83cch5a6.aspx">#pragma
+pointers_to_members</a> and the <a class="reference external" href="http://msdn.microsoft.com/en-us/library/yad46a6z.aspx">/vm</a> flags are supported. However, MSVC
+supports an extension to allow creating a <a class="reference external" href="http://llvm.org/PR15713">pointer to a member of a virtual
+base class</a>.  Clang does not yet support this.</li>
+</ul>
+<ul class="simple">
+<li>Debug info: <span class="partial">Minimal</span>.  Clang emits both CodeView line tables
+(similar to what MSVC emits when given the <tt class="docutils literal"><span class="pre">/Z7</span></tt> flag) and DWARF debug
+information into the object file.
+Microsoft’s link.exe will transform the CodeView line tables into a PDB,
+enabling stack traces in all modern Windows debuggers.  Clang does not emit
+any CodeView-compatible type info or description of variable layout.
+Binaries linked with either binutils’ ld or LLVM’s lld should be usable with
+GDB however sophisticated C++ expressions are likely to fail.</li>
+<li>RTTI: <span class="good">Complete</span>.  Generation of RTTI data structures has been
+finished, along with support for the <tt class="docutils literal"><span class="pre">/GR</span></tt> flag.</li>
+<li>Exceptions and SEH: <span class="partial">Partial</span>.
+C++ exceptions (<tt class="docutils literal"><span class="pre">try</span></tt> / <tt class="docutils literal"><span class="pre">catch</span></tt> / <tt class="docutils literal"><span class="pre">throw</span></tt>) and
+structured exceptions (<tt class="docutils literal"><span class="pre">__try</span></tt> / <tt class="docutils literal"><span class="pre">__except</span></tt> / <tt class="docutils literal"><span class="pre">__finally</span></tt>) mostly
+work on x64. 32-bit exception handling support is being worked on.  LLVM does
+not model asynchronous exceptions, so it is currently impossible to catch an
+asynchronous exception generated in the same frame as the catching <tt class="docutils literal"><span class="pre">__try</span></tt>.
+C++ exception specifications are ignored, but this is <a class="reference external" href="https://msdn.microsoft.com/en-us/library/wfa0edys.aspx">consistent with Visual
+C++</a>.</li>
+</ul>
+<ul class="simple">
+<li>Thread-safe initialization of local statics: <span class="good">Complete</span>.  MSVC 2015
+added support for thread-safe initialization of such variables by taking an
+ABI break.
+We are ABI compatible with both the MSVC 2013 and 2015 ABI for static local
+variables.</li>
+<li>Lambdas: <span class="good">Mostly complete</span>.  Clang is compatible with Microsoft’s
+implementation of lambdas except for providing overloads for conversion to
+function pointer for different calling conventions.  However, Microsoft’s
+extension is non-conforming.</li>
+</ul>
+</div>
+<div class="section" id="template-instantiation-and-name-lookup">
+<h2>Template instantiation and name lookup<a class="headerlink" href="#template-instantiation-and-name-lookup" title="Permalink to this headline">Â¶</a></h2>
+<p>MSVC allows many invalid constructs in class templates that Clang has
+historically rejected.  In order to parse widely distributed headers for
+libraries such as the Active Template Library (ATL) and Windows Runtime Library
+(WRL), some template rules have been relaxed or extended in Clang on Windows.</p>
+<p>The first major semantic difference is that MSVC appears to defer all parsing
+an analysis of inline method bodies in class templates until instantiation
+time.  By default on Windows, Clang attempts to follow suit.  This behavior is
+controlled by the <tt class="docutils literal"><span class="pre">-fdelayed-template-parsing</span></tt> flag.  While Clang delays
+parsing of method bodies, it still parses the bodies <em>before</em> template argument
+substitution, which is not what MSVC does.  The following compatibility tweaks
+are necessary to parse the template in those cases.</p>
+<p>MSVC allows some name lookup into dependent base classes.  Even on other
+platforms, this has been a <a class="reference external" href="http://clang.llvm.org/compatibility.html#dep_lookup">frequently asked question</a> for Clang users.  A
+dependent base class is a base class that depends on the value of a template
+parameter.  Clang cannot see any of the names inside dependent bases while it
+is parsing your template, so the user is sometimes required to use the
+<tt class="docutils literal"><span class="pre">typename</span></tt> keyword to assist the parser.  On Windows, Clang attempts to
+follow the normal lookup rules, but if lookup fails, it will assume that the
+user intended to find the name in a dependent base.  While parsing the
+following program, Clang will recover as if the user had written the
+commented-out code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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">struct</span> <span class="n">Foo</span> <span class="o">:</span> <span class="n">T</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="cm">/*typename*/</span> <span class="n">T</span><span class="o">::</span><span class="n">UnknownType</span> <span class="n">x</span> <span class="o">=</span>  <span class="cm">/*this->*/</span><span class="n">unknownMember</span><span class="p">;</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>After recovery, Clang warns the user that this code is non-standard and issues
+a hint suggesting how to fix the problem.</p>
+<p>As of this writing, Clang is able to compile a simple ATL hello world
+application.  There are still issues parsing WRL headers for modern Windows 8
+apps, but they should be addressed soon.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="Modules.html">Modules</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="CommandGuide/index.html">Clang “man” pages</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/MemorySanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/MemorySanitizer.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/MemorySanitizer.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/MemorySanitizer.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,268 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>MemorySanitizer — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="DataFlowSanitizer" href="DataFlowSanitizer.html" />
+    <link rel="prev" title="ThreadSanitizer" href="ThreadSanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>MemorySanitizer</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ThreadSanitizer.html">ThreadSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DataFlowSanitizer.html">DataFlowSanitizer</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="memorysanitizer">
+<h1>MemorySanitizer<a class="headerlink" href="#memorysanitizer" 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="#how-to-build" id="id2">How to build</a></li>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a><ul>
+<li><a class="reference internal" href="#has-feature-memory-sanitizer" id="id4"><tt class="docutils literal"><span class="pre">__has_feature(memory_sanitizer)</span></tt></a></li>
+<li><a class="reference internal" href="#attribute-no-sanitize-memory" id="id5"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_memory))</span></tt></a></li>
+<li><a class="reference internal" href="#blacklist" id="id6">Blacklist</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#report-symbolization" id="id7">Report symbolization</a></li>
+<li><a class="reference internal" href="#origin-tracking" id="id8">Origin Tracking</a></li>
+<li><a class="reference internal" href="#handling-external-code" id="id9">Handling external code</a></li>
+<li><a class="reference internal" href="#supported-platforms" id="id10">Supported Platforms</a></li>
+<li><a class="reference internal" href="#limitations" id="id11">Limitations</a></li>
+<li><a class="reference internal" href="#current-status" id="id12">Current Status</a></li>
+<li><a class="reference internal" href="#more-information" id="id13">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>MemorySanitizer is a detector of uninitialized reads. It consists of a
+compiler instrumentation module and a run-time library.</p>
+<p>Typical slowdown introduced by MemorySanitizer is <strong>3x</strong>.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2><a class="toc-backref" href="#id2">How to build</a><a class="headerlink" href="#how-to-build" title="Permalink to this headline">Â¶</a></h2>
+<p>Build LLVM/Clang with <a class="reference external" href="http://llvm.org/docs/CMake.html">CMake</a>.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">Â¶</a></h2>
+<p>Simply compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt> flag.
+The MemorySanitizer run-time library should be linked to the final
+executable, so make sure to use <tt class="docutils literal"><span class="pre">clang</span></tt> (not <tt class="docutils literal"><span class="pre">ld</span></tt>) for the final
+link step. When linking shared libraries, the MemorySanitizer run-time
+is not linked, so <tt class="docutils literal"><span class="pre">-Wl,-z,defs</span></tt> may cause link errors (don’t use it
+with MemorySanitizer). To get a reasonable performance add <tt class="docutils literal"><span class="pre">-O1</span></tt> or
+higher. To get meaninful stack traces in error messages add
+<tt class="docutils literal"><span class="pre">-fno-omit-frame-pointer</span></tt>. To get perfect stack traces you may need
+to disable inlining (just use <tt class="docutils literal"><span class="pre">-O1</span></tt>) and tail call elimination
+(<tt class="docutils literal"><span class="pre">-fno-optimize-sibling-calls</span></tt>).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat umr.cc
+<span class="gp">#</span>include <stdio.h>
+
+<span class="go">int main(int argc, char** argv) {</span>
+<span class="go">  int* a = new int[10];</span>
+<span class="go">  a[5] = 0;</span>
+<span class="go">  if (a[argc])</span>
+<span class="go">    printf("xx\n");</span>
+<span class="go">  return 0;</span>
+<span class="go">}</span>
+
+<span class="gp">%</span> clang -fsanitize<span class="o">=</span>memory -fno-omit-frame-pointer -g -O2 umr.cc
+</pre></div>
+</div>
+<p>If a bug is detected, the program will print an error message to
+stderr and exit with a non-zero exit code. Currently, MemorySanitizer
+does not symbolize its output by default, so you may need to use a
+separate script to symbolize the result offline (this will be fixed in
+future).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> ./a.out
+<span class="go">WARNING: MemorySanitizer: use-of-uninitialized-value</span>
+<span class="go">    #0 0x7f45944b418a in main umr.cc:6</span>
+<span class="go">    #1 0x7f45938b676c in __libc_start_main libc-start.c:226</span>
+</pre></div>
+</div>
+<p>By default, MemorySanitizer exits on the first detected error.</p>
+<div class="section" id="has-feature-memory-sanitizer">
+<h3><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">__has_feature(memory_sanitizer)</span></tt></a><a class="headerlink" href="#has-feature-memory-sanitizer" title="Permalink to this headline">Â¶</a></h3>
+<p>In some cases one may need to execute different code depending on
+whether MemorySanitizer is enabled. <a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>__has_feature</em></a> can be used for this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(__has_feature)</span>
+<span class="cp">#  if __has_feature(memory_sanitizer)</span>
+<span class="c1">// code that builds only under MemorySanitizer</span>
+<span class="cp">#  endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-memory">
+<h3><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_memory))</span></tt></a><a class="headerlink" href="#attribute-no-sanitize-memory" title="Permalink to this headline">Â¶</a></h3>
+<p>Some code should not be checked by MemorySanitizer.
+One may use the function attribute
+<a class="reference internal" href="AttributeReference.html#langext-memory-sanitizer"><em>no_sanitize_memory</em></a>
+to disable uninitialized checks in a particular function.
+MemorySanitizer may still instrument such functions to avoid false positives.
+This attribute may not be
+supported by other compilers, so we suggest to use it together with
+<tt class="docutils literal"><span class="pre">__has_feature(memory_sanitizer)</span></tt>.</p>
+</div>
+<div class="section" id="blacklist">
+<h3><a class="toc-backref" href="#id6">Blacklist</a><a class="headerlink" href="#blacklist" title="Permalink to this headline">Â¶</a></h3>
+<p>MemorySanitizer supports <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to relax MemorySanitizer
+checks for certain source files and functions. All “Use of uninitialized value”
+warnings will be suppressed and all values loaded from memory will be
+considered fully initialized.</p>
+</div>
+</div>
+<div class="section" id="report-symbolization">
+<h2><a class="toc-backref" href="#id7">Report symbolization</a><a class="headerlink" href="#report-symbolization" title="Permalink to this headline">Â¶</a></h2>
+<p>MemorySanitizer uses an external symbolizer to print files and line numbers in
+reports. Make sure that <tt class="docutils literal"><span class="pre">llvm-symbolizer</span></tt> binary is in <tt class="docutils literal"><span class="pre">PATH</span></tt>,
+or set environment variable <tt class="docutils literal"><span class="pre">MSAN_SYMBOLIZER_PATH</span></tt> to point to it.</p>
+</div>
+<div class="section" id="origin-tracking">
+<h2><a class="toc-backref" href="#id8">Origin Tracking</a><a class="headerlink" href="#origin-tracking" title="Permalink to this headline">Â¶</a></h2>
+<p>MemorySanitizer can track origins of unitialized values, similar to
+Valgrind’s –track-origins option. This feature is enabled by
+<tt class="docutils literal"><span class="pre">-fsanitize-memory-track-origins=2</span></tt> (or simply
+<tt class="docutils literal"><span class="pre">-fsanitize-memory-track-origins</span></tt>) Clang option. With the code from
+the example above,</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat umr2.cc
+<span class="gp">#</span>include <stdio.h>
+
+<span class="go">int main(int argc, char** argv) {</span>
+<span class="go">  int* a = new int[10];</span>
+<span class="go">  a[5] = 0;</span>
+<span class="go">  volatile int b = a[argc];</span>
+<span class="go">  if (b)</span>
+<span class="go">    printf("xx\n");</span>
+<span class="go">  return 0;</span>
+<span class="go">}</span>
+
+<span class="gp">%</span> clang -fsanitize<span class="o">=</span>memory -fsanitize-memory-track-origins<span class="o">=</span>2 -fno-omit-frame-pointer -g -O2 umr2.cc
+<span class="gp">%</span> ./a.out
+<span class="go">WARNING: MemorySanitizer: use-of-uninitialized-value</span>
+<span class="go">    #0 0x7f7893912f0b in main umr2.cc:7</span>
+<span class="go">    #1 0x7f789249b76c in __libc_start_main libc-start.c:226</span>
+
+<span class="go">  Uninitialized value was stored to memory at</span>
+<span class="go">    #0 0x7f78938b5c25 in __msan_chain_origin msan.cc:484</span>
+<span class="go">    #1 0x7f7893912ecd in main umr2.cc:6</span>
+
+<span class="go">  Uninitialized value was created by a heap allocation</span>
+<span class="go">    #0 0x7f7893901cbd in operator new[](unsigned long) msan_new_delete.cc:44</span>
+<span class="go">    #1 0x7f7893912e06 in main umr2.cc:4</span>
+</pre></div>
+</div>
+<p>By default, MemorySanitizer collects both allocation points and all
+intermediate stores the uninitialized value went through.  Origin
+tracking has proved to be very useful for debugging MemorySanitizer
+reports. It slows down program execution by a factor of 1.5x-2x on top
+of the usual MemorySanitizer slowdown.</p>
+<p>Clang option <tt class="docutils literal"><span class="pre">-fsanitize-memory-track-origins=1</span></tt> enabled a slightly
+faster mode when MemorySanitizer collects only allocation points but
+not intermediate stores.</p>
+</div>
+<div class="section" id="handling-external-code">
+<h2><a class="toc-backref" href="#id9">Handling external code</a><a class="headerlink" href="#handling-external-code" title="Permalink to this headline">Â¶</a></h2>
+<p>MemorySanitizer requires that all program code is instrumented. This
+also includes any libraries that the program depends on, even libc.
+Failing to achieve this may result in false reports.</p>
+<p>Full MemorySanitizer instrumentation is very difficult to achieve. To
+make it easier, MemorySanitizer runtime library includes 70+
+interceptors for the most common libc functions. They make it possible
+to run MemorySanitizer-instrumented programs linked with
+uninstrumented libc. For example, the authors were able to bootstrap
+MemorySanitizer-instrumented Clang compiler by linking it with
+self-built instrumented libc++ (as a replacement for libstdc++).</p>
+</div>
+<div class="section" id="supported-platforms">
+<h2><a class="toc-backref" href="#id10">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">Â¶</a></h2>
+<p>MemorySanitizer is supported on</p>
+<ul class="simple">
+<li>Linux x86_64 (tested on Ubuntu 12.04);</li>
+</ul>
+</div>
+<div class="section" id="limitations">
+<h2><a class="toc-backref" href="#id11">Limitations</a><a class="headerlink" href="#limitations" title="Permalink to this headline">Â¶</a></h2>
+<ul class="simple">
+<li>MemorySanitizer uses 2x more real memory than a native run, 3x with
+origin tracking.</li>
+<li>MemorySanitizer maps (but not reserves) 64 Terabytes of virtual
+address space. This means that tools like <tt class="docutils literal"><span class="pre">ulimit</span></tt> may not work as
+usually expected.</li>
+<li>Static linking is not supported.</li>
+<li>Non-position-independent executables are not supported.  Therefore, the
+<tt class="docutils literal"><span class="pre">fsanitize=memory</span></tt> flag will cause Clang to act as though the <tt class="docutils literal"><span class="pre">-fPIE</span></tt>
+flag had been supplied if compiling without <tt class="docutils literal"><span class="pre">-fPIC</span></tt>, and as though the
+<tt class="docutils literal"><span class="pre">-pie</span></tt> flag had been supplied if linking an executable.</li>
+<li>Depending on the version of Linux kernel, running without ASLR may
+be not supported. Note that GDB disables ASLR by default. To debug
+instrumented programs, use “set disable-randomization off”.</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id12">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">Â¶</a></h2>
+<p>MemorySanitizer is an experimental tool. It is known to work on large
+real-world programs, like Clang/LLVM itself.</p>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id13">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">Â¶</a></h2>
+<p><a class="reference external" href="http://code.google.com/p/memory-sanitizer/">http://code.google.com/p/memory-sanitizer</a></p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ThreadSanitizer.html">ThreadSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DataFlowSanitizer.html">DataFlowSanitizer</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/Modules.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/Modules.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/Modules.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/Modules.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,891 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Modules — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="MSVC compatibility" href="MSVCCompatibility.html" />
+    <link rel="prev" title="SafeStack" href="SafeStack.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Modules</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="SafeStack.html">SafeStack</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="MSVCCompatibility.html">MSVC compatibility</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="modules">
+<h1>Modules<a class="headerlink" href="#modules" 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="id9">Introduction</a><ul>
+<li><a class="reference internal" href="#problems-with-the-current-model" id="id10">Problems with the current model</a></li>
+<li><a class="reference internal" href="#semantic-import" id="id11">Semantic import</a></li>
+<li><a class="reference internal" href="#problems-modules-do-not-solve" id="id12">Problems modules do not solve</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#using-modules" id="id13">Using Modules</a><ul>
+<li><a class="reference internal" href="#objective-c-import-declaration" id="id14">Objective-C Import declaration</a></li>
+<li><a class="reference internal" href="#includes-as-imports" id="id15">Includes as imports</a></li>
+<li><a class="reference internal" href="#module-maps" id="id16">Module maps</a></li>
+<li><a class="reference internal" href="#compilation-model" id="id17">Compilation model</a></li>
+<li><a class="reference internal" href="#command-line-parameters" id="id18">Command-line parameters</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#module-semantics" id="id19">Module Semantics</a><ul>
+<li><a class="reference internal" href="#macros" id="id20">Macros</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#module-map-language" id="id21">Module Map Language</a><ul>
+<li><a class="reference internal" href="#lexical-structure" id="id22">Lexical structure</a></li>
+<li><a class="reference internal" href="#module-map-file" id="id23">Module map file</a></li>
+<li><a class="reference internal" href="#module-declaration" id="id24">Module declaration</a><ul>
+<li><a class="reference internal" href="#requires-declaration" id="id25">Requires declaration</a></li>
+<li><a class="reference internal" href="#header-declaration" id="id26">Header declaration</a></li>
+<li><a class="reference internal" href="#umbrella-directory-declaration" id="id27">Umbrella directory declaration</a></li>
+<li><a class="reference internal" href="#submodule-declaration" id="id28">Submodule declaration</a></li>
+<li><a class="reference internal" href="#export-declaration" id="id29">Export declaration</a></li>
+<li><a class="reference internal" href="#use-declaration" id="id30">Use declaration</a></li>
+<li><a class="reference internal" href="#link-declaration" id="id31">Link declaration</a></li>
+<li><a class="reference internal" href="#configuration-macros-declaration" id="id32">Configuration macros declaration</a></li>
+<li><a class="reference internal" href="#conflict-declarations" id="id33">Conflict declarations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#attributes" id="id34">Attributes</a></li>
+<li><a class="reference internal" href="#private-module-map-files" id="id35">Private Module Map Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#modularizing-a-platform" id="id36">Modularizing a Platform</a></li>
+<li><a class="reference internal" href="#future-directions" id="id37">Future Directions</a></li>
+<li><a class="reference internal" href="#where-to-learn-more-about-modules" id="id38">Where To Learn More About Modules</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id9">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>Most software is built using a number of software libraries, including libraries supplied by the platform, internal libraries built as part of the software itself to provide structure, and third-party libraries. For each library, one needs to access both its interface (API) and its implementation. In the C family of languages, the interface to a library is accessed by including the appropriate header files(s):</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <SomeLib.h></span>
+</pre></div>
+</div>
+<p>The implementation is handled separately by linking against the appropriate library. For example, by passing <tt class="docutils literal"><span class="pre">-lSomeLib</span></tt> to the linker.</p>
+<p>Modules provide an alternative, simpler way to use software libraries that provides better compile-time scalability and eliminates many of the problems inherent to using the C preprocessor to access the API of a library.</p>
+<div class="section" id="problems-with-the-current-model">
+<h3><a class="toc-backref" href="#id10">Problems with the current model</a><a class="headerlink" href="#problems-with-the-current-model" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">#include</span></tt> mechanism provided by the C preprocessor is a very poor way to access the API of a library, for a number of reasons:</p>
+<ul class="simple">
+<li><strong>Compile-time scalability</strong>: Each time a header is included, the
+compiler must preprocess and parse the text in that header and every
+header it includes, transitively. This process must be repeated for
+every translation unit in the application, which involves a huge
+amount of redundant work. In a project with <em>N</em> translation units
+and <em>M</em> headers included in each translation unit, the compiler is
+performing <em>M x N</em> work even though most of the <em>M</em> headers are
+shared among multiple translation units. C++ is particularly bad,
+because the compilation model for templates forces a huge amount of
+code into headers.</li>
+<li><strong>Fragility</strong>: <tt class="docutils literal"><span class="pre">#include</span></tt> directives are treated as textual
+inclusion by the preprocessor, and are therefore subject to any
+active macro definitions at the time of inclusion. If any of the
+active macro definitions happens to collide with a name in the
+library, it can break the library API or cause compilation failures
+in the library header itself. For an extreme example,
+<tt class="docutils literal"><span class="pre">#define</span> <span class="pre">std</span> <span class="pre">"The</span> <span class="pre">C++</span> <span class="pre">Standard"</span></tt> and then include a standard
+library header: the result is a horrific cascade of failures in the
+C++ Standard Library’s implementation. More subtle real-world
+problems occur when the headers for two different libraries interact
+due to macro collisions, and users are forced to reorder
+<tt class="docutils literal"><span class="pre">#include</span></tt> directives or introduce <tt class="docutils literal"><span class="pre">#undef</span></tt> directives to break
+the (unintended) dependency.</li>
+<li><strong>Conventional workarounds</strong>: C programmers have
+adopted a number of conventions to work around the fragility of the
+C preprocessor model. Include guards, for example, are required for
+the vast majority of headers to ensure that multiple inclusion
+doesn’t break the compile. Macro names are written with
+<tt class="docutils literal"><span class="pre">LONG_PREFIXED_UPPERCASE_IDENTIFIERS</span></tt> to avoid collisions, and some
+library/framework developers even use <tt class="docutils literal"><span class="pre">__underscored</span></tt> names
+in headers to avoid collisions with “normal” names that (by
+convention) shouldn’t even be macros. These conventions are a
+barrier to entry for developers coming from non-C languages, are
+boilerplate for more experienced developers, and make our headers
+far uglier than they should be.</li>
+<li><strong>Tool confusion</strong>: In a C-based language, it is hard to build tools
+that work well with software libraries, because the boundaries of
+the libraries are not clear. Which headers belong to a particular
+library, and in what order should those headers be included to
+guarantee that they compile correctly? Are the headers C, C++,
+Objective-C++, or one of the variants of these languages? What
+declarations in those headers are actually meant to be part of the
+API, and what declarations are present only because they had to be
+written as part of the header file?</li>
+</ul>
+</div>
+<div class="section" id="semantic-import">
+<h3><a class="toc-backref" href="#id11">Semantic import</a><a class="headerlink" href="#semantic-import" title="Permalink to this headline">Â¶</a></h3>
+<p>Modules improve access to the API of software libraries by replacing the textual preprocessor inclusion model with a more robust, more efficient semantic model. From the user’s perspective, the code looks only slightly different, because one uses an <tt class="docutils literal"><span class="pre">import</span></tt> declaration rather than a <tt class="docutils literal"><span class="pre">#include</span></tt> preprocessor directive:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">import</span> <span class="n">std</span><span class="p">.</span><span class="n">io</span><span class="p">;</span> <span class="c1">// pseudo-code; see below for syntax discussion</span>
+</pre></div>
+</div>
+<p>However, this module import behaves quite differently from the corresponding <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><stdio.h></span></tt>: when the compiler sees the module import above, it loads a binary representation of the <tt class="docutils literal"><span class="pre">std.io</span></tt> module and makes its API available to the application directly. Preprocessor definitions that precede the import declaration have no impact on the API provided by <tt class="docutils literal"><span class="pre">std.io</span></tt>, because the module itself was compiled as a separate, standalone module. Additionally, any linker flags required to use the <tt class="docutils literal"><span class="pre">std.io</span></tt> module will automatically be provided when the module is imported <a class="footnote-reference" href="#id5" id="id1">[1]</a>
+This semantic import model addresses many of the problems of the preprocessor inclusion model:</p>
+<ul class="simple">
+<li><strong>Compile-time scalability</strong>: The <tt class="docutils literal"><span class="pre">std.io</span></tt> module is only compiled once, and importing the module into a translation unit is a constant-time operation (independent of module system). Thus, the API of each software library is only parsed once, reducing the <em>M x N</em> compilation problem to an <em>M + N</em> problem.</li>
+<li><strong>Fragility</strong>: Each module is parsed as a standalone entity, so it has a consistent preprocessor environment. This completely eliminates the need for <tt class="docutils literal"><span class="pre">__underscored</span></tt> names and similarly defensive tricks. Moreover, the current preprocessor definitions when an import declaration is encountered are ignored, so one software library can not affect how another software library is compiled, eliminating include-order dependencies.</li>
+<li><strong>Tool confusion</strong>: Modules describe the API of software libraries, and tools can reason about and present a module as a representation of that API. Because modules can only be built standalone, tools can rely on the module definition to ensure that they get the complete API for the library. Moreover, modules can specify which languages they work with, so, e.g., one can not accidentally attempt to load a C++ module into a C program.</li>
+</ul>
+</div>
+<div class="section" id="problems-modules-do-not-solve">
+<h3><a class="toc-backref" href="#id12">Problems modules do not solve</a><a class="headerlink" href="#problems-modules-do-not-solve" title="Permalink to this headline">Â¶</a></h3>
+<p>Many programming languages have a module or package system, and because of the variety of features provided by these languages it is important to define what modules do <em>not</em> do. In particular, all of the following are considered out-of-scope for modules:</p>
+<ul class="simple">
+<li><strong>Rewrite the world’s code</strong>: It is not realistic to require applications or software libraries to make drastic or non-backward-compatible changes, nor is it feasible to completely eliminate headers. Modules must interoperate with existing software libraries and allow a gradual transition.</li>
+<li><strong>Versioning</strong>: Modules have no notion of version information. Programmers must still rely on the existing versioning mechanisms of the underlying language (if any exist) to version software libraries.</li>
+<li><strong>Namespaces</strong>: Unlike in some languages, modules do not imply any notion of namespaces. Thus, a struct declared in one module will still conflict with a struct of the same name declared in a different module, just as they would if declared in two different headers. This aspect is important for backward compatibility, because (for example) the mangled names of entities in software libraries must not change when introducing modules.</li>
+<li><strong>Binary distribution of modules</strong>: Headers (particularly C++ headers) expose the full complexity of the language. Maintaining a stable binary module format across architectures, compiler versions, and compiler vendors is technically infeasible.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="using-modules">
+<h2><a class="toc-backref" href="#id13">Using Modules</a><a class="headerlink" href="#using-modules" title="Permalink to this headline">Â¶</a></h2>
+<p>To enable modules, pass the command-line flag <tt class="docutils literal"><span class="pre">-fmodules</span></tt>. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional <a class="reference internal" href="#command-line-parameters">command-line parameters</a> are described in a separate section later.</p>
+<div class="section" id="objective-c-import-declaration">
+<h3><a class="toc-backref" href="#id14">Objective-C Import declaration</a><a class="headerlink" href="#objective-c-import-declaration" title="Permalink to this headline">Â¶</a></h3>
+<p>Objective-C provides syntax for importing a module via an <em>@import declaration</em>, which imports the named module:</p>
+<div class="highlight-python"><div class="highlight"><pre>@import std;
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">@import</span></tt> declaration above imports the entire contents of the <tt class="docutils literal"><span class="pre">std</span></tt> module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specific a particular submodule, e.g.,</p>
+<div class="highlight-python"><div class="highlight"><pre>@import std.io;
+</pre></div>
+</div>
+<p>Redundant import declarations are ignored, and one is free to import modules at any point within the translation unit, so long as the import declaration is at global scope.</p>
+<p>At present, there is no C or C++ syntax for import declarations. Clang
+will track the modules proposal in the C++ committee. See the section
+<a class="reference internal" href="#includes-as-imports">Includes as imports</a> to see how modules get imported today.</p>
+</div>
+<div class="section" id="includes-as-imports">
+<h3><a class="toc-backref" href="#id15">Includes as imports</a><a class="headerlink" href="#includes-as-imports" title="Permalink to this headline">Â¶</a></h3>
+<p>The primary user-level feature of modules is the import operation, which provides access to the API of software libraries. However, today’s programs make extensive use of <tt class="docutils literal"><span class="pre">#include</span></tt>, and it is unrealistic to assume that all of this code will change overnight. Instead, modules automatically translate <tt class="docutils literal"><span class="pre">#include</span></tt> directives into the corresponding module import. For example, the include directive</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
+</pre></div>
+</div>
+<p>will be automatically mapped to an import of the module <tt class="docutils literal"><span class="pre">std.io</span></tt>. Even with specific <tt class="docutils literal"><span class="pre">import</span></tt> syntax in the language, this particular feature is important for both adoption and backward compatibility: automatic translation of <tt class="docutils literal"><span class="pre">#include</span></tt> to <tt class="docutils literal"><span class="pre">import</span></tt> allows an application to get the benefits of modules (for all modules-enabled libraries) without any changes to the application itself. Thus, users can easily use modules with one compiler while falling back to the preprocessor-inclusion mechanism with other compilers.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The automatic mapping of <tt class="docutils literal"><span class="pre">#include</span></tt> to <tt class="docutils literal"><span class="pre">import</span></tt> also solves an implementation problem: importing a module with a definition of some entity (say, a <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">Point</span></tt>) and then parsing a header containing another definition of <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">Point</span></tt> would cause a redefinition error, even if it is the same <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">Point</span></tt>. By mapping <tt class="docutils literal"><span class="pre">#include</span></tt> to <tt class="docutils literal"><span class="pre">import</span></tt>, the compiler can guarantee that it always sees just the already-parsed definition from the module.</p>
+</div>
+<p>While building a module, <tt class="docutils literal"><span class="pre">#include_next</span></tt> is also supported, with one caveat.
+The usual behavior of <tt class="docutils literal"><span class="pre">#include_next</span></tt> is to search for the specified filename
+in the list of include paths, starting from the path <em>after</em> the one
+in which the current file was found.
+Because files listed in module maps are not found through include paths, a
+different strategy is used for <tt class="docutils literal"><span class="pre">#include_next</span></tt> directives in such files: the
+list of include paths is searched for the specified header name, to find the
+first include path that would refer to the current file. <tt class="docutils literal"><span class="pre">#include_next</span></tt> is
+interpreted as if the current file had been found in that path.
+If this search finds a file named by a module map, the <tt class="docutils literal"><span class="pre">#include_next</span></tt>
+directive is translated into an import, just like for a <tt class="docutils literal"><span class="pre">#include</span></tt>
+directive.``</p>
+</div>
+<div class="section" id="module-maps">
+<h3><a class="toc-backref" href="#id16">Module maps</a><a class="headerlink" href="#module-maps" title="Permalink to this headline">Â¶</a></h3>
+<p>The crucial link between modules and headers is described by a <em>module map</em>, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module <tt class="docutils literal"><span class="pre">std</span></tt> covering the C standard library. Each of the C standard library headers (<tt class="docutils literal"><span class="pre"><stdio.h></span></tt>, <tt class="docutils literal"><span class="pre"><stdlib.h></span></tt>, <tt class="docutils literal"><span class="pre"><math.h></span></tt>, etc.) would contribute to the <tt class="docutils literal"><span class="pre">std</span></tt> module, by placing their respective APIs into the corresponding submodule (<tt class="docutils literal"><span class="pre">std.io</span></tt>, <tt class="docutils literal"><span class="pre">std.lib</span></tt>, <tt class="docutils literal"><span class="pre">std.math</span></tt>, etc.). Having a list of the heade
 rs that are part of the <tt class="docutils literal"><span class="pre">std</span></tt> module allows the compiler to build the <tt class="docutils literal"><span class="pre">std</span></tt> module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of <tt class="docutils literal"><span class="pre">#include</span></tt> directives to module imports.</p>
+<p>Module maps are specified as separate files (each named <tt class="docutils literal"><span class="pre">module.modulemap</span></tt>) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases <a class="footnote-reference" href="#id6" id="id2">[2]</a>). The actual <a class="reference internal" href="#module-map-language">Module map language</a> is described in a later section.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section <a class="reference internal" href="#modularizing-a-platform">Modularizing a Platform</a> describes the steps one must take to write these module maps.</p>
+</div>
+<p>One can use module maps without modules to check the integrity of the use of header files. To do this, use the <tt class="docutils literal"><span class="pre">-fimplicit-module-maps</span></tt> option instead of the <tt class="docutils literal"><span class="pre">-fmodules</span></tt> option, or use <tt class="docutils literal"><span class="pre">-fmodule-map-file=</span></tt> option to explicitly specify the module map files to load.</p>
+</div>
+<div class="section" id="compilation-model">
+<h3><a class="toc-backref" href="#id17">Compilation model</a><a class="headerlink" href="#compilation-model" title="Permalink to this headline">Â¶</a></h3>
+<p>The binary representation of modules is automatically generated by the compiler on an as-needed basis. When a module is imported (e.g., by an <tt class="docutils literal"><span class="pre">#include</span></tt> of one of the module’s headers), the compiler will spawn a second instance of itself <a class="footnote-reference" href="#id7" id="id3">[3]</a>, with a fresh preprocessing context <a class="footnote-reference" href="#id8" id="id4">[4]</a>, to parse just the headers in that module. The resulting Abstract Syntax Tree (AST) is then persisted into the binary representation of the module that is then loaded into translation unit where the module import was encountered.</p>
+<p>The binary representation of modules is persisted in the <em>module cache</em>. Imports of a module will first query the module cache and, if a binary representation of the required module is already available, will load that representation directly. Thus, a module’s headers will only be parsed once per language configuration, rather than once per translation unit that uses the module.</p>
+<p>Modules maintain references to each of the headers that were part of the module build. If any of those headers changes, or if any of the modules on which a module depends change, then the module will be (automatically) recompiled. The process should never require any user intervention.</p>
+</div>
+<div class="section" id="command-line-parameters">
+<h3><a class="toc-backref" href="#id18">Command-line parameters</a><a class="headerlink" href="#command-line-parameters" title="Permalink to this headline">Â¶</a></h3>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">-fmodules</span></tt></dt>
+<dd>Enable the modules feature.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fimplicit-module-maps</span></tt></dt>
+<dd>Enable implicit search for module map files named <tt class="docutils literal"><span class="pre">module.modulemap</span></tt> and similar. This option is implied by <tt class="docutils literal"><span class="pre">-fmodules</span></tt>. If this is disabled with <tt class="docutils literal"><span class="pre">-fno-implicit-module-maps</span></tt>, module map files will only be loaded if they are explicitly specified via <tt class="docutils literal"><span class="pre">-fmodule-map-file</span></tt> or transitively used by another module map file.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodules-cache-path=<directory></span></tt></dt>
+<dd>Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fno-autolink</span></tt></dt>
+<dd>Disable automatic linking against the libraries associated with imported modules.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodules-ignore-macro=macroname</span></tt></dt>
+<dd>Instruct modules to ignore the named macro when selecting an appropriate module variant. Use this for macros defined on the command line that don’t affect how modules are built, to improve sharing of compiled module files.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodules-prune-interval=seconds</span></tt></dt>
+<dd>Specify the minimum delay (in seconds) between attempts to prune the module cache. Module cache pruning attempts to clear out old, unused module files so that the module cache itself does not grow without bound. The default delay is large (604,800 seconds, or 7 days) because this is an expensive operation. Set this value to 0 to turn off pruning.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodules-prune-after=seconds</span></tt></dt>
+<dd>Specify the minimum time (in seconds) for which a file in the module cache must be unused (according to access time) before module pruning will remove it. The default delay is large (2,678,400 seconds, or 31 days) to avoid excessive module rebuilding.</dd>
+<dt><tt class="docutils literal"><span class="pre">-module-file-info</span> <span class="pre"><module</span> <span class="pre">file</span> <span class="pre">name></span></tt></dt>
+<dd>Debugging aid that prints information about a given module file (with a <tt class="docutils literal"><span class="pre">.pcm</span></tt> extension), including the language and preprocessor options that particular module variant was built with.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodules-decluse</span></tt></dt>
+<dd>Enable checking of module <tt class="docutils literal"><span class="pre">use</span></tt> declarations.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodule-name=module-id</span></tt></dt>
+<dd>Consider a source file as a part of the given module.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodule-map-file=<file></span></tt></dt>
+<dd>Load the given module map file if a header from its directory or one of its subdirectories is loaded.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodules-search-all</span></tt></dt>
+<dd>If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name.  Note that if the global module index has not been built before, this might take some time as it needs to build all the modules.  Note that this option doesn’t apply in module builds, to avoid the recursion.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fno-implicit-modules</span></tt></dt>
+<dd>All modules used by the build must be specified with <tt class="docutils literal"><span class="pre">-fmodule-file</span></tt>.</dd>
+<dt><tt class="docutils literal"><span class="pre">-fmodule-file=<file></span></tt></dt>
+<dd>Load the given precompiled module file.</dd>
+</dl>
+</div>
+</div>
+<div class="section" id="module-semantics">
+<h2><a class="toc-backref" href="#id19">Module Semantics</a><a class="headerlink" href="#module-semantics" title="Permalink to this headline">Â¶</a></h2>
+<p>Modules are modeled as if each submodule were a separate translation unit, and a module import makes names from the other translation unit visible. Each submodule starts with a new preprocessor state and an empty translation unit.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This behavior is currently only approximated when building a module with submodules. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon. This behavior is subject to change.</p>
+</div>
+<p>As an example, in C, this implies that if two structs are defined in different submodules with the same name, those two types are distinct types (but may be <em>compatible</em> types if their definitions match. In C++, two structs defined with the same name in different submodules are the <em>same</em> type, and must be equivalent under C++’s One Definition Rule.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang currently only performs minimal checking for violations of the One Definition Rule.</p>
+</div>
+<p>If any submodule of a module is imported into any part of a program, the entire top-level module is considered to be part of the program. As a consequence of this, Clang may diagnose conflicts between an entity declared in an unimported submodule and an entity declared in the current translation unit, and Clang may inline or devirtualize based on knowledge from unimported submodules.</p>
+<div class="section" id="macros">
+<h3><a class="toc-backref" href="#id20">Macros</a><a class="headerlink" href="#macros" title="Permalink to this headline">Â¶</a></h3>
+<p>The C and C++ preprocessor assumes that the input text is a single linear buffer, but with modules this is not the case. It is possible to import two modules that have conflicting definitions for a macro (or where one <tt class="docutils literal"><span class="pre">#define</span></tt>s a macro and the other <tt class="docutils literal"><span class="pre">#undef</span></tt>ines it). The rules for handling macro definitions in the presence of modules are as follows:</p>
+<ul class="simple">
+<li>Each definition and undefinition of a macro is considered to be a distinct entity.</li>
+<li>Such entities are <em>visible</em> if they are from the current submodule or translation unit, or if they were exported from a submodule that has been imported.</li>
+<li>A <tt class="docutils literal"><span class="pre">#define</span> <span class="pre">X</span></tt> or <tt class="docutils literal"><span class="pre">#undef</span> <span class="pre">X</span></tt> directive <em>overrides</em> all definitions of <tt class="docutils literal"><span class="pre">X</span></tt> that are visible at the point of the directive.</li>
+<li>A <tt class="docutils literal"><span class="pre">#define</span></tt> or <tt class="docutils literal"><span class="pre">#undef</span></tt> directive is <em>active</em> if it is visible and no visible directive overrides it.</li>
+<li>A set of macro directives is <em>consistent</em> if it consists of only <tt class="docutils literal"><span class="pre">#undef</span></tt> directives, or if all <tt class="docutils literal"><span class="pre">#define</span></tt> directives in the set define the macro name to the same sequence of tokens (following the usual rules for macro redefinitions).</li>
+<li>If a macro name is used and the set of active directives is not consistent, the program is ill-formed. Otherwise, the (unique) meaning of the macro name is used.</li>
+</ul>
+<p>For example, suppose:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre"><stdio.h></span></tt> defines a macro <tt class="docutils literal"><span class="pre">getc</span></tt> (and exports its <tt class="docutils literal"><span class="pre">#define</span></tt>)</li>
+<li><tt class="docutils literal"><span class="pre"><cstdio></span></tt> imports the <tt class="docutils literal"><span class="pre"><stdio.h></span></tt> module and undefines the macro (and exports its <tt class="docutils literal"><span class="pre">#undef</span></tt>)</li>
+</ul>
+<p>The <tt class="docutils literal"><span class="pre">#undef</span></tt> overrides the <tt class="docutils literal"><span class="pre">#define</span></tt>, and a source file that imports both modules <em>in any order</em> will not see <tt class="docutils literal"><span class="pre">getc</span></tt> defined as a macro.</p>
+</div>
+</div>
+<div class="section" id="module-map-language">
+<h2><a class="toc-backref" href="#id21">Module Map Language</a><a class="headerlink" href="#module-map-language" title="Permalink to this headline">Â¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">The module map language is not currently guaranteed to be stable between major revisions of Clang.</p>
+</div>
+<p>The module map language describes the mapping from header files to the
+logical structure of modules. To enable support for using a library as
+a module, one must write a <tt class="docutils literal"><span class="pre">module.modulemap</span></tt> file for that library. The
+<tt class="docutils literal"><span class="pre">module.modulemap</span></tt> file is placed alongside the header files themselves,
+and is written in the module map language described below.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">For compatibility with previous releases, if a module map file named
+<tt class="docutils literal"><span class="pre">module.modulemap</span></tt> is not found, Clang will also search for a file named
+<tt class="docutils literal"><span class="pre">module.map</span></tt>. This behavior is deprecated and we plan to eventually
+remove it.</p>
+</div>
+<p>As an example, the module map file for the C standard library might look a bit like this:</p>
+<div class="highlight-python"><div class="highlight"><pre>module std [system] [extern_c] {
+  module assert {
+    textual header "assert.h"
+    header "bits/assert-decls.h"
+    export *
+  }
+
+  module complex {
+    header "complex.h"
+    export *
+  }
+
+  module ctype {
+    header "ctype.h"
+    export *
+  }
+
+  module errno {
+    header "errno.h"
+    header "sys/errno.h"
+    export *
+  }
+
+  module fenv {
+    header "fenv.h"
+    export *
+  }
+
+  // ...more headers follow...
+}
+</pre></div>
+</div>
+<p>Here, the top-level module <tt class="docutils literal"><span class="pre">std</span></tt> encompasses the whole C standard library. It has a number of submodules containing different parts of the standard library: <tt class="docutils literal"><span class="pre">complex</span></tt> for complex numbers, <tt class="docutils literal"><span class="pre">ctype</span></tt> for character types, etc. Each submodule lists one of more headers that provide the contents for that submodule. Finally, the <tt class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></tt> command specifies that anything included by that submodule will be automatically re-exported.</p>
+<div class="section" id="lexical-structure">
+<h3><a class="toc-backref" href="#id22">Lexical structure</a><a class="headerlink" href="#lexical-structure" title="Permalink to this headline">Â¶</a></h3>
+<p>Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, tokens, string literals, <tt class="docutils literal"><span class="pre">/*</span> <span class="pre">*/</span></tt> and <tt class="docutils literal"><span class="pre">//</span></tt> comments. The module map language has the following reserved words; all other C identifiers are valid identifiers.</p>
+<pre class="literal-block">
+<tt class="docutils literal"><span class="pre">config_macros</span></tt> <tt class="docutils literal"><span class="pre">export</span></tt>     <tt class="docutils literal"><span class="pre">private</span></tt>
+<tt class="docutils literal"><span class="pre">conflict</span></tt>      <tt class="docutils literal"><span class="pre">framework</span></tt>  <tt class="docutils literal"><span class="pre">requires</span></tt>
+<tt class="docutils literal"><span class="pre">exclude</span></tt>       <tt class="docutils literal"><span class="pre">header</span></tt>     <tt class="docutils literal"><span class="pre">textual</span></tt>
+<tt class="docutils literal"><span class="pre">explicit</span></tt>      <tt class="docutils literal"><span class="pre">link</span></tt>       <tt class="docutils literal"><span class="pre">umbrella</span></tt>
+<tt class="docutils literal"><span class="pre">extern</span></tt>        <tt class="docutils literal"><span class="pre">module</span></tt>     <tt class="docutils literal"><span class="pre">use</span></tt>
+</pre>
+</div>
+<div class="section" id="module-map-file">
+<h3><a class="toc-backref" href="#id23">Module map file</a><a class="headerlink" href="#module-map-file" title="Permalink to this headline">Â¶</a></h3>
+<p>A module map file consists of a series of module declarations:</p>
+<pre class="literal-block">
+<em>module-map-file</em>:
+  <em>module-declaration*</em>
+</pre>
+<p>Within a module map file, modules are referred to by a <em>module-id</em>, which uses periods to separate each part of a module’s name:</p>
+<pre class="literal-block">
+<em>module-id</em>:
+  <em>identifier</em> ('.' <em>identifier</em>)*
+</pre>
+</div>
+<div class="section" id="module-declaration">
+<h3><a class="toc-backref" href="#id24">Module declaration</a><a class="headerlink" href="#module-declaration" title="Permalink to this headline">Â¶</a></h3>
+<p>A module declaration describes a module, including the headers that contribute to that module, its submodules, and other aspects of the module.</p>
+<pre class="literal-block">
+<em>module-declaration</em>:
+  <tt class="docutils literal"><span class="pre">explicit</span></tt><sub>opt</sub> <tt class="docutils literal"><span class="pre">framework</span></tt><sub>opt</sub> <tt class="docutils literal"><span class="pre">module</span></tt> <em>module-id</em> <em>attributes</em><sub>opt</sub> '{' <em>module-member*</em> '}'
+  <tt class="docutils literal"><span class="pre">extern</span></tt> <tt class="docutils literal"><span class="pre">module</span></tt> <em>module-id</em> <em>string-literal</em>
+</pre>
+<p>The <em>module-id</em> should consist of only a single <em>identifier</em>, which provides the name of the module being defined. Each module shall have a single definition.</p>
+<p>The <tt class="docutils literal"><span class="pre">explicit</span></tt> qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module.</p>
+<p>The <tt class="docutils literal"><span class="pre">framework</span></tt> qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on Mac OS X and iOS) is contained entirely in directory <tt class="docutils literal"><span class="pre">Name.framework</span></tt>, where <tt class="docutils literal"><span class="pre">Name</span></tt> is the name of the framework (and, therefore, the name of the module). That directory has the following layout:</p>
+<div class="highlight-python"><div class="highlight"><pre>Name.framework/
+  Modules/module.modulemap  Module map for the framework
+  Headers/                  Subdirectory containing framework headers
+  Frameworks/               Subdirectory containing embedded frameworks
+  Resources/                Subdirectory containing additional resources
+  Name                      Symbolic link to the shared library for the framework
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">system</span></tt> attribute specifies that the module is a system module. When a system module is rebuilt, all of the module’s headers will be considered system headers, which suppresses warnings. This is equivalent to placing <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">GCC</span> <span class="pre">system_header</span></tt> in each of the module’s headers. The form of attributes is described in the section <a class="reference internal" href="#attributes">Attributes</a>, below.</p>
+<p>The <tt class="docutils literal"><span class="pre">extern_c</span></tt> attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the module’s headers will be treated as if they were contained within an implicit <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></tt> block. An import for a module with this attribute can appear within an <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></tt> block. No other restrictions are lifted, however: the module currently cannot be imported within an <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></tt> block in a namespace.</p>
+<p>Modules can have a number of different kinds of members, each of which is described below:</p>
+<pre class="literal-block">
+<em>module-member</em>:
+  <em>requires-declaration</em>
+  <em>header-declaration</em>
+  <em>umbrella-dir-declaration</em>
+  <em>submodule-declaration</em>
+  <em>export-declaration</em>
+  <em>use-declaration</em>
+  <em>link-declaration</em>
+  <em>config-macros-declaration</em>
+  <em>conflict-declaration</em>
+</pre>
+<p>An extern module references a module defined by the <em>module-id</em> in a file given by the <em>string-literal</em>. The file can be referenced either by an absolute path or by a path relative to the current map file.</p>
+<div class="section" id="requires-declaration">
+<h4><a class="toc-backref" href="#id25">Requires declaration</a><a class="headerlink" href="#requires-declaration" title="Permalink to this headline">Â¶</a></h4>
+<p>A <em>requires-declaration</em> specifies the requirements that an importing translation unit must satisfy to use the module.</p>
+<pre class="literal-block">
+<em>requires-declaration</em>:
+  <tt class="docutils literal"><span class="pre">requires</span></tt> <em>feature-list</em>
+
+<em>feature-list</em>:
+  <em>feature</em> (',' <em>feature</em>)*
+
+<em>feature</em>:
+  <tt class="docutils literal"><span class="pre">!</span></tt><sub>opt</sub> <em>identifier</em>
+</pre>
+<p>The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects or on certain platforms. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. The optional <tt class="docutils literal"><span class="pre">!</span></tt> indicates that a feature is incompatible with the module.</p>
+<p>The following features are defined:</p>
+<dl class="docutils">
+<dt>altivec</dt>
+<dd>The target supports AltiVec.</dd>
+<dt>blocks</dt>
+<dd>The “blocks” language feature is available.</dd>
+<dt>cplusplus</dt>
+<dd>C++ support is available.</dd>
+<dt>cplusplus11</dt>
+<dd>C++11 support is available.</dd>
+<dt>objc</dt>
+<dd>Objective-C support is available.</dd>
+<dt>objc_arc</dt>
+<dd>Objective-C Automatic Reference Counting (ARC) is available</dd>
+<dt>opencl</dt>
+<dd>OpenCL is available</dd>
+<dt>tls</dt>
+<dd>Thread local storage is available.</dd>
+<dt><em>target feature</em></dt>
+<dd>A specific target feature (e.g., <tt class="docutils literal"><span class="pre">sse4</span></tt>, <tt class="docutils literal"><span class="pre">avx</span></tt>, <tt class="docutils literal"><span class="pre">neon</span></tt>) is available.</dd>
+</dl>
+<p><strong>Example:</strong> The <tt class="docutils literal"><span class="pre">std</span></tt> module can be extended to also include C++ and C++11 headers using a <em>requires-declaration</em>:</p>
+<div class="highlight-python"><div class="highlight"><pre>module std {
+   // C standard library...
+
+   module vector {
+     requires cplusplus
+     header "vector"
+   }
+
+   module type_traits {
+     requires cplusplus11
+     header "type_traits"
+   }
+ }
+</pre></div>
+</div>
+</div>
+<div class="section" id="header-declaration">
+<h4><a class="toc-backref" href="#id26">Header declaration</a><a class="headerlink" href="#header-declaration" title="Permalink to this headline">Â¶</a></h4>
+<p>A header declaration specifies that a particular header is associated with the enclosing module.</p>
+<pre class="literal-block">
+<em>header-declaration</em>:
+  <tt class="docutils literal"><span class="pre">private</span></tt><sub>opt</sub> <tt class="docutils literal"><span class="pre">textual</span></tt><sub>opt</sub> <tt class="docutils literal"><span class="pre">header</span></tt> <em>string-literal</em>
+  <tt class="docutils literal"><span class="pre">umbrella</span></tt> <tt class="docutils literal"><span class="pre">header</span></tt> <em>string-literal</em>
+  <tt class="docutils literal"><span class="pre">exclude</span></tt> <tt class="docutils literal"><span class="pre">header</span></tt> <em>string-literal</em>
+</pre>
+<p>A header declaration that does not contain <tt class="docutils literal"><span class="pre">exclude</span></tt> nor <tt class="docutils literal"><span class="pre">textual</span></tt> specifies a header that contributes to the enclosing module. Specifically, when the module is built, the named header will be parsed and its declarations will be (logically) placed into the enclosing submodule.</p>
+<p>A header with the <tt class="docutils literal"><span class="pre">umbrella</span></tt> specifier is called an umbrella header. An umbrella header includes all of the headers within its directory (and any subdirectories), and is typically used (in the <tt class="docutils literal"><span class="pre">#include</span></tt> world) to easily access the full API provided by a particular library. With modules, an umbrella header is a convenient shortcut that eliminates the need to write out <tt class="docutils literal"><span class="pre">header</span></tt> declarations for every library header. A given directory can only contain a single umbrella header.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Any headers not included by the umbrella header should have
+explicit <tt class="docutils literal"><span class="pre">header</span></tt> declarations. Use the
+<tt class="docutils literal"><span class="pre">-Wincomplete-umbrella</span></tt> warning option to ask Clang to complain
+about headers not covered by the umbrella header or the module map.</p>
+</div>
+<p>A header with the <tt class="docutils literal"><span class="pre">private</span></tt> specifier may not be included from outside the module itself.</p>
+<p>A header with the <tt class="docutils literal"><span class="pre">textual</span></tt> specifier will not be compiled when the module is
+built, and will be textually included if it is named by a <tt class="docutils literal"><span class="pre">#include</span></tt>
+directive. However, it is considered to be part of the module for the purpose
+of checking <em>use-declaration</em>s, and must still be a lexically-valid header
+file. In the future, we intend to pre-tokenize such headers and include the
+token sequence within the prebuilt module representation.</p>
+<p>A header with the <tt class="docutils literal"><span class="pre">exclude</span></tt> specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module, even if an <tt class="docutils literal"><span class="pre">umbrella</span></tt> header or directory would otherwise make it part of the module.</p>
+<p><strong>Example:</strong> The C header <tt class="docutils literal"><span class="pre">assert.h</span></tt> is an excellent candidate for a textual header, because it is meant to be included multiple times (possibly with different <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> settings). However, declarations within it should typically be split into a separate modular header.</p>
+<div class="highlight-python"><div class="highlight"><pre>module std [system] {
+  textual header "assert.h"
+}
+</pre></div>
+</div>
+<p>A given header shall not be referenced by more than one <em>header-declaration</em>.</p>
+</div>
+<div class="section" id="umbrella-directory-declaration">
+<h4><a class="toc-backref" href="#id27">Umbrella directory declaration</a><a class="headerlink" href="#umbrella-directory-declaration" title="Permalink to this headline">Â¶</a></h4>
+<p>An umbrella directory declaration specifies that all of the headers in the specified directory should be included within the module.</p>
+<pre class="literal-block">
+<em>umbrella-dir-declaration</em>:
+  <tt class="docutils literal"><span class="pre">umbrella</span></tt> <em>string-literal</em>
+</pre>
+<p>The <em>string-literal</em> refers to a directory. When the module is built, all of the header files in that directory (and its subdirectories) are included in the module.</p>
+<p>An <em>umbrella-dir-declaration</em> shall not refer to the same directory as the location of an umbrella <em>header-declaration</em>. In other words, only a single kind of umbrella can be specified for a given directory.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Umbrella directories are useful for libraries that have a large number of headers but do not have an umbrella header.</p>
+</div>
+</div>
+<div class="section" id="submodule-declaration">
+<h4><a class="toc-backref" href="#id28">Submodule declaration</a><a class="headerlink" href="#submodule-declaration" title="Permalink to this headline">Â¶</a></h4>
+<p>Submodule declarations describe modules that are nested within their enclosing module.</p>
+<pre class="literal-block">
+<em>submodule-declaration</em>:
+  <em>module-declaration</em>
+  <em>inferred-submodule-declaration</em>
+</pre>
+<p>A <em>submodule-declaration</em> that is a <em>module-declaration</em> is a nested module. If the <em>module-declaration</em> has a <tt class="docutils literal"><span class="pre">framework</span></tt> specifier, the enclosing module shall have a <tt class="docutils literal"><span class="pre">framework</span></tt> specifier; the submodule’s contents shall be contained within the subdirectory <tt class="docutils literal"><span class="pre">Frameworks/SubName.framework</span></tt>, where <tt class="docutils literal"><span class="pre">SubName</span></tt> is the name of the submodule.</p>
+<p>A <em>submodule-declaration</em> that is an <em>inferred-submodule-declaration</em> describes a set of submodules that correspond to any headers that are part of the module but are not explicitly described by a <em>header-declaration</em>.</p>
+<pre class="literal-block">
+<em>inferred-submodule-declaration</em>:
+  <tt class="docutils literal"><span class="pre">explicit</span></tt><sub>opt</sub> <tt class="docutils literal"><span class="pre">framework</span></tt><sub>opt</sub> <tt class="docutils literal"><span class="pre">module</span></tt> '*' <em>attributes</em><sub>opt</sub> '{' <em>inferred-submodule-member*</em> '}'
+
+<em>inferred-submodule-member</em>:
+  <tt class="docutils literal"><span class="pre">export</span></tt> '*'
+</pre>
+<p>A module containing an <em>inferred-submodule-declaration</em> shall have either an umbrella header or an umbrella directory. The headers to which the <em>inferred-submodule-declaration</em> applies are exactly those headers included by the umbrella header (transitively) or included in the module because they reside within the umbrella directory (or its subdirectories).</p>
+<p>For each header included by the umbrella header or in the umbrella directory that is not named by a <em>header-declaration</em>, a module declaration is implicitly generated from the <em>inferred-submodule-declaration</em>. The module will:</p>
+<ul class="simple">
+<li>Have the same name as the header (without the file extension)</li>
+<li>Have the <tt class="docutils literal"><span class="pre">explicit</span></tt> specifier, if the <em>inferred-submodule-declaration</em> has the <tt class="docutils literal"><span class="pre">explicit</span></tt> specifier</li>
+<li>Have the <tt class="docutils literal"><span class="pre">framework</span></tt> specifier, if the
+<em>inferred-submodule-declaration</em> has the <tt class="docutils literal"><span class="pre">framework</span></tt> specifier</li>
+<li>Have the attributes specified by the <em>inferred-submodule-declaration</em></li>
+<li>Contain a single <em>header-declaration</em> naming that header</li>
+<li>Contain a single <em>export-declaration</em> <tt class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></tt>, if the <em>inferred-submodule-declaration</em> contains the <em>inferred-submodule-member</em> <tt class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></tt></li>
+</ul>
+<p><strong>Example:</strong> If the subdirectory “MyLib” contains the headers <tt class="docutils literal"><span class="pre">A.h</span></tt> and <tt class="docutils literal"><span class="pre">B.h</span></tt>, then the following module map:</p>
+<div class="highlight-python"><div class="highlight"><pre>module MyLib {
+  umbrella "MyLib"
+  explicit module * {
+    export *
+  }
+}
+</pre></div>
+</div>
+<p>is equivalent to the (more verbose) module map:</p>
+<div class="highlight-python"><div class="highlight"><pre>module MyLib {
+  explicit module A {
+    header "A.h"
+    export *
+  }
+
+  explicit module B {
+    header "B.h"
+    export *
+  }
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="export-declaration">
+<h4><a class="toc-backref" href="#id29">Export declaration</a><a class="headerlink" href="#export-declaration" title="Permalink to this headline">Â¶</a></h4>
+<p>An <em>export-declaration</em> specifies which imported modules will automatically be re-exported as part of a given module’s API.</p>
+<pre class="literal-block">
+<em>export-declaration</em>:
+  <tt class="docutils literal"><span class="pre">export</span></tt> <em>wildcard-module-id</em>
+
+<em>wildcard-module-id</em>:
+  <em>identifier</em>
+  '*'
+  <em>identifier</em> '.' <em>wildcard-module-id</em>
+</pre>
+<p>The <em>export-declaration</em> names a module or a set of modules that will be re-exported to any translation unit that imports the enclosing module. Each imported module that matches the <em>wildcard-module-id</em> up to, but not including, the first <tt class="docutils literal"><span class="pre">*</span></tt> will be re-exported.</p>
+<p><strong>Example:</strong> In the following example, importing <tt class="docutils literal"><span class="pre">MyLib.Derived</span></tt> also provides the API for <tt class="docutils literal"><span class="pre">MyLib.Base</span></tt>:</p>
+<div class="highlight-python"><div class="highlight"><pre>module MyLib {
+  module Base {
+    header "Base.h"
+  }
+
+  module Derived {
+    header "Derived.h"
+    export Base
+  }
+}
+</pre></div>
+</div>
+<p>Note that, if <tt class="docutils literal"><span class="pre">Derived.h</span></tt> includes <tt class="docutils literal"><span class="pre">Base.h</span></tt>, one can simply use a wildcard export to re-export everything <tt class="docutils literal"><span class="pre">Derived.h</span></tt> includes:</p>
+<div class="highlight-python"><div class="highlight"><pre>module MyLib {
+  module Base {
+    header "Base.h"
+  }
+
+  module Derived {
+    header "Derived.h"
+    export *
+  }
+}
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The wildcard export syntax <tt class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></tt> re-exports all of the
+modules that were imported in the actual header file. Because
+<tt class="docutils literal"><span class="pre">#include</span></tt> directives are automatically mapped to module imports,
+<tt class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></tt> provides the same transitive-inclusion behavior
+provided by the C preprocessor, e.g., importing a given module
+implicitly imports all of the modules on which it depends.
+Therefore, liberal use of <tt class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></tt> provides excellent backward
+compatibility for programs that rely on transitive inclusion (i.e.,
+all of them).</p>
+</div>
+</div>
+<div class="section" id="use-declaration">
+<h4><a class="toc-backref" href="#id30">Use declaration</a><a class="headerlink" href="#use-declaration" title="Permalink to this headline">Â¶</a></h4>
+<p>A <em>use-declaration</em> specifies another module that the current top-level module
+intends to use. When the option <em>-fmodules-decluse</em> is specified, a module can
+only use other modules that are explicitly specified in this way.</p>
+<pre class="literal-block">
+<em>use-declaration</em>:
+  <tt class="docutils literal"><span class="pre">use</span></tt> <em>module-id</em>
+</pre>
+<p><strong>Example:</strong> In the following example, use of A from C is not declared, so will trigger a warning.</p>
+<div class="highlight-python"><div class="highlight"><pre>module A {
+  header "a.h"
+}
+
+module B {
+  header "b.h"
+}
+
+module C {
+  header "c.h"
+  use B
+}
+</pre></div>
+</div>
+<p>When compiling a source file that implements a module, use the option
+<tt class="docutils literal"><span class="pre">-fmodule-name=module-id</span></tt> to indicate that the source file is logically part
+of that module.</p>
+<p>The compiler at present only applies restrictions to the module directly being built.</p>
+</div>
+<div class="section" id="link-declaration">
+<h4><a class="toc-backref" href="#id31">Link declaration</a><a class="headerlink" href="#link-declaration" title="Permalink to this headline">Â¶</a></h4>
+<p>A <em>link-declaration</em> specifies a library or framework against which a program should be linked if the enclosing module is imported in any translation unit in that program.</p>
+<pre class="literal-block">
+<em>link-declaration</em>:
+  <tt class="docutils literal"><span class="pre">link</span></tt> <tt class="docutils literal"><span class="pre">framework</span></tt><sub>opt</sub> <em>string-literal</em>
+</pre>
+<p>The <em>string-literal</em> specifies the name of the library or framework against which the program should be linked. For example, specifying “clangBasic” would instruct the linker to link with <tt class="docutils literal"><span class="pre">-lclangBasic</span></tt> for a Unix-style linker.</p>
+<p>A <em>link-declaration</em> with the <tt class="docutils literal"><span class="pre">framework</span></tt> specifies that the linker should link against the named framework, e.g., with <tt class="docutils literal"><span class="pre">-framework</span> <span class="pre">MyFramework</span></tt>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Automatic linking with the <tt class="docutils literal"><span class="pre">link</span></tt> directive is not yet widely
+implemented, because it requires support from both the object file
+format and the linker. The notion is similar to Microsoft Visual
+Studio’s <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">comment(lib...)</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="configuration-macros-declaration">
+<h4><a class="toc-backref" href="#id32">Configuration macros declaration</a><a class="headerlink" href="#configuration-macros-declaration" title="Permalink to this headline">Â¶</a></h4>
+<p>The <em>config-macros-declaration</em> specifies the set of configuration macros that have an effect on the API of the enclosing module.</p>
+<pre class="literal-block">
+<em>config-macros-declaration</em>:
+  <tt class="docutils literal"><span class="pre">config_macros</span></tt> <em>attributes</em><sub>opt</sub> <em>config-macro-list</em><sub>opt</sub>
+
+<em>config-macro-list</em>:
+  <em>identifier</em> (',' <em>identifier</em>)*
+</pre>
+<p>Each <em>identifier</em> in the <em>config-macro-list</em> specifies the name of a macro. The compiler is required to maintain different variants of the given module for differing definitions of any of the named macros.</p>
+<p>A <em>config-macros-declaration</em> shall only be present on a top-level module, i.e., a module that is not nested within an enclosing module.</p>
+<p>The <tt class="docutils literal"><span class="pre">exhaustive</span></tt> attribute specifies that the list of macros in the <em>config-macros-declaration</em> is exhaustive, meaning that no other macro definition is intended to have an effect on the API of that module.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The <tt class="docutils literal"><span class="pre">exhaustive</span></tt> attribute implies that any macro definitions
+for macros not listed as configuration macros should be ignored
+completely when building the module. As an optimization, the
+compiler could reduce the number of unique module variants by not
+considering these non-configuration macros. This optimization is not
+yet implemented in Clang.</p>
+</div>
+<p>A translation unit shall not import the same module under different definitions of the configuration macros.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang implements a weak form of this requirement: the definitions
+used for configuration macros are fixed based on the definitions
+provided by the command line. If an import occurs and the definition
+of any configuration macro has changed, the compiler will produce a
+warning (under the control of <tt class="docutils literal"><span class="pre">-Wconfig-macros</span></tt>).</p>
+</div>
+<p><strong>Example:</strong> A logging library might provide different API (e.g., in the form of different definitions for a logging macro) based on the <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> macro setting:</p>
+<div class="highlight-python"><div class="highlight"><pre>module MyLogger {
+  umbrella header "MyLogger.h"
+  config_macros [exhaustive] NDEBUG
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="conflict-declarations">
+<h4><a class="toc-backref" href="#id33">Conflict declarations</a><a class="headerlink" href="#conflict-declarations" title="Permalink to this headline">Â¶</a></h4>
+<p>A <em>conflict-declaration</em> describes a case where the presence of two different modules in the same translation unit is likely to cause a problem. For example, two modules may provide similar-but-incompatible functionality.</p>
+<pre class="literal-block">
+<em>conflict-declaration</em>:
+  <tt class="docutils literal"><span class="pre">conflict</span></tt> <em>module-id</em> ',' <em>string-literal</em>
+</pre>
+<p>The <em>module-id</em> of the <em>conflict-declaration</em> specifies the module with which the enclosing module conflicts. The specified module shall not have been imported in the translation unit when the enclosing module is imported.</p>
+<p>The <em>string-literal</em> provides a message to be provided as part of the compiler diagnostic when two modules conflict.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang emits a warning (under the control of <tt class="docutils literal"><span class="pre">-Wmodule-conflict</span></tt>)
+when a module conflict is discovered.</p>
+</div>
+<p><strong>Example:</strong></p>
+<div class="highlight-python"><div class="highlight"><pre>module Conflicts {
+  explicit module A {
+    header "conflict_a.h"
+    conflict B, "we just don't like B"
+  }
+
+  module B {
+    header "conflict_b.h"
+  }
+}
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="attributes">
+<h3><a class="toc-backref" href="#id34">Attributes</a><a class="headerlink" href="#attributes" title="Permalink to this headline">Â¶</a></h3>
+<p>Attributes are used in a number of places in the grammar to describe specific behavior of other declarations. The format of attributes is fairly simple.</p>
+<pre class="literal-block">
+<em>attributes</em>:
+  <em>attribute</em> <em>attributes</em><sub>opt</sub>
+
+<em>attribute</em>:
+  '[' <em>identifier</em> ']'
+</pre>
+<p>Any <em>identifier</em> can be used as an attribute, and each declaration specifies what attributes can be applied to it.</p>
+</div>
+<div class="section" id="private-module-map-files">
+<h3><a class="toc-backref" href="#id35">Private Module Map Files</a><a class="headerlink" href="#private-module-map-files" title="Permalink to this headline">Â¶</a></h3>
+<p>Module map files are typically named <tt class="docutils literal"><span class="pre">module.modulemap</span></tt> and live
+either alongside the headers they describe or in a parent directory of
+the headers they describe. These module maps typically describe all of
+the API for the library.</p>
+<p>However, in some cases, the presence or absence of particular headers
+is used to distinguish between the “public” and “private” APIs of a
+particular library. For example, a library may contain the headers
+<tt class="docutils literal"><span class="pre">Foo.h</span></tt> and <tt class="docutils literal"><span class="pre">Foo_Private.h</span></tt>, providing public and private APIs,
+respectively. Additionally, <tt class="docutils literal"><span class="pre">Foo_Private.h</span></tt> may only be available on
+some versions of library, and absent in others. One cannot easily
+express this with a single module map file in the library:</p>
+<div class="highlight-python"><div class="highlight"><pre>module Foo {
+  header "Foo.h"
+
+  explicit module Private {
+    header "Foo_Private.h"
+  }
+}
+</pre></div>
+</div>
+<p>because the header <tt class="docutils literal"><span class="pre">Foo_Private.h</span></tt> won’t always be available. The
+module map file could be customized based on whether
+<tt class="docutils literal"><span class="pre">Foo_Private.h</span></tt> is available or not, but doing so requires custom
+build machinery.</p>
+<p>Private module map files, which are named <tt class="docutils literal"><span class="pre">module.private.modulemap</span></tt>
+(or, for backward compatibility, <tt class="docutils literal"><span class="pre">module_private.map</span></tt>), allow one to
+augment the primary module map file with an additional submodule. For
+example, we would split the module map file above into two module map
+files:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* module.modulemap */</span>
+<span class="n">module</span> <span class="n">Foo</span> <span class="p">{</span>
+  <span class="n">header</span> <span class="s">"Foo.h"</span>
+<span class="p">}</span>
+
+<span class="cm">/* module.private.modulemap */</span>
+<span class="n">explicit</span> <span class="n">module</span> <span class="n">Foo</span><span class="p">.</span><span class="n">Private</span> <span class="p">{</span>
+  <span class="n">header</span> <span class="s">"Foo_Private.h"</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>When a <tt class="docutils literal"><span class="pre">module.private.modulemap</span></tt> file is found alongside a
+<tt class="docutils literal"><span class="pre">module.modulemap</span></tt> file, it is loaded after the <tt class="docutils literal"><span class="pre">module.modulemap</span></tt>
+file. In our example library, the <tt class="docutils literal"><span class="pre">module.private.modulemap</span></tt> file
+would be available when <tt class="docutils literal"><span class="pre">Foo_Private.h</span></tt> is available, making it
+easier to split a library’s public and private APIs along header
+boundaries.</p>
+</div>
+</div>
+<div class="section" id="modularizing-a-platform">
+<h2><a class="toc-backref" href="#id36">Modularizing a Platform</a><a class="headerlink" href="#modularizing-a-platform" title="Permalink to this headline">Â¶</a></h2>
+<p>To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system’s headers and the C standard library headers (in <tt class="docutils literal"><span class="pre">/usr/include</span></tt>, for a Unix system).</p>
+<p>The module maps will be written using the <a class="reference internal" href="#module-map-language">module map language</a>, which provides the tools necessary to describe the mapping between headers and modules. Because the set of headers differs from one system to the next, the module map will likely have to be somewhat customized for, e.g., a particular distribution and version of the operating system. Moreover, the system headers themselves may require some modification, if they exhibit any anti-patterns that break modules. Such common patterns are described below.</p>
+<dl class="docutils">
+<dt><strong>Macro-guarded copy-and-pasted definitions</strong></dt>
+<dd><p class="first">System headers vend core types such as <tt class="docutils literal"><span class="pre">size_t</span></tt> for users. These types are often needed in a number of system headers, and are almost trivial to write. Hence, it is fairly common to see a definition such as the following copy-and-pasted throughout the headers:</p>
+<div class="highlight-python"><div class="highlight"><pre>#ifndef _SIZE_T
+#define _SIZE_T
+typedef __SIZE_TYPE__ size_t;
+#endif
+</pre></div>
+</div>
+<p class="last">Unfortunately, when modules compiles all of the C library headers together into a single module, only the first actual type definition of <tt class="docutils literal"><span class="pre">size_t</span></tt> will be visible, and then only in the submodule corresponding to the lucky first header. Any other headers that have copy-and-pasted versions of this pattern will <em>not</em> have a definition of <tt class="docutils literal"><span class="pre">size_t</span></tt>. Importing the submodule corresponding to one of those headers will therefore not yield <tt class="docutils literal"><span class="pre">size_t</span></tt> as part of the API, because it wasn’t there when the header was parsed. The fix for this problem is either to pull the copied declarations into a common header that gets included everywhere <tt class="docutils literal"><span class="pre">size_t</span></tt> is part of the API, or to eliminate the <tt class="docutils literal"><span class="pre">#ifndef</sp
 an></tt> and redefine the <tt class="docutils literal"><span class="pre">size_t</span></tt> type. The latter works for C++ headers and C11, but will cause an error for non-modules C90/C99, where redefinition of <tt class="docutils literal"><span class="pre">typedefs</span></tt> is not permitted.</p>
+</dd>
+<dt><strong>Conflicting definitions</strong></dt>
+<dd>Different system headers may provide conflicting definitions for various macros, functions, or types. These conflicting definitions don’t tend to cause problems in a pre-modules world unless someone happens to include both headers in one translation unit. Since the fix is often simply “don’t do that”, such problems persist. Modules requires that the conflicting definitions be eliminated or that they be placed in separate modules (the former is generally the better answer).</dd>
+<dt><strong>Missing includes</strong></dt>
+<dd>Headers are often missing <tt class="docutils literal"><span class="pre">#include</span></tt> directives for headers that they actually depend on. As with the problem of conflicting definitions, this only affects unlucky users who don’t happen to include headers in the right order. With modules, the headers of a particular module will be parsed in isolation, so the module may fail to build if there are missing includes.</dd>
+<dt><strong>Headers that vend multiple APIs at different times</strong></dt>
+<dd>Some systems have headers that contain a number of different kinds of API definitions, only some of which are made available with a given include. For example, the header may vend <tt class="docutils literal"><span class="pre">size_t</span></tt> only when the macro <tt class="docutils literal"><span class="pre">__need_size_t</span></tt> is defined before that header is included, and also vend <tt class="docutils literal"><span class="pre">wchar_t</span></tt> only when the macro <tt class="docutils literal"><span class="pre">__need_wchar_t</span></tt> is defined. Such headers are often included many times in a single translation unit, and will have no include guards. There is no sane way to map this header to a submodule. One can either eliminate the header (e.g., by splitting it into separate headers, one per actual API) or simply <tt class="docutils literal"><span class="pre">exclude</span></tt> it in the module map.</dd>
+</dl>
+<p>To detect and help address some of these problems, the <tt class="docutils literal"><span class="pre">clang-tools-extra</span></tt> repository contains a <tt class="docutils literal"><span class="pre">modularize</span></tt> tool that parses a set of given headers and attempts to detect these problems and produce a report. See the tool’s in-source documentation for information on how to check your system or library headers.</p>
+</div>
+<div class="section" id="future-directions">
+<h2><a class="toc-backref" href="#id37">Future Directions</a><a class="headerlink" href="#future-directions" title="Permalink to this headline">Â¶</a></h2>
+<p>Modules support is under active development, and there are many opportunities remaining to improve it. Here are a few ideas:</p>
+<dl class="docutils">
+<dt><strong>Detect unused module imports</strong></dt>
+<dd>Unlike with <tt class="docutils literal"><span class="pre">#include</span></tt> directives, it should be fairly simple to track whether a directly-imported module has ever been used. By doing so, Clang can emit <tt class="docutils literal"><span class="pre">unused</span> <span class="pre">import</span></tt> or <tt class="docutils literal"><span class="pre">unused</span> <span class="pre">#include</span></tt> diagnostics, including Fix-Its to remove the useless imports/includes.</dd>
+<dt><strong>Fix-Its for missing imports</strong></dt>
+<dd>It’s fairly common for one to make use of some API while writing code, only to get a compiler error about “unknown type” or “no function named” because the corresponding header has not been included. Clang can detect such cases and auto-import the required module, but should provide a Fix-It to add the import.</dd>
+<dt><strong>Improve modularize</strong></dt>
+<dd>The modularize tool is both extremely important (for deployment) and extremely crude. It needs better UI, better detection of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.</dd>
+</dl>
+</div>
+<div class="section" id="where-to-learn-more-about-modules">
+<h2><a class="toc-backref" href="#id38">Where To Learn More About Modules</a><a class="headerlink" href="#where-to-learn-more-about-modules" title="Permalink to this headline">Â¶</a></h2>
+<p>The Clang source code provides additional information about modules:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">clang/lib/Headers/module.modulemap</span></tt></dt>
+<dd>Module map for Clang’s compiler-specific header files.</dd>
+<dt><tt class="docutils literal"><span class="pre">clang/test/Modules/</span></tt></dt>
+<dd>Tests specifically related to modules functionality.</dd>
+<dt><tt class="docutils literal"><span class="pre">clang/include/clang/Basic/Module.h</span></tt></dt>
+<dd>The <tt class="docutils literal"><span class="pre">Module</span></tt> class in this header describes a module, and is used throughout the compiler to implement modules.</dd>
+<dt><tt class="docutils literal"><span class="pre">clang/include/clang/Lex/ModuleMap.h</span></tt></dt>
+<dd>The <tt class="docutils literal"><span class="pre">ModuleMap</span></tt> class in this header describes the full module map, consisting of all of the module map files that have been parsed, and providing facilities for looking up module maps and mapping between modules and headers (in both directions).</dd>
+<dt><a class="reference external" href="PCHInternals.html">PCHInternals</a></dt>
+<dd>Information about the serialized AST format used for precompiled headers and modules. The actual implementation is in the <tt class="docutils literal"><span class="pre">clangSerialization</span></tt> library.</dd>
+</dl>
+<table class="docutils footnote" frame="void" id="id5" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Automatic linking against the libraries of modules requires specific linker support, which is not widely available.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id6" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section <a class="reference internal" href="#modularizing-a-platform">Modularizing a Platform</a> describes some of them.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id7" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id8" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any <tt class="docutils literal"><span class="pre">-D</span></tt> options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the <a class="reference internal" href="#configuration-macros-declaration">Configuration macros declaration</a> for more information.</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="SafeStack.html">SafeStack</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="MSVCCompatibility.html">MSVC compatibility</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/ObjectiveCLiterals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/ObjectiveCLiterals.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/ObjectiveCLiterals.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/ObjectiveCLiterals.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,598 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Objective-C Literals — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="next" title="Language Specification for Blocks" href="BlockLanguageSpec.html" />
+    <link rel="prev" title="Clang Language Extensions" href="LanguageExtensions.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Objective-C Literals</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="LanguageExtensions.html">Clang Language Extensions</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="objective-c-literals">
+<h1>Objective-C Literals<a class="headerlink" href="#objective-c-literals" 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>Three new features were introduced into clang at the same time:
+<em>NSNumber Literals</em> provide a syntax for creating <tt class="docutils literal"><span class="pre">NSNumber</span></tt> from
+scalar literal expressions; <em>Collection Literals</em> provide a short-hand
+for creating arrays and dictionaries; <em>Object Subscripting</em> provides a
+way to use subscripting with Objective-C objects. Users of Apple
+compiler releases can use these features starting with the Apple LLVM
+Compiler 4.0. Users of open-source LLVM.org compiler releases can use
+these features starting with clang v3.1.</p>
+<p>These language additions simplify common Objective-C programming
+patterns, make programs more concise, and improve the safety of
+container creation.</p>
+<p>This document describes how the features are implemented in clang, and
+how to use them in your own programs.</p>
+</div>
+<div class="section" id="nsnumber-literals">
+<h2>NSNumber Literals<a class="headerlink" href="#nsnumber-literals" title="Permalink to this headline">Â¶</a></h2>
+<p>The framework class <tt class="docutils literal"><span class="pre">NSNumber</span></tt> is used to wrap scalar values inside
+objects: signed and unsigned integers (<tt class="docutils literal"><span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>,
+<tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>), floating point numbers (<tt class="docutils literal"><span class="pre">float</span></tt>,
+<tt class="docutils literal"><span class="pre">double</span></tt>), and boolean values (<tt class="docutils literal"><span class="pre">BOOL</span></tt>, C++ <tt class="docutils literal"><span class="pre">bool</span></tt>). Scalar values
+wrapped in objects are also known as <em>boxed</em> values.</p>
+<p>In Objective-C, any character, numeric or boolean literal prefixed with
+the <tt class="docutils literal"><span class="pre">'@'</span></tt> character will evaluate to a pointer to an <tt class="docutils literal"><span class="pre">NSNumber</span></tt>
+object initialized with that value. C’s type suffixes may be used to
+control the size of numeric literals.</p>
+<div class="section" id="examples">
+<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">Â¶</a></h3>
+<p>The following program illustrates the rules for <tt class="docutils literal"><span class="pre">NSNumber</span></tt> literals:</p>
+<div class="highlight-objc"><div class="highlight"><pre>void main(int argc, const char *argv[]) {
+  // character literals.
+  NSNumber *theLetterZ = @'Z';          // equivalent to [NSNumber numberWithChar:'Z']
+
+  // integral literals.
+  NSNumber *fortyTwo = @42;             // equivalent to [NSNumber numberWithInt:42]
+  NSNumber *fortyTwoUnsigned = @42U;    // equivalent to [NSNumber numberWithUnsignedInt:42U]
+  NSNumber *fortyTwoLong = @42L;        // equivalent to [NSNumber numberWithLong:42L]
+  NSNumber *fortyTwoLongLong = @42LL;   // equivalent to [NSNumber numberWithLongLong:42LL]
+
+  // floating point literals.
+  NSNumber *piFloat = @3.141592654F;    // equivalent to [NSNumber numberWithFloat:3.141592654F]
+  NSNumber *piDouble = @3.1415926535;   // equivalent to [NSNumber numberWithDouble:3.1415926535]
+
+  // BOOL literals.
+  NSNumber *yesNumber = @YES;           // equivalent to [NSNumber numberWithBool:YES]
+  NSNumber *noNumber = @NO;             // equivalent to [NSNumber numberWithBool:NO]
+
+#ifdef __cplusplus
+  NSNumber *trueNumber = @true;         // equivalent to [NSNumber numberWithBool:(BOOL)true]
+  NSNumber *falseNumber = @false;       // equivalent to [NSNumber numberWithBool:(BOOL)false]
+#endif
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="discussion">
+<h3>Discussion<a class="headerlink" href="#discussion" title="Permalink to this headline">Â¶</a></h3>
+<p>NSNumber literals only support literal scalar values after the <tt class="docutils literal"><span class="pre">'@'</span></tt>.
+Consequently, <tt class="docutils literal"><span class="pre">@INT_MAX</span></tt> works, but <tt class="docutils literal"><span class="pre">@INT_MIN</span></tt> does not, because
+they are defined like this:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="cp">#define INT_MAX   2147483647  </span><span class="cm">/* max value for an int */</span><span class="cp"></span>
+<span class="cp">#define INT_MIN   (-2147483647-1) </span><span class="cm">/* min value for an int */</span><span class="cp"></span>
+</pre></div>
+</div>
+<p>The definition of <tt class="docutils literal"><span class="pre">INT_MIN</span></tt> is not a simple literal, but a
+parenthesized expression. Parenthesized expressions are supported using
+the <a class="reference external" href="#objc_boxed_expressions">boxed expression</a> syntax, which is
+described in the next section.</p>
+<p>Because <tt class="docutils literal"><span class="pre">NSNumber</span></tt> does not currently support wrapping <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt>
+values, the use of a <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span> <span class="pre">NSNumber</span></tt> literal (e.g.
+<tt class="docutils literal"><span class="pre">@123.23L</span></tt>) will be rejected by the compiler.</p>
+<p>Previously, the <tt class="docutils literal"><span class="pre">BOOL</span></tt> type was simply a typedef for <tt class="docutils literal"><span class="pre">signed</span> <span class="pre">char</span></tt>,
+and <tt class="docutils literal"><span class="pre">YES</span></tt> and <tt class="docutils literal"><span class="pre">NO</span></tt> were macros that expand to <tt class="docutils literal"><span class="pre">(BOOL)1</span></tt> and
+<tt class="docutils literal"><span class="pre">(BOOL)0</span></tt> respectively. To support <tt class="docutils literal"><span class="pre">@YES</span></tt> and <tt class="docutils literal"><span class="pre">@NO</span></tt> expressions,
+these macros are now defined using new language keywords in
+<tt class="docutils literal"><span class="pre"><objc/objc.h></span></tt>:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="cp">#if __has_feature(objc_bool)</span>
+<span class="cp">#define YES             __objc_yes</span>
+<span class="cp">#define NO              __objc_no</span>
+<span class="cp">#else</span>
+<span class="cp">#define YES             ((BOOL)1)</span>
+<span class="cp">#define NO              ((BOOL)0)</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>The compiler implicitly converts <tt class="docutils literal"><span class="pre">__objc_yes</span></tt> and <tt class="docutils literal"><span class="pre">__objc_no</span></tt> to
+<tt class="docutils literal"><span class="pre">(BOOL)1</span></tt> and <tt class="docutils literal"><span class="pre">(BOOL)0</span></tt>. The keywords are used to disambiguate
+<tt class="docutils literal"><span class="pre">BOOL</span></tt> and integer literals.</p>
+<p>Objective-C++ also supports <tt class="docutils literal"><span class="pre">@true</span></tt> and <tt class="docutils literal"><span class="pre">@false</span></tt> expressions, which
+are equivalent to <tt class="docutils literal"><span class="pre">@YES</span></tt> and <tt class="docutils literal"><span class="pre">@NO</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="boxed-expressions">
+<h2>Boxed Expressions<a class="headerlink" href="#boxed-expressions" title="Permalink to this headline">Â¶</a></h2>
+<p>Objective-C provides a new syntax for boxing C expressions:</p>
+<div class="highlight-objc"><div class="highlight"><pre>@( <expression> )
+</pre></div>
+</div>
+<p>Expressions of scalar (numeric, enumerated, BOOL), C string pointer
+and some C structures (via NSValue) are supported:</p>
+<div class="highlight-objc"><div class="highlight"><pre>// numbers.
+NSNumber *smallestInt = @(-INT_MAX - 1);  // [NSNumber numberWithInt:(-INT_MAX - 1)]
+NSNumber *piOverTwo = @(M_PI / 2);        // [NSNumber numberWithDouble:(M_PI / 2)]
+
+// enumerated types.
+typedef enum { Red, Green, Blue } Color;
+NSNumber *favoriteColor = @(Green);       // [NSNumber numberWithInt:((int)Green)]
+
+// strings.
+NSString *path = @(getenv("PATH"));       // [NSString stringWithUTF8String:(getenv("PATH"))]
+NSArray *pathComponents = [path componentsSeparatedByString:@":"];
+
+// structs.
+NSValue *center = @(view.center);         // Point p = view.center;
+                                          // [NSValue valueWithBytes:&p objCType:@encode(Point)];
+NSValue *frame = @(view.frame);           // Rect r = view.frame;
+                                          // [NSValue valueWithBytes:&r objCType:@encode(Rect)];
+</pre></div>
+</div>
+<div class="section" id="boxed-enums">
+<h3>Boxed Enums<a class="headerlink" href="#boxed-enums" title="Permalink to this headline">Â¶</a></h3>
+<p>Cocoa frameworks frequently define constant values using <em>enums.</em>
+Although enum values are integral, they may not be used directly as
+boxed literals (this avoids conflicts with future <tt class="docutils literal"><span class="pre">'@'</span></tt>-prefixed
+Objective-C keywords). Instead, an enum value must be placed inside a
+boxed expression. The following example demonstrates configuring an
+<tt class="docutils literal"><span class="pre">AVAudioRecorder</span></tt> using a dictionary that contains a boxed enumeration
+value:</p>
+<div class="highlight-objc"><div class="highlight"><pre>enum {
+  AVAudioQualityMin = 0,
+  AVAudioQualityLow = 0x20,
+  AVAudioQualityMedium = 0x40,
+  AVAudioQualityHigh = 0x60,
+  AVAudioQualityMax = 0x7F
+};
+
+- (AVAudioRecorder *)recordToFile:(NSURL *)fileURL {
+  NSDictionary *settings = @{ AVEncoderAudioQualityKey : @(AVAudioQualityMax) };
+  return [[AVAudioRecorder alloc] initWithURL:fileURL settings:settings error:NULL];
+}
+</pre></div>
+</div>
+<p>The expression <tt class="docutils literal"><span class="pre">@(AVAudioQualityMax)</span></tt> converts <tt class="docutils literal"><span class="pre">AVAudioQualityMax</span></tt>
+to an integer type, and boxes the value accordingly. If the enum has a
+<a class="reference internal" href="LanguageExtensions.html#objc-fixed-enum"><em>fixed underlying type</em></a> as in:</p>
+<div class="highlight-objc"><div class="highlight"><pre>typedef enum : unsigned char { Red, Green, Blue } Color;
+NSNumber *red = @(Red), *green = @(Green), *blue = @(Blue); // => [NSNumber numberWithUnsignedChar:]
+</pre></div>
+</div>
+<p>then the fixed underlying type will be used to select the correct
+<tt class="docutils literal"><span class="pre">NSNumber</span></tt> creation method.</p>
+<p>Boxing a value of enum type will result in a <tt class="docutils literal"><span class="pre">NSNumber</span></tt> pointer with a
+creation method according to the underlying type of the enum, which can
+be a <a class="reference internal" href="LanguageExtensions.html#objc-fixed-enum"><em>fixed underlying type</em></a>
+or a compiler-defined integer type capable of representing the values of
+all the members of the enumeration:</p>
+<div class="highlight-objc"><div class="highlight"><pre>typedef enum : unsigned char { Red, Green, Blue } Color;
+Color col = Red;
+NSNumber *nsCol = @(col); // => [NSNumber numberWithUnsignedChar:]
+</pre></div>
+</div>
+</div>
+<div class="section" id="boxed-c-strings">
+<h3>Boxed C Strings<a class="headerlink" href="#boxed-c-strings" title="Permalink to this headline">Â¶</a></h3>
+<p>A C string literal prefixed by the <tt class="docutils literal"><span class="pre">'@'</span></tt> token denotes an <tt class="docutils literal"><span class="pre">NSString</span></tt>
+literal in the same way a numeric literal prefixed by the <tt class="docutils literal"><span class="pre">'@'</span></tt> token
+denotes an <tt class="docutils literal"><span class="pre">NSNumber</span></tt> literal. When the type of the parenthesized
+expression is <tt class="docutils literal"><span class="pre">(char</span> <span class="pre">*)</span></tt> or <tt class="docutils literal"><span class="pre">(const</span> <span class="pre">char</span> <span class="pre">*)</span></tt>, the result of the
+boxed expression is a pointer to an <tt class="docutils literal"><span class="pre">NSString</span></tt> object containing
+equivalent character data, which is assumed to be ‘\0’-terminated and
+UTF-8 encoded. The following example converts C-style command line
+arguments into <tt class="docutils literal"><span class="pre">NSString</span></tt> objects.</p>
+<div class="highlight-objc"><div class="highlight"><pre>// Partition command line arguments into positional and option arguments.
+NSMutableArray *args = [NSMutableArray new];
+NSMutableDictionary *options = [NSMutableDictionary new];
+while (--argc) {
+    const char *arg = *++argv;
+    if (strncmp(arg, "--", 2) == 0) {
+        options[@(arg + 2)] = @(*++argv);   // --key value
+    } else {
+        [args addObject:@(arg)];            // positional argument
+    }
+}
+</pre></div>
+</div>
+<p>As with all C pointers, character pointer expressions can involve
+arbitrary pointer arithmetic, therefore programmers must ensure that the
+character data is valid. Passing <tt class="docutils literal"><span class="pre">NULL</span></tt> as the character pointer will
+raise an exception at runtime. When possible, the compiler will reject
+<tt class="docutils literal"><span class="pre">NULL</span></tt> character pointers used in boxed expressions.</p>
+</div>
+<div class="section" id="boxed-c-structures">
+<h3>Boxed C Structures<a class="headerlink" href="#boxed-c-structures" title="Permalink to this headline">Â¶</a></h3>
+<p>Boxed expressions support construction of NSValue objects.
+It said that C structures can be used, the only requirement is:
+structure should be marked with <tt class="docutils literal"><span class="pre">objc_boxable</span></tt> attribute.
+To support older version of frameworks and/or third-party libraries
+you may need to add the attribute via <tt class="docutils literal"><span class="pre">typedef</span></tt>.</p>
+<div class="highlight-objc"><div class="highlight"><pre>struct __attribute__((objc_boxable)) Point {
+    // ...
+};
+
+typedef struct __attribute__((objc_boxable)) _Size {
+    // ...
+} Size;
+
+typedef struct _Rect {
+    // ...
+} Rect;
+
+struct Point p;
+NSValue *point = @(p);          // ok
+Size s;
+NSValue *size = @(s);           // ok
+
+Rect r;
+NSValue *bad_rect = @(r);       // error
+
+typedef struct __attribute__((objc_boxable)) _Rect Rect;
+
+NSValue *good_rect = @(r);      // ok
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="container-literals">
+<h2>Container Literals<a class="headerlink" href="#container-literals" title="Permalink to this headline">Â¶</a></h2>
+<p>Objective-C now supports a new expression syntax for creating immutable
+array and dictionary container objects.</p>
+<div class="section" id="id1">
+<h3>Examples<a class="headerlink" href="#id1" title="Permalink to this headline">Â¶</a></h3>
+<p>Immutable array expression:</p>
+<div class="highlight-objc"><div class="highlight"><pre>NSArray *array = @[ @"Hello", NSApp, [NSNumber numberWithInt:42] ];
+</pre></div>
+</div>
+<p>This creates an <tt class="docutils literal"><span class="pre">NSArray</span></tt> with 3 elements. The comma-separated
+sub-expressions of an array literal can be any Objective-C object
+pointer typed expression.</p>
+<p>Immutable dictionary expression:</p>
+<div class="highlight-objc"><div class="highlight"><pre>NSDictionary *dictionary = @{
+    @"name" : NSUserName(),
+    @"date" : [NSDate date],
+    @"processInfo" : [NSProcessInfo processInfo]
+};
+</pre></div>
+</div>
+<p>This creates an <tt class="docutils literal"><span class="pre">NSDictionary</span></tt> with 3 key/value pairs. Value
+sub-expressions of a dictionary literal must be Objective-C object
+pointer typed, as in array literals. Key sub-expressions must be of an
+Objective-C object pointer type that implements the
+<tt class="docutils literal"><span class="pre"><NSCopying></span></tt> protocol.</p>
+</div>
+<div class="section" id="id2">
+<h3>Discussion<a class="headerlink" href="#id2" title="Permalink to this headline">Â¶</a></h3>
+<p>Neither keys nor values can have the value <tt class="docutils literal"><span class="pre">nil</span></tt> in containers. If the
+compiler can prove that a key or value is <tt class="docutils literal"><span class="pre">nil</span></tt> at compile time, then
+a warning will be emitted. Otherwise, a runtime error will occur.</p>
+<p>Using array and dictionary literals is safer than the variadic creation
+forms commonly in use today. Array literal expressions expand to calls
+to <tt class="docutils literal"><span class="pre">+[NSArray</span> <span class="pre">arrayWithObjects:count:]</span></tt>, which validates that all
+objects are non-<tt class="docutils literal"><span class="pre">nil</span></tt>. The variadic form,
+<tt class="docutils literal"><span class="pre">+[NSArray</span> <span class="pre">arrayWithObjects:]</span></tt> uses <tt class="docutils literal"><span class="pre">nil</span></tt> as an argument list
+terminator, which can lead to malformed array objects. Dictionary
+literals are similarly created with
+<tt class="docutils literal"><span class="pre">+[NSDictionary</span> <span class="pre">dictionaryWithObjects:forKeys:count:]</span></tt> which validates
+all objects and keys, unlike
+<tt class="docutils literal"><span class="pre">+[NSDictionary</span> <span class="pre">dictionaryWithObjectsAndKeys:]</span></tt> which also uses a
+<tt class="docutils literal"><span class="pre">nil</span></tt> parameter as an argument list terminator.</p>
+</div>
+</div>
+<div class="section" id="object-subscripting">
+<h2>Object Subscripting<a class="headerlink" href="#object-subscripting" title="Permalink to this headline">Â¶</a></h2>
+<p>Objective-C object pointer values can now be used with C’s subscripting
+operator.</p>
+<div class="section" id="id3">
+<h3>Examples<a class="headerlink" href="#id3" title="Permalink to this headline">Â¶</a></h3>
+<p>The following code demonstrates the use of object subscripting syntax
+with <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt> and <tt class="docutils literal"><span class="pre">NSMutableDictionary</span></tt> objects:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">NSMutableArray</span> <span class="o">*</span><span class="n">array</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">NSUInteger</span> <span class="n">idx</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">id</span> <span class="n">newObject</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">id</span> <span class="n">oldObject</span> <span class="o">=</span> <span class="n">array</span><span class="p">[</span><span class="n">idx</span><span class="p">];</span>
+<span class="n">array</span><span class="p">[</span><span class="n">idx</span><span class="p">]</span> <span class="o">=</span> <span class="n">newObject</span><span class="p">;</span>         <span class="c1">// replace oldObject with newObject</span>
+
+<span class="n">NSMutableDictionary</span> <span class="o">*</span><span class="n">dictionary</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">key</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">oldObject</span> <span class="o">=</span> <span class="n">dictionary</span><span class="p">[</span><span class="n">key</span><span class="p">];</span>
+<span class="n">dictionary</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">newObject</span><span class="p">;</span>    <span class="c1">// replace oldObject with newObject</span>
+</pre></div>
+</div>
+<p>The next section explains how subscripting expressions map to accessor
+methods.</p>
+</div>
+<div class="section" id="subscripting-methods">
+<h3>Subscripting Methods<a class="headerlink" href="#subscripting-methods" title="Permalink to this headline">Â¶</a></h3>
+<p>Objective-C supports two kinds of subscript expressions: <em>array-style</em>
+subscript expressions use integer typed subscripts; <em>dictionary-style</em>
+subscript expressions use Objective-C object pointer typed subscripts.
+Each type of subscript expression is mapped to a message send using a
+predefined selector. The advantage of this design is flexibility: class
+designers are free to introduce subscripting by declaring methods or by
+adopting protocols. Moreover, because the method names are selected by
+the type of the subscript, an object can be subscripted using both array
+and dictionary styles.</p>
+<div class="section" id="array-style-subscripting">
+<h4>Array-Style Subscripting<a class="headerlink" href="#array-style-subscripting" title="Permalink to this headline">Â¶</a></h4>
+<p>When the subscript operand has an integral type, the expression is
+rewritten to use one of two different selectors, depending on whether
+the element is being read or written. When an expression reads an
+element using an integral index, as in the following example:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">NSUInteger</span> <span class="n">idx</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">id</span> <span class="n">value</span> <span class="o">=</span> <span class="n">object</span><span class="p">[</span><span class="n">idx</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>it is translated into a call to <tt class="docutils literal"><span class="pre">objectAtIndexedSubscript:</span></tt></p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">object</span> <span class="n">objectAtIndexedSubscript</span><span class="o">:</span><span class="n">idx</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>When an expression writes an element using an integral index:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">object</span><span class="p">[</span><span class="n">idx</span><span class="p">]</span> <span class="o">=</span> <span class="n">newValue</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>it is translated to a call to <tt class="docutils literal"><span class="pre">setObject:atIndexedSubscript:</span></tt></p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">object</span> <span class="n">setObject</span><span class="o">:</span><span class="n">newValue</span> <span class="n">atIndexedSubscript</span><span class="o">:</span><span class="n">idx</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>These message sends are then type-checked and performed just like
+explicit message sends. The method used for objectAtIndexedSubscript:
+must be declared with an argument of integral type and a return value of
+some Objective-C object pointer type. The method used for
+setObject:atIndexedSubscript: must be declared with its first argument
+having some Objective-C pointer type and its second argument having
+integral type.</p>
+<p>The meaning of indexes is left up to the declaring class. The compiler
+will coerce the index to the appropriate argument type of the method it
+uses for type-checking. For an instance of <tt class="docutils literal"><span class="pre">NSArray</span></tt>, reading an
+element using an index outside the range <tt class="docutils literal"><span class="pre">[0,</span> <span class="pre">array.count)</span></tt> will raise
+an exception. For an instance of <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt>, assigning to an
+element using an index within this range will replace that element, but
+assigning to an element using an index outside this range will raise an
+exception; no syntax is provided for inserting, appending, or removing
+elements for mutable arrays.</p>
+<p>A class need not declare both methods in order to take advantage of this
+language feature. For example, the class <tt class="docutils literal"><span class="pre">NSArray</span></tt> declares only
+<tt class="docutils literal"><span class="pre">objectAtIndexedSubscript:</span></tt>, so that assignments to elements will fail
+to type-check; moreover, its subclass <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt> declares
+<tt class="docutils literal"><span class="pre">setObject:atIndexedSubscript:</span></tt>.</p>
+</div>
+<div class="section" id="dictionary-style-subscripting">
+<h4>Dictionary-Style Subscripting<a class="headerlink" href="#dictionary-style-subscripting" title="Permalink to this headline">Â¶</a></h4>
+<p>When the subscript operand has an Objective-C object pointer type, the
+expression is rewritten to use one of two different selectors, depending
+on whether the element is being read from or written to. When an
+expression reads an element using an Objective-C object pointer
+subscript operand, as in the following example:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">key</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">id</span> <span class="n">value</span> <span class="o">=</span> <span class="n">object</span><span class="p">[</span><span class="n">key</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>it is translated into a call to the <tt class="docutils literal"><span class="pre">objectForKeyedSubscript:</span></tt> method:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">object</span> <span class="n">objectForKeyedSubscript</span><span class="o">:</span><span class="n">key</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>When an expression writes an element using an Objective-C object pointer
+subscript:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">object</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">newValue</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>it is translated to a call to <tt class="docutils literal"><span class="pre">setObject:forKeyedSubscript:</span></tt></p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">object</span> <span class="n">setObject</span><span class="o">:</span><span class="n">newValue</span> <span class="n">forKeyedSubscript</span><span class="o">:</span><span class="n">key</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>The behavior of <tt class="docutils literal"><span class="pre">setObject:forKeyedSubscript:</span></tt> is class-specific; but
+in general it should replace an existing value if one is already
+associated with a key, otherwise it should add a new value for the key.
+No syntax is provided for removing elements from mutable dictionaries.</p>
+</div>
+</div>
+<div class="section" id="id4">
+<h3>Discussion<a class="headerlink" href="#id4" title="Permalink to this headline">Â¶</a></h3>
+<p>An Objective-C subscript expression occurs when the base operand of the
+C subscript operator has an Objective-C object pointer type. Since this
+potentially collides with pointer arithmetic on the value, these
+expressions are only supported under the modern Objective-C runtime,
+which categorically forbids such arithmetic.</p>
+<p>Currently, only subscripts of integral or Objective-C object pointer
+type are supported. In C++, a class type can be used if it has a single
+conversion function to an integral or Objective-C pointer type, in which
+case that conversion is applied and analysis continues as appropriate.
+Otherwise, the expression is ill-formed.</p>
+<p>An Objective-C object subscript expression is always an l-value. If the
+expression appears on the left-hand side of a simple assignment operator
+(=), the element is written as described below. If the expression
+appears on the left-hand side of a compound assignment operator (e.g.
++=), the program is ill-formed, because the result of reading an element
+is always an Objective-C object pointer and no binary operators are
+legal on such pointers. If the expression appears in any other position,
+the element is read as described below. It is an error to take the
+address of a subscript expression, or (in C++) to bind a reference to
+it.</p>
+<p>Programs can use object subscripting with Objective-C object pointers of
+type <tt class="docutils literal"><span class="pre">id</span></tt>. Normal dynamic message send rules apply; the compiler must
+see <em>some</em> declaration of the subscripting methods, and will pick the
+declaration seen first.</p>
+</div>
+</div>
+<div class="section" id="caveats">
+<h2>Caveats<a class="headerlink" href="#caveats" title="Permalink to this headline">Â¶</a></h2>
+<p>Objects created using the literal or boxed expression syntax are not
+guaranteed to be uniqued by the runtime, but nor are they guaranteed to
+be newly-allocated. As such, the result of performing direct comparisons
+against the location of an object literal (using <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">!=</span></tt>, <tt class="docutils literal"><span class="pre"><</span></tt>,
+<tt class="docutils literal"><span class="pre"><=</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, or <tt class="docutils literal"><span class="pre">>=</span></tt>) is not well-defined. This is usually a simple
+mistake in code that intended to call the <tt class="docutils literal"><span class="pre">isEqual:</span></tt> method (or the
+<tt class="docutils literal"><span class="pre">compare:</span></tt> method).</p>
+<p>This caveat applies to compile-time string literals as well.
+Historically, string literals (using the <tt class="docutils literal"><span class="pre">@"..."</span></tt> syntax) have been
+uniqued across translation units during linking. This is an
+implementation detail of the compiler and should not be relied upon. If
+you are using such code, please use global string constants instead
+(<tt class="docutils literal"><span class="pre">NSString</span> <span class="pre">*</span> <span class="pre">const</span> <span class="pre">MyConst</span> <span class="pre">=</span> <span class="pre">@"..."</span></tt>) or use <tt class="docutils literal"><span class="pre">isEqual:</span></tt>.</p>
+</div>
+<div class="section" id="grammar-additions">
+<h2>Grammar Additions<a class="headerlink" href="#grammar-additions" title="Permalink to this headline">Â¶</a></h2>
+<p>To support the new syntax described above, the Objective-C
+<tt class="docutils literal"><span class="pre">@</span></tt>-expression grammar has the following new productions:</p>
+<div class="highlight-python"><div class="highlight"><pre>objc-at-expression : '@' (string-literal | encode-literal | selector-literal | protocol-literal | object-literal)
+                   ;
+
+object-literal : ('+' | '-')? numeric-constant
+               | character-constant
+               | boolean-constant
+               | array-literal
+               | dictionary-literal
+               ;
+
+boolean-constant : '__objc_yes' | '__objc_no' | 'true' | 'false'  /* boolean keywords. */
+                 ;
+
+array-literal : '[' assignment-expression-list ']'
+              ;
+
+assignment-expression-list : assignment-expression (',' assignment-expression-list)?
+                           | /* empty */
+                           ;
+
+dictionary-literal : '{' key-value-list '}'
+                   ;
+
+key-value-list : key-value-pair (',' key-value-list)?
+               | /* empty */
+               ;
+
+key-value-pair : assignment-expression ':' assignment-expression
+               ;
+</pre></div>
+</div>
+<p>Note: <tt class="docutils literal"><span class="pre">@true</span></tt> and <tt class="docutils literal"><span class="pre">@false</span></tt> are only supported in Objective-C++.</p>
+</div>
+<div class="section" id="availability-checks">
+<h2>Availability Checks<a class="headerlink" href="#availability-checks" title="Permalink to this headline">Â¶</a></h2>
+<p>Programs test for the new features by using clang’s __has_feature
+checks. Here are examples of their use:</p>
+<div class="highlight-objc"><div class="highlight"><pre>#if __has_feature(objc_array_literals)
+    // new way.
+    NSArray *elements = @[ @"H", @"He", @"O", @"C" ];
+#else
+    // old way (equivalent).
+    id objects[] = { @"H", @"He", @"O", @"C" };
+    NSArray *elements = [NSArray arrayWithObjects:objects count:4];
+#endif
+
+#if __has_feature(objc_dictionary_literals)
+    // new way.
+    NSDictionary *masses = @{ @"H" : @1.0078,  @"He" : @4.0026, @"O" : @15.9990, @"C" : @12.0096 };
+#else
+    // old way (equivalent).
+    id keys[] = { @"H", @"He", @"O", @"C" };
+    id values[] = { [NSNumber numberWithDouble:1.0078], [NSNumber numberWithDouble:4.0026],
+                    [NSNumber numberWithDouble:15.9990], [NSNumber numberWithDouble:12.0096] };
+    NSDictionary *masses = [NSDictionary dictionaryWithObjects:objects forKeys:keys count:4];
+#endif
+
+#if __has_feature(objc_subscripting)
+    NSUInteger i, count = elements.count;
+    for (i = 0; i < count; ++i) {
+        NSString *element = elements[i];
+        NSNumber *mass = masses[element];
+        NSLog(@"the mass of %@ is %@", element, mass);
+    }
+#else
+    NSUInteger i, count = [elements count];
+    for (i = 0; i < count; ++i) {
+        NSString *element = [elements objectAtIndex:i];
+        NSNumber *mass = [masses objectForKey:element];
+        NSLog(@"the mass of %@ is %@", element, mass);
+    }
+#endif
+
+#if __has_attribute(objc_boxable)
+    typedef struct __attribute__((objc_boxable)) _Rect Rect;
+#endif
+
+#if __has_feature(objc_boxed_nsvalue_expressions)
+    CABasicAnimation animation = [CABasicAnimation animationWithKeyPath:@"position"];
+    animation.fromValue = @(layer.position);
+    animation.toValue = @(newPosition);
+    [layer addAnimation:animation forKey:@"move"];
+#else
+    CABasicAnimation animation = [CABasicAnimation animationWithKeyPath:@"position"];
+    animation.fromValue = [NSValue valueWithCGPoint:layer.position];
+    animation.toValue = [NSValue valueWithCGPoint:newPosition];
+    [layer addAnimation:animation forKey:@"move"];
+#endif
+</pre></div>
+</div>
+<p>Code can use also <tt class="docutils literal"><span class="pre">__has_feature(objc_bool)</span></tt> to check for the
+availability of numeric literals support. This checks for the new
+<tt class="docutils literal"><span class="pre">__objc_yes</span> <span class="pre">/</span> <span class="pre">__objc_no</span></tt> keywords, which enable the use of
+<tt class="docutils literal"><span class="pre">@YES</span> <span class="pre">/</span> <span class="pre">@NO</span></tt> literals.</p>
+<p>To check whether boxed expressions are supported, use
+<tt class="docutils literal"><span class="pre">__has_feature(objc_boxed_expressions)</span></tt> feature macro.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="LanguageExtensions.html">Clang Language Extensions</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/PCHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/PCHInternals.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/PCHInternals.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/PCHInternals.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,585 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Precompiled Header and Modules Internals — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="prev" title="Pretokenized Headers (PTH)" href="PTHInternals.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Precompiled Header and Modules Internals</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="precompiled-header-and-modules-internals">
+<h1>Precompiled Header and Modules Internals<a class="headerlink" href="#precompiled-header-and-modules-internals" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#using-precompiled-headers-with-clang" id="id1">Using Precompiled Headers with <tt class="docutils literal"><span class="pre">clang</span></tt></a></li>
+<li><a class="reference internal" href="#design-philosophy" id="id2">Design Philosophy</a></li>
+<li><a class="reference internal" href="#ast-file-contents" id="id3">AST File Contents</a><ul>
+<li><a class="reference internal" href="#metadata-block" id="id4">Metadata Block</a></li>
+<li><a class="reference internal" href="#source-manager-block" id="id5">Source Manager Block</a></li>
+<li><a class="reference internal" href="#preprocessor-block" id="id6">Preprocessor Block</a></li>
+<li><a class="reference internal" href="#types-block" id="id7">Types Block</a></li>
+<li><a class="reference internal" href="#declarations-block" id="id8">Declarations Block</a></li>
+<li><a class="reference internal" href="#statements-and-expressions" id="id9">Statements and Expressions</a></li>
+<li><a class="reference internal" href="#pchinternals-ident-table" id="id10">Identifier Table Block</a></li>
+<li><a class="reference internal" href="#method-pool-block" id="id11">Method Pool Block</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ast-reader-integration-points" id="id12">AST Reader Integration Points</a></li>
+<li><a class="reference internal" href="#chained-precompiled-headers" id="id13">Chained precompiled headers</a></li>
+<li><a class="reference internal" href="#modules" id="id14">Modules</a></li>
+</ul>
+</div>
+<p>This document describes the design and implementation of Clang’s precompiled
+headers (PCH) and modules.  If you are interested in the end-user view, please
+see the <a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>User’s Manual</em></a>.</p>
+<div class="section" id="using-precompiled-headers-with-clang">
+<h2><a class="toc-backref" href="#id1">Using Precompiled Headers with <tt class="docutils literal"><span class="pre">clang</span></tt></a><a class="headerlink" href="#using-precompiled-headers-with-clang" title="Permalink to this headline">Â¶</a></h2>
+<p>The Clang compiler frontend, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, supports two command line options
+for generating and using PCH files.</p>
+<p>To generate PCH files using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, use the option <em class="xref std std-option">-emit-pch</em>:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>clang -cc1 test.h -emit-pch -o test.h.pch
+</pre></div>
+</div>
+<p>This option is transparently used by <tt class="docutils literal"><span class="pre">clang</span></tt> when generating PCH files.  The
+resulting PCH file contains the serialized form of the compiler’s internal
+representation after it has completed parsing and semantic analysis.  The PCH
+file can then be used as a prefix header with the <em class="xref std std-option">-include-pch</em>
+option:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>clang -cc1 -include-pch test.h.pch test.c -o test.s
+</pre></div>
+</div>
+</div>
+<div class="section" id="design-philosophy">
+<h2><a class="toc-backref" href="#id2">Design Philosophy</a><a class="headerlink" href="#design-philosophy" title="Permalink to this headline">Â¶</a></h2>
+<p>Precompiled headers are meant to improve overall compile times for projects, so
+the design of precompiled headers is entirely driven by performance concerns.
+The use case for precompiled headers is relatively simple: when there is a
+common set of headers that is included in nearly every source file in the
+project, we <em>precompile</em> that bundle of headers into a single precompiled
+header (PCH file).  Then, when compiling the source files in the project, we
+load the PCH file first (as a prefix header), which acts as a stand-in for that
+bundle of headers.</p>
+<p>A precompiled header implementation improves performance when:</p>
+<ul class="simple">
+<li>Loading the PCH file is significantly faster than re-parsing the bundle of
+headers stored within the PCH file.  Thus, a precompiled header design
+attempts to minimize the cost of reading the PCH file.  Ideally, this cost
+should not vary with the size of the precompiled header file.</li>
+<li>The cost of generating the PCH file initially is not so large that it
+counters the per-source-file performance improvement due to eliminating the
+need to parse the bundled headers in the first place.  This is particularly
+important on multi-core systems, because PCH file generation serializes the
+build when all compilations require the PCH file to be up-to-date.</li>
+</ul>
+<p>Modules, as implemented in Clang, use the same mechanisms as precompiled
+headers to save a serialized AST file (one per module) and use those AST
+modules.  From an implementation standpoint, modules are a generalization of
+precompiled headers, lifting a number of restrictions placed on precompiled
+headers.  In particular, there can only be one precompiled header and it must
+be included at the beginning of the translation unit.  The extensions to the
+AST file format required for modules are discussed in the section on
+<a class="reference internal" href="#pchinternals-modules"><em>modules</em></a>.</p>
+<p>Clang’s AST files are designed with a compact on-disk representation, which
+minimizes both creation time and the time required to initially load the AST
+file.  The AST file itself contains a serialized representation of Clang’s
+abstract syntax trees and supporting data structures, stored using the same
+compressed bitstream as <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM’s bitcode file format</a>.</p>
+<p>Clang’s AST files are loaded “lazily” from disk.  When an AST file is initially
+loaded, Clang reads only a small amount of data from the AST file to establish
+where certain important data structures are stored.  The amount of data read in
+this initial load is independent of the size of the AST file, such that a
+larger AST file does not lead to longer AST load times.  The actual header data
+in the AST file — macros, functions, variables, types, etc. — is loaded
+only when it is referenced from the user’s code, at which point only that
+entity (and those entities it depends on) are deserialized from the AST file.
+With this approach, the cost of using an AST file for a translation unit is
+proportional to the amount of code actually used from the AST file, rather than
+being proportional to the size of the AST file itself.</p>
+<p>When given the <em class="xref std std-option">-print-stats</em> option, Clang produces statistics
+describing how much of the AST file was actually loaded from disk.  For a
+simple “Hello, World!” program that includes the Apple <tt class="docutils literal"><span class="pre">Cocoa.h</span></tt> header
+(which is built as a precompiled header), this option illustrates how little of
+the actual precompiled header is required:</p>
+<div class="highlight-none"><div class="highlight"><pre>*** AST File Statistics:
+  895/39981 source location entries read (2.238563%)
+  19/15315 types read (0.124061%)
+  20/82685 declarations read (0.024188%)
+  154/58070 identifiers read (0.265197%)
+  0/7260 selectors read (0.000000%)
+  0/30842 statements read (0.000000%)
+  4/8400 macros read (0.047619%)
+  1/4995 lexical declcontexts read (0.020020%)
+  0/4413 visible declcontexts read (0.000000%)
+  0/7230 method pool entries read (0.000000%)
+  0 method pool misses
+</pre></div>
+</div>
+<p>For this small program, only a tiny fraction of the source locations, types,
+declarations, identifiers, and macros were actually deserialized from the
+precompiled header.  These statistics can be useful to determine whether the
+AST file implementation can be improved by making more of the implementation
+lazy.</p>
+<p>Precompiled headers can be chained.  When you create a PCH while including an
+existing PCH, Clang can create the new PCH by referencing the original file and
+only writing the new data to the new file.  For example, you could create a PCH
+out of all the headers that are very commonly used throughout your project, and
+then create a PCH for every single source file in the project that includes the
+code that is specific to that file, so that recompiling the file itself is very
+fast, without duplicating the data from the common headers for every file.  The
+mechanisms behind chained precompiled headers are discussed in a <a class="reference internal" href="#pchinternals-chained"><em>later
+section</em></a>.</p>
+</div>
+<div class="section" id="ast-file-contents">
+<h2><a class="toc-backref" href="#id3">AST File Contents</a><a class="headerlink" href="#ast-file-contents" title="Permalink to this headline">Â¶</a></h2>
+<p>An AST file produced by clang is an object file container with a <tt class="docutils literal"><span class="pre">clangast</span></tt>
+(COFF) or <tt class="docutils literal"><span class="pre">__clangast</span></tt> (ELF and Mach-O) section containing the serialized AST.
+Other target-specific sections in the object file container are used to hold
+debug information for the data types defined in the AST.  Tools built on top of
+libclang that do not need debug information may also produce raw AST files that
+only contain the serialized AST.</p>
+<p>The <tt class="docutils literal"><span class="pre">clangast</span></tt> section is organized into several different blocks, each of
+which contains the serialized representation of a part of Clang’s internal
+representation.  Each of the blocks corresponds to either a block or a record
+within <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM’s bitstream format</a>.
+The contents of each of these logical blocks are described below.</p>
+<img alt="_images/PCHLayout.png" src="_images/PCHLayout.png" />
+<p>The <tt class="docutils literal"><span class="pre">llvm-objdump</span></tt> utility provides a <tt class="docutils literal"><span class="pre">-raw-clang-ast</span></tt> option to extract the
+binary contents of the AST section from an object file container.</p>
+<p>The <a class="reference external" href="http://llvm.org/docs/CommandGuide/llvm-bcanalyzer.html">llvm-bcanalyzer</a>
+utility can be used to examine the actual structure of the bitstream for the AST
+section.  This information can be used both to help understand the structure of
+the AST section and to isolate areas where the AST representation can still be
+optimized, e.g., through the introduction of abbreviations.</p>
+<div class="section" id="metadata-block">
+<h3><a class="toc-backref" href="#id4">Metadata Block</a><a class="headerlink" href="#metadata-block" title="Permalink to this headline">Â¶</a></h3>
+<p>The metadata block contains several records that provide information about how
+the AST file was built.  This metadata is primarily used to validate the use of
+an AST file.  For example, a precompiled header built for a 32-bit x86 target
+cannot be used when compiling for a 64-bit x86 target.  The metadata block
+contains information about:</p>
+<dl class="docutils">
+<dt>Language options</dt>
+<dd>Describes the particular language dialect used to compile the AST file,
+including major options (e.g., Objective-C support) and more minor options
+(e.g., support for “<tt class="docutils literal"><span class="pre">//</span></tt>” comments).  The contents of this record correspond to
+the <tt class="docutils literal"><span class="pre">LangOptions</span></tt> class.</dd>
+<dt>Target architecture</dt>
+<dd>The target triple that describes the architecture, platform, and ABI for
+which the AST file was generated, e.g., <tt class="docutils literal"><span class="pre">i386-apple-darwin9</span></tt>.</dd>
+<dt>AST version</dt>
+<dd>The major and minor version numbers of the AST file format.  Changes in the
+minor version number should not affect backward compatibility, while changes
+in the major version number imply that a newer compiler cannot read an older
+precompiled header (and vice-versa).</dd>
+<dt>Original file name</dt>
+<dd>The full path of the header that was used to generate the AST file.</dd>
+<dt>Predefines buffer</dt>
+<dd>Although not explicitly stored as part of the metadata, the predefines buffer
+is used in the validation of the AST file.  The predefines buffer itself
+contains code generated by the compiler to initialize the preprocessor state
+according to the current target, platform, and command-line options.  For
+example, the predefines buffer will contain “<tt class="docutils literal"><span class="pre">#define</span> <span class="pre">__STDC__</span> <span class="pre">1</span></tt>” when we
+are compiling C without Microsoft extensions.  The predefines buffer itself
+is stored within the <a class="reference internal" href="#pchinternals-sourcemgr"><em>Source Manager Block</em></a>, but its contents are
+verified along with the rest of the metadata.</dd>
+</dl>
+<p>A chained PCH file (that is, one that references another PCH) and a module
+(which may import other modules) have additional metadata containing the list
+of all AST files that this AST file depends on.  Each of those files will be
+loaded along with this AST file.</p>
+<p>For chained precompiled headers, the language options, target architecture and
+predefines buffer data is taken from the end of the chain, since they have to
+match anyway.</p>
+</div>
+<div class="section" id="source-manager-block">
+<span id="pchinternals-sourcemgr"></span><h3><a class="toc-backref" href="#id5">Source Manager Block</a><a class="headerlink" href="#source-manager-block" title="Permalink to this headline">Â¶</a></h3>
+<p>The source manager block contains the serialized representation of Clang’s
+<a class="reference internal" href="InternalsManual.html#sourcemanager"><em>SourceManager</em></a> class, which handles the mapping from
+source locations (as represented in Clang’s abstract syntax tree) into actual
+column/line positions within a source file or macro instantiation.  The AST
+file’s representation of the source manager also includes information about all
+of the headers that were (transitively) included when building the AST file.</p>
+<p>The bulk of the source manager block is dedicated to information about the
+various files, buffers, and macro instantiations into which a source location
+can refer.  Each of these is referenced by a numeric “file ID”, which is a
+unique number (allocated starting at 1) stored in the source location.  Clang
+serializes the information for each kind of file ID, along with an index that
+maps file IDs to the position within the AST file where the information about
+that file ID is stored.  The data associated with a file ID is loaded only when
+required by the front end, e.g., to emit a diagnostic that includes a macro
+instantiation history inside the header itself.</p>
+<p>The source manager block also contains information about all of the headers
+that were included when building the AST file.  This includes information about
+the controlling macro for the header (e.g., when the preprocessor identified
+that the contents of the header dependent on a macro like
+<tt class="docutils literal"><span class="pre">LLVM_CLANG_SOURCEMANAGER_H</span></tt>).</p>
+</div>
+<div class="section" id="preprocessor-block">
+<span id="pchinternals-preprocessor"></span><h3><a class="toc-backref" href="#id6">Preprocessor Block</a><a class="headerlink" href="#preprocessor-block" title="Permalink to this headline">Â¶</a></h3>
+<p>The preprocessor block contains the serialized representation of the
+preprocessor.  Specifically, it contains all of the macros that have been
+defined by the end of the header used to build the AST file, along with the
+token sequences that comprise each macro.  The macro definitions are only read
+from the AST file when the name of the macro first occurs in the program.  This
+lazy loading of macro definitions is triggered by lookups into the
+<a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>.</p>
+</div>
+<div class="section" id="types-block">
+<span id="pchinternals-types"></span><h3><a class="toc-backref" href="#id7">Types Block</a><a class="headerlink" href="#types-block" title="Permalink to this headline">Â¶</a></h3>
+<p>The types block contains the serialized representation of all of the types
+referenced in the translation unit.  Each Clang type node (<tt class="docutils literal"><span class="pre">PointerType</span></tt>,
+<tt class="docutils literal"><span class="pre">FunctionProtoType</span></tt>, etc.) has a corresponding record type in the AST file.
+When types are deserialized from the AST file, the data within the record is
+used to reconstruct the appropriate type node using the AST context.</p>
+<p>Each type has a unique type ID, which is an integer that uniquely identifies
+that type.  Type ID 0 represents the NULL type, type IDs less than
+<tt class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></tt> represent predefined types (<tt class="docutils literal"><span class="pre">void</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, etc.),
+while other “user-defined” type IDs are assigned consecutively from
+<tt class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></tt> upward as the types are encountered.  The AST file has
+an associated mapping from the user-defined types block to the location within
+the types block where the serialized representation of that type resides,
+enabling lazy deserialization of types.  When a type is referenced from within
+the AST file, that reference is encoded using the type ID shifted left by 3
+bits.  The lower three bits are used to represent the <tt class="docutils literal"><span class="pre">const</span></tt>, <tt class="docutils literal"><span class="pre">volatile</span></tt>,
+and <tt class="docutils literal"><span class="pre">restrict</span></tt> qualifiers, as in Clang’s <a class="reference internal" href="InternalsManual.html#qualtype"><em>QualType</em></a> class.</p>
+</div>
+<div class="section" id="declarations-block">
+<span id="pchinternals-decls"></span><h3><a class="toc-backref" href="#id8">Declarations Block</a><a class="headerlink" href="#declarations-block" title="Permalink to this headline">Â¶</a></h3>
+<p>The declarations block contains the serialized representation of all of the
+declarations referenced in the translation unit.  Each Clang declaration node
+(<tt class="docutils literal"><span class="pre">VarDecl</span></tt>, <tt class="docutils literal"><span class="pre">FunctionDecl</span></tt>, etc.) has a corresponding record type in the
+AST file.  When declarations are deserialized from the AST file, the data
+within the record is used to build and populate a new instance of the
+corresponding <tt class="docutils literal"><span class="pre">Decl</span></tt> node.  As with types, each declaration node has a
+numeric ID that is used to refer to that declaration within the AST file.  In
+addition, a lookup table provides a mapping from that numeric ID to the offset
+within the precompiled header where that declaration is described.</p>
+<p>Declarations in Clang’s abstract syntax trees are stored hierarchically.  At
+the top of the hierarchy is the translation unit (<tt class="docutils literal"><span class="pre">TranslationUnitDecl</span></tt>),
+which contains all of the declarations in the translation unit but is not
+actually written as a specific declaration node.  Its child declarations (such
+as functions or struct types) may also contain other declarations inside them,
+and so on.  Within Clang, each declaration is stored within a <a class="reference internal" href="InternalsManual.html#declcontext"><em>declaration
+context</em></a>, as represented by the <tt class="docutils literal"><span class="pre">DeclContext</span></tt> class.
+Declaration contexts provide the mechanism to perform name lookup within a
+given declaration (e.g., find the member named <tt class="docutils literal"><span class="pre">x</span></tt> in a structure) and
+iterate over the declarations stored within a context (e.g., iterate over all
+of the fields of a structure for structure layout).</p>
+<p>In Clang’s AST file format, deserializing a declaration that is a
+<tt class="docutils literal"><span class="pre">DeclContext</span></tt> is a separate operation from deserializing all of the
+declarations stored within that declaration context.  Therefore, Clang will
+deserialize the translation unit declaration without deserializing the
+declarations within that translation unit.  When required, the declarations
+stored within a declaration context will be deserialized.  There are two
+representations of the declarations within a declaration context, which
+correspond to the name-lookup and iteration behavior described above:</p>
+<ul class="simple">
+<li>When the front end performs name lookup to find a name <tt class="docutils literal"><span class="pre">x</span></tt> within a given
+declaration context (for example, during semantic analysis of the expression
+<tt class="docutils literal"><span class="pre">p->x</span></tt>, where <tt class="docutils literal"><span class="pre">p</span></tt>‘s type is defined in the precompiled header), Clang
+refers to an on-disk hash table that maps from the names within that
+declaration context to the declaration IDs that represent each visible
+declaration with that name.  The actual declarations will then be
+deserialized to provide the results of name lookup.</li>
+<li>When the front end performs iteration over all of the declarations within a
+declaration context, all of those declarations are immediately
+de-serialized.  For large declaration contexts (e.g., the translation unit),
+this operation is expensive; however, large declaration contexts are not
+traversed in normal compilation, since such a traversal is unnecessary.
+However, it is common for the code generator and semantic analysis to
+traverse declaration contexts for structs, classes, unions, and
+enumerations, although those contexts contain relatively few declarations in
+the common case.</li>
+</ul>
+</div>
+<div class="section" id="statements-and-expressions">
+<h3><a class="toc-backref" href="#id9">Statements and Expressions</a><a class="headerlink" href="#statements-and-expressions" title="Permalink to this headline">Â¶</a></h3>
+<p>Statements and expressions are stored in the AST file in both the <a class="reference internal" href="#pchinternals-types"><em>types</em></a> and the <a class="reference internal" href="#pchinternals-decls"><em>declarations</em></a> blocks,
+because every statement or expression will be associated with either a type or
+declaration.  The actual statement and expression records are stored
+immediately following the declaration or type that owns the statement or
+expression.  For example, the statement representing the body of a function
+will be stored directly following the declaration of the function.</p>
+<p>As with types and declarations, each statement and expression kind in Clang’s
+abstract syntax tree (<tt class="docutils literal"><span class="pre">ForStmt</span></tt>, <tt class="docutils literal"><span class="pre">CallExpr</span></tt>, etc.) has a corresponding
+record type in the AST file, which contains the serialized representation of
+that statement or expression.  Each substatement or subexpression within an
+expression is stored as a separate record (which keeps most records to a fixed
+size).  Within the AST file, the subexpressions of an expression are stored, in
+reverse order, prior to the expression that owns those expression, using a form
+of <a class="reference external" href="http://en.wikipedia.org/wiki/Reverse_Polish_notation">Reverse Polish Notation</a>.  For example, an
+expression <tt class="docutils literal"><span class="pre">3</span> <span class="pre">-</span> <span class="pre">4</span> <span class="pre">+</span> <span class="pre">5</span></tt> would be represented as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="100%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(5)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(4)</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(3)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(-)</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(+)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">STOP</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p>When reading this representation, Clang evaluates each expression record it
+encounters, builds the appropriate abstract syntax tree node, and then pushes
+that expression on to a stack.  When a record contains <em>N</em> subexpressions —
+<tt class="docutils literal"><span class="pre">BinaryOperator</span></tt> has two of them — those expressions are popped from the
+top of the stack.  The special STOP code indicates that we have reached the end
+of a serialized expression or statement; other expression or statement records
+may follow, but they are part of a different expression.</p>
+</div>
+<div class="section" id="pchinternals-ident-table">
+<span id="identifier-table-block"></span><h3><a class="toc-backref" href="#id10">Identifier Table Block</a><a class="headerlink" href="#pchinternals-ident-table" title="Permalink to this headline">Â¶</a></h3>
+<p>The identifier table block contains an on-disk hash table that maps each
+identifier mentioned within the AST file to the serialized representation of
+the identifier’s information (e.g, the <tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> structure).  The
+serialized representation contains:</p>
+<ul class="simple">
+<li>The actual identifier string.</li>
+<li>Flags that describe whether this identifier is the name of a built-in, a
+poisoned identifier, an extension token, or a macro.</li>
+<li>If the identifier names a macro, the offset of the macro definition within
+the <a class="reference internal" href="#pchinternals-preprocessor"><em>Preprocessor Block</em></a>.</li>
+<li>If the identifier names one or more declarations visible from translation
+unit scope, the <a class="reference internal" href="#pchinternals-decls"><em>declaration IDs</em></a> of these
+declarations.</li>
+</ul>
+<p>When an AST file is loaded, the AST file reader mechanism introduces itself
+into the identifier table as an external lookup source.  Thus, when the user
+program refers to an identifier that has not yet been seen, Clang will perform
+a lookup into the identifier table.  If an identifier is found, its contents
+(macro definitions, flags, top-level declarations, etc.) will be deserialized,
+at which point the corresponding <tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> structure will have the
+same contents it would have after parsing the headers in the AST file.</p>
+<p>Within the AST file, the identifiers used to name declarations are represented
+with an integral value.  A separate table provides a mapping from this integral
+value (the identifier ID) to the location within the on-disk hash table where
+that identifier is stored.  This mapping is used when deserializing the name of
+a declaration, the identifier of a token, or any other construct in the AST
+file that refers to a name.</p>
+</div>
+<div class="section" id="method-pool-block">
+<span id="pchinternals-method-pool"></span><h3><a class="toc-backref" href="#id11">Method Pool Block</a><a class="headerlink" href="#method-pool-block" title="Permalink to this headline">Â¶</a></h3>
+<p>The method pool block is represented as an on-disk hash table that serves two
+purposes: it provides a mapping from the names of Objective-C selectors to the
+set of Objective-C instance and class methods that have that particular
+selector (which is required for semantic analysis in Objective-C) and also
+stores all of the selectors used by entities within the AST file.  The design
+of the method pool is similar to that of the <a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>: the first time a particular selector is formed
+during the compilation of the program, Clang will search in the on-disk hash
+table of selectors; if found, Clang will read the Objective-C methods
+associated with that selector into the appropriate front-end data structure
+(<tt class="docutils literal"><span class="pre">Sema::InstanceMethodPool</span></tt> and <tt class="docutils literal"><span class="pre">Sema::FactoryMethodPool</span></tt> for instance and
+class methods, respectively).</p>
+<p>As with identifiers, selectors are represented by numeric values within the AST
+file.  A separate index maps these numeric selector values to the offset of the
+selector within the on-disk hash table, and will be used when de-serializing an
+Objective-C method declaration (or other Objective-C construct) that refers to
+the selector.</p>
+</div>
+</div>
+<div class="section" id="ast-reader-integration-points">
+<h2><a class="toc-backref" href="#id12">AST Reader Integration Points</a><a class="headerlink" href="#ast-reader-integration-points" title="Permalink to this headline">Â¶</a></h2>
+<p>The “lazy” deserialization behavior of AST files requires their integration
+into several completely different submodules of Clang.  For example, lazily
+deserializing the declarations during name lookup requires that the name-lookup
+routines be able to query the AST file to find entities stored there.</p>
+<p>For each Clang data structure that requires direct interaction with the AST
+reader logic, there is an abstract class that provides the interface between
+the two modules.  The <tt class="docutils literal"><span class="pre">ASTReader</span></tt> class, which handles the loading of an AST
+file, inherits from all of these abstract classes to provide lazy
+deserialization of Clang’s data structures.  <tt class="docutils literal"><span class="pre">ASTReader</span></tt> implements the
+following abstract classes:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">ExternalSLocEntrySource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">SourceManager</span></tt> class, and
+is used whenever the <a class="reference internal" href="#pchinternals-sourcemgr"><em>source manager</em></a> needs to
+load the details of a file, buffer, or macro instantiation.</dd>
+<dt><tt class="docutils literal"><span class="pre">IdentifierInfoLookup</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">IdentifierTable</span></tt> class, and
+is used whenever the program source refers to an identifier that has not yet
+been seen.  In this case, the AST reader searches for this identifier within
+its <a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a> to load any top-level
+declarations or macros associated with that identifier.</dd>
+<dt><tt class="docutils literal"><span class="pre">ExternalASTSource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">ASTContext</span></tt> class, and is
+used whenever the abstract syntax tree nodes need to loaded from the AST
+file.  It provides the ability to de-serialize declarations and types
+identified by their numeric values, read the bodies of functions when
+required, and read the declarations stored within a declaration context
+(either for iteration or for name lookup).</dd>
+<dt><tt class="docutils literal"><span class="pre">ExternalSemaSource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">Sema</span></tt> class, and is used
+whenever semantic analysis needs to read information from the <a class="reference internal" href="#pchinternals-method-pool"><em>global
+method pool</em></a>.</dd>
+</dl>
+</div>
+<div class="section" id="chained-precompiled-headers">
+<span id="pchinternals-chained"></span><h2><a class="toc-backref" href="#id13">Chained precompiled headers</a><a class="headerlink" href="#chained-precompiled-headers" title="Permalink to this headline">Â¶</a></h2>
+<p>Chained precompiled headers were initially intended to improve the performance
+of IDE-centric operations such as syntax highlighting and code completion while
+a particular source file is being edited by the user.  To minimize the amount
+of reparsing required after a change to the file, a form of precompiled header
+— called a precompiled <em>preamble</em> — is automatically generated by parsing
+all of the headers in the source file, up to and including the last
+<tt class="docutils literal"><span class="pre">#include</span></tt>.  When only the source file changes (and none of the headers it
+depends on), reparsing of that source file can use the precompiled preamble and
+start parsing after the <tt class="docutils literal"><span class="pre">#include</span></tt>s, so parsing time is proportional to the
+size of the source file (rather than all of its includes).  However, the
+compilation of that translation unit may already use a precompiled header: in
+this case, Clang will create the precompiled preamble as a chained precompiled
+header that refers to the original precompiled header.  This drastically
+reduces the time needed to serialize the precompiled preamble for use in
+reparsing.</p>
+<p>Chained precompiled headers get their name because each precompiled header can
+depend on one other precompiled header, forming a chain of dependencies.  A
+translation unit will then include the precompiled header that starts the chain
+(i.e., nothing depends on it).  This linearity of dependencies is important for
+the semantic model of chained precompiled headers, because the most-recent
+precompiled header can provide information that overrides the information
+provided by the precompiled headers it depends on, just like a header file
+<tt class="docutils literal"><span class="pre">B.h</span></tt> that includes another header <tt class="docutils literal"><span class="pre">A.h</span></tt> can modify the state produced by
+parsing <tt class="docutils literal"><span class="pre">A.h</span></tt>, e.g., by <tt class="docutils literal"><span class="pre">#undef</span></tt>‘ing a macro defined in <tt class="docutils literal"><span class="pre">A.h</span></tt>.</p>
+<p>There are several ways in which chained precompiled headers generalize the AST
+file model:</p>
+<dl class="docutils">
+<dt>Numbering of IDs</dt>
+<dd>Many different kinds of entities — identifiers, declarations, types, etc.
+— have ID numbers that start at 1 or some other predefined constant and
+grow upward.  Each precompiled header records the maximum ID number it has
+assigned in each category.  Then, when a new precompiled header is generated
+that depends on (chains to) another precompiled header, it will start
+counting at the next available ID number.  This way, one can determine, given
+an ID number, which AST file actually contains the entity.</dd>
+<dt>Name lookup</dt>
+<dd>When writing a chained precompiled header, Clang attempts to write only
+information that has changed from the precompiled header on which it is
+based.  This changes the lookup algorithm for the various tables, such as the
+<a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>: the search starts at the
+most-recent precompiled header.  If no entry is found, lookup then proceeds
+to the identifier table in the precompiled header it depends on, and so one.
+Once a lookup succeeds, that result is considered definitive, overriding any
+results from earlier precompiled headers.</dd>
+<dt>Update records</dt>
+<dd>There are various ways in which a later precompiled header can modify the
+entities described in an earlier precompiled header.  For example, later
+precompiled headers can add entries into the various name-lookup tables for
+the translation unit or namespaces, or add new categories to an Objective-C
+class.  Each of these updates is captured in an “update record” that is
+stored in the chained precompiled header file and will be loaded along with
+the original entity.</dd>
+</dl>
+</div>
+<div class="section" id="modules">
+<span id="pchinternals-modules"></span><h2><a class="toc-backref" href="#id14">Modules</a><a class="headerlink" href="#modules" title="Permalink to this headline">Â¶</a></h2>
+<p>Modules generalize the chained precompiled header model yet further, from a
+linear chain of precompiled headers to an arbitrary directed acyclic graph
+(DAG) of AST files.  All of the same techniques used to make chained
+precompiled headers work — ID number, name lookup, update records — are
+shared with modules.  However, the DAG nature of modules introduce a number of
+additional complications to the model:</p>
+<dl class="docutils">
+<dt>Numbering of IDs</dt>
+<dd>The simple, linear numbering scheme used in chained precompiled headers falls
+apart with the module DAG, because different modules may end up with
+different numbering schemes for entities they imported from common shared
+modules.  To account for this, each module file provides information about
+which modules it depends on and which ID numbers it assigned to the entities
+in those modules, as well as which ID numbers it took for its own new
+entities.  The AST reader then maps these “local” ID numbers into a “global”
+ID number space for the current translation unit, providing a 1-1 mapping
+between entities (in whatever AST file they inhabit) and global ID numbers.
+If that translation unit is then serialized into an AST file, this mapping
+will be stored for use when the AST file is imported.</dd>
+<dt>Declaration merging</dt>
+<dd>It is possible for a given entity (from the language’s perspective) to be
+declared multiple times in different places.  For example, two different
+headers can have the declaration of <tt class="docutils literal"><span class="pre">printf</span></tt> or could forward-declare
+<tt class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></tt>.  If each of those headers is included in a module, and some
+third party imports both of those modules, there is a potentially serious
+problem: name lookup for <tt class="docutils literal"><span class="pre">printf</span></tt> or <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></tt> will find both
+declarations, but the AST nodes are unrelated.  This would result in a
+compilation error, due to an ambiguity in name lookup.  Therefore, the AST
+reader performs declaration merging according to the appropriate language
+semantics, ensuring that the two disjoint declarations are merged into a
+single redeclaration chain (with a common canonical declaration), so that it
+is as if one of the headers had been included before the other.</dd>
+<dt>Name Visibility</dt>
+<dd>Modules allow certain names that occur during module creation to be “hidden”,
+so that they are not part of the public interface of the module and are not
+visible to its clients.  The AST reader maintains a “visible” bit on various
+AST nodes (declarations, macros, etc.) to indicate whether that particular
+AST node is currently visible; the various name lookup mechanisms in Clang
+inspect the visible bit to determine whether that entity, which is still in
+the AST (because other, visible AST nodes may depend on it), can actually be
+found by name lookup.  When a new (sub)module is imported, it may make
+existing, non-visible, already-deserialized AST nodes visible; it is the
+responsibility of the AST reader to find and update these AST nodes when it
+is notified of the import.</dd>
+</dl>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/PTHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/PTHInternals.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/PTHInternals.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/PTHInternals.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,214 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Pretokenized Headers (PTH) — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Precompiled Header and Modules Internals" href="PCHInternals.html" />
+    <link rel="prev" title="Driver Design & Internals" href="DriverInternals.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Pretokenized Headers (PTH)</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="DriverInternals.html">Driver Design & Internals</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="pretokenized-headers-pth">
+<h1>Pretokenized Headers (PTH)<a class="headerlink" href="#pretokenized-headers-pth" title="Permalink to this headline">Â¶</a></h1>
+<p>This document first describes the low-level interface for using PTH and
+then briefly elaborates on its design and implementation. If you are
+interested in the end-user view, please see the <a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>User’s Manual</em></a>.</p>
+<div class="section" id="using-pretokenized-headers-with-clang-low-level-interface">
+<h2>Using Pretokenized Headers with <tt class="docutils literal"><span class="pre">clang</span></tt> (Low-level Interface)<a class="headerlink" href="#using-pretokenized-headers-with-clang-low-level-interface" title="Permalink to this headline">Â¶</a></h2>
+<p>The Clang compiler frontend, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, supports three command line
+options for generating and using PTH files.</p>
+<p>To generate PTH files using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, use the option <tt class="docutils literal"><span class="pre">-emit-pth</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 test.h -emit-pth -o test.h.pth
+</pre></div>
+</div>
+<p>This option is transparently used by <tt class="docutils literal"><span class="pre">clang</span></tt> when generating PTH
+files. Similarly, PTH files can be used as prefix headers using the
+<tt class="docutils literal"><span class="pre">-include-pth</span></tt> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 -include-pth test.h.pth test.c -o test.s
+</pre></div>
+</div>
+<p>Alternatively, Clang’s PTH files can be used as a raw “token-cache” (or
+“content” cache) of the source included by the original header file.
+This means that the contents of the PTH file are searched as substitutes
+for <em>any</em> source files that are used by <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> to process a
+source file. This is done by specifying the <tt class="docutils literal"><span class="pre">-token-cache</span></tt> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat test.h
+<span class="gp">#</span>include <stdio.h>
+<span class="gp">$</span> clang -cc1 -emit-pth test.h -o test.h.pth
+<span class="gp">$</span> cat test.c
+<span class="gp">#</span>include <span class="s2">"test.h"</span>
+<span class="gp">$</span> clang -cc1 test.c -o <span class="nb">test</span> -token-cache test.h.pth
+</pre></div>
+</div>
+<p>In this example the contents of <tt class="docutils literal"><span class="pre">stdio.h</span></tt> (and the files it includes)
+will be retrieved from <tt class="docutils literal"><span class="pre">test.h.pth</span></tt>, as the PTH file is being used in
+this case as a raw cache of the contents of <tt class="docutils literal"><span class="pre">test.h</span></tt>. This is a
+low-level interface used to both implement the high-level PTH interface
+as well as to provide alternative means to use PTH-style caching.</p>
+</div>
+<div class="section" id="pth-design-and-implementation">
+<h2>PTH Design and Implementation<a class="headerlink" href="#pth-design-and-implementation" title="Permalink to this headline">Â¶</a></h2>
+<p>Unlike GCC’s precompiled headers, which cache the full ASTs and
+preprocessor state of a header file, Clang’s pretokenized header files
+mainly cache the raw lexer <em>tokens</em> that are needed to segment the
+stream of characters in a source file into keywords, identifiers, and
+operators. Consequently, PTH serves to mainly directly speed up the
+lexing and preprocessing of a source file, while parsing and
+type-checking must be completely redone every time a PTH file is used.</p>
+<div class="section" id="basic-design-tradeoffs">
+<h3>Basic Design Tradeoffs<a class="headerlink" href="#basic-design-tradeoffs" title="Permalink to this headline">Â¶</a></h3>
+<p>In the long term there are plans to provide an alternate PCH
+implementation for Clang that also caches the work for parsing and type
+checking the contents of header files. The current implementation of PCH
+in Clang as pretokenized header files was motivated by the following
+factors:</p>
+<dl class="docutils">
+<dt><strong>Language independence</strong></dt>
+<dd>PTH files work with any language that
+Clang’s lexer can handle, including C, Objective-C, and (in the early
+stages) C++. This means development on language features at the
+parsing level or above (which is basically almost all interesting
+pieces) does not require PTH to be modified.</dd>
+<dt><strong>Simple design</strong></dt>
+<dd>Relatively speaking, PTH has a simple design and
+implementation, making it easy to test. Further, because the
+machinery for PTH resides at the lower-levels of the Clang library
+stack it is fairly straightforward to profile and optimize.</dd>
+</dl>
+<p>Further, compared to GCC’s PCH implementation (which is the dominate
+precompiled header file implementation that Clang can be directly
+compared against) the PTH design in Clang yields several attractive
+features:</p>
+<dl class="docutils">
+<dt><strong>Architecture independence</strong></dt>
+<dd><p class="first">In contrast to GCC’s PCH files (and
+those of several other compilers), Clang’s PTH files are architecture
+independent, requiring only a single PTH file when building a
+program for multiple architectures.</p>
+<p class="last">For example, on Mac OS X one may wish to compile a “universal binary”
+that runs on PowerPC, 32-bit Intel (i386), and 64-bit Intel
+architectures. In contrast, GCC requires a PCH file for each
+architecture, as the definitions of types in the AST are
+architecture-specific. Since a Clang PTH file essentially represents
+a lexical cache of header files, a single PTH file can be safely used
+when compiling for multiple architectures. This can also reduce
+compile times because only a single PTH file needs to be generated
+during a build instead of several.</p>
+</dd>
+<dt><strong>Reduced memory pressure</strong></dt>
+<dd>Similar to GCC, Clang reads PTH files
+via the use of memory mapping (i.e., <tt class="docutils literal"><span class="pre">mmap</span></tt>). Clang, however,
+memory maps PTH files as read-only, meaning that multiple invocations
+of <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> can share the same pages in memory from a
+memory-mapped PTH file. In comparison, GCC also memory maps its PCH
+files but also modifies those pages in memory, incurring the
+copy-on-write costs. The read-only nature of PTH can greatly reduce
+memory pressure for builds involving multiple cores, thus improving
+overall scalability.</dd>
+<dt><strong>Fast generation</strong></dt>
+<dd>PTH files can be generated in a small fraction
+of the time needed to generate GCC’s PCH files. Since PTH/PCH
+generation is a serial operation that typically blocks progress
+during a build, faster generation time leads to improved processor
+utilization with parallel builds on multicore machines.</dd>
+</dl>
+<p>Despite these strengths, PTH’s simple design suffers some algorithmic
+handicaps compared to other PCH strategies such as those used by GCC.
+While PTH can greatly speed up the processing time of a header file, the
+amount of work required to process a header file is still roughly linear
+in the size of the header file. In contrast, the amount of work done by
+GCC to process a precompiled header is (theoretically) constant (the
+ASTs for the header are literally memory mapped into the compiler). This
+means that only the pieces of the header file that are referenced by the
+source file including the header are the only ones the compiler needs to
+process during actual compilation. While GCC’s particular implementation
+of PCH mitigates some of these algorithmic strengths via the use of
+copy-on-write pages, the approach itself can fundamentally dominate at
+an algorithmic level, especially when one considers header files of
+arbitrary size.</p>
+<p>There is also a PCH implementation for Clang based on the lazy
+deserialization of ASTs. This approach theoretically has the same
+constant-time algorithmic advantages just mentioned but also retains some
+of the strengths of PTH such as reduced memory pressure (ideal for
+multi-core builds).</p>
+</div>
+<div class="section" id="internal-pth-optimizations">
+<h3>Internal PTH Optimizations<a class="headerlink" href="#internal-pth-optimizations" title="Permalink to this headline">Â¶</a></h3>
+<p>While the main optimization employed by PTH is to reduce lexing time of
+header files by caching pre-lexed tokens, PTH also employs several other
+optimizations to speed up the processing of header files:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">stat</span></tt> caching: PTH files cache information obtained via calls to
+<tt class="docutils literal"><span class="pre">stat</span></tt> that <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> uses to resolve which files are included
+by <tt class="docutils literal"><span class="pre">#include</span></tt> directives. This greatly reduces the overhead
+involved in context-switching to the kernel to resolve included
+files.</li>
+<li>Fast skipping of <tt class="docutils literal"><span class="pre">#ifdef</span></tt> ... <tt class="docutils literal"><span class="pre">#endif</span></tt> chains: PTH files
+record the basic structure of nested preprocessor blocks. When the
+condition of the preprocessor block is false, all of its tokens are
+immediately skipped instead of requiring them to be handled by
+Clang’s preprocessor.</li>
+</ul>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="DriverInternals.html">Driver Design & Internals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="PCHInternals.html">Precompiled Header and Modules Internals</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/RAVFrontendAction.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/RAVFrontendAction.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/RAVFrontendAction.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/RAVFrontendAction.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,266 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>How to write RecursiveASTVisitor based ASTFrontendActions. — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Tutorial for building tools using LibTooling and LibASTMatchers" href="LibASTMatchersTutorial.html" />
+    <link rel="prev" title="Clang Plugins" href="ClangPlugins.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>How to write RecursiveASTVisitor based ASTFrontendActions.</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ClangPlugins.html">Clang Plugins</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="how-to-write-recursiveastvisitor-based-astfrontendactions">
+<h1>How to write RecursiveASTVisitor based ASTFrontendActions.<a class="headerlink" href="#how-to-write-recursiveastvisitor-based-astfrontendactions" 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>In this tutorial you will learn how to create a FrontendAction that uses
+a RecursiveASTVisitor to find CXXRecordDecl AST nodes with a specified
+name.</p>
+</div>
+<div class="section" id="creating-a-frontendaction">
+<h2>Creating a FrontendAction<a class="headerlink" href="#creating-a-frontendaction" title="Permalink to this headline">Â¶</a></h2>
+<p>When writing a clang based tool like a Clang Plugin or a standalone tool
+based on LibTooling, the common entry point is the FrontendAction.
+FrontendAction is an interface that allows execution of user specific
+actions as part of the compilation. To run tools over the AST clang
+provides the convenience interface ASTFrontendAction, which takes care
+of executing the action. The only part left is to implement the
+CreateASTConsumer method that returns an ASTConsumer per translation
+unit.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassAction : public clang::ASTFrontendAction {
+public:
+  virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+    clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+    return std::unique_ptr<clang::ASTConsumer>(
+        new FindNamedClassConsumer);
+  }
+};
+</pre></div>
+</div>
+</div>
+<div class="section" id="creating-an-astconsumer">
+<h2>Creating an ASTConsumer<a class="headerlink" href="#creating-an-astconsumer" title="Permalink to this headline">Â¶</a></h2>
+<p>ASTConsumer is an interface used to write generic actions on an AST,
+regardless of how the AST was produced. ASTConsumer provides many
+different entry points, but for our use case the only one needed is
+HandleTranslationUnit, which is called with the ASTContext for the
+translation unit.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassConsumer : public clang::ASTConsumer {
+public:
+  virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+    // Traversing the translation unit decl via a RecursiveASTVisitor
+    // will visit all nodes in the AST.
+    Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+  }
+private:
+  // A RecursiveASTVisitor implementation.
+  FindNamedClassVisitor Visitor;
+};
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-the-recursiveastvisitor">
+<h2>Using the RecursiveASTVisitor<a class="headerlink" href="#using-the-recursiveastvisitor" title="Permalink to this headline">Â¶</a></h2>
+<p>Now that everything is hooked up, the next step is to implement a
+RecursiveASTVisitor to extract the relevant information from the AST.</p>
+<p>The RecursiveASTVisitor provides hooks of the form bool
+VisitNodeType(NodeType *) for most AST nodes; the exception are TypeLoc
+nodes, which are passed by-value. We only need to implement the methods
+for the relevant node types.</p>
+<p>Let’s start by writing a RecursiveASTVisitor that visits all
+CXXRecordDecl’s.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassVisitor
+  : public RecursiveASTVisitor<FindNamedClassVisitor> {
+public:
+  bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+    // For debugging, dumping the AST nodes will show which nodes are already
+    // being visited.
+    Declaration->dump();
+
+    // The return value indicates whether we want the visitation to proceed.
+    // Return false to stop the traversal of the AST.
+    return true;
+  }
+};
+</pre></div>
+</div>
+<p>In the methods of our RecursiveASTVisitor we can now use the full power
+of the Clang AST to drill through to the parts that are interesting for
+us. For example, to find all class declaration with a certain name, we
+can check for a specific qualified name:</p>
+<div class="highlight-python"><div class="highlight"><pre>bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+  if (Declaration->getQualifiedNameAsString() == "n::m::C")
+    Declaration->dump();
+  return true;
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="accessing-the-sourcemanager-and-astcontext">
+<h2>Accessing the SourceManager and ASTContext<a class="headerlink" href="#accessing-the-sourcemanager-and-astcontext" title="Permalink to this headline">Â¶</a></h2>
+<p>Some of the information about the AST, like source locations and global
+identifier information, are not stored in the AST nodes themselves, but
+in the ASTContext and its associated source manager. To retrieve them we
+need to hand the ASTContext into our RecursiveASTVisitor implementation.</p>
+<p>The ASTContext is available from the CompilerInstance during the call to
+CreateASTConsumer. We can thus extract it there and hand it into our
+freshly created FindNamedClassConsumer:</p>
+<div class="highlight-python"><div class="highlight"><pre>virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+  clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+  return std::unique_ptr<clang::ASTConsumer>(
+      new FindNamedClassConsumer(&Compiler.getASTContext()));
+}
+</pre></div>
+</div>
+<p>Now that the ASTContext is available in the RecursiveASTVisitor, we can
+do more interesting things with AST nodes, like looking up their source
+locations:</p>
+<div class="highlight-python"><div class="highlight"><pre>bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+  if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+    // getFullLoc uses the ASTContext's SourceManager to resolve the source
+    // location and break it up into its line and column parts.
+    FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+    if (FullLocation.isValid())
+      llvm::outs() << "Found declaration at "
+                   << FullLocation.getSpellingLineNumber() << ":"
+                   << FullLocation.getSpellingColumnNumber() << "\n";
+  }
+  return true;
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="putting-it-all-together">
+<h2>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Permalink to this headline">Â¶</a></h2>
+<p>Now we can combine all of the above into a small example program:</p>
+<div class="highlight-python"><div class="highlight"><pre>#include "clang/AST/ASTConsumer.h"
+#include "clang/AST/RecursiveASTVisitor.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Frontend/FrontendAction.h"
+#include "clang/Tooling/Tooling.h"
+
+using namespace clang;
+
+class FindNamedClassVisitor
+  : public RecursiveASTVisitor<FindNamedClassVisitor> {
+public:
+  explicit FindNamedClassVisitor(ASTContext *Context)
+    : Context(Context) {}
+
+  bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+    if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+      FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+      if (FullLocation.isValid())
+        llvm::outs() << "Found declaration at "
+                     << FullLocation.getSpellingLineNumber() << ":"
+                     << FullLocation.getSpellingColumnNumber() << "\n";
+    }
+    return true;
+  }
+
+private:
+  ASTContext *Context;
+};
+
+class FindNamedClassConsumer : public clang::ASTConsumer {
+public:
+  explicit FindNamedClassConsumer(ASTContext *Context)
+    : Visitor(Context) {}
+
+  virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+    Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+  }
+private:
+  FindNamedClassVisitor Visitor;
+};
+
+class FindNamedClassAction : public clang::ASTFrontendAction {
+public:
+  virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+    clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+    return std::unique_ptr<clang::ASTConsumer>(
+        new FindNamedClassConsumer(&Compiler.getASTContext()));
+  }
+};
+
+int main(int argc, char **argv) {
+  if (argc > 1) {
+    clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]);
+  }
+}
+</pre></div>
+</div>
+<p>We store this into a file called FindClassDecls.cpp and create the
+following CMakeLists.txt to link it:</p>
+<div class="highlight-python"><div class="highlight"><pre>set(LLVM_USED_LIBS clangTooling)
+
+add_clang_executable(find-class-decls FindClassDecls.cpp)
+</pre></div>
+</div>
+<p>When running this tool over a small code snippet it will output all
+declarations of a class n::m::C it found:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }"
+Found declaration at 1:29
+</pre></div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ClangPlugins.html">Clang Plugins</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/ReleaseNotes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/ReleaseNotes.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/ReleaseNotes.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/ReleaseNotes.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,312 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Clang 3.7 Release Notes — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Clang Compiler Userâs Manual" href="UsersManual.html" />
+    <link rel="prev" title="Using Clang as a Compiler" href="index.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang 3.7 Release Notes</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="index.html">Using Clang as a Compiler</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="UsersManual.html">Clang Compiler User’s Manual</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-3-7-release-notes">
+<h1>Clang 3.7 Release Notes<a class="headerlink" href="#clang-3-7-release-notes" 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="#what-s-new-in-clang-3-7" id="id2">What’s New in Clang 3.7?</a><ul>
+<li><a class="reference internal" href="#major-new-features" id="id3">Major New Features</a></li>
+<li><a class="reference internal" href="#improvements-to-clang-s-diagnostics" id="id4">Improvements to Clang’s diagnostics</a></li>
+<li><a class="reference internal" href="#new-compiler-flags" id="id5">New Compiler Flags</a></li>
+<li><a class="reference internal" href="#objective-c-language-changes-in-clang" id="id6">Objective-C Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#profile-guided-optimization" id="id7">Profile Guided Optimization</a></li>
+<li><a class="reference internal" href="#openmp-support" id="id8">OpenMP Support</a></li>
+<li><a class="reference internal" href="#internal-api-changes" id="id9">Internal API Changes</a></li>
+<li><a class="reference internal" href="#static-analyzer" id="id10">Static Analyzer</a></li>
+<li><a class="reference internal" href="#systemz" id="id11">SystemZ</a></li>
+<li><a class="reference internal" href="#clang-tidy" id="id12">clang-tidy</a></li>
+<li><a class="reference internal" href="#last-release-which-will-run-on-windows-xp-and-windows-vista" id="id13">Last release which will run on Windows XP and Windows Vista</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-information" id="id14">Additional Information</a></li>
+</ul>
+</div>
+<p>Written by the <a class="reference external" href="http://llvm.org/">LLVM Team</a></p>
+<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>This document contains the release notes for the Clang C/C++/Objective-C
+frontend, part of the LLVM Compiler Infrastructure, release 3.7. Here we
+describe the status of Clang in some detail, including major
+improvements from the previous release and new feature work. For the
+general LLVM release notes, see <a class="reference external" href="http://llvm.org/docs/ReleaseNotes.html">the LLVM
+documentation</a>. All LLVM
+releases may be downloaded from the <a class="reference external" href="http://llvm.org/releases/">LLVM releases web
+site</a>.</p>
+<p>For more information about Clang or LLVM, including information about
+the latest release, please check out the main please see the <a class="reference external" href="http://clang.llvm.org">Clang Web
+Site</a> or the <a class="reference external" href="http://llvm.org">LLVM Web
+Site</a>.</p>
+</div>
+<div class="section" id="what-s-new-in-clang-3-7">
+<h2><a class="toc-backref" href="#id2">What’s New in Clang 3.7?</a><a class="headerlink" href="#what-s-new-in-clang-3-7" title="Permalink to this headline">Â¶</a></h2>
+<p>Some of the major new features and improvements to Clang are listed
+here. Generic improvements to Clang as a whole or to its underlying
+infrastructure are described first, followed by language-specific
+sections with improvements to Clang’s support for those languages.</p>
+<div class="section" id="major-new-features">
+<h3><a class="toc-backref" href="#id3">Major New Features</a><a class="headerlink" href="#major-new-features" title="Permalink to this headline">Â¶</a></h3>
+<ul class="simple">
+<li>Use of the <tt class="docutils literal"><span class="pre">__declspec</span></tt> language extension for declaration attributes now
+requires passing the -fms-extensions or -fborland compiler flag. This language
+extension is also enabled when compiling CUDA code, but its use should be
+viewed as an implementation detail that is subject to change.</li>
+<li>On Windows targets, some uses of the <tt class="docutils literal"><span class="pre">__try</span></tt>, <tt class="docutils literal"><span class="pre">__except</span></tt>, and
+<tt class="docutils literal"><span class="pre">__finally</span></tt> language constructs are supported in Clang 3.7. MSVC-compatible
+C++ exceptions are not yet supported, however.</li>
+<li>Clang 3.7 fully supports OpenMP 3.1 and reported to work on many platforms,
+including x86, x86-64 and Power. Also, pragma <tt class="docutils literal"><span class="pre">omp</span> <span class="pre">simd</span></tt> from OpenMP 4.0 is
+supported as well. See below for details.</li>
+<li>Clang 3.7 includes an implementation of <a class="reference internal" href="ControlFlowIntegrity.html"><em>control flow integrity</em></a>, a security hardening mechanism.</li>
+</ul>
+</div>
+<div class="section" id="improvements-to-clang-s-diagnostics">
+<h3><a class="toc-backref" href="#id4">Improvements to Clang’s diagnostics</a><a class="headerlink" href="#improvements-to-clang-s-diagnostics" title="Permalink to this headline">Â¶</a></h3>
+<p>Clang’s diagnostics are constantly being improved to catch more issues,
+explain them more clearly, and provide more accurate source information
+about them. The improvements since the 3.6 release include:</p>
+<ul class="simple">
+<li>-Wrange-loop-analysis analyzes the loop variable type and the container type
+to determine whether copies are made of the container elements.  If possible,
+suggest a const reference type to prevent copies, or a non-reference type
+to indicate a copy is made.</li>
+<li>-Wredundant-move warns when a parameter variable is moved on return and the
+return type is the same as the variable.  Returning the variable directly
+will already make a move, so the call is not needed.</li>
+<li>-Wpessimizing-move warns when a local variable is moved on return and the
+return type is the same as the variable.  Copy elision cannot take place with
+a move, but can take place if the variable is returned directly.</li>
+<li>-Wmove is a new warning group which has the previous two warnings,
+-Wredundant-move and -Wpessimizing-move, as well as previous warning
+-Wself-move.  In addition, this group is part of -Wmost and -Wall now.</li>
+<li>-Winfinite-recursion, a warning for functions that only call themselves,
+is now part of -Wmost and -Wall.</li>
+<li>-Wobjc-circular-container prevents creation of circular containers,
+it covers <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt>, <tt class="docutils literal"><span class="pre">NSMutableSet</span></tt>, <tt class="docutils literal"><span class="pre">NSMutableDictionary</span></tt>,
+<tt class="docutils literal"><span class="pre">NSMutableOrderedSet</span></tt> and all their subclasses.</li>
+</ul>
+</div>
+<div class="section" id="new-compiler-flags">
+<h3><a class="toc-backref" href="#id5">New Compiler Flags</a><a class="headerlink" href="#new-compiler-flags" title="Permalink to this headline">Â¶</a></h3>
+<p>The sized deallocation feature of C++14 is now controlled by the
+<tt class="docutils literal"><span class="pre">-fsized-deallocation</span></tt> flag. This feature relies on library support that
+isn’t yet widely deployed, so the user must supply an extra flag to get the
+extra functionality.</p>
+</div>
+<div class="section" id="objective-c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id6">Objective-C Language Changes in Clang</a><a class="headerlink" href="#objective-c-language-changes-in-clang" title="Permalink to this headline">Â¶</a></h3>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">objc_boxable</span></tt> attribute was added. Structs and unions marked with this attribute can be
+used with boxed expressions (<tt class="docutils literal"><span class="pre">@(...)</span></tt>) to create <tt class="docutils literal"><span class="pre">NSValue</span></tt>.</li>
+</ul>
+</div>
+<div class="section" id="profile-guided-optimization">
+<h3><a class="toc-backref" href="#id7">Profile Guided Optimization</a><a class="headerlink" href="#profile-guided-optimization" title="Permalink to this headline">Â¶</a></h3>
+<p>Clang now accepts GCC-compatible flags for profile guided optimization (PGO).
+You can now use <tt class="docutils literal"><span class="pre">-fprofile-generate=<dir></span></tt>, <tt class="docutils literal"><span class="pre">-fprofile-use=<dir></span></tt>,
+<tt class="docutils literal"><span class="pre">-fno-profile-generate</span></tt> and <tt class="docutils literal"><span class="pre">-fno-profile-use</span></tt>. These flags have the
+same semantics as their GCC counterparts. However, the generated profile
+is still LLVM-specific. PGO profiles generated with Clang cannot be used
+by GCC and vice-versa.</p>
+<p>Clang now emits function entry counts in profile-instrumented binaries.
+This has improved the computation of weights and frequencies in
+profile analysis.</p>
+</div>
+<div class="section" id="openmp-support">
+<h3><a class="toc-backref" href="#id8">OpenMP Support</a><a class="headerlink" href="#openmp-support" title="Permalink to this headline">Â¶</a></h3>
+<p>OpenMP 3.1 is fully supported, but disabled by default. To enable it, please use
+the <tt class="docutils literal"><span class="pre">-fopenmp=libomp</span></tt> command line option. Your feedback (positive or negative) on
+using OpenMP-enabled clang would be much appreciated; please share it either on
+<a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> or <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/openmp-dev">openmp-dev</a> mailing lists.</p>
+<p>In addition to OpenMP 3.1, several important elements of the 4.0 version of the
+standard are supported as well:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">omp</span> <span class="pre">simd</span></tt>, <tt class="docutils literal"><span class="pre">omp</span> <span class="pre">for</span> <span class="pre">simd</span></tt> and <tt class="docutils literal"><span class="pre">omp</span> <span class="pre">parallel</span> <span class="pre">for</span> <span class="pre">simd</span></tt> pragmas</li>
+<li>atomic constructs</li>
+<li><tt class="docutils literal"><span class="pre">proc_bind</span></tt> clause of <tt class="docutils literal"><span class="pre">omp</span> <span class="pre">parallel</span></tt> pragma</li>
+<li><tt class="docutils literal"><span class="pre">depend</span></tt> clause of <tt class="docutils literal"><span class="pre">omp</span> <span class="pre">task</span></tt> pragma (except for array sections)</li>
+<li><tt class="docutils literal"><span class="pre">omp</span> <span class="pre">cancel</span></tt> and <tt class="docutils literal"><span class="pre">omp</span> <span class="pre">cancellation</span> <span class="pre">point</span></tt> pragmas</li>
+<li><tt class="docutils literal"><span class="pre">omp</span> <span class="pre">taskgroup</span></tt> pragma</li>
+</ul>
+</div>
+<div class="section" id="internal-api-changes">
+<h3><a class="toc-backref" href="#id9">Internal API Changes</a><a class="headerlink" href="#internal-api-changes" title="Permalink to this headline">Â¶</a></h3>
+<p>These are major API changes that have happened since the 3.6 release of
+Clang. If upgrading an external codebase that uses Clang as a library,
+this section should help get you past the largest hurdles of upgrading.</p>
+<ul class="simple">
+<li>Some of the <tt class="docutils literal"><span class="pre">PPCallbacks</span></tt> interface now deals in <tt class="docutils literal"><span class="pre">MacroDefinition</span></tt>
+objects instead of <tt class="docutils literal"><span class="pre">MacroDirective</span></tt> objects. This allows preserving
+full information on macros imported from modules.</li>
+<li><tt class="docutils literal"><span class="pre">clang-c/Index.h</span></tt> no longer <tt class="docutils literal"><span class="pre">#include</span></tt>s <tt class="docutils literal"><span class="pre">clang-c/Documentation.h</span></tt>.
+You now need to explicitly <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"clang-c/Documentation.h"</span></tt> if
+you use the libclang documentation API.</li>
+</ul>
+</div>
+<div class="section" id="static-analyzer">
+<h3><a class="toc-backref" href="#id10">Static Analyzer</a><a class="headerlink" href="#static-analyzer" title="Permalink to this headline">Â¶</a></h3>
+<ul class="simple">
+<li>The generated plists now contain the name of the check that generated it.</li>
+<li>Configuration options can now be passed to the checkers (not just the static
+analyzer core).</li>
+<li>New check for dereferencing object that the result of a zero-length
+allocation.</li>
+<li>Also check functions in precompiled headers.</li>
+<li>Properly handle alloca() in some checkers.</li>
+<li>Various improvements to the retain count checker.</li>
+</ul>
+</div>
+<div class="section" id="systemz">
+<h3><a class="toc-backref" href="#id11">SystemZ</a><a class="headerlink" href="#systemz" title="Permalink to this headline">Â¶</a></h3>
+<ul class="simple">
+<li>Clang will now always default to the z10 processor when compiling
+without any <tt class="docutils literal"><span class="pre">-march=</span></tt> option. Previous releases used to automatically
+detect the current host CPU when compiling natively. If you wish to
+still have clang detect the current host CPU, you now need to use the
+<tt class="docutils literal"><span class="pre">-march=native</span></tt> option.</li>
+<li>Clang now provides the <tt class="docutils literal"><span class="pre"><s390intrin.h></span></tt> header file.</li>
+<li>Clang now supports the transactional-execution facility and
+provides associated builtins and the <tt class="docutils literal"><span class="pre"><htmintrin.h></span></tt> and
+<tt class="docutils literal"><span class="pre"><htmxlintrin.h></span></tt> header files. Support is enabled by default
+on zEC12 and above, and can additionally be enabled or disabled
+via the <tt class="docutils literal"><span class="pre">-mhtm</span></tt> / <tt class="docutils literal"><span class="pre">-mno-htm</span></tt> command line options.</li>
+<li>Clang now supports the vector facility. This includes a
+change in the ABI to pass arguments and return values of
+vector types in vector registers, as well as a change in
+the default alignment of vector types. Support is enabled
+by default on z13 and above, and can additionally be enabled
+or disabled via the <tt class="docutils literal"><span class="pre">-mvx</span></tt> / <tt class="docutils literal"><span class="pre">-mno-vx</span></tt> command line options.</li>
+<li>Clang now supports the System z vector language extension,
+providing a “vector” keyword to define vector types, and a
+set of builtins defined in the <tt class="docutils literal"><span class="pre"><vecintrin.h></span></tt> header file.
+This can be enabled via the <tt class="docutils literal"><span class="pre">-fzvector</span></tt> command line option.
+For compatibility with GCC, Clang also supports the
+<tt class="docutils literal"><span class="pre">-mzvector</span></tt> option as an alias.</li>
+<li>Several cases of ABI incompatibility with GCC have been fixed.</li>
+</ul>
+</div>
+<div class="section" id="clang-tidy">
+<h3><a class="toc-backref" href="#id12">clang-tidy</a><a class="headerlink" href="#clang-tidy" title="Permalink to this headline">Â¶</a></h3>
+<p>Added new checks:</p>
+<ul class="simple">
+<li>google-global-names-in-headers: flag global namespace pollution in header
+files.</li>
+<li>misc-assert-side-effect: detects <tt class="docutils literal"><span class="pre">assert()</span></tt> conditions with side effects
+which can cause different behavior in debug / release builds.</li>
+<li>misc-assign-operator-signature: finds declarations of assign operators with
+the wrong return and/or argument types.</li>
+<li>misc-inaccurate-erase: warns when some elements of a container are not
+removed due to using the <tt class="docutils literal"><span class="pre">erase()</span></tt> algorithm incorrectly.</li>
+<li>misc-inefficient-algorithm: warns on inefficient use of STL algorithms on
+associative containers.</li>
+<li>misc-macro-parentheses: finds macros that can have unexpected behavior due
+to missing parentheses.</li>
+<li>misc-macro-repeated-side-effects: checks for repeated argument with side
+effects in macros.</li>
+<li>misc-noexcept-move-constructor: flags user-defined move constructors and
+assignment operators not marked with <tt class="docutils literal"><span class="pre">noexcept</span></tt> or marked with
+<tt class="docutils literal"><span class="pre">noexcept(expr)</span></tt> where <tt class="docutils literal"><span class="pre">expr</span></tt> evaluates to <tt class="docutils literal"><span class="pre">false</span></tt> (but is not a
+<tt class="docutils literal"><span class="pre">false</span></tt> literal itself).</li>
+<li>misc-static-assert: replaces <tt class="docutils literal"><span class="pre">assert()</span></tt> with <tt class="docutils literal"><span class="pre">static_assert()</span></tt> if the
+condition is evaluable at compile time.</li>
+<li>readability-container-size-empty: checks whether a call to the <tt class="docutils literal"><span class="pre">size()</span></tt>
+method can be replaced with a call to <tt class="docutils literal"><span class="pre">empty()</span></tt>.</li>
+<li>readability-else-after-return: flags conditional statements having the
+<tt class="docutils literal"><span class="pre">else</span></tt> branch, when the <tt class="docutils literal"><span class="pre">true</span></tt> branch has a <tt class="docutils literal"><span class="pre">return</span></tt> as the last statement.</li>
+<li>readability-redundant-string-cstr: finds unnecessary calls to
+<tt class="docutils literal"><span class="pre">std::string::c_str()</span></tt>.</li>
+<li>readability-shrink-to-fit: replaces copy and swap tricks on shrinkable
+containers with the <tt class="docutils literal"><span class="pre">shrink_to_fit()</span></tt> method call.</li>
+<li>readability-simplify-boolean-expr: looks for boolean expressions involving
+boolean constants and simplifies them to use the appropriate boolean
+expression directly (<tt class="docutils literal"><span class="pre">if</span> <span class="pre">(x</span> <span class="pre">==</span> <span class="pre">true)</span> <span class="pre">...</span> <span class="pre">-></span> <span class="pre">if</span> <span class="pre">(x)</span></tt>, etc.)</li>
+</ul>
+</div>
+<div class="section" id="last-release-which-will-run-on-windows-xp-and-windows-vista">
+<h3><a class="toc-backref" href="#id13">Last release which will run on Windows XP and Windows Vista</a><a class="headerlink" href="#last-release-which-will-run-on-windows-xp-and-windows-vista" title="Permalink to this headline">Â¶</a></h3>
+<p>This is expected to the be the last major release of Clang that will support
+running on Windows XP and Windows Vista.  For the next major release the
+minimum Windows version requirement will be Windows 7.</p>
+</div>
+</div>
+<div class="section" id="additional-information">
+<h2><a class="toc-backref" href="#id14">Additional Information</a><a class="headerlink" href="#additional-information" title="Permalink to this headline">Â¶</a></h2>
+<p>A wide variety of additional information is available on the <a class="reference external" href="http://clang.llvm.org/">Clang web
+page</a>. The web page contains versions of the
+API documentation which are up-to-date with the Subversion version of
+the source code. You can access versions of these documents specific to
+this release by going into the “<tt class="docutils literal"><span class="pre">clang/docs/</span></tt>” directory in the Clang
+tree.</p>
+<p>If you have any questions or comments about Clang, please feel free to
+contact us via the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-dev">mailing
+list</a>.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="index.html">Using Clang as a Compiler</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="UsersManual.html">Clang Compiler User’s Manual</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/SafeStack.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/SafeStack.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/SafeStack.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/SafeStack.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,257 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>SafeStack — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Modules" href="Modules.html" />
+    <link rel="prev" title="Control Flow Integrity Design Documentation" href="ControlFlowIntegrityDesign.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>SafeStack</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ControlFlowIntegrityDesign.html">Control Flow Integrity Design Documentation</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Modules.html">Modules</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="safestack">
+<h1>SafeStack<a class="headerlink" href="#safestack" 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><ul>
+<li><a class="reference internal" href="#performance" id="id2">Performance</a></li>
+<li><a class="reference internal" href="#compatibility" id="id3">Compatibility</a><ul>
+<li><a class="reference internal" href="#known-compatibility-limitations" id="id4">Known compatibility limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#security" id="id5">Security</a><ul>
+<li><a class="reference internal" href="#known-security-limitations" id="id6">Known security limitations</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#usage" id="id7">Usage</a><ul>
+<li><a class="reference internal" href="#supported-platforms" id="id8">Supported Platforms</a></li>
+<li><a class="reference internal" href="#low-level-api" id="id9">Low-level API</a><ul>
+<li><a class="reference internal" href="#has-feature-safe-stack" id="id10"><tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt></a></li>
+<li><a class="reference internal" href="#attribute-no-sanitize-safe-stack" id="id11"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-ptr" id="id12"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></tt></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-start" id="id13"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#design" id="id14">Design</a><ul>
+<li><a class="reference internal" href="#publications" id="id15">Publications</a></li>
+</ul>
+</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>SafeStack is an instrumentation pass that protects programs against attacks
+based on stack buffer overflows, without introducing any measurable performance
+overhead. It works by separating the program stack into two distinct regions:
+the safe stack and the unsafe stack. The safe stack stores return addresses,
+register spills, and local variables that are always accessed in a safe way,
+while the unsafe stack stores everything else. This separation ensures that
+buffer overflows on the unsafe stack cannot be used to overwrite anything
+on the safe stack.</p>
+<p>SafeStack is a part of the <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">Code-Pointer Integrity (CPI) Project</a>.</p>
+<div class="section" id="performance">
+<h3><a class="toc-backref" href="#id2">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">Â¶</a></h3>
+<p>The performance overhead of the SafeStack instrumentation is less than 0.1% on
+average across a variety of benchmarks (see the <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">Code-Pointer Integrity</a> paper for details). This is mainly
+because most small functions do not have any variables that require the unsafe
+stack and, hence, do not need unsafe stack frames to be created. The cost of
+creating unsafe stack frames for large functions is amortized by the cost of
+executing the function.</p>
+<p>In some cases, SafeStack actually improves the performance. Objects that end up
+being moved to the unsafe stack are usually large arrays or variables that are
+used through multiple stack frames. Moving such objects away from the safe
+stack increases the locality of frequently accessed values on the stack, such
+as register spills, return addresses, and small local variables.</p>
+</div>
+<div class="section" id="compatibility">
+<h3><a class="toc-backref" href="#id3">Compatibility</a><a class="headerlink" href="#compatibility" title="Permalink to this headline">Â¶</a></h3>
+<p>Most programs, static libraries, or individual files can be compiled
+with SafeStack as is. SafeStack requires basic runtime support, which, on most
+platforms, is implemented as a compiler-rt library that is automatically linked
+in when the program is compiled with SafeStack.</p>
+<p>Linking a DSO with SafeStack is not currently supported.</p>
+<div class="section" id="known-compatibility-limitations">
+<h4><a class="toc-backref" href="#id4">Known compatibility limitations</a><a class="headerlink" href="#known-compatibility-limitations" title="Permalink to this headline">Â¶</a></h4>
+<p>Certain code that relies on low-level stack manipulations requires adaption to
+work with SafeStack. One example is mark-and-sweep garbage collection
+implementations for C/C++ (e.g., Oilpan in chromium/blink), which must be
+changed to look for the live pointers on both safe and unsafe stacks.</p>
+<p>SafeStack supports linking statically modules that are compiled with and
+without SafeStack. An executable compiled with SafeStack can load dynamic
+libraries that are not compiled with SafeStack. At the moment, compiling
+dynamic libraries with SafeStack is not supported.</p>
+<p>Signal handlers that use <tt class="docutils literal"><span class="pre">sigaltstack()</span></tt> must not use the unsafe stack (see
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt> below).</p>
+<p>Programs that use APIs from <tt class="docutils literal"><span class="pre">ucontext.h</span></tt> are not supported yet.</p>
+</div>
+</div>
+<div class="section" id="security">
+<h3><a class="toc-backref" href="#id5">Security</a><a class="headerlink" href="#security" title="Permalink to this headline">Â¶</a></h3>
+<p>SafeStack protects return addresses, spilled registers and local variables that
+are always accessed in a safe way by separating them in a dedicated safe stack
+region. The safe stack is automatically protected against stack-based buffer
+overflows, since it is disjoint from the unsafe stack in memory, and it itself
+is always accessed in a safe way. In the current implementation, the safe stack
+is protected against arbitrary memory write vulnerabilities though
+randomization and information hiding: the safe stack is allocated at a random
+address and the instrumentation ensures that no pointers to the safe stack are
+ever stored outside of the safe stack itself (see limitations below).</p>
+<div class="section" id="known-security-limitations">
+<h4><a class="toc-backref" href="#id6">Known security limitations</a><a class="headerlink" href="#known-security-limitations" title="Permalink to this headline">Â¶</a></h4>
+<p>A complete protection against control-flow hijack attacks requires combining
+SafeStack with another mechanism that enforces the integrity of code pointers
+that are stored on the heap or the unsafe stack, such as <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">CPI</a>, or a forward-edge control flow integrity
+mechanism that enforces correct calling conventions at indirect call sites,
+such as <a class="reference external" href="http://research.google.com/pubs/archive/42808.pdf">IFCC</a> with arity
+checks. Clang has control-flow integrity protection scheme for <a class="reference internal" href="ControlFlowIntegrity.html"><em>C++ virtual
+calls</em></a>, but not non-virtual indirect calls. With
+SafeStack alone, an attacker can overwrite a function pointer on the heap or
+the unsafe stack and cause a program to call arbitrary location, which in turn
+might enable stack pivoting and return-oriented programming.</p>
+<p>In its current implementation, SafeStack provides precise protection against
+stack-based buffer overflows, but protection against arbitrary memory write
+vulnerabilities is probabilistic and relies on randomization and information
+hiding. The randomization is currently based on system-enforced ASLR and shares
+its known security limitations. The safe stack pointer hiding is not perfect
+yet either: system library functions such as <tt class="docutils literal"><span class="pre">swapcontext</span></tt>, exception
+handling mechanisms, intrinsics such as <tt class="docutils literal"><span class="pre">__builtin_frame_address</span></tt>, or
+low-level bugs in runtime support could leak the safe stack pointer. In the
+future, such leaks could be detected by static or dynamic analysis tools and
+prevented by adjusting such functions to either encrypt the stack pointer when
+storing it in the heap (as already done e.g., by <tt class="docutils literal"><span class="pre">setjmp</span></tt>/<tt class="docutils literal"><span class="pre">longjmp</span></tt>
+implementation in glibc), or store it in a safe region instead.</p>
+<p>The <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">CPI paper</a> describes two alternative,
+stronger safe stack protection mechanisms, that rely on software fault
+isolation, or hardware segmentation (as available on x86-32 and some x86-64
+CPUs).</p>
+<p>At the moment, SafeStack assumes that the compiler’s implementation is correct.
+This has not been verified except through manual code inspection, and could
+always regress in the future. It’s therefore desirable to have a separate
+static or dynamic binary verification tool that would check the correctness of
+the SafeStack instrumentation in final binaries.</p>
+</div>
+</div>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id7">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">Â¶</a></h2>
+<p>To enable SafeStack, just pass <tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt> flag to both compile
+and link command lines.</p>
+<div class="section" id="supported-platforms">
+<h3><a class="toc-backref" href="#id8">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">Â¶</a></h3>
+<p>SafeStack was tested on Linux, FreeBSD and MacOSX.</p>
+</div>
+<div class="section" id="low-level-api">
+<h3><a class="toc-backref" href="#id9">Low-level API</a><a class="headerlink" href="#low-level-api" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="has-feature-safe-stack">
+<h4><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt></a><a class="headerlink" href="#has-feature-safe-stack" title="Permalink to this headline">Â¶</a></h4>
+<p>In some rare cases one may need to execute different code depending on
+whether SafeStack is enabled. The macro <tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt> can
+be used for this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if __has_feature(safe_stack)</span>
+<span class="c1">// code that builds only under SafeStack</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-safe-stack">
+<h4><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt></a><a class="headerlink" href="#attribute-no-sanitize-safe-stack" title="Permalink to this headline">Â¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt> on a function declaration
+to specify that the safe stack instrumentation should not be applied to that
+function, even if enabled globally (see <tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt> flag). This
+attribute may be required for functions that make assumptions about the
+exact layout of their stack frames.</p>
+<p>All local variables in functions with this attribute will be stored on the safe
+stack. The safe stack remains unprotected against memory errors when accessing
+these variables, so extra care must be taken to manually ensure that all such
+accesses are safe. Furthermore, the addresses of such local variables should
+never be stored on the heap, as it would leak the location of the SafeStack.</p>
+</div>
+<div class="section" id="builtin-get-unsafe-stack-ptr">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></tt></a><a class="headerlink" href="#builtin-get-unsafe-stack-ptr" title="Permalink to this headline">Â¶</a></h4>
+<p>This builtin function returns current unsafe stack pointer of the current
+thread.</p>
+</div>
+<div class="section" id="builtin-get-unsafe-stack-start">
+<h4><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></tt></a><a class="headerlink" href="#builtin-get-unsafe-stack-start" title="Permalink to this headline">Â¶</a></h4>
+<p>This builtin function returns a pointer to the start of the unsafe stack of the
+current thread.</p>
+</div>
+</div>
+</div>
+<div class="section" id="design">
+<h2><a class="toc-backref" href="#id14">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">Â¶</a></h2>
+<p>Please refer to the <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">Code-Pointer Integrity</a>
+project page for more information about the design of the SafeStack and its
+related technologies.</p>
+<div class="section" id="publications">
+<h3><a class="toc-backref" href="#id15">Publications</a><a class="headerlink" href="#publications" title="Permalink to this headline">Â¶</a></h3>
+<p><a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">Code-Pointer Integrity</a>.
+Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song.
+USENIX Symposium on Operating Systems Design and Implementation
+(<a class="reference external" href="https://www.usenix.org/conference/osdi14">OSDI</a>), Broomfield, CO, October 2014</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ControlFlowIntegrityDesign.html">Control Flow Integrity Design Documentation</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Modules.html">Modules</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/SanitizerCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/SanitizerCoverage.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/SanitizerCoverage.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/SanitizerCoverage.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,551 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>SanitizerCoverage — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Sanitizer special case list" href="SanitizerSpecialCaseList.html" />
+    <link rel="prev" title="LeakSanitizer" href="LeakSanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>SanitizerCoverage</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="LeakSanitizer.html">LeakSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="sanitizercoverage">
+<h1>SanitizerCoverage<a class="headerlink" href="#sanitizercoverage" 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="#how-to-build-and-run" id="id2">How to build and run</a></li>
+<li><a class="reference internal" href="#postprocessing" id="id3">Postprocessing</a></li>
+<li><a class="reference internal" href="#how-good-is-the-coverage" id="id4">How good is the coverage?</a></li>
+<li><a class="reference internal" href="#edge-coverage" id="id5">Edge coverage</a></li>
+<li><a class="reference internal" href="#bitset" id="id6">Bitset</a></li>
+<li><a class="reference internal" href="#caller-callee-coverage" id="id7">Caller-callee coverage</a></li>
+<li><a class="reference internal" href="#coverage-counters" id="id8">Coverage counters</a></li>
+<li><a class="reference internal" href="#output-directory" id="id9">Output directory</a></li>
+<li><a class="reference internal" href="#sudden-death" id="id10">Sudden death</a></li>
+<li><a class="reference internal" href="#in-process-fuzzing" id="id11">In-process fuzzing</a></li>
+<li><a class="reference internal" href="#performance" id="id12">Performance</a></li>
+<li><a class="reference internal" href="#why-another-coverage" id="id13">Why another coverage?</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>Sanitizer tools have a very simple code coverage tool built in. It allows to
+get function-level, basic-block-level, and edge-level coverage at a very low
+cost.</p>
+</div>
+<div class="section" id="how-to-build-and-run">
+<h2><a class="toc-backref" href="#id2">How to build and run</a><a class="headerlink" href="#how-to-build-and-run" title="Permalink to this headline">Â¶</a></h2>
+<p>SanitizerCoverage can be used with <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>,
+<a class="reference internal" href="LeakSanitizer.html"><em>LeakSanitizer</em></a>, <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a>, and UndefinedBehaviorSanitizer.
+In addition to <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt>, pass one of the following compile-time flags:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=func</span></tt> for function-level coverage (very fast).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=bb</span></tt> for basic-block-level coverage (may add up to 30%
+<strong>extra</strong> slowdown).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=edge</span></tt> for edge-level coverage (up to 40% slowdown).</li>
+</ul>
+<p>You may also specify <tt class="docutils literal"><span class="pre">-fsanitize-coverage=indirect-calls</span></tt> for
+additional <a class="reference internal" href="#caller-callee-coverage">caller-callee coverage</a>.</p>
+<p>At run time, pass <tt class="docutils literal"><span class="pre">coverage=1</span></tt> in <tt class="docutils literal"><span class="pre">ASAN_OPTIONS</span></tt>, <tt class="docutils literal"><span class="pre">LSAN_OPTIONS</span></tt>,
+<tt class="docutils literal"><span class="pre">MSAN_OPTIONS</span></tt> or <tt class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></tt>, as appropriate.</p>
+<p>To get <a class="reference internal" href="#coverage-counters">Coverage counters</a>, add <tt class="docutils literal"><span class="pre">-fsanitize-coverage=8bit-counters</span></tt>
+to one of the above compile-time flags. At runtime, use
+<tt class="docutils literal"><span class="pre">*SAN_OPTIONS=coverage=1:coverage_counters=1</span></tt>.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat -n cov.cc
+<span class="go">     1  #include <stdio.h></span>
+<span class="go">     2  __attribute__((noinline))</span>
+<span class="go">     3  void foo() { printf("foo\n"); }</span>
+<span class="go">     4</span>
+<span class="go">     5  int main(int argc, char **argv) {</span>
+<span class="go">     6    if (argc == 2)</span>
+<span class="go">     7      foo();</span>
+<span class="go">     8    printf("main\n");</span>
+<span class="go">     9  }</span>
+<span class="gp">%</span> clang++ -g cov.cc -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>func
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span>1 ./a.out; ls -l *sancov
+<span class="go">main</span>
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span>1 ./a.out foo ; ls -l *sancov
+<span class="go">foo</span>
+<span class="go">main</span>
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="go">-rw-r----- 1 kcc eng 8 Nov 27 12:21 a.out.22679.sancov</span>
+</pre></div>
+</div>
+<p>Every time you run an executable instrumented with SanitizerCoverage
+one <tt class="docutils literal"><span class="pre">*.sancov</span></tt> file is created during the process shutdown.
+If the executable is dynamically linked against instrumented DSOs,
+one <tt class="docutils literal"><span class="pre">*.sancov</span></tt> file will be also created for every DSO.</p>
+</div>
+<div class="section" id="postprocessing">
+<h2><a class="toc-backref" href="#id3">Postprocessing</a><a class="headerlink" href="#postprocessing" title="Permalink to this headline">Â¶</a></h2>
+<p>The format of <tt class="docutils literal"><span class="pre">*.sancov</span></tt> files is very simple: the first 8 bytes is the magic,
+one of <tt class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF64</span></tt> and <tt class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF32</span></tt>. The last byte of the
+magic defines the size of the following offsets. The rest of the data is the
+offsets in the corresponding binary/DSO that were executed during the run.</p>
+<p>A simple script
+<tt class="docutils literal"><span class="pre">$LLVM/projects/compiler-rt/lib/sanitizer_common/scripts/sancov.py</span></tt> is
+provided to dump these offsets.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.22679.sancov a.out.22673.sancov
+<span class="go">sancov.py: read 2 PCs from a.out.22679.sancov</span>
+<span class="go">sancov.py: read 1 PCs from a.out.22673.sancov</span>
+<span class="go">sancov.py: 2 files merged; 2 PCs total</span>
+<span class="go">0x465250</span>
+<span class="go">0x4652a0</span>
+</pre></div>
+</div>
+<p>You can then filter the output of <tt class="docutils literal"><span class="pre">sancov.py</span></tt> through <tt class="docutils literal"><span class="pre">addr2line</span> <span class="pre">--exe</span>
+<span class="pre">ObjectFile</span></tt> or <tt class="docutils literal"><span class="pre">llvm-symbolizer</span> <span class="pre">--obj</span> <span class="pre">ObjectFile</span></tt> to get file names and line
+numbers:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.22679.sancov a.out.22673.sancov 2> /dev/null | llvm-symbolizer --obj a.out
+<span class="go">cov.cc:3</span>
+<span class="go">cov.cc:5</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="how-good-is-the-coverage">
+<h2><a class="toc-backref" href="#id4">How good is the coverage?</a><a class="headerlink" href="#how-good-is-the-coverage" title="Permalink to this headline">Â¶</a></h2>
+<p>It is possible to find out which PCs are not covered, by subtracting the covered
+set from the set of all instrumented PCs. The latter can be obtained by listing
+all callsites of <tt class="docutils literal"><span class="pre">__sanitizer_cov()</span></tt> in the binary. On Linux, <tt class="docutils literal"><span class="pre">sancov.py</span></tt>
+can do this for you. Just supply the path to binary and a list of covered PCs:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.12345.sancov > covered.txt
+<span class="go">sancov.py: read 2 64-bit PCs from a.out.12345.sancov</span>
+<span class="go">sancov.py: 1 file merged; 2 PCs total</span>
+<span class="gp">%</span> sancov.py missing a.out < covered.txt
+<span class="go">sancov.py: found 3 instrumented PCs in a.out</span>
+<span class="go">sancov.py: read 2 PCs from stdin</span>
+<span class="go">sancov.py: 1 PCs missing from coverage</span>
+<span class="go">0x4cc61c</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="edge-coverage">
+<h2><a class="toc-backref" href="#id5">Edge coverage</a><a class="headerlink" href="#edge-coverage" title="Permalink to this headline">Â¶</a></h2>
+<p>Consider this code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">if</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="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It contains 3 basic blocks, let’s name them A, B, C:</p>
+<div class="highlight-none"><div class="highlight"><pre>A
+|\
+| \
+|  B
+| /
+|/
+C
+</pre></div>
+</div>
+<p>If blocks A, B, and C are all covered we know for certain that the edges A=>B
+and B=>C were executed, but we still don’t know if the edge A=>C was executed.
+Such edges of control flow graph are called
+<a class="reference external" href="http://en.wikipedia.org/wiki/Control_flow_graph#Special_edges">critical</a>. The
+edge-level coverage (<tt class="docutils literal"><span class="pre">-fsanitize-coverage=edge</span></tt>) simply splits all critical
+edges by introducing new dummy blocks and then instruments those blocks:</p>
+<div class="highlight-none"><div class="highlight"><pre>A
+|\
+| \
+D  B
+| /
+|/
+C
+</pre></div>
+</div>
+</div>
+<div class="section" id="bitset">
+<h2><a class="toc-backref" href="#id6">Bitset</a><a class="headerlink" href="#bitset" title="Permalink to this headline">Â¶</a></h2>
+<p>When <tt class="docutils literal"><span class="pre">coverage_bitset=1</span></tt> run-time flag is given, the coverage will also be
+dumped as a bitset (text file with 1 for blocks that have been executed and 0
+for blocks that were not).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>edge cov.cc
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_bitset=1"</span> ./a.out
+<span class="go">main</span>
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_bitset=1"</span> ./a.out 1
+<span class="go">foo</span>
+<span class="go">main</span>
+<span class="gp">%</span> head *bitset*
+<span class="go">==> a.out.38214.bitset-sancov <==</span>
+<span class="go">01101</span>
+<span class="go">==> a.out.6128.bitset-sancov <==</span>
+<span class="go">11011%</span>
+</pre></div>
+</div>
+<p>For a given executable the length of the bitset is always the same (well,
+unless dlopen/dlclose come into play), so the bitset coverage can be
+easily used for bitset-based corpus distillation.</p>
+</div>
+<div class="section" id="caller-callee-coverage">
+<h2><a class="toc-backref" href="#id7">Caller-callee coverage</a><a class="headerlink" href="#caller-callee-coverage" title="Permalink to this headline">Â¶</a></h2>
+<p>(Experimental!)
+Every indirect function call is instrumented with a run-time function call that
+captures caller and callee.  At the shutdown time the process dumps a separate
+file called <tt class="docutils literal"><span class="pre">caller-callee.PID.sancov</span></tt> which contains caller/callee pairs as
+pairs of lines (odd lines are callers, even lines are callees)</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">a.out 0x4a2e0c</span>
+<span class="go">a.out 0x4a6510</span>
+<span class="go">a.out 0x4a2e0c</span>
+<span class="go">a.out 0x4a87f0</span>
+</pre></div>
+</div>
+<p>Current limitations:</p>
+<ul class="simple">
+<li>Only the first 14 callees for every caller are recorded, the rest are silently
+ignored.</li>
+<li>The output format is not very compact since caller and callee may reside in
+different modules and we need to spell out the module names.</li>
+<li>The routine that dumps the output is not optimized for speed</li>
+<li>Only Linux x86_64 is tested so far.</li>
+<li>Sandboxes are not supported.</li>
+</ul>
+</div>
+<div class="section" id="coverage-counters">
+<h2><a class="toc-backref" href="#id8">Coverage counters</a><a class="headerlink" href="#coverage-counters" title="Permalink to this headline">Â¶</a></h2>
+<p>This experimental feature is inspired by
+<a class="reference external" href="http://lcamtuf.coredump.cx/afl/technical_details.txt">AFL</a>‘s coverage
+instrumentation. With additional compile-time and run-time flags you can get
+more sensitive coverage information.  In addition to boolean values assigned to
+every basic block (edge) the instrumentation will collect imprecise counters.
+On exit, every counter will be mapped to a 8-bit bitset representing counter
+ranges: <tt class="docutils literal"><span class="pre">1,</span> <span class="pre">2,</span> <span class="pre">3,</span> <span class="pre">4-7,</span> <span class="pre">8-15,</span> <span class="pre">16-31,</span> <span class="pre">32-127,</span> <span class="pre">128+</span></tt> and those 8-bit bitsets will
+be dumped to disk.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang++ -g cov.cc -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>edge,8bit-counters
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_counters=1"</span> ./a.out
+<span class="gp">%</span> ls -l *counters-sancov
+<span class="go">... a.out.17110.counters-sancov</span>
+<span class="gp">%</span> xxd *counters-sancov
+<span class="go">0000000: 0001 0100 01</span>
+</pre></div>
+</div>
+<p>These counters may also be used for in-process coverage-guided fuzzers. See
+<tt class="docutils literal"><span class="pre">include/sanitizer/coverage_interface.h</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// The coverage instrumentation may optionally provide imprecise counters.</span>
+<span class="c1">// Rather than exposing the counter values to the user we instead map</span>
+<span class="c1">// the counters to a bitset.</span>
+<span class="c1">// Every counter is associated with 8 bits in the bitset.</span>
+<span class="c1">// We define 8 value ranges: 1, 2, 3, 4-7, 8-15, 16-31, 32-127, 128+</span>
+<span class="c1">// The i-th bit is set to 1 if the counter value is in the i-th range.</span>
+<span class="c1">// This counter-based coverage implementation is *not* thread-safe.</span>
+
+<span class="c1">// Returns the number of registered coverage counters.</span>
+<span class="kt">uintptr_t</span> <span class="nf">__sanitizer_get_number_of_counters</span><span class="p">();</span>
+<span class="c1">// Updates the counter 'bitset', clears the counters and returns the number of</span>
+<span class="c1">// new bits in 'bitset'.</span>
+<span class="c1">// If 'bitset' is nullptr, only clears the counters.</span>
+<span class="c1">// Otherwise 'bitset' should be at least</span>
+<span class="c1">// __sanitizer_get_number_of_counters bytes long and 8-aligned.</span>
+<span class="kt">uintptr_t</span>
+<span class="nf">__sanitizer_update_counter_bitset_and_clear_counters</span><span class="p">(</span><span class="kt">uint8_t</span> <span class="o">*</span><span class="n">bitset</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="output-directory">
+<h2><a class="toc-backref" href="#id9">Output directory</a><a class="headerlink" href="#output-directory" title="Permalink to this headline">Â¶</a></h2>
+<p>By default, .sancov files are created in the current working directory.
+This can be changed with <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=coverage_dir=/path</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_dir=/tmp/cov"</span> ./a.out foo
+<span class="gp">%</span> ls -l /tmp/cov/*sancov
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="go">-rw-r----- 1 kcc eng 8 Nov 27 12:21 a.out.22679.sancov</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="sudden-death">
+<h2><a class="toc-backref" href="#id10">Sudden death</a><a class="headerlink" href="#sudden-death" title="Permalink to this headline">Â¶</a></h2>
+<p>Normally, coverage data is collected in memory and saved to disk when the
+program exits (with an <tt class="docutils literal"><span class="pre">atexit()</span></tt> handler), when a SIGSEGV is caught, or when
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_dump()</span></tt> is called.</p>
+<p>If the program ends with a signal that ASan does not handle (or can not handle
+at all, like SIGKILL), coverage data will be lost. This is a big problem on
+Android, where SIGKILL is a normal way of evicting applications from memory.</p>
+<p>With <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=coverage=1:coverage_direct=1</span></tt> coverage data is written to a
+memory-mapped file as soon as it collected.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_direct=1"</span> ./a.out
+<span class="go">main</span>
+<span class="gp">%</span> ls
+<span class="go">7036.sancov.map  7036.sancov.raw  a.out</span>
+<span class="gp">%</span> sancov.py rawunpack 7036.sancov.raw
+<span class="go">sancov.py: reading map 7036.sancov.map</span>
+<span class="go">sancov.py: unpacking 7036.sancov.raw</span>
+<span class="go">writing 1 PCs to a.out.7036.sancov</span>
+<span class="gp">%</span> sancov.py print a.out.7036.sancov
+<span class="go">sancov.py: read 1 PCs from a.out.7036.sancov</span>
+<span class="go">sancov.py: 1 files merged; 1 PCs total</span>
+<span class="go">0x4b2bae</span>
+</pre></div>
+</div>
+<p>Note that on 64-bit platforms, this method writes 2x more data than the default,
+because it stores full PC values instead of 32-bit offsets.</p>
+</div>
+<div class="section" id="in-process-fuzzing">
+<h2><a class="toc-backref" href="#id11">In-process fuzzing</a><a class="headerlink" href="#in-process-fuzzing" title="Permalink to this headline">Â¶</a></h2>
+<p>Coverage data could be useful for fuzzers and sometimes it is preferable to run
+a fuzzer in the same process as the code being fuzzed (in-process fuzzer).</p>
+<p>You can use <tt class="docutils literal"><span class="pre">__sanitizer_get_total_unique_coverage()</span></tt> from
+<tt class="docutils literal"><span class="pre"><sanitizer/coverage_interface.h></span></tt> which returns the number of currently
+covered entities in the program. This will tell the fuzzer if the coverage has
+increased after testing every new input.</p>
+<p>If a fuzzer finds a bug in the ASan run, you will need to save the reproducer
+before exiting the process.  Use <tt class="docutils literal"><span class="pre">__asan_set_death_callback</span></tt> from
+<tt class="docutils literal"><span class="pre"><sanitizer/asan_interface.h></span></tt> to do that.</p>
+<p>An example of such fuzzer can be found in <a class="reference external" href="http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Fuzzer/README.txt?view=markup">the LLVM tree</a>.</p>
+</div>
+<div class="section" id="performance">
+<h2><a class="toc-backref" href="#id12">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">Â¶</a></h2>
+<p>This coverage implementation is <strong>fast</strong>. With function-level coverage
+(<tt class="docutils literal"><span class="pre">-fsanitize-coverage=func</span></tt>) the overhead is not measurable. With
+basic-block-level coverage (<tt class="docutils literal"><span class="pre">-fsanitize-coverage=bb</span></tt>) the overhead varies
+between 0 and 25%.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="21%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">benchmark</th>
+<th class="head">cov0</th>
+<th class="head">cov1</th>
+<th class="head">diff 0-1</th>
+<th class="head">cov2</th>
+<th class="head">diff 0-2</th>
+<th class="head">diff 1-2</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>400.perlbench</td>
+<td>1296.00</td>
+<td>1307.00</td>
+<td>1.01</td>
+<td>1465.00</td>
+<td>1.13</td>
+<td>1.12</td>
+</tr>
+<tr class="row-odd"><td>401.bzip2</td>
+<td>858.00</td>
+<td>854.00</td>
+<td>1.00</td>
+<td>1010.00</td>
+<td>1.18</td>
+<td>1.18</td>
+</tr>
+<tr class="row-even"><td>403.gcc</td>
+<td>613.00</td>
+<td>617.00</td>
+<td>1.01</td>
+<td>683.00</td>
+<td>1.11</td>
+<td>1.11</td>
+</tr>
+<tr class="row-odd"><td>429.mcf</td>
+<td>605.00</td>
+<td>582.00</td>
+<td>0.96</td>
+<td>610.00</td>
+<td>1.01</td>
+<td>1.05</td>
+</tr>
+<tr class="row-even"><td>445.gobmk</td>
+<td>896.00</td>
+<td>880.00</td>
+<td>0.98</td>
+<td>1050.00</td>
+<td>1.17</td>
+<td>1.19</td>
+</tr>
+<tr class="row-odd"><td>456.hmmer</td>
+<td>892.00</td>
+<td>892.00</td>
+<td>1.00</td>
+<td>918.00</td>
+<td>1.03</td>
+<td>1.03</td>
+</tr>
+<tr class="row-even"><td>458.sjeng</td>
+<td>995.00</td>
+<td>1009.00</td>
+<td>1.01</td>
+<td>1217.00</td>
+<td>1.22</td>
+<td>1.21</td>
+</tr>
+<tr class="row-odd"><td>462.libquantum</td>
+<td>497.00</td>
+<td>492.00</td>
+<td>0.99</td>
+<td>534.00</td>
+<td>1.07</td>
+<td>1.09</td>
+</tr>
+<tr class="row-even"><td>464.h264ref</td>
+<td>1461.00</td>
+<td>1467.00</td>
+<td>1.00</td>
+<td>1543.00</td>
+<td>1.06</td>
+<td>1.05</td>
+</tr>
+<tr class="row-odd"><td>471.omnetpp</td>
+<td>575.00</td>
+<td>590.00</td>
+<td>1.03</td>
+<td>660.00</td>
+<td>1.15</td>
+<td>1.12</td>
+</tr>
+<tr class="row-even"><td>473.astar</td>
+<td>658.00</td>
+<td>652.00</td>
+<td>0.99</td>
+<td>715.00</td>
+<td>1.09</td>
+<td>1.10</td>
+</tr>
+<tr class="row-odd"><td>483.xalancbmk</td>
+<td>471.00</td>
+<td>491.00</td>
+<td>1.04</td>
+<td>582.00</td>
+<td>1.24</td>
+<td>1.19</td>
+</tr>
+<tr class="row-even"><td>433.milc</td>
+<td>616.00</td>
+<td>627.00</td>
+<td>1.02</td>
+<td>627.00</td>
+<td>1.02</td>
+<td>1.00</td>
+</tr>
+<tr class="row-odd"><td>444.namd</td>
+<td>602.00</td>
+<td>601.00</td>
+<td>1.00</td>
+<td>654.00</td>
+<td>1.09</td>
+<td>1.09</td>
+</tr>
+<tr class="row-even"><td>447.dealII</td>
+<td>630.00</td>
+<td>634.00</td>
+<td>1.01</td>
+<td>653.00</td>
+<td>1.04</td>
+<td>1.03</td>
+</tr>
+<tr class="row-odd"><td>450.soplex</td>
+<td>365.00</td>
+<td>368.00</td>
+<td>1.01</td>
+<td>395.00</td>
+<td>1.08</td>
+<td>1.07</td>
+</tr>
+<tr class="row-even"><td>453.povray</td>
+<td>427.00</td>
+<td>434.00</td>
+<td>1.02</td>
+<td>495.00</td>
+<td>1.16</td>
+<td>1.14</td>
+</tr>
+<tr class="row-odd"><td>470.lbm</td>
+<td>357.00</td>
+<td>375.00</td>
+<td>1.05</td>
+<td>370.00</td>
+<td>1.04</td>
+<td>0.99</td>
+</tr>
+<tr class="row-even"><td>482.sphinx3</td>
+<td>927.00</td>
+<td>928.00</td>
+<td>1.00</td>
+<td>1000.00</td>
+<td>1.08</td>
+<td>1.08</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="why-another-coverage">
+<h2><a class="toc-backref" href="#id13">Why another coverage?</a><a class="headerlink" href="#why-another-coverage" title="Permalink to this headline">Â¶</a></h2>
+<dl class="docutils">
+<dt>Why did we implement yet another code coverage?</dt>
+<dd><ul class="first last simple">
+<li>We needed something that is lightning fast, plays well with
+AddressSanitizer, and does not significantly increase the binary size.</li>
+<li>Traditional coverage implementations based in global counters
+<a class="reference external" href="https://groups.google.com/forum/#!topic/llvm-dev/cDqYgnxNEhY">suffer from contention on counters</a>.</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="LeakSanitizer.html">LeakSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/SanitizerSpecialCaseList.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/SanitizerSpecialCaseList.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/SanitizerSpecialCaseList.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/SanitizerSpecialCaseList.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,149 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Sanitizer special case list — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Control Flow Integrity" href="ControlFlowIntegrity.html" />
+    <link rel="prev" title="SanitizerCoverage" href="SanitizerCoverage.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Sanitizer special case list</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="SanitizerCoverage.html">SanitizerCoverage</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ControlFlowIntegrity.html">Control Flow Integrity</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="sanitizer-special-case-list">
+<h1>Sanitizer special case list<a class="headerlink" href="#sanitizer-special-case-list" 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="#goal-and-usage" id="id2">Goal and usage</a></li>
+<li><a class="reference internal" href="#example" id="id3">Example</a></li>
+<li><a class="reference internal" href="#format" id="id4">Format</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>This document describes the way to disable or alter the behavior of
+sanitizer tools for certain source-level entities by providing a special
+file at compile-time.</p>
+</div>
+<div class="section" id="goal-and-usage">
+<h2><a class="toc-backref" href="#id2">Goal and usage</a><a class="headerlink" href="#goal-and-usage" title="Permalink to this headline">Â¶</a></h2>
+<p>User of sanitizer tools, such as <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>, <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>
+or <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a> may want to disable or alter some checks for
+certain source-level entities to:</p>
+<ul class="simple">
+<li>speedup hot function, which is known to be correct;</li>
+<li>ignore a function that does some low-level magic (e.g. walks through the
+thread stack, bypassing the frame boundaries);</li>
+<li>ignore a known problem.</li>
+</ul>
+<p>To achieve this, user may create a file listing the entities they want to
+ignore, and pass it to clang at compile-time using
+<tt class="docutils literal"><span class="pre">-fsanitize-blacklist</span></tt> flag. See <a class="reference internal" href="UsersManual.html"><em>Clang Compiler User’s Manual</em></a> for details.</p>
+</div>
+<div class="section" id="example">
+<h2><a class="toc-backref" href="#id3">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">Â¶</a></h2>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>cat foo.c
+<span class="c">#include <stdlib.h></span>
+void bad_foo<span class="o">()</span> <span class="o">{</span>
+  int *a <span class="o">=</span> <span class="o">(</span>int*<span class="o">)</span>malloc<span class="o">(</span>40<span class="o">)</span>;
+  a<span class="o">[</span>10<span class="o">]</span> <span class="o">=</span> 1;
+<span class="o">}</span>
+int main<span class="o">()</span> <span class="o">{</span> bad_foo<span class="o">()</span>; <span class="o">}</span>
+<span class="nv">$ </span>cat blacklist.txt
+<span class="c"># Ignore reports from bad_foo function.</span>
+fun:bad_foo
+<span class="nv">$ </span>clang -fsanitize<span class="o">=</span>address foo.c ; ./a.out
+<span class="c"># AddressSanitizer prints an error report.</span>
+<span class="nv">$ </span>clang -fsanitize<span class="o">=</span>address -fsanitize-blacklist<span class="o">=</span>blacklist.txt foo.c ; ./a.out
+<span class="c"># No error report here.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="format">
+<h2><a class="toc-backref" href="#id4">Format</a><a class="headerlink" href="#format" title="Permalink to this headline">Â¶</a></h2>
+<p>Each line contains an entity type, followed by a colon and a regular
+expression, specifying the names of the entities, optionally followed by
+an equals sign and a tool-specific category. Empty lines and lines starting
+with “#” are ignored. The meanining of <tt class="docutils literal"><span class="pre">*</span></tt> in regular expression for entity
+names is different - it is treated as in shell wildcarding. Two generic
+entity types are <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt>, which allow user to add, respectively,
+source files and functions to special case list. Some sanitizer tools may
+introduce custom entity types - refer to tool-specific docs.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Lines starting with # are ignored.</span>
+<span class="c"># Turn off checks for the source file (use absolute path or path relative</span>
+<span class="c"># to the current working directory):</span>
+src:/path/to/source/file.c
+<span class="c"># Turn off checks for a particular functions (use mangled names):</span>
+fun:MyFooBar
+fun:_Z8MyFooBarv
+<span class="c"># Extended regular expressions are supported:</span>
+fun:bad_<span class="o">(</span>foo|bar<span class="o">)</span>
+src:bad_source<span class="o">[</span>1-9<span class="o">]</span>.c
+<span class="c"># Shell like usage of * is supported (* is treated as .*):</span>
+src:bad/sources/*
+fun:*BadFunction*
+<span class="c"># Specific sanitizer tools may introduce categories.</span>
+src:/special/path/*<span class="o">=</span>special_sources
+</pre></div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="SanitizerCoverage.html">SanitizerCoverage</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ControlFlowIntegrity.html">Control Flow Integrity</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/ThreadSafetyAnalysis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/ThreadSafetyAnalysis.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/ThreadSafetyAnalysis.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/ThreadSafetyAnalysis.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,914 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Thread Safety Analysis — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="AddressSanitizer" href="AddressSanitizer.html" />
+    <link rel="prev" title="Cross-compilation using Clang" href="CrossCompilation.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Thread Safety Analysis</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="CrossCompilation.html">Cross-compilation using Clang</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AddressSanitizer.html">AddressSanitizer</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="thread-safety-analysis">
+<h1>Thread Safety Analysis<a class="headerlink" href="#thread-safety-analysis" 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>Clang Thread Safety Analysis is a C++ language extension which warns about
+potential race conditions in code.  The analysis is completely static (i.e.
+compile-time); there is no run-time overhead.  The analysis is still
+under active development, but it is mature enough to be deployed in an
+industrial setting.  It is being developed by Google, in collaboration with
+CERT/SEI, and is used extensively in Google’s internal code base.</p>
+<p>Thread safety analysis works very much like a type system for multi-threaded
+programs.  In addition to declaring the <em>type</em> of data (e.g. <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment.  For example, if <tt class="docutils literal"><span class="pre">foo</span></tt> is
+<em>guarded by</em> the mutex <tt class="docutils literal"><span class="pre">mu</span></tt>, then the analysis will issue a warning whenever
+a piece of code reads or writes to <tt class="docutils literal"><span class="pre">foo</span></tt> without first locking <tt class="docutils literal"><span class="pre">mu</span></tt>.
+Similarly, if there are particular routines that should only be called by
+the GUI thread, then the analysis will warn if other threads call those
+routines.</p>
+<div class="section" id="getting-started">
+<h3>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">Â¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "mutex.h"</span>
+
+<span class="k">class</span> <span class="nc">BankAccount</span> <span class="p">{</span>
+<span class="nl">private:</span>
+  <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+  <span class="kt">int</span>   <span class="n">balance</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+  <span class="kt">void</span> <span class="nf">depositImpl</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">balance</span> <span class="o">+=</span> <span class="n">amount</span><span class="p">;</span>       <span class="c1">// WARNING! Cannot write balance without locking mu.</span>
+  <span class="p">}</span>
+
+  <span class="kt">void</span> <span class="nf">withdrawImpl</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">balance</span> <span class="o">-=</span> <span class="n">amount</span><span class="p">;</span>       <span class="c1">// OK. Caller must have locked mu.</span>
+  <span class="p">}</span>
+
+<span class="nl">public:</span>
+  <span class="kt">void</span> <span class="nf">withdraw</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+    <span class="n">withdrawImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span>    <span class="c1">// OK.  We've locked mu.</span>
+  <span class="p">}</span>                          <span class="c1">// WARNING!  Failed to unlock mu.</span>
+
+  <span class="kt">void</span> <span class="nf">transferFrom</span><span class="p">(</span><span class="n">BankAccount</span><span class="o">&</span> <span class="n">b</span><span class="p">,</span> <span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+    <span class="n">b</span><span class="p">.</span><span class="n">withdrawImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span>  <span class="c1">// WARNING!  Calling withdrawImpl() requires locking b.mu.</span>
+    <span class="n">depositImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span>     <span class="c1">// OK.  depositImpl() has no requirements.</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>This example demonstrates the basic concepts behind the analysis.  The
+<tt class="docutils literal"><span class="pre">GUARDED_BY</span></tt> attribute declares that a thread must lock <tt class="docutils literal"><span class="pre">mu</span></tt> before it can
+read or write to <tt class="docutils literal"><span class="pre">balance</span></tt>, thus ensuring that the increment and decrement
+operations are atomic.  Similarly, <tt class="docutils literal"><span class="pre">REQUIRES</span></tt> declares that
+the calling thread must lock <tt class="docutils literal"><span class="pre">mu</span></tt> before calling <tt class="docutils literal"><span class="pre">withdrawImpl</span></tt>.
+Because the caller is assumed to have locked <tt class="docutils literal"><span class="pre">mu</span></tt>, it is safe to modify
+<tt class="docutils literal"><span class="pre">balance</span></tt> within the body of the method.</p>
+<p>The <tt class="docutils literal"><span class="pre">depositImpl()</span></tt> method does not have <tt class="docutils literal"><span class="pre">REQUIRES</span></tt>, so the
+analysis issues a warning.  Thread safety analysis is not inter-procedural, so
+caller requirements must be explicitly declared.
+There is also a warning in <tt class="docutils literal"><span class="pre">transferFrom()</span></tt>, because although the method
+locks <tt class="docutils literal"><span class="pre">this->mu</span></tt>, it does not lock <tt class="docutils literal"><span class="pre">b.mu</span></tt>.  The analysis understands
+that these are two separate mutexes, in two different objects.</p>
+<p>Finally, there is a warning in the <tt class="docutils literal"><span class="pre">withdraw()</span></tt> method, because it fails to
+unlock <tt class="docutils literal"><span class="pre">mu</span></tt>.  Every lock must have a corresponding unlock, and the analysis
+will detect both double locks, and double unlocks.  A function is allowed to
+acquire a lock without releasing it, (or vice versa), but it must be annotated
+as such (using <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt>/<tt class="docutils literal"><span class="pre">RELEASE</span></tt>).</p>
+</div>
+<div class="section" id="running-the-analysis">
+<h3>Running The Analysis<a class="headerlink" href="#running-the-analysis" title="Permalink to this headline">Â¶</a></h3>
+<p>To run the analysis, simply compile with the <tt class="docutils literal"><span class="pre">-Wthread-safety</span></tt> flag, e.g.</p>
+<div class="highlight-bash"><div class="highlight"><pre>clang -c -Wthread-safety example.cpp
+</pre></div>
+</div>
+<p>Note that this example assumes the presence of a suitably annotated
+<a class="reference internal" href="#mutexheader"><em>mutex.h</em></a> that declares which methods perform locking,
+unlocking, and so on.</p>
+</div>
+</div>
+<div class="section" id="basic-concepts-capabilities">
+<h2>Basic Concepts: Capabilities<a class="headerlink" href="#basic-concepts-capabilities" title="Permalink to this headline">Â¶</a></h2>
+<p>Thread safety analysis provides a way of protecting <em>resources</em> with
+<em>capabilities</em>.  A resource is either a data member, or a function/method
+that provides access to some underlying resource.  The analysis ensures that
+the calling thread cannot access the <em>resource</em> (i.e. call the function, or
+read/write the data) unless it has the <em>capability</em> to do so.</p>
+<p>Capabilities are associated with named C++ objects which declare specific
+methods to acquire and release the capability.  The name of the object serves
+to identify the capability.  The most common example is a mutex.  For example,
+if <tt class="docutils literal"><span class="pre">mu</span></tt> is a mutex, then calling <tt class="docutils literal"><span class="pre">mu.Lock()</span></tt> causes the calling thread
+to acquire the capability to access data that is protected by <tt class="docutils literal"><span class="pre">mu</span></tt>. Similarly,
+calling <tt class="docutils literal"><span class="pre">mu.Unlock()</span></tt> releases that capability.</p>
+<p>A thread may hold a capability either <em>exclusively</em> or <em>shared</em>.  An exclusive
+capability can be held by only one thread at a time, while a shared capability
+can be held by many threads at the same time.  This mechanism enforces a
+multiple-reader, single-writer pattern.  Write operations to protected data
+require exclusive access, while read operations require only shared access.</p>
+<p>At any given moment during program execution, a thread holds a specific set of
+capabilities (e.g. the set of mutexes that it has locked.)  These act like keys
+or tokens that allow the thread to access a given resource.  Just like physical
+security keys, a thread cannot make copy of a capability, nor can it destroy
+one.  A thread can only release a capability to another thread, or acquire one
+from another thread.  The annotations are deliberately agnostic about the
+exact mechanism used to acquire and release capabilities; it assumes that the
+underlying implementation (e.g. the Mutex implementation) does the handoff in
+an appropriate manner.</p>
+<p>The set of capabilities that are actually held by a given thread at a given
+point in program execution is a run-time concept.  The static analysis works
+by calculating an approximation of that set, called the <em>capability
+environment</em>.  The capability environment is calculated for every program point,
+and describes the set of capabilities that are statically known to be held, or
+not held, at that particular point.  This environment is a conservative
+approximation of the full set of capabilities that will actually held by a
+thread at run-time.</p>
+</div>
+<div class="section" id="reference-guide">
+<h2>Reference Guide<a class="headerlink" href="#reference-guide" title="Permalink to this headline">Â¶</a></h2>
+<p>The thread safety analysis uses attributes to declare threading constraints.
+Attributes must be attached to named declarations, such as classes, methods,
+and data members. Users are <em>strongly advised</em> to define macros for the various
+attributes; example definitions can be found in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below.
+The following documentation assumes the use of macros.</p>
+<p>For historical reasons, prior versions of thread safety used macro names that
+were very lock-centric.  These macros have since been renamed to fit a more
+general capability model.  The prior names are still in use, and will be
+mentioned under the tag <em>previously</em> where appropriate.</p>
+<div class="section" id="guarded-by-c-and-pt-guarded-by-c">
+<h3>GUARDED_BY(c) and PT_GUARDED_BY(c)<a class="headerlink" href="#guarded-by-c-and-pt-guarded-by-c" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">GUARDED_BY</span></tt> is an attribute on data members, which declares that the data
+member is protected by the given capability.  Read operations on the data
+require shared access, while write operations require exclusive access.</p>
+<p><tt class="docutils literal"><span class="pre">PT_GUARDED_BY</span></tt> is similar, but is intended for use on pointers and smart
+pointers. There is no constraint on the data member itself, but the <em>data that
+it points to</em> is protected by the given capability.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">int</span> <span class="o">*</span><span class="n">p1</span>             <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="kt">int</span> <span class="o">*</span><span class="n">p2</span>             <span class="nf">PT_GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="n">unique_ptr</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">p3</span>  <span class="n">PT_GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">p1</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>             <span class="c1">// Warning!</span>
+
+  <span class="o">*</span><span class="n">p2</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span>           <span class="c1">// Warning!</span>
+  <span class="n">p2</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">int</span><span class="p">;</span>       <span class="c1">// OK.</span>
+
+  <span class="o">*</span><span class="n">p3</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span>           <span class="c1">// Warning!</span>
+  <span class="n">p3</span><span class="p">.</span><span class="n">reset</span><span class="p">(</span><span class="k">new</span> <span class="kt">int</span><span class="p">);</span>  <span class="c1">// OK.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="requires-requires-shared">
+<h3>REQUIRES(...), REQUIRES_SHARED(...)<a class="headerlink" href="#requires-requires-shared" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">EXCLUSIVE_LOCKS_REQUIRED</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_LOCKS_REQUIRED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">REQUIRES</span></tt> is an attribute on functions or methods, which
+declares that the calling thread must have exclusive access to the given
+capabilities.  More than one capability may be specified.  The capabilities
+must be held on entry to the function, <em>and must still be held on exit</em>.</p>
+<p><tt class="docutils literal"><span class="pre">REQUIRES_SHARED</span></tt> is similar, but requires only shared access.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu1</span><span class="p">,</span> <span class="n">mu2</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu1</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">b</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu2</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu1</span><span class="p">,</span> <span class="n">mu2</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+  <span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">mu1</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+  <span class="n">foo</span><span class="p">();</span>         <span class="c1">// Warning!  Requires mu2.</span>
+  <span class="n">mu1</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="acquire-acquire-shared-release-release-shared">
+<h3>ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...)<a class="headerlink" href="#acquire-acquire-shared-release-release-shared" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">EXCLUSIVE_LOCK_FUNCTION</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_LOCK_FUNCTION</span></tt>,
+<tt class="docutils literal"><span class="pre">UNLOCK_FUNCTION</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">ACQUIRE</span></tt> is an attribute on functions or methods, which
+declares that the function acquires a capability, but does not release it.  The
+caller must not hold the given capability on entry, and it will hold the
+capability on exit.  <tt class="docutils literal"><span class="pre">ACQUIRE_SHARED</span></tt> is similar.</p>
+<p><tt class="docutils literal"><span class="pre">RELEASE</span></tt> and <tt class="docutils literal"><span class="pre">RELEASE_SHARED</span></tt> declare that the function releases the given
+capability.  The caller must hold the capability on entry, and will no longer
+hold it on exit. It does not matter whether the given capability is shared or
+exclusive.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="n">MyClass</span> <span class="n">myObject</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">lockAndInit</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+  <span class="n">myObject</span><span class="p">.</span><span class="n">init</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">cleanupAndUnlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">myObject</span><span class="p">.</span><span class="n">cleanup</span><span class="p">();</span>
+<span class="p">}</span>                          <span class="c1">// Warning!  Need to unlock mu.</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">lockAndInit</span><span class="p">();</span>
+  <span class="n">myObject</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+  <span class="n">cleanupAndUnlock</span><span class="p">();</span>
+  <span class="n">myObject</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>  <span class="c1">// Warning, mu is not locked.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If no argument is passed to <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt> or <tt class="docutils literal"><span class="pre">RELEASE</span></tt>, then the argument is
+assumed to be <tt class="docutils literal"><span class="pre">this</span></tt>, and the analysis will not check the body of the
+function.  This pattern is intended for use by classes which hide locking
+details behind an abstract interface.  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">CAPABILITY</span><span class="p">(</span><span class="s">"mutex"</span><span class="p">)</span> <span class="n">Container</span> <span class="p">{</span>
+<span class="nl">private:</span>
+  <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+  <span class="n">T</span><span class="o">*</span> <span class="n">data</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+  <span class="c1">// Hide mu from public interface.</span>
+  <span class="kt">void</span> <span class="nf">Lock</span><span class="p">()</span>   <span class="n">ACQUIRE</span><span class="p">()</span> <span class="p">{</span> <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span> <span class="p">}</span>
+  <span class="kt">void</span> <span class="nf">Unlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">()</span> <span class="p">{</span> <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span> <span class="p">}</span>
+
+  <span class="n">T</span><span class="o">&</span> <span class="n">getElem</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">data</span><span class="p">[</span><span class="n">i</span><span class="p">];</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">Container</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">c</span><span class="p">;</span>
+  <span class="n">c</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+  <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">c</span><span class="p">.</span><span class="n">getElem</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+  <span class="n">c</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="excludes">
+<h3>EXCLUDES(...)<a class="headerlink" href="#excludes" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCKS_EXCLUDED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">EXCLUDES</span></tt> is an attribute on functions or methods, which declares that
+the caller must <em>not</em> hold the given capabilities.  This annotation is
+used to prevent deadlock.  Many mutex implementations are not re-entrant, so
+deadlock can occur if the function acquires the mutex a second time.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">clear</span><span class="p">()</span> <span class="n">EXCLUDES</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+  <span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+  <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">reset</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+  <span class="n">clear</span><span class="p">();</span>     <span class="c1">// Warning!  Caller cannot hold 'mu'.</span>
+  <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Unlike <tt class="docutils literal"><span class="pre">REQUIRES</span></tt>, <tt class="docutils literal"><span class="pre">EXCLUDES</span></tt> is optional.  The analysis will not issue a
+warning if the attribute is missing, which can lead to false negatives in some
+cases.  This issue is discussed further in <a class="reference internal" href="#negative"><em>Negative Capabilities</em></a>.</p>
+</div>
+<div class="section" id="no-thread-safety-analysis">
+<h3>NO_THREAD_SAFETY_ANALYSIS<a class="headerlink" href="#no-thread-safety-analysis" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></tt> is an attribute on functions or methods, which
+turns off thread safety checking for that method.  It provides an escape hatch
+for functions which are either (1) deliberately thread-unsafe, or (2) are
+thread-safe, but too complicated for the analysis to understand.  Reasons for
+(2) will be described in the <a class="reference internal" href="#limitations"><em>Known Limitations</em></a>, below.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Counter</span> <span class="p">{</span>
+  <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+  <span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+  <span class="kt">void</span> <span class="n">unsafeIncrement</span><span class="p">()</span> <span class="n">NO_THREAD_SAFETY_ANALYSIS</span> <span class="p">{</span> <span class="n">a</span><span class="o">++</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Unlike the other attributes, NO_THREAD_SAFETY_ANALYSIS is not part of the
+interface of a function, and should thus be placed on the function definition
+(in the <tt class="docutils literal"><span class="pre">.cc</span></tt> or <tt class="docutils literal"><span class="pre">.cpp</span></tt> file) rather than on the function declaration
+(in the header).</p>
+</div>
+<div class="section" id="return-capability-c">
+<h3>RETURN_CAPABILITY(c)<a class="headerlink" href="#return-capability-c" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCK_RETURNED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></tt> is an attribute on functions or methods, which declares
+that the function returns a reference to the given capability.  It is used to
+annotate getter methods that return mutexes.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="nl">private:</span>
+  <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+  <span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="nl">public:</span>
+  <span class="n">Mutex</span><span class="o">*</span> <span class="nf">getMu</span><span class="p">()</span> <span class="n">RETURN_CAPABILITY</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&</span><span class="n">mu</span><span class="p">;</span> <span class="p">}</span>
+
+  <span class="c1">// analysis knows that getMu() == mu</span>
+  <span class="kt">void</span> <span class="nf">clear</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">getMu</span><span class="p">())</span> <span class="p">{</span> <span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="acquired-before-acquired-after">
+<h3>ACQUIRED_BEFORE(...), ACQUIRED_AFTER(...)<a class="headerlink" href="#acquired-before-acquired-after" title="Permalink to this headline">Â¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">ACQUIRED_BEFORE</span></tt> and <tt class="docutils literal"><span class="pre">ACQUIRED_AFTER</span></tt> are attributes on member
+declarations, specifically declarations of mutexes or other capabilities.
+These declarations enforce a particular order in which the mutexes must be
+acquired, in order to prevent deadlock.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">m1</span><span class="p">;</span>
+<span class="n">Mutex</span> <span class="n">m2</span> <span class="nf">ACQUIRED_AFTER</span><span class="p">(</span><span class="n">m1</span><span class="p">);</span>
+
+<span class="c1">// Alternative declaration</span>
+<span class="c1">// Mutex m2;</span>
+<span class="c1">// Mutex m1 ACQUIRED_BEFORE(m2);</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">m2</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+  <span class="n">m1</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>  <span class="c1">// Warning!  m2 must be acquired after m1.</span>
+  <span class="n">m1</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+  <span class="n">m2</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="capability-string">
+<h3>CAPABILITY(<string>)<a class="headerlink" href="#capability-string" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCKABLE</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">CAPABILITY</span></tt> is an attribute on classes, which specifies that objects of the
+class can be used as a capability.  The string argument specifies the kind of
+capability in error messages, e.g. <tt class="docutils literal"><span class="pre">"mutex"</span></tt>.  See the <tt class="docutils literal"><span class="pre">Container</span></tt> example
+given above, or the <tt class="docutils literal"><span class="pre">Mutex</span></tt> class in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>.</p>
+</div>
+<div class="section" id="scoped-capability">
+<h3>SCOPED_CAPABILITY<a class="headerlink" href="#scoped-capability" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">SCOPED_LOCKABLE</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">SCOPED_CAPABILITY</span></tt> is an attribute on classes that implement RAII-style
+locking, in which a capability is acquired in the constructor, and released in
+the destructor.  Such classes require special handling because the constructor
+and destructor refer to the capability via different names; see the
+<tt class="docutils literal"><span class="pre">MutexLocker</span></tt> class in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below.</p>
+</div>
+<div class="section" id="try-acquire-bool-try-acquire-shared-bool">
+<h3>TRY_ACQUIRE(<bool>, ...), TRY_ACQUIRE_SHARED(<bool>, ...)<a class="headerlink" href="#try-acquire-bool-try-acquire-shared-bool" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Previously:</em> <tt class="docutils literal"><span class="pre">EXCLUSIVE_TRYLOCK_FUNCTION</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_TRYLOCK_FUNCTION</span></tt></p>
+<p>These are attributes on a function or method that tries to acquire the given
+capability, and returns a boolean value indicating success or failure.
+The first argument must be <tt class="docutils literal"><span class="pre">true</span></tt> or <tt class="docutils literal"><span class="pre">false</span></tt>, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt>.  See <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below, for example uses.</p>
+</div>
+<div class="section" id="assert-capability-and-assert-shared-capability">
+<h3>ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...)<a class="headerlink" href="#assert-capability-and-assert-shared-capability" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Previously:</em>  <tt class="docutils literal"><span class="pre">ASSERT_EXCLUSIVE_LOCK</span></tt>, <tt class="docutils literal"><span class="pre">ASSERT_SHARED_LOCK</span></tt></p>
+<p>These are attributes on a function or method that does a run-time test to see
+whether the calling thread holds the given capability.  The function is assumed
+to fail (no return) if the capability is not held.  See <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>,
+below, for example uses.</p>
+</div>
+<div class="section" id="guarded-var-and-pt-guarded-var">
+<h3>GUARDED_VAR and PT_GUARDED_VAR<a class="headerlink" href="#guarded-var-and-pt-guarded-var" title="Permalink to this headline">Â¶</a></h3>
+<p>Use of these attributes has been deprecated.</p>
+</div>
+<div class="section" id="warning-flags">
+<h3>Warning flags<a class="headerlink" href="#warning-flags" title="Permalink to this headline">Â¶</a></h3>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety</span></tt>:  Umbrella flag which turns on the following three:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-attributes</span></tt>: Sanity checks on attribute syntax.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-analysis</span></tt>: The core analysis.</p>
+</li>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal"><span class="pre">-Wthread-safety-precise</span></tt>: Requires that mutex expressions match precisely.</dt>
+<dd><p class="first last">This warning can be disabled for code which has a lot of aliases.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-reference</span></tt>: Checks when guarded members are passed by reference.</p>
+</li>
+</ul>
+</li>
+</ul>
+<p><a class="reference internal" href="#negative"><em>Negative Capabilities</em></a> are an experimental feature, which are enabled with:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wthread-safety-negative</span></tt>:  Negative capabilities.  Off by default.</li>
+</ul>
+<p>When new features and checks are added to the analysis, they can often introduce
+additional warnings.  Those warnings are initially released as <em>beta</em> warnings
+for a period of time, after which they are migrated into the standard analysis.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wthread-safety-beta</span></tt>:  New features.  Off by default.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="negative-capabilities">
+<span id="negative"></span><h2>Negative Capabilities<a class="headerlink" href="#negative-capabilities" title="Permalink to this headline">Â¶</a></h2>
+<p>Thread Safety Analysis is designed to prevent both race conditions and
+deadlock.  The GUARDED_BY and REQUIRES attributes prevent race conditions, by
+ensuring that a capability is held before reading or writing to guarded data,
+and the EXCLUDES attribute prevents deadlock, by making sure that a mutex is
+<em>not</em> held.</p>
+<p>However, EXCLUDES is an optional attribute, and does not provide the same
+safety guarantee as REQUIRES.  In particular:</p>
+<blockquote>
+<div><ul class="simple">
+<li>A function which acquires a capability does not have to exclude it.</li>
+<li>A function which calls a function that excludes a capability does not
+have transitively exclude that capability.</li>
+</ul>
+</div></blockquote>
+<p>As a result, EXCLUDES can easily produce false negatives:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+  <span class="n">Mutex</span> <span class="n">mu</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">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+    <span class="n">bar</span><span class="p">();</span>           <span class="c1">// No warning.</span>
+    <span class="n">baz</span><span class="p">();</span>           <span class="c1">// No warning.</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+  <span class="p">}</span>
+
+  <span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span>       <span class="c1">// No warning.  (Should have EXCLUDES(mu)).</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+    <span class="c1">// ...</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+  <span class="p">}</span>
+
+  <span class="kt">void</span> <span class="nf">baz</span><span class="p">()</span> <span class="p">{</span>
+    <span class="n">bif</span><span class="p">();</span>           <span class="c1">// No warning.  (Should have EXCLUDES(mu)).</span>
+  <span class="p">}</span>
+
+  <span class="kt">void</span> <span class="nf">bif</span><span class="p">()</span> <span class="n">EXCLUDES</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Negative requirements are an alternative EXCLUDES that provide
+a stronger safety guarantee.  A negative requirement uses the  REQUIRES
+attribute, in conjunction with the <tt class="docutils literal"><span class="pre">!</span></tt> operator, to indicate that a capability
+should <em>not</em> be held.</p>
+<p>For example, using <tt class="docutils literal"><span class="pre">REQUIRES(!mu)</span></tt> instead of <tt class="docutils literal"><span class="pre">EXCLUDES(mu)</span></tt> will produce
+the appropriate warnings:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">FooNeg</span> <span class="p">{</span>
+  <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+  <span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="o">!</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>   <span class="c1">// foo() now requires !mu.</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+    <span class="n">bar</span><span class="p">();</span>
+    <span class="n">baz</span><span class="p">();</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+  <span class="p">}</span>
+
+  <span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>       <span class="c1">// WARNING!  Missing REQUIRES(!mu).</span>
+    <span class="c1">// ...</span>
+    <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+  <span class="p">}</span>
+
+  <span class="kt">void</span> <span class="nf">baz</span><span class="p">()</span> <span class="p">{</span>
+    <span class="n">bif</span><span class="p">();</span>           <span class="c1">// WARNING!  Missing REQUIRES(!mu).</span>
+  <span class="p">}</span>
+
+  <span class="kt">void</span> <span class="nf">bif</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="o">!</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Negative requirements are an experimental feature which is off by default,
+because it will produce many warnings in existing code.  It can be enabled
+by passing <tt class="docutils literal"><span class="pre">-Wthread-safety-negative</span></tt>.</p>
+</div>
+<div class="section" id="frequently-asked-questions">
+<span id="faq"></span><h2>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">Â¶</a></h2>
+<ol class="upperalpha simple" start="17">
+<li>Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?</li>
+</ol>
+<p>(A) Attributes are part of the formal interface of a function, and should
+always go in the header, where they are visible to anything that includes
+the header.  Attributes in the .cpp file are not visible outside of the
+immediate translation unit, which leads to false negatives and false positives.</p>
+<ol class="upperalpha simple" start="17">
+<li>“<em>Mutex is not locked on every path through here?</em>”  What does that mean?</li>
+</ol>
+<ol class="upperalpha simple">
+<li>See <a class="reference internal" href="#conditional-locks"><em>No conditionally held locks.</em></a>, below.</li>
+</ol>
+</div>
+<div class="section" id="known-limitations">
+<span id="limitations"></span><h2>Known Limitations<a class="headerlink" href="#known-limitations" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="lexical-scope">
+<h3>Lexical scope<a class="headerlink" href="#lexical-scope" title="Permalink to this headline">Â¶</a></h3>
+<p>Thread safety attributes contain ordinary C++ expressions, and thus follow
+ordinary C++ scoping rules.  In particular, this means that mutexes and other
+capabilities must be declared before they can be used in an attribute.
+Use-before-declaration is okay within a single class, because attributes are
+parsed at the same time as method bodies. (C++ delays parsing of method bodies
+until the end of the class.)  However, use-before-declaration is not allowed
+between classes, as illustrated below.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span><span class="p">;</span>
+
+<span class="k">class</span> <span class="nc">Bar</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">f</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">f</span><span class="o">-></span><span class="n">mu</span><span class="p">);</span>  <span class="c1">// Error: mu undeclared.</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+  <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="private-mutexes">
+<h3>Private Mutexes<a class="headerlink" href="#private-mutexes" title="Permalink to this headline">Â¶</a></h3>
+<p>Good software engineering practice dictates that mutexes should be private
+members, because the locking mechanism used by a thread-safe class is part of
+its internal implementation.  However, private mutexes can sometimes leak into
+the public interface of a class.
+Thread safety attributes follow normal C++ access restrictions, so if <tt class="docutils literal"><span class="pre">mu</span></tt>
+is a private member of <tt class="docutils literal"><span class="pre">c</span></tt>, then it is an error to write <tt class="docutils literal"><span class="pre">c.mu</span></tt> in an
+attribute.</p>
+<p>One workaround is to (ab)use the <tt class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></tt> attribute to provide a
+public <em>name</em> for a private mutex, without actually exposing the underlying
+mutex.  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="nl">private:</span>
+  <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+  <span class="c1">// For thread safety analysis only.  Does not actually return mu.</span>
+  <span class="n">Mutex</span><span class="o">*</span> <span class="nf">getMu</span><span class="p">()</span> <span class="n">RETURN_CAPABILITY</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> <span class="p">}</span>
+
+  <span class="kt">void</span> <span class="nf">doSomething</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">doSomethingTwice</span><span class="p">(</span><span class="n">MyClass</span><span class="o">&</span> <span class="n">c</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">c</span><span class="p">.</span><span class="n">getMu</span><span class="p">())</span> <span class="p">{</span>
+  <span class="c1">// The analysis thinks that c.getMu() == c.mu</span>
+  <span class="n">c</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+  <span class="n">c</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In the above example, <tt class="docutils literal"><span class="pre">doSomethingTwice()</span></tt> is an external routine that
+requires <tt class="docutils literal"><span class="pre">c.mu</span></tt> to be locked, which cannot be declared directly because <tt class="docutils literal"><span class="pre">mu</span></tt>
+is private.  This pattern is discouraged because it
+violates encapsulation, but it is sometimes necessary, especially when adding
+annotations to an existing code base.  The workaround is to define <tt class="docutils literal"><span class="pre">getMu()</span></tt>
+as a fake getter method, which is provided only for the benefit of thread
+safety analysis.</p>
+</div>
+<div class="section" id="no-conditionally-held-locks">
+<span id="conditional-locks"></span><h3>No conditionally held locks.<a class="headerlink" href="#no-conditionally-held-locks" title="Permalink to this headline">Â¶</a></h3>
+<p>The analysis must be able to determine whether a lock is held, or not held, at
+every program point.  Thus, sections of code where a lock <em>might be held</em> will
+generate spurious warnings (false positives).  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">bool</span> <span class="n">b</span> <span class="o">=</span> <span class="n">needsToLock</span><span class="p">();</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+  <span class="p">...</span>  <span class="c1">// Warning!  Mutex 'mu' is not held on every path through here.</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="no-checking-inside-constructors-and-destructors">
+<h3>No checking inside constructors and destructors.<a class="headerlink" href="#no-checking-inside-constructors-and-destructors" title="Permalink to this headline">Â¶</a></h3>
+<p>The analysis currently does not do any checking inside constructors or
+destructors.  In other words, every constructor and destructor is treated as
+if it was annotated with <tt class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></tt>.
+The reason for this is that during initialization, only one thread typically
+has access to the object which is being initialized, and it is thus safe (and
+common practice) to initialize guarded members without acquiring any locks.
+The same is true of destructors.</p>
+<p>Ideally, the analysis would allow initialization of guarded members inside the
+object being initialized or destroyed, while still enforcing the usual access
+restrictions on everything else.  However, this is difficult to enforce in
+practice, because in complex pointer-based data structures, it is hard to
+determine what data is owned by the enclosing object.</p>
+</div>
+<div class="section" id="no-inlining">
+<h3>No inlining.<a class="headerlink" href="#no-inlining" title="Permalink to this headline">Â¶</a></h3>
+<p>Thread safety analysis is strictly intra-procedural, just like ordinary type
+checking.  It relies only on the declared attributes of a function, and will
+not attempt to inline any method calls.  As a result, code such as the
+following will not work:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">AutoCleanup</span> <span class="p">{</span>
+  <span class="n">T</span><span class="o">*</span> <span class="n">object</span><span class="p">;</span>
+  <span class="kt">void</span> <span class="p">(</span><span class="n">T</span><span class="o">::*</span><span class="n">mp</span><span class="p">)();</span>
+
+<span class="nl">public:</span>
+  <span class="n">AutoCleanup</span><span class="p">(</span><span class="n">T</span><span class="o">*</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">void</span> <span class="p">(</span><span class="n">T</span><span class="o">::*</span><span class="n">imp</span><span class="p">)())</span> <span class="o">:</span> <span class="n">object</span><span class="p">(</span><span class="n">obj</span><span class="p">),</span> <span class="n">mp</span><span class="p">(</span><span class="n">imp</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
+  <span class="o">~</span><span class="n">AutoCleanup</span><span class="p">()</span> <span class="p">{</span> <span class="p">(</span><span class="n">object</span><span class="o">->*</span><span class="n">mp</span><span class="p">)();</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="n">Mutex</span> <span class="n">mu</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">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+  <span class="n">AutoCleanup</span><span class="o"><</span><span class="n">Mutex</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">mu</span><span class="p">,</span> <span class="o">&</span><span class="n">Mutex</span><span class="o">::</span><span class="n">Unlock</span><span class="p">);</span>
+  <span class="c1">// ...</span>
+<span class="p">}</span>  <span class="c1">// Warning, mu is not unlocked.</span>
+</pre></div>
+</div>
+<p>In this case, the destructor of <tt class="docutils literal"><span class="pre">Autocleanup</span></tt> calls <tt class="docutils literal"><span class="pre">mu.Unlock()</span></tt>, so
+the warning is bogus.  However,
+thread safety analysis cannot see the unlock, because it does not attempt to
+inline the destructor.  Moreover, there is no way to annotate the destructor,
+because the destructor is calling a function that is not statically known.
+This pattern is simply not supported.</p>
+</div>
+<div class="section" id="no-alias-analysis">
+<h3>No alias analysis.<a class="headerlink" href="#no-alias-analysis" title="Permalink to this headline">Â¶</a></h3>
+<p>The analysis currently does not track pointer aliases.  Thus, there can be
+false positives if two pointers both point to the same mutex.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MutexUnlocker</span> <span class="p">{</span>
+  <span class="n">Mutex</span><span class="o">*</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+  <span class="n">MutexUnlocker</span><span class="p">(</span><span class="n">Mutex</span><span class="o">*</span> <span class="n">m</span><span class="p">)</span> <span class="n">RELEASE</span><span class="p">(</span><span class="n">m</span><span class="p">)</span> <span class="o">:</span> <span class="n">mu</span><span class="p">(</span><span class="n">m</span><span class="p">)</span>  <span class="p">{</span> <span class="n">mu</span><span class="o">-></span><span class="n">Unlock</span><span class="p">();</span> <span class="p">}</span>
+  <span class="o">~</span><span class="n">MutexUnlocker</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="n">mu</span><span class="o">-></span><span class="n">Lock</span><span class="p">();</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="n">Mutex</span> <span class="n">mutex</span><span class="p">;</span>
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mutex</span><span class="p">)</span> <span class="p">{</span>
+  <span class="p">{</span>
+    <span class="n">MutexUnlocker</span> <span class="n">munl</span><span class="p">(</span><span class="o">&</span><span class="n">mutex</span><span class="p">);</span>  <span class="c1">// unlocks mutex</span>
+    <span class="n">doSomeIO</span><span class="p">();</span>
+  <span class="p">}</span>                              <span class="c1">// Warning: locks munl.mu</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The MutexUnlocker class is intended to be the dual of the MutexLocker class,
+defined in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>.  However, it doesn’t work because the analysis
+doesn’t know that munl.mu == mutex.  The SCOPED_CAPABILITY attribute handles
+aliasing for MutexLocker, but does so only for that particular pattern.</p>
+</div>
+<div class="section" id="acquired-before-and-acquired-after-are-currently-unimplemented">
+<h3>ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.<a class="headerlink" href="#acquired-before-and-acquired-after-are-currently-unimplemented" title="Permalink to this headline">Â¶</a></h3>
+<p>To be fixed in a future update.</p>
+</div>
+</div>
+<div class="section" id="mutex-h">
+<span id="mutexheader"></span><h2>mutex.h<a class="headerlink" href="#mutex-h" title="Permalink to this headline">Â¶</a></h2>
+<p>Thread safety analysis can be used with any threading library, but it does
+require that the threading API be wrapped in classes and methods which have the
+appropriate annotations.  The following code provides <tt class="docutils literal"><span class="pre">mutex.h</span></tt> as an example;
+these methods should be filled in to call the appropriate underlying
+implementation.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+<span class="cp">#define THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+
+<span class="c1">// Enable thread safety attributes only with clang.</span>
+<span class="c1">// The attributes can be safely erased when compiling with other compilers.</span>
+<span class="cp">#if defined(__clang__) && (!defined(SWIG))</span>
+<span class="cp">#define THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))</span>
+<span class="cp">#else</span>
+<span class="cp">#define THREAD_ANNOTATION_ATTRIBUTE__(x)   </span><span class="c1">// no-op</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#define THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))</span>
+
+<span class="cp">#define CAPABILITY(x) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(capability(x))</span>
+
+<span class="cp">#define SCOPED_CAPABILITY \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)</span>
+
+<span class="cp">#define GUARDED_BY(x) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))</span>
+
+<span class="cp">#define PT_GUARDED_BY(x) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))</span>
+
+<span class="cp">#define ACQUIRED_BEFORE(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRED_AFTER(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))</span>
+
+<span class="cp">#define REQUIRES(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define REQUIRES_SHARED(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRE(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRE_SHARED(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define RELEASE(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define RELEASE_SHARED(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define TRY_ACQUIRE(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define TRY_ACQUIRE_SHARED(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define EXCLUDES(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))</span>
+
+<span class="cp">#define ASSERT_CAPABILITY(x) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))</span>
+
+<span class="cp">#define ASSERT_SHARED_CAPABILITY(x) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))</span>
+
+<span class="cp">#define RETURN_CAPABILITY(x) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))</span>
+
+<span class="cp">#define NO_THREAD_SAFETY_ANALYSIS \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)</span>
+
+
+<span class="c1">// Defines an annotated interface for mutexes.</span>
+<span class="c1">// These methods can be implemented to use any internal mutex implementation.</span>
+<span class="k">class</span> <span class="nf">CAPABILITY</span><span class="p">(</span><span class="s">"mutex"</span><span class="p">)</span> <span class="n">Mutex</span> <span class="p">{</span>
+<span class="nl">public:</span>
+  <span class="c1">// Acquire/lock this mutex exclusively.  Only one thread can have exclusive</span>
+  <span class="c1">// access at any one time.  Write operations to guarded data require an</span>
+  <span class="c1">// exclusive lock.</span>
+  <span class="kt">void</span> <span class="n">Lock</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">();</span>
+
+  <span class="c1">// Acquire/lock this mutex for read operations, which require only a shared</span>
+  <span class="c1">// lock.  This assumes a multiple-reader, single writer semantics.  Multiple</span>
+  <span class="c1">// threads may acquire the mutex simultaneously as readers, but a writer</span>
+  <span class="c1">// must wait for all of them to release the mutex before it can acquire it</span>
+  <span class="c1">// exclusively.</span>
+  <span class="kt">void</span> <span class="nf">ReaderLock</span><span class="p">()</span> <span class="n">ACQUIRE_SHARED</span><span class="p">();</span>
+
+  <span class="c1">// Release/unlock an exclusive mutex.</span>
+  <span class="kt">void</span> <span class="nf">Unlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">();</span>
+
+  <span class="c1">// Release/unlock a shared mutex.</span>
+  <span class="kt">void</span> <span class="nf">ReaderUnlock</span><span class="p">()</span> <span class="n">RELEASE_SHARED</span><span class="p">();</span>
+
+  <span class="c1">// Try to acquire the mutex.  Returns true on success, and false on failure.</span>
+  <span class="kt">bool</span> <span class="nf">TryLock</span><span class="p">()</span> <span class="n">TRY_ACQUIRE</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span>
+
+  <span class="c1">// Try to acquire the mutex for read operations.</span>
+  <span class="kt">bool</span> <span class="nf">ReaderTryLock</span><span class="p">()</span> <span class="n">TRY_ACQUIRE_SHARED</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span>
+
+  <span class="c1">// Assert that this mutex is currently held by the calling thread.</span>
+  <span class="kt">void</span> <span class="nf">AssertHeld</span><span class="p">()</span> <span class="n">ASSERT_CAPABILITY</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
+
+  <span class="c1">// Assert that is mutex is currently held for read operations.</span>
+  <span class="kt">void</span> <span class="nf">AssertReaderHeld</span><span class="p">()</span> <span class="n">ASSERT_SHARED_CAPABILITY</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
+
+  <span class="c1">// For negative capabilities.</span>
+  <span class="k">const</span> <span class="n">Mutex</span><span class="o">&</span> <span class="k">operator</span><span class="o">!</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">this</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+
+
+<span class="c1">// MutexLocker is an RAII class that acquires a mutex in its constructor, and</span>
+<span class="c1">// releases it in its destructor.</span>
+<span class="k">class</span> <span class="nc">SCOPED_CAPABILITY</span> <span class="n">MutexLocker</span> <span class="p">{</span>
+<span class="nl">private:</span>
+  <span class="n">Mutex</span><span class="o">*</span> <span class="n">mut</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+  <span class="n">MutexLocker</span><span class="p">(</span><span class="n">Mutex</span> <span class="o">*</span><span class="n">mu</span><span class="p">)</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="o">:</span> <span class="n">mut</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">mu</span><span class="o">-></span><span class="n">Lock</span><span class="p">();</span>
+  <span class="p">}</span>
+  <span class="o">~</span><span class="n">MutexLocker</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">()</span> <span class="p">{</span>
+    <span class="n">mut</span><span class="o">-></span><span class="n">Unlock</span><span class="p">();</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+
+
+<span class="cp">#ifdef USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES</span>
+<span class="c1">// The original version of thread safety analysis the following attribute</span>
+<span class="c1">// definitions.  These use a lock-based terminology.  They are still in use</span>
+<span class="c1">// by existing thread safety code, and will continue to be supported.</span>
+
+<span class="c1">// Deprecated.</span>
+<span class="cp">#define PT_GUARDED_VAR \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded)</span>
+
+<span class="c1">// Deprecated.</span>
+<span class="cp">#define GUARDED_VAR \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(guarded)</span>
+
+<span class="c1">// Replaced by REQUIRES</span>
+<span class="cp">#define EXCLUSIVE_LOCKS_REQUIRED(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by REQUIRES_SHARED</span>
+<span class="cp">#define SHARED_LOCKS_REQUIRED(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by CAPABILITY</span>
+<span class="cp">#define LOCKABLE \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(lockable)</span>
+
+<span class="c1">// Replaced by SCOPED_CAPABILITY</span>
+<span class="cp">#define SCOPED_LOCKABLE \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)</span>
+
+<span class="c1">// Replaced by ACQUIRE</span>
+<span class="cp">#define EXCLUSIVE_LOCK_FUNCTION(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ACQUIRE_SHARED</span>
+<span class="cp">#define SHARED_LOCK_FUNCTION(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by RELEASE and RELEASE_SHARED</span>
+<span class="cp">#define UNLOCK_FUNCTION(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by TRY_ACQUIRE</span>
+<span class="cp">#define EXCLUSIVE_TRYLOCK_FUNCTION(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by TRY_ACQUIRE_SHARED</span>
+<span class="cp">#define SHARED_TRYLOCK_FUNCTION(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ASSERT_CAPABILITY</span>
+<span class="cp">#define ASSERT_EXCLUSIVE_LOCK(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ASSERT_SHARED_CAPABILITY</span>
+<span class="cp">#define ASSERT_SHARED_LOCK(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by EXCLUDE_CAPABILITY.</span>
+<span class="cp">#define LOCKS_EXCLUDED(...) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by RETURN_CAPABILITY</span>
+<span class="cp">#define LOCK_RETURNED(x) \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))</span>
+
+<span class="cp">#endif  </span><span class="c1">// USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES</span>
+
+<span class="cp">#endif  </span><span class="c1">// THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="CrossCompilation.html">Cross-compilation using Clang</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AddressSanitizer.html">AddressSanitizer</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/ThreadSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/ThreadSanitizer.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/ThreadSanitizer.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/ThreadSanitizer.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,195 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>ThreadSanitizer — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="MemorySanitizer" href="MemorySanitizer.html" />
+    <link rel="prev" title="AddressSanitizer" href="AddressSanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>ThreadSanitizer</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="AddressSanitizer.html">AddressSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="MemorySanitizer.html">MemorySanitizer</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="threadsanitizer">
+<h1>ThreadSanitizer<a class="headerlink" href="#threadsanitizer" 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>ThreadSanitizer is a tool that detects data races.  It consists of a compiler
+instrumentation module and a run-time library.  Typical slowdown introduced by
+ThreadSanitizer is about <strong>5x-15x</strong>.  Typical memory overhead introduced by
+ThreadSanitizer is about <strong>5x-10x</strong>.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2>How to build<a class="headerlink" href="#how-to-build" title="Permalink to this headline">Â¶</a></h2>
+<p>Build LLVM/Clang with <a class="reference external" href="http://llvm.org/docs/CMake.html">CMake</a>.</p>
+</div>
+<div class="section" id="supported-platforms">
+<h2>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Permalink to this headline">Â¶</a></h2>
+<p>ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
+Support for other 64-bit architectures is possible, contributions are welcome.
+Support for 32-bit platforms is problematic and is not planned.</p>
+</div>
+<div class="section" id="usage">
+<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">Â¶</a></h2>
+<p>Simply compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>.  To get a
+reasonable performance add <tt class="docutils literal"><span class="pre">-O1</span></tt> or higher.  Use <tt class="docutils literal"><span class="pre">-g</span></tt> to get file names
+and line numbers in the warning messages.</p>
+<p>Example:</p>
+<div class="highlight-c++"><div class="highlight"><pre>% cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c
+#include <pthread.h>
+int Global;
+void *Thread1(void *x) {
+  Global = 42;
+  return x;
+}
+int main() {
+  pthread_t t;
+  pthread_create(&t, NULL, Thread1, NULL);
+  Global = 43;
+  pthread_join(t, NULL);
+  return Global;
+}
+
+$ clang -fsanitize=thread -g -O1 tiny_race.c
+</pre></div>
+</div>
+<p>If a bug is detected, the program will print an error message to stderr.
+Currently, ThreadSanitizer symbolizes its output using an external
+<tt class="docutils literal"><span class="pre">addr2line</span></tt> process (this will be fixed in future).</p>
+<div class="highlight-bash"><div class="highlight"><pre>% ./a.out
+WARNING: ThreadSanitizer: data race <span class="o">(</span><span class="nv">pid</span><span class="o">=</span>19219<span class="o">)</span>
+  Write of size 4 at 0x7fcf47b21bc0 by thread T1:
+    <span class="c">#0 Thread1 tiny_race.c:4 (exe+0x00000000a360)</span>
+
+  Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
+    <span class="c">#0 main tiny_race.c:10 (exe+0x00000000a3b4)</span>
+
+  Thread T1 <span class="o">(</span>running<span class="o">)</span> created at:
+    <span class="c">#0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)</span>
+    <span class="c">#1 main tiny_race.c:9 (exe+0x00000000a3a4)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-feature-thread-sanitizer">
+<h2><tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt><a class="headerlink" href="#has-feature-thread-sanitizer" title="Permalink to this headline">Â¶</a></h2>
+<p>In some cases one may need to execute different code depending on whether
+ThreadSanitizer is enabled.
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>__has_feature</em></a> can be used for
+this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(__has_feature)</span>
+<span class="cp">#  if __has_feature(thread_sanitizer)</span>
+<span class="c1">// code that builds only under ThreadSanitizer</span>
+<span class="cp">#  endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-thread">
+<h2><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_thread))</span></tt><a class="headerlink" href="#attribute-no-sanitize-thread" title="Permalink to this headline">Â¶</a></h2>
+<p>Some code should not be instrumented by ThreadSanitizer.
+One may use the function attribute
+<a class="reference internal" href="AttributeReference.html#langext-thread-sanitizer"><em>no_sanitize_thread</em></a>
+to disable instrumentation of plain (non-atomic) loads/stores in a particular function.
+ThreadSanitizer still instruments such functions to avoid false positives and
+provide meaningful stack traces.
+This attribute may not be
+supported by other compilers, so we suggest to use it together with
+<tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt>.</p>
+</div>
+<div class="section" id="blacklist">
+<h2>Blacklist<a class="headerlink" href="#blacklist" title="Permalink to this headline">Â¶</a></h2>
+<p>ThreadSanitizer supports <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to suppress data race reports in
+the specified source files or functions. Unlike functions marked with
+<a class="reference internal" href="AttributeReference.html#langext-thread-sanitizer"><em>no_sanitize_thread</em></a> attribute,
+blacklisted functions are not instrumented at all. This can lead to false positives
+due to missed synchronization via atomic operations and missed stack frames in reports.</p>
+</div>
+<div class="section" id="limitations">
+<h2>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">Â¶</a></h2>
+<ul class="simple">
+<li>ThreadSanitizer uses more real memory than a native run. At the default
+settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x
+(less accurate analysis) and 9x (more accurate analysis) overhead are also
+available.</li>
+<li>ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
+This means that tools like <tt class="docutils literal"><span class="pre">ulimit</span></tt> may not work as usually expected.</li>
+<li>Libc/libstdc++ static linking is not supported.</li>
+<li>Non-position-independent executables are not supported.  Therefore, the
+<tt class="docutils literal"><span class="pre">fsanitize=thread</span></tt> flag will cause Clang to act as though the <tt class="docutils literal"><span class="pre">-fPIE</span></tt>
+flag had been supplied if compiling without <tt class="docutils literal"><span class="pre">-fPIC</span></tt>, and as though the
+<tt class="docutils literal"><span class="pre">-pie</span></tt> flag had been supplied if linking an executable.</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this headline">Â¶</a></h2>
+<p>ThreadSanitizer is in beta stage.  It is known to work on large C++ programs
+using pthreads, but we do not promise anything (yet).  C++11 threading is
+supported with llvm libc++.  The test suite is integrated into CMake build
+and can be run with <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-tsan</span></tt> command.</p>
+<p>We are actively working on enhancing the tool — stay tuned.  Any help,
+especially in the form of minimized standalone tests is more than welcome.</p>
+</div>
+<div class="section" id="more-information">
+<h2>More Information<a class="headerlink" href="#more-information" title="Permalink to this headline">Â¶</a></h2>
+<p><a class="reference external" href="http://code.google.com/p/thread-sanitizer/">http://code.google.com/p/thread-sanitizer</a>.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="AddressSanitizer.html">AddressSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="MemorySanitizer.html">MemorySanitizer</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/Tooling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/Tooling.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/Tooling.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/Tooling.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,162 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Choosing the Right Interface for Your Application — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="External Clang Examples" href="ExternalClangExamples.html" />
+    <link rel="prev" title="Frequently Asked Questions (FAQ)" href="FAQ.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Choosing the Right Interface for Your Application</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="FAQ.html">Frequently Asked Questions (FAQ)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ExternalClangExamples.html">External Clang Examples</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="choosing-the-right-interface-for-your-application">
+<h1>Choosing the Right Interface for Your Application<a class="headerlink" href="#choosing-the-right-interface-for-your-application" title="Permalink to this headline">Â¶</a></h1>
+<p>Clang provides infrastructure to write tools that need syntactic and semantic
+information about a program.  This document will give a short introduction of
+the different ways to write clang tools, and their pros and cons.</p>
+<div class="section" id="libclang">
+<h2>LibClang<a class="headerlink" href="#libclang" title="Permalink to this headline">Â¶</a></h2>
+<p><a class="reference external" href="http://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a> is a stable high
+level C interface to clang.  When in doubt LibClang is probably the interface
+you want to use.  Consider the other interfaces only when you have a good
+reason not to use LibClang.</p>
+<p>Canonical examples of when to use LibClang:</p>
+<ul class="simple">
+<li>Xcode</li>
+<li>Clang Python Bindings</li>
+</ul>
+<p>Use LibClang when you...:</p>
+<ul class="simple">
+<li>want to interface with clang from other languages than C++</li>
+<li>need a stable interface that takes care to be backwards compatible</li>
+<li>want powerful high-level abstractions, like iterating through an AST with a
+cursor, and don’t want to learn all the nitty gritty details of Clang’s AST.</li>
+</ul>
+<p>Do not use LibClang when you...:</p>
+<ul class="simple">
+<li>want full control over the Clang AST</li>
+</ul>
+</div>
+<div class="section" id="clang-plugins">
+<h2>Clang Plugins<a class="headerlink" href="#clang-plugins" title="Permalink to this headline">Â¶</a></h2>
+<p><a class="reference internal" href="ClangPlugins.html"><em>Clang Plugins</em></a> allow you to run additional actions on the
+AST as part of a compilation.  Plugins are dynamic libraries that are loaded at
+runtime by the compiler, and they’re easy to integrate into your build
+environment.</p>
+<p>Canonical examples of when to use Clang Plugins:</p>
+<ul class="simple">
+<li>special lint-style warnings or errors for your project</li>
+<li>creating additional build artifacts from a single compile step</li>
+</ul>
+<p>Use Clang Plugins when you...:</p>
+<ul class="simple">
+<li>need your tool to rerun if any of the dependencies change</li>
+<li>want your tool to make or break a build</li>
+<li>need full control over the Clang AST</li>
+</ul>
+<p>Do not use Clang Plugins when you...:</p>
+<ul class="simple">
+<li>want to run tools outside of your build environment</li>
+<li>want full control on how Clang is set up, including mapping of in-memory
+virtual files</li>
+<li>need to run over a specific subset of files in your project which is not
+necessarily related to any changes which would trigger rebuilds</li>
+</ul>
+</div>
+<div class="section" id="libtooling">
+<h2>LibTooling<a class="headerlink" href="#libtooling" title="Permalink to this headline">Â¶</a></h2>
+<p><a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> is a C++ interface aimed at writing standalone
+tools, as well as integrating into services that run clang tools.  Canonical
+examples of when to use LibTooling:</p>
+<ul class="simple">
+<li>a simple syntax checker</li>
+<li>refactoring tools</li>
+</ul>
+<p>Use LibTooling when you...:</p>
+<ul class="simple">
+<li>want to run tools over a single file, or a specific subset of files,
+independently of the build system</li>
+<li>want full control over the Clang AST</li>
+<li>want to share code with Clang Plugins</li>
+</ul>
+<p>Do not use LibTooling when you...:</p>
+<ul class="simple">
+<li>want to run as part of the build triggered by dependency changes</li>
+<li>want a stable interface so you don’t need to change your code when the AST API
+changes</li>
+<li>want high level abstractions like cursors and code completion out of the box</li>
+<li>do not want to write your tools in C++</li>
+</ul>
+<p><a class="reference internal" href="ClangTools.html"><em>Clang tools</em></a> are a collection of specific developer tools
+built on top of the LibTooling infrastructure as part of the Clang project.
+They are targeted at automating and improving core development activities of
+C/C++ developers.</p>
+<p>Examples of tools we are building or planning as part of the Clang project:</p>
+<ul class="simple">
+<li>Syntax checking (<strong class="program">clang-check</strong>)</li>
+<li>Automatic fixing of compile errors (<strong class="program">clang-fixit</strong>)</li>
+<li>Automatic code formatting (<strong class="program">clang-format</strong>)</li>
+<li>Migration tools for new features in new language standards</li>
+<li>Core refactoring tools</li>
+</ul>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="FAQ.html">Frequently Asked Questions (FAQ)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ExternalClangExamples.html">External Clang Examples</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/UsersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/UsersManual.html?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/UsersManual.html (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/UsersManual.html Tue Sep  1 15:55:31 2015
@@ -0,0 +1,2136 @@
+<!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="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Clang Compiler Userâs Manual — Clang 3.7 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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.7',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </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="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.7 documentation" href="index.html" />
+    <link rel="next" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="prev" title="Clang 3.7 Release Notes" href="ReleaseNotes.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.7 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang Compiler Userâs Manual</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ReleaseNotes.html">Clang 3.7 Release Notes</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LanguageExtensions.html">Clang Language Extensions</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-compiler-user-s-manual">
+<h1>Clang Compiler User’s Manual<a class="headerlink" href="#clang-compiler-user-s-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="id7">Introduction</a><ul>
+<li><a class="reference internal" href="#terminology" id="id8">Terminology</a></li>
+<li><a class="reference internal" href="#basic-usage" id="id9">Basic Usage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#command-line-options" id="id10">Command Line Options</a><ul>
+<li><a class="reference internal" href="#options-to-control-error-and-warning-messages" id="id11">Options to Control Error and Warning Messages</a><ul>
+<li><a class="reference internal" href="#formatting-of-diagnostics" id="id12">Formatting of Diagnostics</a></li>
+<li><a class="reference internal" href="#individual-warning-groups" id="id13">Individual Warning Groups</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#options-to-control-clang-crash-diagnostics" id="id14">Options to Control Clang Crash Diagnostics</a></li>
+<li><a class="reference internal" href="#options-to-emit-optimization-reports" id="id15">Options to Emit Optimization Reports</a><ul>
+<li><a class="reference internal" href="#current-limitations" id="id16">Current limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-options" id="id17">Other Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#language-and-target-independent-features" id="id18">Language and Target-Independent Features</a><ul>
+<li><a class="reference internal" href="#controlling-errors-and-warnings" id="id19">Controlling Errors and Warnings</a><ul>
+<li><a class="reference internal" href="#controlling-how-clang-displays-diagnostics" id="id20">Controlling How Clang Displays Diagnostics</a></li>
+<li><a class="reference internal" href="#diagnostic-mappings" id="id21">Diagnostic Mappings</a></li>
+<li><a class="reference internal" href="#diagnostic-categories" id="id22">Diagnostic Categories</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-command-line-flags" id="id23">Controlling Diagnostics via Command Line Flags</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-pragmas" id="id24">Controlling Diagnostics via Pragmas</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-in-system-headers" id="id25">Controlling Diagnostics in System Headers</a></li>
+<li><a class="reference internal" href="#enabling-all-diagnostics" id="id26">Enabling All Diagnostics</a></li>
+<li><a class="reference internal" href="#controlling-static-analyzer-diagnostics" id="id27">Controlling Static Analyzer Diagnostics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#precompiled-headers" id="id28">Precompiled Headers</a><ul>
+<li><a class="reference internal" href="#generating-a-pch-file" id="id29">Generating a PCH File</a></li>
+<li><a class="reference internal" href="#using-a-pch-file" id="id30">Using a PCH File</a></li>
+<li><a class="reference internal" href="#relocatable-pch-files" id="id31">Relocatable PCH Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-code-generation" id="id32">Controlling Code Generation</a></li>
+<li><a class="reference internal" href="#profile-guided-optimization" id="id33">Profile Guided Optimization</a><ul>
+<li><a class="reference internal" href="#differences-between-sampling-and-instrumentation" id="id34">Differences Between Sampling and Instrumentation</a></li>
+<li><a class="reference internal" href="#using-sampling-profilers" id="id35">Using Sampling Profilers</a><ul>
+<li><a class="reference internal" href="#sample-profile-formats" id="id36">Sample Profile Formats</a></li>
+<li><a class="reference internal" href="#sample-profile-text-format" id="id37">Sample Profile Text Format</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#profiling-with-instrumentation" id="id38">Profiling with Instrumentation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-size-of-debug-information" id="id39">Controlling Size of Debug Information</a></li>
+<li><a class="reference internal" href="#comment-parsing-options" id="id40">Comment Parsing Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-language-features" id="id41">C Language Features</a><ul>
+<li><a class="reference internal" href="#extensions-supported-by-clang" id="id42">Extensions supported by clang</a></li>
+<li><a class="reference internal" href="#differences-between-various-standard-modes" id="id43">Differences between various standard modes</a></li>
+<li><a class="reference internal" href="#gcc-extensions-not-implemented-yet" id="id44">GCC extensions not implemented yet</a></li>
+<li><a class="reference internal" href="#intentionally-unsupported-gcc-extensions" id="id45">Intentionally unsupported GCC extensions</a></li>
+<li><a class="reference internal" href="#microsoft-extensions" id="id46">Microsoft extensions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#cxx" id="id47">C++ Language Features</a><ul>
+<li><a class="reference internal" href="#controlling-implementation-limits" id="id48">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-language-features" id="id49">Objective-C Language Features</a></li>
+<li><a class="reference internal" href="#objcxx" id="id50">Objective-C++ Language Features</a></li>
+<li><a class="reference internal" href="#target-specific-features-and-limitations" id="id51">Target-Specific Features and Limitations</a><ul>
+<li><a class="reference internal" href="#cpu-architectures-features-and-limitations" id="id52">CPU Architectures Features and Limitations</a><ul>
+<li><a class="reference internal" href="#x86" id="id53">X86</a></li>
+<li><a class="reference internal" href="#arm" id="id54">ARM</a></li>
+<li><a class="reference internal" href="#powerpc" id="id55">PowerPC</a></li>
+<li><a class="reference internal" href="#other-platforms" id="id56">Other platforms</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#operating-system-features-and-limitations" id="id57">Operating System Features and Limitations</a><ul>
+<li><a class="reference internal" href="#darwin-mac-os-x" id="id58">Darwin (Mac OS X)</a></li>
+<li><a class="reference internal" href="#windows" id="id59">Windows</a><ul>
+<li><a class="reference internal" href="#cygwin" id="id60">Cygwin</a></li>
+<li><a class="reference internal" href="#mingw32" id="id61">MinGW32</a></li>
+<li><a class="reference internal" href="#mingw-w64" id="id62">MinGW-w64</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-cl" id="id63">clang-cl</a><ul>
+<li><a class="reference internal" href="#id6" id="id64">Command-Line Options</a><ul>
+<li><a class="reference internal" href="#the-fallback-option" id="id65">The /fallback Option</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id7">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>The Clang Compiler is an open-source compiler for the C family of
+programming languages, aiming to be the best in class implementation of
+these languages. Clang builds on the LLVM optimizer and code generator,
+allowing it to provide high-quality optimization and code generation
+support for many targets. For more general information, please see the
+<a class="reference external" href="http://clang.llvm.org">Clang Web Site</a> or the <a class="reference external" href="http://llvm.org">LLVM Web
+Site</a>.</p>
+<p>This document describes important notes about using Clang as a compiler
+for an end-user, documenting the supported features, command line
+options, etc. If you are interested in using Clang to build a tool that
+processes code, please see <a class="reference internal" href="InternalsManual.html"><em>“Clang” CFE Internals Manual</em></a>. If you are interested in the
+<a class="reference external" href="http://clang-analyzer.llvm.org">Clang Static Analyzer</a>, please see its web
+page.</p>
+<p>Clang is designed to support the C family of programming languages,
+which includes <a class="reference internal" href="#c"><em>C</em></a>, <a class="reference internal" href="#objc"><em>Objective-C</em></a>, <a class="reference internal" href="#cxx"><em>C++</em></a>, and
+<a class="reference internal" href="#objcxx"><em>Objective-C++</em></a> as well as many dialects of those. For
+language-specific information, please see the corresponding language
+specific section:</p>
+<ul class="simple">
+<li><a class="reference internal" href="#c"><em>C Language</em></a>: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
+C99 (+TC1, TC2, TC3).</li>
+<li><a class="reference internal" href="#objc"><em>Objective-C Language</em></a>: ObjC 1, ObjC 2, ObjC 2.1, plus
+variants depending on base language.</li>
+<li><a class="reference internal" href="#cxx"><em>C++ Language</em></a></li>
+<li><a class="reference internal" href="#objcxx"><em>Objective C++ Language</em></a></li>
+</ul>
+<p>In addition to these base languages and their dialects, Clang supports a
+broad variety of language extensions, which are documented in the
+corresponding language section. These extensions are provided to be
+compatible with the GCC, Microsoft, and other popular compilers as well
+as to improve functionality through Clang-specific features. The Clang
+driver and language features are intentionally designed to be as
+compatible with the GNU GCC compiler as reasonably possible, easing
+migration from GCC to Clang. In most cases, code “just works”.
+Clang also provides an alternative driver, <a class="reference internal" href="#clang-cl"><em>clang-cl</em></a>, that is designed
+to be compatible with the Visual C++ compiler, cl.exe.</p>
+<p>In addition to language specific features, Clang has a variety of
+features that depend on what CPU architecture or operating system is
+being compiled for. Please see the <a class="reference internal" href="#target-features"><em>Target-Specific Features and
+Limitations</em></a> section for more details.</p>
+<p>The rest of the introduction introduces some basic <a class="reference internal" href="#terminology"><em>compiler
+terminology</em></a> that is used throughout this manual and
+contains a basic <a class="reference internal" href="#basicusage"><em>introduction to using Clang</em></a> as a
+command line compiler.</p>
+<div class="section" id="terminology">
+<span id="id1"></span><h3><a class="toc-backref" href="#id8">Terminology</a><a class="headerlink" href="#terminology" title="Permalink to this headline">Â¶</a></h3>
+<p>Front end, parser, backend, preprocessor, undefined behavior,
+diagnostic, optimizer</p>
+</div>
+<div class="section" id="basic-usage">
+<span id="basicusage"></span><h3><a class="toc-backref" href="#id9">Basic Usage</a><a class="headerlink" href="#basic-usage" title="Permalink to this headline">Â¶</a></h3>
+<p>Intro to how to use a C compiler for newbies.</p>
+<p>compile + link compile then link debug info enabling optimizations
+picking a language to use, defaults to C11 by default. Autosenses based
+on extension. using a makefile</p>
+</div>
+</div>
+<div class="section" id="command-line-options">
+<h2><a class="toc-backref" href="#id10">Command Line Options</a><a class="headerlink" href="#command-line-options" title="Permalink to this headline">Â¶</a></h2>
+<p>This section is generally an index into other sections. It does not go
+into depth on the ones that are covered by other sections. However, the
+first part introduces the language selection and other high level
+options like <a class="reference internal" href="CommandGuide/clang.html#cmdoption-c"><em class="xref std std-option">-c</em></a>, <a class="reference internal" href="#cmdoption-g"><em class="xref std std-option">-g</em></a>, etc.</p>
+<div class="section" id="options-to-control-error-and-warning-messages">
+<h3><a class="toc-backref" href="#id11">Options to Control Error and Warning Messages</a><a class="headerlink" href="#options-to-control-error-and-warning-messages" title="Permalink to this headline">Â¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-Werror">
+<tt class="descname">-Werror</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Werror" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Turn warnings into errors.</p>
+</dd></dl>
+
+<p><tt class="docutils literal"><span class="pre">-Werror=foo</span></tt></p>
+<blockquote>
+<div>Turn warning “foo” into an error.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-Wno-error">
+<tt class="descname">-Wno-error</tt><tt class="descclassname">=foo</tt><a class="headerlink" href="#cmdoption-Wno-error" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Turn warning “foo” into an warning even if <a class="reference internal" href="#cmdoption-Werror"><em class="xref std std-option">-Werror</em></a> is specified.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wfoo">
+<tt class="descname">-Wfoo</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wfoo" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Enable warning “foo”.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wno-foo">
+<tt class="descname">-Wno-foo</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wno-foo" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Disable warning “foo”.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-w">
+<tt class="descname">-w</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-w" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Disable all diagnostics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Weverything">
+<tt class="descname">-Weverything</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Weverything" title="Permalink to this definition">Â¶</a></dt>
+<dd><p><a class="reference internal" href="#diagnostics-enable-everything"><em>Enable all diagnostics.</em></a></p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic">
+<tt class="descname">-pedantic</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pedantic" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Warn on language extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic-errors">
+<tt class="descname">-pedantic-errors</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pedantic-errors" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Error on language extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wsystem-headers">
+<tt class="descname">-Wsystem-headers</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wsystem-headers" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Enable warnings from system headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ferror-limit">
+<tt class="descname">-ferror-limit</tt><tt class="descclassname">=123</tt><a class="headerlink" href="#cmdoption-ferror-limit" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Stop emitting diagnostics after 123 errors have been produced. The default is
+20, and the error limit can be disabled with <em class="xref std std-option">-ferror-limit=0</em>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-backtrace-limit">
+<tt class="descname">-ftemplate-backtrace-limit</tt><tt class="descclassname">=123</tt><a class="headerlink" href="#cmdoption-ftemplate-backtrace-limit" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Only emit up to 123 template instantiation notes within the template
+instantiation backtrace for a single warning or error. The default is 10, and
+the limit can be disabled with <em class="xref std std-option">-ftemplate-backtrace-limit=0</em>.</p>
+</dd></dl>
+
+<div class="section" id="formatting-of-diagnostics">
+<span id="cl-diag-formatting"></span><h4><a class="toc-backref" href="#id12">Formatting of Diagnostics</a><a class="headerlink" href="#formatting-of-diagnostics" title="Permalink to this headline">Â¶</a></h4>
+<p>Clang aims to produce beautiful diagnostics by default, particularly for
+new users that first come to Clang. However, different people have
+different preferences, and sometimes Clang is driven by another program
+that wants to parse simple and consistent output, not a person. For
+these cases, Clang provides a wide range of options to control the exact
+output format of the diagnostics that it generates.</p>
+<dl class="docutils" id="opt-fshow-column">
+<dt><strong>-f[no-]show-column</strong></dt>
+<dd><p class="first">Print column number in diagnostic.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the column number of a diagnostic. For example, when this is
+enabled, Clang will print something like:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</pre></div>
+</div>
+<p>When this is disabled, Clang will print “test.c:28: warning...” with
+no column number.</p>
+<p class="last">The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fshow-source-location">
+<dt><strong>-f[no-]show-source-location</strong></dt>
+<dd><p class="first">Print source file/line/column information in diagnostic.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the filename, line number and column number of a diagnostic.
+For example, when this is enabled, Clang will print something like:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</pre></div>
+</div>
+<p class="last">When this is disabled, Clang will not print the “test.c:28:8: ”
+part.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fcaret-diagnostics">
+<dt><strong>-f[no-]caret-diagnostics</strong></dt>
+<dd><p class="first">Print source line and ranges from source code in diagnostic.
+This option, which defaults to on, controls whether or not Clang
+prints the source line, source ranges, and caret when emitting a
+diagnostic. For example, when this is enabled, Clang will print
+something like:</p>
+<div class="last highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</pre></div>
+</div>
+</dd>
+<dt><strong>-f[no-]color-diagnostics</strong></dt>
+<dd><p class="first">This option, which defaults to on when a color-capable terminal is
+detected, controls whether or not Clang prints diagnostics in color.</p>
+<p>When this option is enabled, Clang will use colors to highlight
+specific parts of the diagnostic, e.g.,</p>
+<pre>
+  <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b>
+  #endif bad
+         <span style="color:green">^</span>
+         <span style="color:green">//</span>
+</pre><p>When this is disabled, Clang will just print:</p>
+<div class="last highlight-python"><div class="highlight"><pre>test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</pre></div>
+</div>
+</dd>
+<dt><strong>-fansi-escape-codes</strong></dt>
+<dd>Controls whether ANSI escape codes are used instead of the Windows Console
+API to output colored diagnostics. This option is only used on Windows and
+defaults to off.</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-format">
+<tt class="descname">-fdiagnostics-format</tt><tt class="descclassname">=clang/msvc/vi</tt><a class="headerlink" href="#cmdoption-fdiagnostics-format" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Changes diagnostic output format to better match IDEs and command line tools.</p>
+<p>This option controls the output format of the filename, line number,
+and column printed in diagnostic messages. The options, and their
+affect on formatting a simple conversion diagnostic, follow:</p>
+<dl class="docutils">
+<dt><strong>clang</strong> (default)</dt>
+<dd><div class="first last highlight-python"><div class="highlight"><pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+</pre></div>
+</div>
+</dd>
+<dt><strong>msvc</strong></dt>
+<dd><div class="first last highlight-python"><div class="highlight"><pre>t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
+</pre></div>
+</div>
+</dd>
+<dt><strong>vi</strong></dt>
+<dd><div class="first last highlight-python"><div class="highlight"><pre>t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+</pre></div>
+</div>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="docutils" id="opt-fdiagnostics-show-option">
+<dt><strong>-f[no-]diagnostics-show-option</strong></dt>
+<dd><p class="first">Enable <tt class="docutils literal"><span class="pre">[-Woption]</span></tt> information in diagnostic line.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the associated <a class="reference internal" href="#cl-diag-warning-groups"><em>warning group</em></a>
+option name when outputting a warning diagnostic. For example, in
+this output:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</pre></div>
+</div>
+<p class="last">Passing <strong>-fno-diagnostics-show-option</strong> will prevent Clang from
+printing the [<a class="reference internal" href="#opt-wextra-tokens"><em>-Wextra-tokens</em></a>] information in
+the diagnostic. This information tells you the flag needed to enable
+or disable the diagnostic, either from the command line or through
+<a class="reference internal" href="#pragma-gcc-diagnostic"><em>#pragma GCC diagnostic</em></a>.</p>
+</dd>
+</dl>
+<span class="target" id="opt-fdiagnostics-show-category"></span><dl class="option">
+<dt id="cmdoption-fdiagnostics-show-category">
+<tt class="descname">-fdiagnostics-show-category</tt><tt class="descclassname">=none/id/name</tt><a class="headerlink" href="#cmdoption-fdiagnostics-show-category" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Enable printing category information in diagnostic line.</p>
+<p>This option, which defaults to “none”, controls whether or not Clang
+prints the category associated with a diagnostic when emitting it.
+Each diagnostic may or many not have an associated category, if it
+has one, it is listed in the diagnostic categorization field of the
+diagnostic line (in the []’s).</p>
+<p>For example, a format string warning will produce these three
+renditions based on the setting of this option:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
+t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
+t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
+</pre></div>
+</div>
+<p>This category can be used by clients that want to group diagnostics
+by category, so it should be a high level category. We want dozens
+of these, not hundreds or thousands of them.</p>
+</dd></dl>
+
+<dl class="docutils" id="opt-fdiagnostics-fixit-info">
+<dt><strong>-f[no-]diagnostics-fixit-info</strong></dt>
+<dd><p class="first">Enable “FixIt” information in the diagnostics output.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the information on how to fix a specific diagnostic
+underneath it when it knows. For example, in this output:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</pre></div>
+</div>
+<p class="last">Passing <strong>-fno-diagnostics-fixit-info</strong> will prevent Clang from
+printing the “//” line at the end of the message. This information
+is useful for users who may not understand what is wrong, but can be
+confusing for machine parsing.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-print-source-range-info">
+<dt><strong>-fdiagnostics-print-source-range-info</strong></dt>
+<dd><p class="first">Print machine parsable information about source ranges.
+This option makes Clang print information about source ranges in a machine
+parsable format after the file/line/column number information. The
+information is a simple sequence of brace enclosed ranges, where each range
+lists the start and end line/column locations. For example, in this output:</p>
+<div class="highlight-python"><div class="highlight"><pre>exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
+   P = (P-42) + Gamma*4;
+       ~~~~~~ ^ ~~~~~~~
+</pre></div>
+</div>
+<p>The {}’s are generated by -fdiagnostics-print-source-range-info.</p>
+<p class="last">The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-parseable-fixits">
+<tt class="descname">-fdiagnostics-parseable-fixits</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fdiagnostics-parseable-fixits" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Print Fix-Its in a machine parseable form.</p>
+<p>This option makes Clang print available Fix-Its in a machine
+parseable format at the end of diagnostics. The following example
+illustrates the format:</p>
+<div class="highlight-python"><div class="highlight"><pre>fix-it:"t.cpp":{7:25-7:29}:"Gamma"
+</pre></div>
+</div>
+<p>The range printed is a half-open range, so in this example the
+characters at column 25 up to but not including column 29 on line 7
+in t.cpp should be replaced with the string “Gamma”. Either the
+range or the replacement string may be empty (representing strict
+insertions and strict erasures, respectively). Both the file name
+and the insertion string escape backslash (as “\\”), tabs (as
+“\t”), newlines (as “\n”), double quotes(as “\””) and
+non-printable characters (as octal “\xxx”).</p>
+<p>The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-elide-type">
+<tt class="descname">-fno-elide-type</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-elide-type" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Turns off elision in template type printing.</p>
+<p>The default for template type printing is to elide as many template
+arguments as possible, removing those which are the same in both
+template types, leaving only the differences. Adding this flag will
+print all the template arguments. If supported by the terminal,
+highlighting will still appear on differing arguments.</p>
+<p>Default:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+</pre></div>
+</div>
+<p>-fno-elide-type:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-show-template-tree">
+<tt class="descname">-fdiagnostics-show-template-tree</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fdiagnostics-show-template-tree" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Template type diffing prints a text tree.</p>
+<p>For diffing large templated types, this option will cause Clang to
+display the templates as an indented text tree, one argument per
+line, with differences marked inline. This is compatible with
+-fno-elide-type.</p>
+<p>Default:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+</pre></div>
+</div>
+<p>With <a class="reference internal" href="#cmdoption-fdiagnostics-show-template-tree"><em class="xref std std-option">-fdiagnostics-show-template-tree</em></a>:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
+  vector<
+    map<
+      [...],
+      map<
+        [float != double],
+        [...]>>>
+</pre></div>
+</div>
+</dd></dl>
+
+</div>
+<div class="section" id="individual-warning-groups">
+<span id="cl-diag-warning-groups"></span><h4><a class="toc-backref" href="#id13">Individual Warning Groups</a><a class="headerlink" href="#individual-warning-groups" title="Permalink to this headline">Â¶</a></h4>
+<p>TODO: Generate this from tblgen. Define one anchor per warning group.</p>
+<span class="target" id="opt-wextra-tokens"></span><dl class="option">
+<dt id="cmdoption-Wextra-tokens">
+<tt class="descname">-Wextra-tokens</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wextra-tokens" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Warn about excess tokens at the end of a preprocessor directive.</p>
+<p>This option, which defaults to on, enables warnings about extra
+tokens at the end of preprocessor directives. For example:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+</pre></div>
+</div>
+<p>These extra tokens are not strictly conforming, and are usually best
+handled by commenting them out.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wambiguous-member-template">
+<tt class="descname">-Wambiguous-member-template</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wambiguous-member-template" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Warn about unqualified uses of a member template whose name resolves to
+another template at the location of the use.</p>
+<p>This option, which defaults to on, enables a warning in the
+following code:</p>
+<div class="highlight-python"><div class="highlight"><pre>template<typename T> struct set{};
+template<typename T> struct trait { typedef const T& type; };
+struct Value {
+  template<typename T> void set(typename trait<T>::type value) {}
+};
+void foo() {
+  Value v;
+  v.set<double>(3.2);
+}
+</pre></div>
+</div>
+<p>C++ [basic.lookup.classref] requires this to be an error, but,
+because it’s hard to work around, Clang downgrades it to a warning
+as an extension.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wbind-to-temporary-copy">
+<tt class="descname">-Wbind-to-temporary-copy</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wbind-to-temporary-copy" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Warn about an unusable copy constructor when binding a reference to a
+temporary.</p>
+<p>This option enables warnings about binding a
+reference to a temporary when the temporary doesn’t have a usable
+copy constructor. For example:</p>
+<div class="highlight-python"><div class="highlight"><pre>struct NonCopyable {
+  NonCopyable();
+private:
+  NonCopyable(const NonCopyable&);
+};
+void foo(const NonCopyable&);
+void bar() {
+  foo(NonCopyable());  // Disallowed in C++98; allowed in C++11.
+}
+</pre></div>
+</div>
+<div class="highlight-python"><div class="highlight"><pre>struct NonCopyable2 {
+  NonCopyable2();
+  NonCopyable2(NonCopyable2&);
+};
+void foo(const NonCopyable2&);
+void bar() {
+  foo(NonCopyable2());  // Disallowed in C++98; allowed in C++11.
+}
+</pre></div>
+</div>
+<p>Note that if <tt class="docutils literal"><span class="pre">NonCopyable2::NonCopyable2()</span></tt> has a default argument
+whose instantiation produces a compile error, that error will still
+be a hard error in C++98 mode even if this warning is turned off.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="options-to-control-clang-crash-diagnostics">
+<h3><a class="toc-backref" href="#id14">Options to Control Clang Crash Diagnostics</a><a class="headerlink" href="#options-to-control-clang-crash-diagnostics" title="Permalink to this headline">Â¶</a></h3>
+<p>As unbelievable as it may sound, Clang does crash from time to time.
+Generally, this only occurs to those living on the <a class="reference external" href="http://llvm.org/releases/download.html#svn">bleeding
+edge</a>. Clang goes to great
+lengths to assist you in filing a bug report. Specifically, Clang
+generates preprocessed source file(s) and associated run script(s) upon
+a crash. These files should be attached to a bug report to ease
+reproducibility of the failure. Below are the command line options to
+control the crash diagnostics.</p>
+<dl class="option">
+<dt id="cmdoption-fno-crash-diagnostics">
+<tt class="descname">-fno-crash-diagnostics</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-crash-diagnostics" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Disable auto-generation of preprocessed source files during a clang crash.</p>
+</dd></dl>
+
+<p>The -fno-crash-diagnostics flag can be helpful for speeding the process
+of generating a delta reduced test case.</p>
+</div>
+<div class="section" id="options-to-emit-optimization-reports">
+<h3><a class="toc-backref" href="#id15">Options to Emit Optimization Reports</a><a class="headerlink" href="#options-to-emit-optimization-reports" title="Permalink to this headline">Â¶</a></h3>
+<p>Optimization reports trace, at a high-level, all the major decisions
+done by compiler transformations. For instance, when the inliner
+decides to inline function <tt class="docutils literal"><span class="pre">foo()</span></tt> into <tt class="docutils literal"><span class="pre">bar()</span></tt>, or the loop unroller
+decides to unroll a loop N times, or the vectorizer decides to
+vectorize a loop body.</p>
+<p>Clang offers a family of flags which the optimizers can use to emit
+a diagnostic in three cases:</p>
+<ol class="arabic simple">
+<li>When the pass makes a transformation (<em class="xref std std-option">-Rpass</em>).</li>
+<li>When the pass fails to make a transformation (<em class="xref std std-option">-Rpass-missed</em>).</li>
+<li>When the pass determines whether or not to make a transformation
+(<em class="xref std std-option">-Rpass-analysis</em>).</li>
+</ol>
+<p>NOTE: Although the discussion below focuses on <em class="xref std std-option">-Rpass</em>, the exact
+same options apply to <em class="xref std std-option">-Rpass-missed</em> and <em class="xref std std-option">-Rpass-analysis</em>.</p>
+<p>Since there are dozens of passes inside the compiler, each of these flags
+take a regular expression that identifies the name of the pass which should
+emit the associated diagnostic. For example, to get a report from the inliner,
+compile the code with:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -O2 -Rpass<span class="o">=</span>inline code.cc -o code
+<span class="go">code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]</span>
+<span class="go">int bar(int j) { return foo(j, j - 2); }</span>
+<span class="go">                        ^</span>
+</pre></div>
+</div>
+<p>Note that remarks from the inliner are identified with <cite>[-Rpass=inline]</cite>.
+To request a report from every optimization pass, you should use
+<em class="xref std std-option">-Rpass=.*</em> (in fact, you can use any valid POSIX regular
+expression). However, do not expect a report from every transformation
+made by the compiler. Optimization remarks do not really make sense
+outside of the major transformations (e.g., inlining, vectorization,
+loop optimizations) and not every optimization pass supports this
+feature.</p>
+<div class="section" id="current-limitations">
+<h4><a class="toc-backref" href="#id16">Current limitations</a><a class="headerlink" href="#current-limitations" title="Permalink to this headline">Â¶</a></h4>
+<ol class="arabic simple">
+<li>Optimization remarks that refer to function names will display the
+mangled name of the function. Since these remarks are emitted by the
+back end of the compiler, it does not know anything about the input
+language, nor its mangling rules.</li>
+<li>Some source locations are not displayed correctly. The front end has
+a more detailed source location tracking than the locations included
+in the debug info (e.g., the front end can locate code inside macro
+expansions). However, the locations used by <em class="xref std std-option">-Rpass</em> are
+translated from debug annotations. That translation can be lossy,
+which results in some remarks having no location information.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="other-options">
+<h3><a class="toc-backref" href="#id17">Other Options</a><a class="headerlink" href="#other-options" title="Permalink to this headline">Â¶</a></h3>
+<p>Clang options that that don’t fit neatly into other categories.</p>
+<dl class="option">
+<dt id="cmdoption-MV">
+<tt class="descname">-MV</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-MV" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>When emitting a dependency file, use formatting conventions appropriate
+for NMake or Jom. Ignored unless another option causes Clang to emit a
+dependency file.</p>
+</dd></dl>
+
+<p>When Clang emits a dependency file (e.g., you supplied the -M option)
+most filenames can be written to the file without any special formatting.
+Different Make tools will treat different sets of characters as “special”
+and use different conventions for telling the Make tool that the character
+is actually part of the filename. Normally Clang uses backslash to “escape”
+a special character, which is the convention used by GNU Make. The -MV
+option tells Clang to put double-quotes around the entire filename, which
+is the convention used by NMake and Jom.</p>
+</div>
+</div>
+<div class="section" id="language-and-target-independent-features">
+<h2><a class="toc-backref" href="#id18">Language and Target-Independent Features</a><a class="headerlink" href="#language-and-target-independent-features" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="controlling-errors-and-warnings">
+<h3><a class="toc-backref" href="#id19">Controlling Errors and Warnings</a><a class="headerlink" href="#controlling-errors-and-warnings" title="Permalink to this headline">Â¶</a></h3>
+<p>Clang provides a number of ways to control which code constructs cause
+it to emit errors and warning messages, and how they are displayed to
+the console.</p>
+<div class="section" id="controlling-how-clang-displays-diagnostics">
+<h4><a class="toc-backref" href="#id20">Controlling How Clang Displays Diagnostics</a><a class="headerlink" href="#controlling-how-clang-displays-diagnostics" title="Permalink to this headline">Â¶</a></h4>
+<p>When Clang emits a diagnostic, it includes rich information in the
+output, and gives you fine-grain control over which information is
+printed. Clang has the ability to print this information, and these are
+the options that control it:</p>
+<ol class="arabic simple">
+<li>A file/line/column indicator that shows exactly where the diagnostic
+occurs in your code [<a class="reference internal" href="#opt-fshow-column"><em>-fshow-column</em></a>,
+<a class="reference internal" href="#opt-fshow-source-location"><em>-fshow-source-location</em></a>].</li>
+<li>A categorization of the diagnostic as a note, warning, error, or
+fatal error.</li>
+<li>A text string that describes what the problem is.</li>
+<li>An option that indicates how to control the diagnostic (for
+diagnostics that support it)
+[<a class="reference internal" href="#opt-fdiagnostics-show-option"><em>-fdiagnostics-show-option</em></a>].</li>
+<li>A <a class="reference internal" href="#diagnostics-categories"><em>high-level category</em></a> for the diagnostic
+for clients that want to group diagnostics by class (for diagnostics
+that support it)
+[<a class="reference internal" href="#opt-fdiagnostics-show-category"><em>-fdiagnostics-show-category</em></a>].</li>
+<li>The line of source code that the issue occurs on, along with a caret
+and ranges that indicate the important locations
+[<a class="reference internal" href="#opt-fcaret-diagnostics"><em>-fcaret-diagnostics</em></a>].</li>
+<li>“FixIt” information, which is a concise explanation of how to fix the
+problem (when Clang is certain it knows)
+[<a class="reference internal" href="#opt-fdiagnostics-fixit-info"><em>-fdiagnostics-fixit-info</em></a>].</li>
+<li>A machine-parsable representation of the ranges involved (off by
+default)
+[<a class="reference internal" href="#opt-fdiagnostics-print-source-range-info"><em>-fdiagnostics-print-source-range-info</em></a>].</li>
+</ol>
+<p>For more information please see <a class="reference internal" href="#cl-diag-formatting"><em>Formatting of
+Diagnostics</em></a>.</p>
+</div>
+<div class="section" id="diagnostic-mappings">
+<h4><a class="toc-backref" href="#id21">Diagnostic Mappings</a><a class="headerlink" href="#diagnostic-mappings" title="Permalink to this headline">Â¶</a></h4>
+<p>All diagnostics are mapped into one of these 6 classes:</p>
+<ul class="simple">
+<li>Ignored</li>
+<li>Note</li>
+<li>Remark</li>
+<li>Warning</li>
+<li>Error</li>
+<li>Fatal</li>
+</ul>
+</div>
+<div class="section" id="diagnostic-categories">
+<span id="diagnostics-categories"></span><h4><a class="toc-backref" href="#id22">Diagnostic Categories</a><a class="headerlink" href="#diagnostic-categories" title="Permalink to this headline">Â¶</a></h4>
+<p>Though not shown by default, diagnostics may each be associated with a
+high-level category. This category is intended to make it possible to
+triage builds that produce a large number of errors or warnings in a
+grouped way.</p>
+<p>Categories are not shown by default, but they can be turned on with the
+<a class="reference internal" href="#opt-fdiagnostics-show-category"><em>-fdiagnostics-show-category</em></a> option.
+When set to “<tt class="docutils literal"><span class="pre">name</span></tt>”, the category is printed textually in the
+diagnostic output. When it is set to “<tt class="docutils literal"><span class="pre">id</span></tt>”, a category number is
+printed. The mapping of category names to category id’s can be obtained
+by running ‘<tt class="docutils literal"><span class="pre">clang</span>   <span class="pre">--print-diagnostic-categories</span></tt>‘.</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-command-line-flags">
+<h4><a class="toc-backref" href="#id23">Controlling Diagnostics via Command Line Flags</a><a class="headerlink" href="#controlling-diagnostics-via-command-line-flags" title="Permalink to this headline">Â¶</a></h4>
+<p>TODO: -W flags, -pedantic, etc</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-pragmas">
+<span id="pragma-gcc-diagnostic"></span><h4><a class="toc-backref" href="#id24">Controlling Diagnostics via Pragmas</a><a class="headerlink" href="#controlling-diagnostics-via-pragmas" title="Permalink to this headline">Â¶</a></h4>
+<p>Clang can also control what diagnostics are enabled through the use of
+pragmas in the source code. This is useful for turning off specific
+warnings in a section of source code. Clang supports GCC’s pragma for
+compatibility with existing source code, as well as several extensions.</p>
+<p>The pragma may control any warning that can be used from the command
+line. Warnings may be set to ignored, warning, error, or fatal. The
+following example code will tell Clang or GCC to ignore the -Wall
+warnings:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#pragma GCC diagnostic ignored "-Wall"</span>
+</pre></div>
+</div>
+<p>In addition to all of the functionality provided by GCC’s pragma, Clang
+also allows you to push and pop the current warning state. This is
+particularly useful when writing a header file that will be compiled by
+other people, because you don’t know what warning flags they build with.</p>
+<p>In the below example <em class="xref std std-option">-Wmultichar</em> is ignored for only a single line of
+code, after which the diagnostics return to whatever state had previously
+existed.</p>
+<div class="highlight-c"><div class="highlight"><pre>#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wmultichar"
+
+char b = 'df'; // no warning.
+
+#pragma clang diagnostic pop
+</pre></div>
+</div>
+<p>The push and pop pragmas will save and restore the full diagnostic state
+of the compiler, regardless of how it was set. That means that it is
+possible to use push and pop around GCC compatible diagnostics and Clang
+will push and pop them appropriately, while GCC will ignore the pushes
+and pops as unknown pragmas. It should be noted that while Clang
+supports the GCC pragma, Clang and GCC do not support the exact same set
+of warnings, so even when using GCC compatible #pragmas there is no
+guarantee that they will have identical behaviour on both compilers.</p>
+<p>In addition to controlling warnings and errors generated by the compiler, it is
+possible to generate custom warning and error messages through the following
+pragmas:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="c1">// The following will produce warning messages</span>
+<span class="cp">#pragma message "some diagnostic message"</span>
+<span class="cp">#pragma GCC warning "TODO: replace deprecated feature"</span>
+
+<span class="c1">// The following will produce an error message</span>
+<span class="cp">#pragma GCC error "Not supported"</span>
+</pre></div>
+</div>
+<p>These pragmas operate similarly to the <tt class="docutils literal"><span class="pre">#warning</span></tt> and <tt class="docutils literal"><span class="pre">#error</span></tt> preprocessor
+directives, except that they may also be embedded into preprocessor macros via
+the C99 <tt class="docutils literal"><span class="pre">_Pragma</span></tt> operator, for example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define STR(X) #X</span>
+<span class="cp">#define DEFER(M,...) M(__VA_ARGS__)</span>
+<span class="cp">#define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))</span>
+
+<span class="n">CUSTOM_ERROR</span><span class="p">(</span><span class="s">"Feature not available"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="controlling-diagnostics-in-system-headers">
+<h4><a class="toc-backref" href="#id25">Controlling Diagnostics in System Headers</a><a class="headerlink" href="#controlling-diagnostics-in-system-headers" title="Permalink to this headline">Â¶</a></h4>
+<p>Warnings are suppressed when they occur in system headers. By default,
+an included file is treated as a system header if it is found in an
+include path specified by <tt class="docutils literal"><span class="pre">-isystem</span></tt>, but this can be overridden in
+several ways.</p>
+<p>The <tt class="docutils literal"><span class="pre">system_header</span></tt> pragma can be used to mark the current file as
+being a system header. No warnings will be produced from the location of
+the pragma onwards within the same file.</p>
+<div class="highlight-c"><div class="highlight"><pre>char a = 'xy'; // warning
+
+#pragma clang system_header
+
+char b = 'ab'; // no warning
+</pre></div>
+</div>
+<p>The <em class="xref std std-option">--system-header-prefix=</em> and <em class="xref std std-option">--no-system-header-prefix=</em>
+command-line arguments can be used to override whether subsets of an include
+path are treated as system headers. When the name in a <tt class="docutils literal"><span class="pre">#include</span></tt> directive
+is found within a header search path and starts with a system prefix, the
+header is treated as a system header. The last prefix on the
+command-line which matches the specified header name takes precedence.
+For instance:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -Ifoo -isystem bar --system-header-prefix<span class="o">=</span>x/ <span class="se">\</span>
+<span class="go">    --no-system-header-prefix=x/y/</span>
+</pre></div>
+</div>
+<p>Here, <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/a.h"</span></tt> is treated as including a system header, even
+if the header is found in <tt class="docutils literal"><span class="pre">foo</span></tt>, and <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/y/b.h"</span></tt> is treated
+as not including a system header, even if the header is found in
+<tt class="docutils literal"><span class="pre">bar</span></tt>.</p>
+<p>A <tt class="docutils literal"><span class="pre">#include</span></tt> directive which finds a file relative to the current
+directory is treated as including a system header if the including file
+is treated as a system header.</p>
+</div>
+<div class="section" id="enabling-all-diagnostics">
+<span id="diagnostics-enable-everything"></span><h4><a class="toc-backref" href="#id26">Enabling All Diagnostics</a><a class="headerlink" href="#enabling-all-diagnostics" title="Permalink to this headline">Â¶</a></h4>
+<p>In addition to the traditional <tt class="docutils literal"><span class="pre">-W</span></tt> flags, one can enable <strong>all</strong>
+diagnostics by passing <a class="reference internal" href="#cmdoption-Weverything"><em class="xref std std-option">-Weverything</em></a>. This works as expected
+with
+<a class="reference internal" href="#cmdoption-Werror"><em class="xref std std-option">-Werror</em></a>, and also includes the warnings from <a class="reference internal" href="#cmdoption-pedantic"><em class="xref std std-option">-pedantic</em></a>.</p>
+<p>Note that when combined with <a class="reference internal" href="#cmdoption-w"><em class="xref std std-option">-w</em></a> (which disables all warnings), that
+flag wins.</p>
+</div>
+<div class="section" id="controlling-static-analyzer-diagnostics">
+<h4><a class="toc-backref" href="#id27">Controlling Static Analyzer Diagnostics</a><a class="headerlink" href="#controlling-static-analyzer-diagnostics" title="Permalink to this headline">Â¶</a></h4>
+<p>While not strictly part of the compiler, the diagnostics from Clang’s
+<a class="reference external" href="http://clang-analyzer.llvm.org">static analyzer</a> can also be
+influenced by the user via changes to the source code. See the available
+<a class="reference external" href="http://clang-analyzer.llvm.org/annotations.html">annotations</a> and the
+analyzer’s <a class="reference external" href="http://clang-analyzer.llvm.org/faq.html#exclude_code">FAQ
+page</a> for more
+information.</p>
+</div>
+</div>
+<div class="section" id="precompiled-headers">
+<span id="usersmanual-precompiled-headers"></span><h3><a class="toc-backref" href="#id28">Precompiled Headers</a><a class="headerlink" href="#precompiled-headers" title="Permalink to this headline">Â¶</a></h3>
+<p><a class="reference external" href="http://en.wikipedia.org/wiki/Precompiled_header">Precompiled headers</a>
+are a general approach employed by many compilers to reduce compilation
+time. The underlying motivation of the approach is that it is common for
+the same (and often large) header files to be included by multiple
+source files. Consequently, compile times can often be greatly improved
+by caching some of the (redundant) work done by a compiler to process
+headers. Precompiled header files, which represent one of many ways to
+implement this optimization, are literally files that represent an
+on-disk cache that contains the vital information necessary to reduce
+some of the work needed to process a corresponding header file. While
+details of precompiled headers vary between compilers, precompiled
+headers have been shown to be highly effective at speeding up program
+compilation on systems with very large system headers (e.g., Mac OS X).</p>
+<div class="section" id="generating-a-pch-file">
+<h4><a class="toc-backref" href="#id29">Generating a PCH File</a><a class="headerlink" href="#generating-a-pch-file" title="Permalink to this headline">Â¶</a></h4>
+<p>To generate a PCH file using Clang, one invokes Clang with the
+<em class="xref std std-option">-x <language>-header</em> option. This mirrors the interface in GCC
+for generating PCH files:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> gcc -x c-header test.h -o test.h.gch
+<span class="gp">$</span> clang -x c-header test.h -o test.h.pch
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-a-pch-file">
+<h4><a class="toc-backref" href="#id30">Using a PCH File</a><a class="headerlink" href="#using-a-pch-file" title="Permalink to this headline">Â¶</a></h4>
+<p>A PCH file can then be used as a prefix header when a <a class="reference internal" href="CommandGuide/clang.html#cmdoption-include"><em class="xref std std-option">-include</em></a>
+option is passed to <tt class="docutils literal"><span class="pre">clang</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -include test.h test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">clang</span></tt> driver will first check if a PCH file for <tt class="docutils literal"><span class="pre">test.h</span></tt> is
+available; if so, the contents of <tt class="docutils literal"><span class="pre">test.h</span></tt> (and the files it includes)
+will be processed from the PCH file. Otherwise, Clang falls back to
+directly processing the content of <tt class="docutils literal"><span class="pre">test.h</span></tt>. This mirrors the behavior
+of GCC.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>Clang does <em>not</em> automatically use PCH files for headers that are directly
+included within a source file. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -x c-header test.h -o test.h.pch
+<span class="gp">$</span> cat test.c
+<span class="gp">#</span>include <span class="s2">"test.h"</span>
+<span class="gp">$</span> clang test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p class="last">In this example, <tt class="docutils literal"><span class="pre">clang</span></tt> will not automatically use the PCH file for
+<tt class="docutils literal"><span class="pre">test.h</span></tt> since <tt class="docutils literal"><span class="pre">test.h</span></tt> was included directly in the source file and not
+specified on the command line using <a class="reference internal" href="CommandGuide/clang.html#cmdoption-include"><em class="xref std std-option">-include</em></a>.</p>
+</div>
+</div>
+<div class="section" id="relocatable-pch-files">
+<h4><a class="toc-backref" href="#id31">Relocatable PCH Files</a><a class="headerlink" href="#relocatable-pch-files" title="Permalink to this headline">Â¶</a></h4>
+<p>It is sometimes necessary to build a precompiled header from headers
+that are not yet in their final, installed locations. For example, one
+might build a precompiled header within the build tree that is then
+meant to be installed alongside the headers. Clang permits the creation
+of “relocatable” precompiled headers, which are built with a given path
+(into the build directory) and can later be used from an installed
+location.</p>
+<p>To build a relocatable precompiled header, place your headers into a
+subdirectory whose structure mimics the installed location. For example,
+if you want to build a precompiled header for the header <tt class="docutils literal"><span class="pre">mylib.h</span></tt>
+that will be installed into <tt class="docutils literal"><span class="pre">/usr/include</span></tt>, create a subdirectory
+<tt class="docutils literal"><span class="pre">build/usr/include</span></tt> and place the header <tt class="docutils literal"><span class="pre">mylib.h</span></tt> into that
+subdirectory. If <tt class="docutils literal"><span class="pre">mylib.h</span></tt> depends on other headers, then they can be
+stored within <tt class="docutils literal"><span class="pre">build/usr/include</span></tt> in a way that mimics the installed
+location.</p>
+<p>Building a relocatable precompiled header requires two additional
+arguments. First, pass the <tt class="docutils literal"><span class="pre">--relocatable-pch</span></tt> flag to indicate that
+the resulting PCH file should be relocatable. Second, pass
+<em class="xref std std-option">-isysroot /path/to/build</em>, which makes all includes for your library
+relative to the build directory. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+</pre></div>
+</div>
+<p>When loading the relocatable PCH file, the various headers used in the
+PCH file are found from the system header root. For example, <tt class="docutils literal"><span class="pre">mylib.h</span></tt>
+can be found in <tt class="docutils literal"><span class="pre">/usr/include/mylib.h</span></tt>. If the headers are installed
+in some other system root, the <em class="xref std std-option">-isysroot</em> option can be used provide
+a different system root from which the headers will be based. For
+example, <em class="xref std std-option">-isysroot /Developer/SDKs/MacOSX10.4u.sdk</em> will look for
+<tt class="docutils literal"><span class="pre">mylib.h</span></tt> in <tt class="docutils literal"><span class="pre">/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h</span></tt>.</p>
+<p>Relocatable precompiled headers are intended to be used in a limited
+number of cases where the compilation environment is tightly controlled
+and the precompiled header cannot be generated after headers have been
+installed.</p>
+</div>
+</div>
+<div class="section" id="controlling-code-generation">
+<span id="id2"></span><h3><a class="toc-backref" href="#id32">Controlling Code Generation</a><a class="headerlink" href="#controlling-code-generation" title="Permalink to this headline">Â¶</a></h3>
+<p>Clang provides a number of ways to control code generation. The options
+are listed below.</p>
+<dl class="docutils">
+<dt><strong>-f[no-]sanitize=check1,check2,...</strong></dt>
+<dd><p class="first">Turn on runtime checks for various forms of undefined or suspicious
+behavior.</p>
+<p>This option controls whether Clang adds runtime checks for various
+forms of undefined or suspicious behavior, and is disabled by
+default. If a check fails, a diagnostic message is produced at
+runtime explaining the problem. The main checks are:</p>
+<ul class="simple">
+<li><p id="opt-fsanitize-address"><tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>:
+<a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>, a memory error
+detector.</p>
+</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=integer</span></tt>: Enables checks for undefined or
+suspicious integer behavior.</li>
+<li><p id="opt-fsanitize-thread"><tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>: <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>, a data race detector.</p>
+</li>
+<li><p id="opt-fsanitize-memory"><tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt>: <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a>,
+an <em>experimental</em> detector of uninitialized reads. Not ready for
+widespread use.</p>
+</li>
+<li><p id="opt-fsanitize-undefined"><tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>: Fast and compatible undefined behavior
+checker. Enables the undefined behavior checks that have small
+runtime cost and no impact on address space layout or ABI. This
+includes all of the checks listed below other than
+<tt class="docutils literal"><span class="pre">unsigned-integer-overflow</span></tt>.</p>
+</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=undefined-trap</span></tt>: This is a deprecated alias for
+<tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=dataflow</span></tt>: <a class="reference internal" href="DataFlowSanitizer.html"><em>DataFlowSanitizer</em></a>, a general data
+flow analysis.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi</span></tt>: <a class="reference internal" href="ControlFlowIntegrity.html"><em>control flow integrity</em></a>
+checks. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt>: <a class="reference internal" href="SafeStack.html"><em>safe stack</em></a>
+protection against stack-based memory corruption errors.</li>
+</ul>
+<p>The following more fine-grained checks are also available:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize=alignment</span></tt>: Use of a misaligned pointer or creation
+of a misaligned reference.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=bool</span></tt>: Load of a <tt class="docutils literal"><span class="pre">bool</span></tt> value which is neither
+<tt class="docutils literal"><span class="pre">true</span></tt> nor <tt class="docutils literal"><span class="pre">false</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=bounds</span></tt>: Out of bounds array indexing, in cases
+where the array bound can be statically determined.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-cast-strict</span></tt>: Enables <a class="reference internal" href="ControlFlowIntegrity.html#cfi-strictness"><em>strict cast checks</em></a>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-derived-cast</span></tt>: Base-to-derived cast to the wrong
+dynamic type. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-unrelated-cast</span></tt>: Cast from <tt class="docutils literal"><span class="pre">void*</span></tt> or another
+unrelated type to the wrong dynamic type. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-nvcall</span></tt>: Non-virtual call via an object whose vptr is of
+the wrong dynamic type. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-vcall</span></tt>: Virtual call via an object whose vptr is of the
+wrong dynamic type. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=enum</span></tt>: Load of a value of an enumerated type which
+is not in the range of representable values for that enumerated
+type.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=float-cast-overflow</span></tt>: Conversion to, from, or
+between floating-point types which would overflow the
+destination.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=float-divide-by-zero</span></tt>: Floating point division by
+zero.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt>: Indirect call of a function through a
+function pointer of the wrong type (Linux, C++ and x86/x86_64 only).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=integer-divide-by-zero</span></tt>: Integer division by zero.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=nonnull-attribute</span></tt>: Passing null pointer as a function
+parameter which is declared to never be null.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=null</span></tt>: Use of a null pointer or creation of a null
+reference.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=object-size</span></tt>: An attempt to use bytes which the
+optimizer can determine are not part of the object being
+accessed. The sizes of objects are determined using
+<tt class="docutils literal"><span class="pre">__builtin_object_size</span></tt>, and consequently may be able to detect
+more problems at higher optimization levels.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=return</span></tt>: In C++, reaching the end of a
+value-returning function without returning a value.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=returns-nonnull-attribute</span></tt>: Returning null pointer
+from a function which is declared to never return null.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=shift</span></tt>: Shift operators where the amount shifted is
+greater or equal to the promoted bit-width of the left hand side
+or less than zero, or where the left hand side is negative. For a
+signed left shift, also checks for signed overflow in C, and for
+unsigned overflow in C++. You can use <tt class="docutils literal"><span class="pre">-fsanitize=shift-base</span></tt> or
+<tt class="docutils literal"><span class="pre">-fsanitize=shift-exponent</span></tt> to check only left-hand side or
+right-hand side of shift operation, respectively.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=signed-integer-overflow</span></tt>: Signed integer overflow,
+including all the checks added by <tt class="docutils literal"><span class="pre">-ftrapv</span></tt>, and checking for
+overflow in signed division (<tt class="docutils literal"><span class="pre">INT_MIN</span> <span class="pre">/</span> <span class="pre">-1</span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=unreachable</span></tt>: If control flow reaches
+<tt class="docutils literal"><span class="pre">__builtin_unreachable</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=unsigned-integer-overflow</span></tt>: Unsigned integer
+overflows.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=vla-bound</span></tt>: A variable-length array whose bound
+does not evaluate to a positive value.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=vptr</span></tt>: Use of an object whose vptr indicates that
+it is of the wrong dynamic type, or that its lifetime has not
+begun or has ended. Incompatible with <tt class="docutils literal"><span class="pre">-fno-rtti</span></tt>.</li>
+</ul>
+<p>You can turn off or modify checks for certain source files, functions
+or even variables by providing a special file:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize-blacklist=/path/to/blacklist/file</span></tt>: disable or modify
+sanitizer checks for objects listed in the file. See
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a> for file format description.</li>
+<li><tt class="docutils literal"><span class="pre">-fno-sanitize-blacklist</span></tt>: don’t use blacklist file, if it was
+specified earlier in the command line.</li>
+</ul>
+<p>Extra features of MemorySanitizer (require explicit
+<tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt>):</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-fsanitize-memory-track-origins[=level]</span></tt>: Enables origin tracking in
+MemorySanitizer. Adds a second section to MemorySanitizer
+reports pointing to the heap or stack allocation the
+uninitialized bits came from. Slows down execution by additional
+1.5x-2x.</p>
+<p>Possible values for level are 0 (off), 1, 2 (default). Level 2
+adds more sections to MemorySanitizer reports describing the
+order of memory stores the uninitialized value went
+through. This mode may use extra memory in programs that copy
+uninitialized memory a lot.</p>
+</li>
+</ul>
+<p>The <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> argument must also be provided when linking, in
+order to link to the appropriate runtime library. When using
+<tt class="docutils literal"><span class="pre">-fsanitize=vptr</span></tt> (or a group that includes it, such as
+<tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>) with a C++ program, the link must be
+performed by <tt class="docutils literal"><span class="pre">clang++</span></tt>, not <tt class="docutils literal"><span class="pre">clang</span></tt>, in order to link against the
+C++-specific parts of the runtime library.</p>
+<p class="last">It is not possible to combine more than one of the <tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>,
+<tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>, and <tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt> checkers in the same
+program. The <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt> checks can only be combined with
+<tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>.</p>
+</dd>
+</dl>
+<p><strong>-f[no-]sanitize-recover=check1,check2,...</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag are non-fatal.
+If the check is fatal, program will halt after the first error
+of this kind is detected and error report is printed.</p>
+<p>By default, non-fatal checks are those enabled by UndefinedBehaviorSanitizer,
+except for <tt class="docutils literal"><span class="pre">-fsanitize=return</span></tt> and <tt class="docutils literal"><span class="pre">-fsanitize=unreachable</span></tt>. Some
+sanitizers (e.g. <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>) may not support recovery,
+and always crash the program after the issue is detected.</p>
+<p>Note that the <tt class="docutils literal"><span class="pre">-fsanitize-trap</span></tt> flag has precedence over this flag.
+This means that if a check has been configured to trap elsewhere on the
+command line, or if the check traps by default, this flag will not have
+any effect unless that sanitizer’s trapping behavior is disabled with
+<tt class="docutils literal"><span class="pre">-fno-sanitize-trap</span></tt>.</p>
+<p>For example, if a command line contains the flags <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span>
+<span class="pre">-fsanitize-trap=undefined</span></tt>, the flag <tt class="docutils literal"><span class="pre">-fsanitize-recover=alignment</span></tt>
+will have no effect on its own; it will need to be accompanied by
+<tt class="docutils literal"><span class="pre">-fno-sanitize-trap=alignment</span></tt>.</p>
+</div></blockquote>
+<p><strong>-f[no-]sanitize-trap=check1,check2,...</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by the <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag trap. This
+option is intended for use in cases where the sanitizer runtime cannot
+be used (for instance, when building libc or a kernel module), or where
+the binary size increase caused by the sanitizer runtime is a concern.</p>
+<p>This flag is only compatible with <tt class="docutils literal"><span class="pre">local-bounds</span></tt>,
+<tt class="docutils literal"><span class="pre">unsigned-integer-overflow</span></tt>, sanitizers in the <tt class="docutils literal"><span class="pre">cfi</span></tt> group and
+sanitizers in the <tt class="docutils literal"><span class="pre">undefined</span></tt> group other than <tt class="docutils literal"><span class="pre">vptr</span></tt>. If this flag
+is supplied together with <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>, the <tt class="docutils literal"><span class="pre">vptr</span></tt> sanitizer
+will be implicitly disabled.</p>
+<p>This flag is enabled by default for sanitizers in the <tt class="docutils literal"><span class="pre">cfi</span></tt> group.</p>
+</div></blockquote>
+<p><strong>-f[no-]sanitize-coverage=[type,features,...]</strong></p>
+<blockquote>
+<div>Enable simple code coverage in addition to certain sanitizers.
+See <a class="reference internal" href="SanitizerCoverage.html"><em>SanitizerCoverage</em></a> for more details.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-undefined-trap-on-error">
+<tt class="descname">-fsanitize-undefined-trap-on-error</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fsanitize-undefined-trap-on-error" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Deprecated alias for <tt class="docutils literal"><span class="pre">-fsanitize-trap=undefined</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-assume-sane-operator-new">
+<tt class="descname">-fno-assume-sane-operator-new</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-assume-sane-operator-new" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Don’t assume that the C++’s new operator is sane.</p>
+<p>This option tells the compiler to do not assume that C++’s global
+new operator will always return a pointer that does not alias any
+other pointer when the function returns.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftrap-function">
+<tt class="descname">-ftrap-function</tt><tt class="descclassname">=[name]</tt><a class="headerlink" href="#cmdoption-ftrap-function" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Instruct code generator to emit a function call to the specified
+function name for <tt class="docutils literal"><span class="pre">__builtin_trap()</span></tt>.</p>
+<p>LLVM code generator translates <tt class="docutils literal"><span class="pre">__builtin_trap()</span></tt> to a trap
+instruction if it is supported by the target ISA. Otherwise, the
+builtin is translated into a call to <tt class="docutils literal"><span class="pre">abort</span></tt>. If this option is
+set, then the code generator will always lower the builtin to a call
+to the specified function regardless of whether the target ISA has a
+trap instruction. This option is useful for environments (e.g.
+deeply embedded) where a trap cannot be properly handled, or when
+some custom behavior is desired.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftls-model">
+<tt class="descname">-ftls-model</tt><tt class="descclassname">=[model]</tt><a class="headerlink" href="#cmdoption-ftls-model" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Select which TLS model to use.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">global-dynamic</span></tt>, <tt class="docutils literal"><span class="pre">local-dynamic</span></tt>,
+<tt class="docutils literal"><span class="pre">initial-exec</span></tt> and <tt class="docutils literal"><span class="pre">local-exec</span></tt>. The default value is
+<tt class="docutils literal"><span class="pre">global-dynamic</span></tt>. The compiler may use a different model if the
+selected model is not supported by the target, or if a more
+efficient model can be used. The TLS model can be overridden per
+variable using the <tt class="docutils literal"><span class="pre">tls_model</span></tt> attribute.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mhwdiv">
+<tt class="descname">-mhwdiv</tt><tt class="descclassname">=[values]</tt><a class="headerlink" href="#cmdoption-mhwdiv" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Select the ARM modes (arm or thumb) that support hardware division
+instructions.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">arm</span></tt>, <tt class="docutils literal"><span class="pre">thumb</span></tt> and <tt class="docutils literal"><span class="pre">arm,thumb</span></tt>.
+This option is used to indicate which mode (arm or thumb) supports
+hardware division instructions. This only applies to the ARM
+architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-m">
+<tt class="descname">-m</tt><tt class="descclassname">[no-]crc</tt><a class="headerlink" href="#cmdoption-m" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Enable or disable CRC instructions.</p>
+<p>This option is used to indicate whether CRC instructions are to
+be generated. This only applies to the ARM architecture.</p>
+<p>CRC instructions are enabled by default on ARMv8.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mgeneral-regs-only">
+<tt class="descname">-mgeneral-regs-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-mgeneral-regs-only" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Generate code which only uses the general purpose registers.</p>
+<p>This option restricts the generated code to use general registers
+only. This only applies to the AArch64 architecture.</p>
+</dd></dl>
+
+<dl class="docutils">
+<dt><strong>-f[no-]max-unknown-pointer-align=[number]</strong></dt>
+<dd><p class="first">Instruct the code generator to not enforce a higher alignment than the given
+number (of bytes) when accessing memory via an opaque pointer or reference.
+This cap is ignored when directly accessing a variable or when the pointee
+type has an explicit âalignedâ attribute.</p>
+<p>The value should usually be determined by the properties of the system allocator.
+Some builtin types, especially vector types, have very high natural alignments;
+when working with values of those types, Clang usually wants to use instructions
+that take advantage of that alignment.  However, many system allocators do
+not promise to return memory that is more than 8-byte or 16-byte-aligned.  Use
+this option to limit the alignment that the compiler can assume for an arbitrary
+pointer, which may point onto the heap.</p>
+<p>This option does not affect the ABI alignment of types; the layout of structs and
+unions and the value returned by the alignof operator remain the same.</p>
+<p>This option can be overridden on a case-by-case basis by putting an explicit
+âalignedâ alignment on a struct, union, or typedef.  For example:</p>
+<div class="last highlight-console"><div class="highlight"><pre><span class="gp">#</span>include <immintrin.h>
+<span class="go">// Make an aligned typedef of the AVX-512 16-int vector type.</span>
+<span class="go">typedef __v16si __aligned_v16si __attribute__((aligned(64)));</span>
+
+<span class="go">void initialize_vector(__aligned_v16si *v) {</span>
+<span class="go">  // The compiler may assume that âvâ is 64-byte aligned, regardless of the</span>
+<span class="go">  // value of -fmax-unknown-pointer-align.</span>
+<span class="go">}</span>
+</pre></div>
+</div>
+</dd>
+</dl>
+</div>
+<div class="section" id="profile-guided-optimization">
+<h3><a class="toc-backref" href="#id33">Profile Guided Optimization</a><a class="headerlink" href="#profile-guided-optimization" title="Permalink to this headline">Â¶</a></h3>
+<p>Profile information enables better optimization. For example, knowing that a
+branch is taken very frequently helps the compiler make better decisions when
+ordering basic blocks. Knowing that a function <tt class="docutils literal"><span class="pre">foo</span></tt> is called more
+frequently than another function <tt class="docutils literal"><span class="pre">bar</span></tt> helps the inliner.</p>
+<p>Clang supports profile guided optimization with two different kinds of
+profiling. A sampling profiler can generate a profile with very low runtime
+overhead, or you can build an instrumented version of the code that collects
+more detailed profile information. Both kinds of profiles can provide execution
+counts for instructions in the code and information on branches taken and
+function invocation.</p>
+<p>Regardless of which kind of profiling you use, be careful to collect profiles
+by running your code with inputs that are representative of the typical
+behavior. Code that is not exercised in the profile will be optimized as if it
+is unimportant, and the compiler may make poor optimization choices for code
+that is disproportionately used while profiling.</p>
+<div class="section" id="differences-between-sampling-and-instrumentation">
+<h4><a class="toc-backref" href="#id34">Differences Between Sampling and Instrumentation</a><a class="headerlink" href="#differences-between-sampling-and-instrumentation" title="Permalink to this headline">Â¶</a></h4>
+<p>Although both techniques are used for similar purposes, there are important
+differences between the two:</p>
+<ol class="arabic simple">
+<li>Profile data generated with one cannot be used by the other, and there is no
+conversion tool that can convert one to the other. So, a profile generated
+via <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> must be used with <tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt>.
+Similarly, sampling profiles generated by external profilers must be
+converted and used with <tt class="docutils literal"><span class="pre">-fprofile-sample-use</span></tt>.</li>
+<li>Instrumentation profile data can be used for code coverage analysis and
+optimization.</li>
+<li>Sampling profiles can only be used for optimization. They cannot be used for
+code coverage analysis. Although it would be technically possible to use
+sampling profiles for code coverage, sample-based profiles are too
+coarse-grained for code coverage purposes; it would yield poor results.</li>
+<li>Sampling profiles must be generated by an external tool. The profile
+generated by that tool must then be converted into a format that can be read
+by LLVM. The section on sampling profilers describes one of the supported
+sampling profile formats.</li>
+</ol>
+</div>
+<div class="section" id="using-sampling-profilers">
+<h4><a class="toc-backref" href="#id35">Using Sampling Profilers</a><a class="headerlink" href="#using-sampling-profilers" title="Permalink to this headline">Â¶</a></h4>
+<p>Sampling profilers are used to collect runtime information, such as
+hardware counters, while your application executes. They are typically
+very efficient and do not incur a large runtime overhead. The
+sample data collected by the profiler can be used during compilation
+to determine what the most executed areas of the code are.</p>
+<p>Using the data from a sample profiler requires some changes in the way
+a program is built. Before the compiler can use profiling information,
+the code needs to execute under the profiler. The following is the
+usual build cycle when using sample profilers for optimization:</p>
+<ol class="arabic">
+<li><p class="first">Build the code with source line table information. You can use all the
+usual build flags that you always build your application with. The only
+requirement is that you add <tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> or <tt class="docutils literal"><span class="pre">-g</span></tt> to the
+command line. This is important for the profiler to be able to map
+instructions back to source line locations.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -gline-tables-only code.cc -o code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the executable under a sampling profiler. The specific profiler
+you use does not really matter, as long as its output can be converted
+into the format that the LLVM optimizer understands. Currently, there
+exists a conversion tool for the Linux Perf profiler
+(<a class="reference external" href="https://perf.wiki.kernel.org/">https://perf.wiki.kernel.org/</a>), so these examples assume that you
+are using Linux Perf to profile your code.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> perf record -b ./code
+</pre></div>
+</div>
+<p>Note the use of the <tt class="docutils literal"><span class="pre">-b</span></tt> flag. This tells Perf to use the Last Branch
+Record (LBR) to record call chains. While this is not strictly required,
+it provides better call information, which improves the accuracy of
+the profile data.</p>
+</li>
+<li><p class="first">Convert the collected profile data to LLVM’s sample profile format.
+This is currently supported via the AutoFDO converter <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt>.
+It is available at <a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>. Once built and
+installed, you can convert the <tt class="docutils literal"><span class="pre">perf.data</span></tt> file to LLVM using
+the command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> create_llvm_prof --binary<span class="o">=</span>./code --out<span class="o">=</span>code.prof
+</pre></div>
+</div>
+<p>This will read <tt class="docutils literal"><span class="pre">perf.data</span></tt> and the binary file <tt class="docutils literal"><span class="pre">./code</span></tt> and emit
+the profile data in <tt class="docutils literal"><span class="pre">code.prof</span></tt>. Note that if you ran <tt class="docutils literal"><span class="pre">perf</span></tt>
+without the <tt class="docutils literal"><span class="pre">-b</span></tt> flag, you need to use <tt class="docutils literal"><span class="pre">--use_lbr=false</span></tt> when
+calling <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt>.</p>
+</li>
+<li><p class="first">Build the code again using the collected profile. This step feeds
+the profile back to the optimizers. This should result in a binary
+that executes faster than the original one. Note that you are not
+required to build the code with the exact same arguments that you
+used in the first step. The only requirement is that you build the code
+with <tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> and <tt class="docutils literal"><span class="pre">-fprofile-sample-use</span></tt>.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -gline-tables-only -fprofile-sample-use<span class="o">=</span>code.prof code.cc -o code
+</pre></div>
+</div>
+</li>
+</ol>
+<div class="section" id="sample-profile-formats">
+<h5><a class="toc-backref" href="#id36">Sample Profile Formats</a><a class="headerlink" href="#sample-profile-formats" title="Permalink to this headline">Â¶</a></h5>
+<p>Since external profilers generate profile data in a variety of custom formats,
+the data generated by the profiler must be converted into a format that can be
+read by the backend. LLVM supports three different sample profile formats:</p>
+<ol class="arabic simple">
+<li>ASCII text. This is the easiest one to generate. The file is divided into
+sections, which correspond to each of the functions with profile
+information. The format is described below.</li>
+<li>Binary encoding. This uses a more efficient encoding that yields smaller
+profile files, which may be useful when generating large profiles. It can be
+generated from the text format using the <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool.</li>
+<li>GCC encoding. This is based on the gcov format, which is accepted by GCC. It
+is only interesting in environments where GCC and Clang co-exist. Similarly
+to the binary encoding, it can be generated using the <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool.</li>
+</ol>
+<p>If you are using Linux Perf to generate sampling profiles, you can use the
+conversion tool <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt> described in the previous section.
+Otherwise, you will need to write a conversion tool that converts your
+profiler’s native format into one of these three.</p>
+</div>
+<div class="section" id="sample-profile-text-format">
+<h5><a class="toc-backref" href="#id37">Sample Profile Text Format</a><a class="headerlink" href="#sample-profile-text-format" title="Permalink to this headline">Â¶</a></h5>
+<p>This section describes the ASCII text format for sampling profiles. It is,
+arguably, the easiest one to generate. If you are interested in generating any
+of the other two, consult the <tt class="docutils literal"><span class="pre">ProfileData</span></tt> library in in LLVM’s source tree
+(specifically, <tt class="docutils literal"><span class="pre">llvm/lib/ProfileData/SampleProfWriter.cpp</span></tt>).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">function1:total_samples:total_head_samples</span>
+<span class="go">offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]</span>
+<span class="go">offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]</span>
+<span class="go">...</span>
+<span class="go">offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]</span>
+</pre></div>
+</div>
+<p>The file may contain blank lines between sections and within a
+section. However, the spacing within a single line is fixed. Additional
+spaces will result in an error while reading the file.</p>
+<p>Function names must be mangled in order for the profile loader to
+match them in the current translation unit. The two numbers in the
+function header specify how many total samples were accumulated in the
+function (first number), and the total number of samples accumulated
+in the prologue of the function (second number). This head sample
+count provides an indicator of how frequently the function is invoked.</p>
+<p>Each sampled line may contain several items. Some are optional (marked
+below):</p>
+<ol class="loweralpha">
+<li><p class="first">Source line offset. This number represents the line number
+in the function where the sample was collected. The line number is
+always relative to the line where symbol of the function is
+defined. So, if the function has its header at line 280, the offset
+13 is at line 293 in the file.</p>
+<p>Note that this offset should never be a negative number. This could
+happen in cases like macros. The debug machinery will register the
+line number at the point of macro expansion. So, if the macro was
+expanded in a line before the start of the function, the profile
+converter should emit a 0 as the offset (this means that the optimizers
+will not be able to associate a meaningful weight to the instructions
+in the macro).</p>
+</li>
+<li><p class="first">[OPTIONAL] Discriminator. This is used if the sampled program
+was compiled with DWARF discriminator support
+(<a class="reference external" href="http://wiki.dwarfstd.org/index.php?title=Path_Discriminators">http://wiki.dwarfstd.org/index.php?title=Path_Discriminators</a>).
+DWARF discriminators are unsigned integer values that allow the
+compiler to distinguish between multiple execution paths on the
+same source line location.</p>
+<p>For example, consider the line of code <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(cond)</span> <span class="pre">foo();</span> <span class="pre">else</span> <span class="pre">bar();</span></tt>.
+If the predicate <tt class="docutils literal"><span class="pre">cond</span></tt> is true 80% of the time, then the edge
+into function <tt class="docutils literal"><span class="pre">foo</span></tt> should be considered to be taken most of the
+time. But both calls to <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> are at the same source
+line, so a sample count at that line is not sufficient. The
+compiler needs to know which part of that line is taken more
+frequently.</p>
+<p>This is what discriminators provide. In this case, the calls to
+<tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> will be at the same line, but will have
+different discriminator values. This allows the compiler to correctly
+set edge weights into <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt>.</p>
+</li>
+<li><p class="first">Number of samples. This is an integer quantity representing the
+number of samples collected by the profiler at this source
+location.</p>
+</li>
+<li><p class="first">[OPTIONAL] Potential call targets and samples. If present, this
+line contains a call instruction. This models both direct and
+number of samples. For example,</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">130: 7  foo:3  bar:2  baz:7</span>
+</pre></div>
+</div>
+<p>The above means that at relative line offset 130 there is a call
+instruction that calls one of <tt class="docutils literal"><span class="pre">foo()</span></tt>, <tt class="docutils literal"><span class="pre">bar()</span></tt> and <tt class="docutils literal"><span class="pre">baz()</span></tt>,
+with <tt class="docutils literal"><span class="pre">baz()</span></tt> being the relatively more frequently called target.</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="section" id="profiling-with-instrumentation">
+<h4><a class="toc-backref" href="#id38">Profiling with Instrumentation</a><a class="headerlink" href="#profiling-with-instrumentation" title="Permalink to this headline">Â¶</a></h4>
+<p>Clang also supports profiling via instrumentation. This requires building a
+special instrumented version of the code and has some runtime
+overhead during the profiling, but it provides more detailed results than a
+sampling profiler. It also provides reproducible results, at least to the
+extent that the code behaves consistently across runs.</p>
+<p>Here are the steps for using profile guided optimization with
+instrumentation:</p>
+<ol class="arabic">
+<li><p class="first">Build an instrumented version of the code by compiling and linking with the
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> option.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-instr-generate code.cc -o code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the instrumented executable with inputs that reflect the typical usage.
+By default, the profile data will be written to a <tt class="docutils literal"><span class="pre">default.profraw</span></tt> file
+in the current directory. You can override that default by setting the
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> environment variable to specify an alternate file.
+Any instance of <tt class="docutils literal"><span class="pre">%p</span></tt> in that file name will be replaced by the process
+ID, so that you can easily distinguish the profile output from multiple
+runs.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"code-%p.profraw"</span> ./code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Combine profiles from multiple runs and convert the “raw” profile format to
+the input expected by clang. Use the <tt class="docutils literal"><span class="pre">merge</span></tt> command of the
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool to do this.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>code.profdata code-*.profraw
+</pre></div>
+</div>
+<p>Note that this step is necessary even when there is only one “raw” profile,
+since the merge operation also changes the file format.</p>
+</li>
+<li><p class="first">Build the code again using the <tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt> option to specify the
+collected profile data.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-instr-use<span class="o">=</span>code.profdata code.cc -o code
+</pre></div>
+</div>
+<p>You can repeat step 4 as often as you like without regenerating the
+profile. As you make changes to your code, clang may no longer be able to
+use the profile data. It will warn you when this happens.</p>
+</li>
+</ol>
+<p>Profile generation and use can also be controlled by the GCC-compatible flags
+<tt class="docutils literal"><span class="pre">-fprofile-generate</span></tt> and <tt class="docutils literal"><span class="pre">-fprofile-use</span></tt>. Although these flags are
+semantically equivalent to their GCC counterparts, they <em>do not</em> handle
+GCC-compatible profiles. They are only meant to implement GCC’s semantics
+with respect to profile creation and use.</p>
+<dl class="option">
+<dt id="cmdoption-fprofile-generate">
+<tt class="descname">-fprofile-generate</tt><tt class="descclassname">[=<dirname>]</tt><a class="headerlink" href="#cmdoption-fprofile-generate" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Without any other arguments, <tt class="docutils literal"><span class="pre">-fprofile-generate</span></tt> behaves identically to
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt>. When given a directory name, it generates the
+profile file <tt class="docutils literal"><span class="pre">default.profraw</span></tt> in the directory named <tt class="docutils literal"><span class="pre">dirname</span></tt>. If
+<tt class="docutils literal"><span class="pre">dirname</span></tt> does not exist, it will be created at runtime. The environment
+variable <tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> can be used to override the directory and
+filename for the profile file at runtime. For example,</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-generate<span class="o">=</span>yyy/zzz code.cc -o code
+</pre></div>
+</div>
+<p>When <tt class="docutils literal"><span class="pre">code</span></tt> is executed, the profile will be written to the file
+<tt class="docutils literal"><span class="pre">yyy/zzz/default.profraw</span></tt>. This can be altered at runtime via the
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> environment variable:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span>/tmp/myprofile/code.profraw ./code
+</pre></div>
+</div>
+<p>The above invocation will produce the profile file
+<tt class="docutils literal"><span class="pre">/tmp/myprofile/code.profraw</span></tt> instead of <tt class="docutils literal"><span class="pre">yyy/zzz/default.profraw</span></tt>.
+Notice that <tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> overrides the directory <em>and</em> the file
+name for the profile file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fprofile-use">
+<tt class="descname">-fprofile-use</tt><tt class="descclassname">[=<pathname>]</tt><a class="headerlink" href="#cmdoption-fprofile-use" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Without any other arguments, <tt class="docutils literal"><span class="pre">-fprofile-use</span></tt> behaves identically to
+<tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt>. Otherwise, if <tt class="docutils literal"><span class="pre">pathname</span></tt> is the full path to a
+profile file, it reads from that file. If <tt class="docutils literal"><span class="pre">pathname</span></tt> is a directory name,
+it reads from <tt class="docutils literal"><span class="pre">pathname/default.profdata</span></tt>.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="controlling-size-of-debug-information">
+<h3><a class="toc-backref" href="#id39">Controlling Size of Debug Information</a><a class="headerlink" href="#controlling-size-of-debug-information" title="Permalink to this headline">Â¶</a></h3>
+<p>Debug info kind generated by Clang can be set by one of the flags listed
+below. If multiple flags are present, the last one is used.</p>
+<dl class="option">
+<dt id="cmdoption-g0">
+<tt class="descname">-g0</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-g0" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Don’t generate any debug info (default).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-gline-tables-only">
+<tt class="descname">-gline-tables-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-gline-tables-only" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Generate line number tables only.</p>
+<p>This kind of debug info allows to obtain stack traces with function names,
+file names and line numbers (by such tools as <tt class="docutils literal"><span class="pre">gdb</span></tt> or <tt class="docutils literal"><span class="pre">addr2line</span></tt>).  It
+doesn’t contain any other data (e.g. description of local variables or
+function parameters).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstandalone-debug">
+<tt class="descname">-fstandalone-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fstandalone-debug" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Clang supports a number of optimizations to reduce the size of debug
+information in the binary. They work based on the assumption that
+the debug type information can be spread out over multiple
+compilation units.  For instance, Clang will not emit type
+definitions for types that are not needed by a module and could be
+replaced with a forward declaration.  Further, Clang will only emit
+type info for a dynamic C++ class in the module that contains the
+vtable for the class.</p>
+<p>The <strong>-fstandalone-debug</strong> option turns off these optimizations.
+This is useful when working with 3rd-party libraries that don’t come
+with debug information.  Note that Clang will never emit type
+information for types that are not referenced at all by the program.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-standalone-debug">
+<tt class="descname">-fno-standalone-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-standalone-debug" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>On Darwin <strong>-fstandalone-debug</strong> is enabled by default. The
+<strong>-fno-standalone-debug</strong> option can be used to get to turn on the
+vtable-based optimization described above.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-g">
+<tt class="descname">-g</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-g" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Generate complete debug info.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="comment-parsing-options">
+<h3><a class="toc-backref" href="#id40">Comment Parsing Options</a><a class="headerlink" href="#comment-parsing-options" title="Permalink to this headline">Â¶</a></h3>
+<p>Clang parses Doxygen and non-Doxygen style documentation comments and attaches
+them to the appropriate declaration nodes.  By default, it only parses
+Doxygen-style comments and ignores ordinary comments starting with <tt class="docutils literal"><span class="pre">//</span></tt> and
+<tt class="docutils literal"><span class="pre">/*</span></tt>.</p>
+<dl class="option">
+<dt id="cmdoption-Wdocumentation">
+<tt class="descname">-Wdocumentation</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wdocumentation" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Emit warnings about use of documentation comments.  This warning group is off
+by default.</p>
+<p>This includes checking that <tt class="docutils literal"><span class="pre">\param</span></tt> commands name parameters that actually
+present in the function signature, checking that <tt class="docutils literal"><span class="pre">\returns</span></tt> is used only on
+functions that actually return a value etc.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wno-documentation-unknown-command">
+<tt class="descname">-Wno-documentation-unknown-command</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wno-documentation-unknown-command" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Don’t warn when encountering an unknown Doxygen command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fparse-all-comments">
+<tt class="descname">-fparse-all-comments</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fparse-all-comments" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Parse all comments as documentation comments (including ordinary comments
+starting with <tt class="docutils literal"><span class="pre">//</span></tt> and <tt class="docutils literal"><span class="pre">/*</span></tt>).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fcomment-block-commands">
+<tt class="descname">-fcomment-block-commands</tt><tt class="descclassname">=[commands]</tt><a class="headerlink" href="#cmdoption-fcomment-block-commands" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Define custom documentation commands as block commands.  This allows Clang to
+construct the correct AST for these custom commands, and silences warnings
+about unknown commands.  Several commands must be separated by a comma
+<em>without trailing space</em>; e.g. <tt class="docutils literal"><span class="pre">-fcomment-block-commands=foo,bar</span></tt> defines
+custom commands <tt class="docutils literal"><span class="pre">\foo</span></tt> and <tt class="docutils literal"><span class="pre">\bar</span></tt>.</p>
+<p>It is also possible to use <tt class="docutils literal"><span class="pre">-fcomment-block-commands</span></tt> several times; e.g.
+<tt class="docutils literal"><span class="pre">-fcomment-block-commands=foo</span> <span class="pre">-fcomment-block-commands=bar</span></tt> does the same
+as above.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="c-language-features">
+<span id="c"></span><h2><a class="toc-backref" href="#id41">C Language Features</a><a class="headerlink" href="#c-language-features" title="Permalink to this headline">Â¶</a></h2>
+<p>The support for standard C in clang is feature-complete except for the
+C99 floating-point pragmas.</p>
+<div class="section" id="extensions-supported-by-clang">
+<h3><a class="toc-backref" href="#id42">Extensions supported by clang</a><a class="headerlink" href="#extensions-supported-by-clang" title="Permalink to this headline">Â¶</a></h3>
+<p>See <a class="reference internal" href="LanguageExtensions.html"><em>Clang Language Extensions</em></a>.</p>
+</div>
+<div class="section" id="differences-between-various-standard-modes">
+<h3><a class="toc-backref" href="#id43">Differences between various standard modes</a><a class="headerlink" href="#differences-between-various-standard-modes" title="Permalink to this headline">Â¶</a></h3>
+<p>clang supports the -std option, which changes what language mode clang
+uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11,
+gnu11, and various aliases for those modes. If no -std option is
+specified, clang defaults to gnu11 mode. Many C99 and C11 features are
+supported in earlier modes as a conforming extension, with a warning. Use
+<tt class="docutils literal"><span class="pre">-pedantic-errors</span></tt> to request an error if a feature from a later standard
+revision is used in an earlier mode.</p>
+<p>Differences between all <tt class="docutils literal"><span class="pre">c*</span></tt> and <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">c*</span></tt> modes define “<tt class="docutils literal"><span class="pre">__STRICT_ANSI__</span></tt>”.</li>
+<li>Target-specific defines not prefixed by underscores, like “linux”,
+are defined in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes.</li>
+<li>Trigraphs default to being off in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes; they can be enabled by
+the -trigraphs option.</li>
+<li>The parser recognizes “asm” and “typeof” as keywords in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes;
+the variants “<tt class="docutils literal"><span class="pre">__asm__</span></tt>” and “<tt class="docutils literal"><span class="pre">__typeof__</span></tt>” are recognized in all
+modes.</li>
+<li>The Apple “blocks” extension is recognized by default in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes
+on some platforms; it can be enabled in any mode with the “-fblocks”
+option.</li>
+<li>Arrays that are VLA’s according to the standard, but which can be
+constant folded by the frontend are treated as fixed size arrays.
+This occurs for things like “int X[(1, 2)];”, which is technically a
+VLA. <tt class="docutils literal"><span class="pre">c*</span></tt> modes are strictly compliant and treat these as VLAs.</li>
+</ul>
+<p>Differences between <tt class="docutils literal"><span class="pre">*89</span></tt> and <tt class="docutils literal"><span class="pre">*99</span></tt> modes:</p>
+<ul class="simple">
+<li>The <tt class="docutils literal"><span class="pre">*99</span></tt> modes default to implementing “inline” as specified in C99,
+while the <tt class="docutils literal"><span class="pre">*89</span></tt> modes implement the GNU version. This can be
+overridden for individual functions with the <tt class="docutils literal"><span class="pre">__gnu_inline__</span></tt>
+attribute.</li>
+<li>Digraphs are not recognized in c89 mode.</li>
+<li>The scope of names defined inside a “for”, “if”, “switch”, “while”,
+or “do” statement is different. (example: “<tt class="docutils literal"><span class="pre">if</span> <span class="pre">((struct</span> <span class="pre">x</span> <span class="pre">{int</span>
+<span class="pre">x;}*)0)</span> <span class="pre">{}</span></tt>”.)</li>
+<li><tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> is not defined in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>“inline” is not recognized as a keyword in c89 mode.</li>
+<li>“restrict” is not recognized as a keyword in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>Commas are allowed in integer constant expressions in <tt class="docutils literal"><span class="pre">*99</span></tt> modes.</li>
+<li>Arrays which are not lvalues are not implicitly promoted to pointers
+in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>Some warnings are different.</li>
+</ul>
+<p>Differences between <tt class="docutils literal"><span class="pre">*99</span></tt> and <tt class="docutils literal"><span class="pre">*11</span></tt> modes:</p>
+<ul class="simple">
+<li>Warnings for use of C11 features are disabled.</li>
+<li><tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> is defined to <tt class="docutils literal"><span class="pre">201112L</span></tt> rather than <tt class="docutils literal"><span class="pre">199901L</span></tt>.</li>
+</ul>
+<p>c94 mode is identical to c89 mode except that digraphs are enabled in
+c94 mode (FIXME: And <tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> should be defined!).</p>
+</div>
+<div class="section" id="gcc-extensions-not-implemented-yet">
+<h3><a class="toc-backref" href="#id44">GCC extensions not implemented yet</a><a class="headerlink" href="#gcc-extensions-not-implemented-yet" title="Permalink to this headline">Â¶</a></h3>
+<p>clang tries to be compatible with gcc as much as possible, but some gcc
+extensions are not implemented yet:</p>
+<ul>
+<li><p class="first">clang does not support #pragma weak (<a class="reference external" href="http://llvm.org/bugs/show_bug.cgi?id=3679">bug
+3679</a>). Due to the uses
+described in the bug, this is likely to be implemented at some point,
+at least partially.</p>
+</li>
+<li><p class="first">clang does not support decimal floating point types (<tt class="docutils literal"><span class="pre">_Decimal32</span></tt> and
+friends) or fixed-point types (<tt class="docutils literal"><span class="pre">_Fract</span></tt> and friends); nobody has
+expressed interest in these features yet, so it’s hard to say when
+they will be implemented.</p>
+</li>
+<li><p class="first">clang does not support nested functions; this is a complex feature
+which is infrequently used, so it is unlikely to be implemented
+anytime soon. In C++11 it can be emulated by assigning lambda
+functions to local variables, e.g:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span class="k">auto</span> <span class="k">const</span> <span class="n">local_function</span> <span class="o">=</span> <span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="kt">int</span> <span class="n">parameter</span><span class="p">)</span> <span class="p">{</span>
+  <span class="c1">// Do something</span>
+<span class="p">};</span>
+<span class="p">...</span>
+<span class="n">local_function</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">clang does not support global register variables; this is unlikely to
+be implemented soon because it requires additional LLVM backend
+support.</p>
+</li>
+<li><p class="first">clang does not support static initialization of flexible array
+members. This appears to be a rarely used extension, but could be
+implemented pending user demand.</p>
+</li>
+<li><p class="first">clang does not support
+<tt class="docutils literal"><span class="pre">__builtin_va_arg_pack</span></tt>/<tt class="docutils literal"><span class="pre">__builtin_va_arg_pack_len</span></tt>. This is
+used rarely, but in some potentially interesting places, like the
+glibc headers, so it may be implemented pending user demand. Note
+that because clang pretends to be like GCC 4.2, and this extension
+was introduced in 4.3, the glibc headers will not try to use this
+extension with clang at the moment.</p>
+</li>
+<li><p class="first">clang does not support the gcc extension for forward-declaring
+function parameters; this has not shown up in any real-world code
+yet, though, so it might never be implemented.</p>
+</li>
+</ul>
+<p>This is not a complete list; if you find an unsupported extension
+missing from this list, please send an e-mail to cfe-dev. This list
+currently excludes C++; see <a class="reference internal" href="#cxx"><em>C++ Language Features</em></a>. Also, this
+list does not include bugs in mostly-implemented features; please see
+the <a class="reference external" href="http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer">bug
+tracker</a>
+for known existing bugs (FIXME: Is there a section for bug-reporting
+guidelines somewhere?).</p>
+</div>
+<div class="section" id="intentionally-unsupported-gcc-extensions">
+<h3><a class="toc-backref" href="#id45">Intentionally unsupported GCC extensions</a><a class="headerlink" href="#intentionally-unsupported-gcc-extensions" title="Permalink to this headline">Â¶</a></h3>
+<ul class="simple">
+<li>clang does not support the gcc extension that allows variable-length
+arrays in structures. This is for a few reasons: one, it is tricky to
+implement, two, the extension is completely undocumented, and three,
+the extension appears to be rarely used. Note that clang <em>does</em>
+support flexible array members (arrays with a zero or unspecified
+size at the end of a structure).</li>
+<li>clang does not have an equivalent to gcc’s “fold”; this means that
+clang doesn’t accept some constructs gcc might accept in contexts
+where a constant expression is required, like “x-x” where x is a
+variable.</li>
+<li>clang does not support <tt class="docutils literal"><span class="pre">__builtin_apply</span></tt> and friends; this extension
+is extremely obscure and difficult to implement reliably.</li>
+</ul>
+</div>
+<div class="section" id="microsoft-extensions">
+<span id="c-ms"></span><h3><a class="toc-backref" href="#id46">Microsoft extensions</a><a class="headerlink" href="#microsoft-extensions" title="Permalink to this headline">Â¶</a></h3>
+<p>clang has some experimental support for extensions from Microsoft Visual
+C++; to enable it, use the <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> command-line option. This is
+the default for Windows targets. Note that the support is incomplete.
+Some constructs such as <tt class="docutils literal"><span class="pre">dllexport</span></tt> on classes are ignored with a warning,
+and others such as <a class="reference external" href="http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx">Microsoft IDL annotations</a> are silently
+ignored.</p>
+<p>clang has a <tt class="docutils literal"><span class="pre">-fms-compatibility</span></tt> flag that makes clang accept enough
+invalid C++ to be able to parse most Microsoft headers. For example, it
+allows <a class="reference external" href="http://clang.llvm.org/compatibility.html#dep_lookup_bases">unqualified lookup of dependent base class members</a>, which is
+a common compatibility issue with clang. This flag is enabled by default
+for Windows targets.</p>
+<p><tt class="docutils literal"><span class="pre">-fdelayed-template-parsing</span></tt> lets clang delay parsing of function template
+definitions until the end of a translation unit. This flag is enabled by
+default for Windows targets.</p>
+<ul class="simple">
+<li>clang allows setting <tt class="docutils literal"><span class="pre">_MSC_VER</span></tt> with <tt class="docutils literal"><span class="pre">-fmsc-version=</span></tt>. It defaults to
+1700 which is the same as Visual C/C++ 2012. Any number is supported
+and can greatly affect what Windows SDK and c++stdlib headers clang
+can compile.</li>
+<li>clang does not support the Microsoft extension where anonymous record
+members can be declared using user defined typedefs.</li>
+<li>clang supports the Microsoft <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">pack</span></tt> feature for controlling
+record layout. GCC also contains support for this feature, however
+where MSVC and GCC are incompatible clang follows the MSVC
+definition.</li>
+<li>clang supports the Microsoft <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">comment(lib,</span> <span class="pre">"foo.lib")</span></tt> feature for
+automatically linking against the specified library.  Currently this feature
+only works with the Visual C++ linker.</li>
+<li>clang supports the Microsoft <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">comment(linker,</span> <span class="pre">"/flag:foo")</span></tt> feature
+for adding linker flags to COFF object files.  The user is responsible for
+ensuring that the linker understands the flags.</li>
+<li>clang defaults to C++11 for Windows targets.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="cxx">
+<span id="id3"></span><h2><a class="toc-backref" href="#id47">C++ Language Features</a><a class="headerlink" href="#cxx" title="Permalink to this headline">Â¶</a></h2>
+<p>clang fully implements all of standard C++98 except for exported
+templates (which were removed in C++11), and all of standard C++11
+and the current draft standard for C++1y.</p>
+<div class="section" id="controlling-implementation-limits">
+<h3><a class="toc-backref" href="#id48">Controlling implementation limits</a><a class="headerlink" href="#controlling-implementation-limits" title="Permalink to this headline">Â¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fbracket-depth">
+<tt class="descname">-fbracket-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-fbracket-depth" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Sets the limit for nested parentheses, brackets, and braces to N.  The
+default is 256.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fconstexpr-depth">
+<tt class="descname">-fconstexpr-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-fconstexpr-depth" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Sets the limit for recursive constexpr function invocations to N.  The
+default is 512.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-depth">
+<tt class="descname">-ftemplate-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-ftemplate-depth" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Sets the limit for recursively nested template instantiations to N.  The
+default is 256.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-foperator-arrow-depth">
+<tt class="descname">-foperator-arrow-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-foperator-arrow-depth" title="Permalink to this definition">Â¶</a></dt>
+<dd><p>Sets the limit for iterative calls to ‘operator->’ functions to N.  The
+default is 256.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="objective-c-language-features">
+<span id="objc"></span><h2><a class="toc-backref" href="#id49">Objective-C Language Features</a><a class="headerlink" href="#objective-c-language-features" title="Permalink to this headline">Â¶</a></h2>
+</div>
+<div class="section" id="objcxx">
+<span id="id4"></span><h2><a class="toc-backref" href="#id50">Objective-C++ Language Features</a><a class="headerlink" href="#objcxx" title="Permalink to this headline">Â¶</a></h2>
+</div>
+<div class="section" id="target-specific-features-and-limitations">
+<span id="target-features"></span><h2><a class="toc-backref" href="#id51">Target-Specific Features and Limitations</a><a class="headerlink" href="#target-specific-features-and-limitations" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="cpu-architectures-features-and-limitations">
+<h3><a class="toc-backref" href="#id52">CPU Architectures Features and Limitations</a><a class="headerlink" href="#cpu-architectures-features-and-limitations" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="x86">
+<h4><a class="toc-backref" href="#id53">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">Â¶</a></h4>
+<p>The support for X86 (both 32-bit and 64-bit) is considered stable on
+Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
+to correctly compile many large C, C++, Objective-C, and Objective-C++
+codebases.</p>
+<p>On <tt class="docutils literal"><span class="pre">x86_64-mingw32</span></tt>, passing i128(by value) is incompatible with the
+Microsoft x64 calling convention. You might need to tweak
+<tt class="docutils literal"><span class="pre">WinX86_64ABIInfo::classify()</span></tt> in lib/CodeGen/TargetInfo.cpp.</p>
+<p>For the X86 target, clang supports the <em class="xref std std-option">-m16</em> command line
+argument which enables 16-bit code output. This is broadly similar to
+using <tt class="docutils literal"><span class="pre">asm(".code16gcc")</span></tt> with the GNU toolchain. The generated code
+and the ABI remains 32-bit but the assembler emits instructions
+appropriate for a CPU running in 16-bit mode, with address-size and
+operand-size prefixes to enable 32-bit addressing and operations.</p>
+</div>
+<div class="section" id="arm">
+<h4><a class="toc-backref" href="#id54">ARM</a><a class="headerlink" href="#arm" title="Permalink to this headline">Â¶</a></h4>
+<p>The support for ARM (specifically ARMv6 and ARMv7) is considered stable
+on Darwin (iOS): it has been tested to correctly compile many large C,
+C++, Objective-C, and Objective-C++ codebases. Clang only supports a
+limited number of ARM architectures. It does not yet fully support
+ARMv5, for example.</p>
+</div>
+<div class="section" id="powerpc">
+<h4><a class="toc-backref" href="#id55">PowerPC</a><a class="headerlink" href="#powerpc" title="Permalink to this headline">Â¶</a></h4>
+<p>The support for PowerPC (especially PowerPC64) is considered stable
+on Linux and FreeBSD: it has been tested to correctly compile many
+large C and C++ codebases. PowerPC (32bit) is still missing certain
+features (e.g. PIC code on ELF platforms).</p>
+</div>
+<div class="section" id="other-platforms">
+<h4><a class="toc-backref" href="#id56">Other platforms</a><a class="headerlink" href="#other-platforms" title="Permalink to this headline">Â¶</a></h4>
+<p>clang currently contains some support for other architectures (e.g. Sparc);
+however, significant pieces of code generation are still missing, and they
+haven’t undergone significant testing.</p>
+<p>clang contains limited support for the MSP430 embedded processor, but
+both the clang support and the LLVM backend support are highly
+experimental.</p>
+<p>Other platforms are completely unsupported at the moment. Adding the
+minimal support needed for parsing and semantic analysis on a new
+platform is quite easy; see <tt class="docutils literal"><span class="pre">lib/Basic/Targets.cpp</span></tt> in the clang source
+tree. This level of support is also sufficient for conversion to LLVM IR
+for simple programs. Proper support for conversion to LLVM IR requires
+adding code to <tt class="docutils literal"><span class="pre">lib/CodeGen/CGCall.cpp</span></tt> at the moment; this is likely to
+change soon, though. Generating assembly requires a suitable LLVM
+backend.</p>
+</div>
+</div>
+<div class="section" id="operating-system-features-and-limitations">
+<h3><a class="toc-backref" href="#id57">Operating System Features and Limitations</a><a class="headerlink" href="#operating-system-features-and-limitations" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="darwin-mac-os-x">
+<h4><a class="toc-backref" href="#id58">Darwin (Mac OS X)</a><a class="headerlink" href="#darwin-mac-os-x" title="Permalink to this headline">Â¶</a></h4>
+<p>Thread Sanitizer is not supported.</p>
+</div>
+<div class="section" id="windows">
+<h4><a class="toc-backref" href="#id59">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">Â¶</a></h4>
+<p>Clang has experimental support for targeting “Cygming” (Cygwin / MinGW)
+platforms.</p>
+<p>See also <a class="reference internal" href="#c-ms"><em>Microsoft Extensions</em></a>.</p>
+<div class="section" id="cygwin">
+<h5><a class="toc-backref" href="#id60">Cygwin</a><a class="headerlink" href="#cygwin" title="Permalink to this headline">Â¶</a></h5>
+<p>Clang works on Cygwin-1.7.</p>
+</div>
+<div class="section" id="mingw32">
+<h5><a class="toc-backref" href="#id61">MinGW32</a><a class="headerlink" href="#mingw32" title="Permalink to this headline">Â¶</a></h5>
+<p>Clang works on some mingw32 distributions. Clang assumes directories as
+below;</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">C:/mingw/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">C:/mingw/lib</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++</span></tt></li>
+</ul>
+<p>On MSYS, a few tests might fail.</p>
+</div>
+<div class="section" id="mingw-w64">
+<h5><a class="toc-backref" href="#id62">MinGW-w64</a><a class="headerlink" href="#mingw-w64" title="Permalink to this headline">Â¶</a></h5>
+<p>For 32-bit (i686-w64-mingw32), and 64-bit (x86_64-w64-mingw32), Clang
+assumes as below;</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">GCC</span> <span class="pre">versions</span> <span class="pre">4.5.0</span> <span class="pre">to</span> <span class="pre">4.5.3,</span> <span class="pre">4.6.0</span> <span class="pre">to</span> <span class="pre">4.6.2,</span> <span class="pre">or</span> <span class="pre">4.7.0</span> <span class="pre">(for</span> <span class="pre">the</span> <span class="pre">C++</span> <span class="pre">header</span> <span class="pre">search</span> <span class="pre">path)</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/gcc.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/clang.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/clang++.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/backward</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../x86_64-w64-mingw32/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../i686-w64-mingw32/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include</span></tt></li>
+</ul>
+<p>This directory layout is standard for any toolchain you will find on the
+official <a class="reference external" href="http://mingw-w64.sourceforge.net">MinGW-w64 website</a>.</p>
+<p>Clang expects the GCC executable “gcc.exe” compiled for
+<tt class="docutils literal"><span class="pre">i686-w64-mingw32</span></tt> (or <tt class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></tt>) to be present on PATH.</p>
+<p><a class="reference external" href="http://llvm.org/bugs/show_bug.cgi?id=9072">Some tests might fail</a> on
+<tt class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></tt>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="clang-cl">
+<span id="id5"></span><h2><a class="toc-backref" href="#id63">clang-cl</a><a class="headerlink" href="#clang-cl" title="Permalink to this headline">Â¶</a></h2>
+<p>clang-cl is an alternative command-line interface to Clang driver, designed for
+compatibility with the Visual C++ compiler, cl.exe.</p>
+<p>To enable clang-cl to find system headers, libraries, and the linker when run
+from the command-line, it should be executed inside a Visual Studio Native Tools
+Command Prompt or a regular Command Prompt where the environment has been set
+up using e.g. <a class="reference external" href="http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx">vcvars32.bat</a>.</p>
+<p>clang-cl can also be used from inside Visual Studio  by using an LLVM Platform
+Toolset.</p>
+<div class="section" id="id6">
+<h3><a class="toc-backref" href="#id64">Command-Line Options</a><a class="headerlink" href="#id6" title="Permalink to this headline">Â¶</a></h3>
+<p>To be compatible with cl.exe, clang-cl supports most of the same command-line
+options. Those options can start with either <tt class="docutils literal"><span class="pre">/</span></tt> or <tt class="docutils literal"><span class="pre">-</span></tt>. It also supports
+some of Clang’s core options, such as the <tt class="docutils literal"><span class="pre">-W</span></tt> options.</p>
+<p>Options that are known to clang-cl, but not currently supported, are ignored
+with a warning. For example:</p>
+<blockquote>
+<div><div class="highlight-python"><div class="highlight"><pre>clang-cl.exe: warning: argument unused during compilation: '/AI'
+</pre></div>
+</div>
+</div></blockquote>
+<p>To suppress warnings about unused arguments, use the <tt class="docutils literal"><span class="pre">-Qunused-arguments</span></tt> option.</p>
+<p>Options that are not known to clang-cl will cause errors. If they are spelled with a
+leading <tt class="docutils literal"><span class="pre">/</span></tt>, they will be mistaken for a filename:</p>
+<blockquote>
+<div><div class="highlight-python"><div class="highlight"><pre>clang-cl.exe: error: no such file or directory: '/foobar'
+</pre></div>
+</div>
+</div></blockquote>
+<p>Please <a class="reference external" href="http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver">file a bug</a>
+for any valid cl.exe flags that clang-cl does not understand.</p>
+<p>Execute <tt class="docutils literal"><span class="pre">clang-cl</span> <span class="pre">/?</span></tt> to see a list of supported options:</p>
+<blockquote>
+<div><div class="highlight-python"><div class="highlight"><pre>CL.EXE COMPATIBILITY OPTIONS:
+  /?                     Display available options
+  /arch:<value>          Set architecture for code generation
+  /C                     Don't discard comments when preprocessing
+  /c                     Compile only
+  /D <macro[=value]>     Define macro
+  /EH<value>             Exception handling model
+  /EP                    Disable linemarker output and preprocess to stdout
+  /E                     Preprocess to stdout
+  /fallback              Fall back to cl.exe if clang-cl fails to compile
+  /FA                    Output assembly code file during compilation
+  /Fa<file or directory> Output assembly code to this file during compilation (with /FA)
+  /Fe<file or directory> Set output executable file or directory (ends in / or \)
+  /FI <value>            Include file before parsing
+  /Fi<file>              Set preprocess output file name (with /P)
+  /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
+  /fp:except-
+  /fp:except
+  /fp:fast
+  /fp:precise
+  /fp:strict
+  /GA                    Assume thread-local variables are defined in the executable
+  /GF-                   Disable string pooling
+  /GR-                   Disable emission of RTTI data
+  /GR                    Enable emission of RTTI data
+  /Gs<value>             Set stack probe size
+  /Gw-                   Don't put each data item in its own section
+  /Gw                    Put each data item in its own section
+  /Gy-                   Don't put each function in its own section
+  /Gy                    Put each function in its own section
+  /help                  Display available options
+  /I <dir>               Add directory to include search path
+  /J                     Make char type unsigned
+  /LDd                   Create debug DLL
+  /LD                    Create DLL
+  /link <options>        Forward options to the linker
+  /MDd                   Use DLL debug run-time
+  /MD                    Use DLL run-time
+  /MTd                   Use static debug run-time
+  /MT                    Use static run-time
+  /Ob0                   Disable inlining
+  /Od                    Disable optimization
+  /Oi-                   Disable use of builtin functions
+  /Oi                    Enable use of builtin functions
+  /Os                    Optimize for size
+  /Ot                    Optimize for speed
+  /Ox                    Maximum optimization
+  /Oy-                   Disable frame pointer omission
+  /Oy                    Enable frame pointer omission
+  /O<n>                  Optimization level
+  /o <file or directory> Set output file or directory (ends in / or \)
+  /P                     Preprocess to file
+  /Qvec-                 Disable the loop vectorization passes
+  /Qvec                  Enable the loop vectorization passes
+  /showIncludes          Print info about included files to stderr
+  /TC                    Treat all source files as C
+  /Tc <filename>         Specify a C source file
+  /TP                    Treat all source files as C++
+  /Tp <filename>         Specify a C++ source file
+  /U <macro>             Undefine macro
+  /vd<value>             Control vtordisp placement
+  /vmb                   Use a best-case representation method for member pointers
+  /vmg                   Use a most-general representation for member pointers
+  /vmm                   Set the default most-general representation to multiple inheritance
+  /vms                   Set the default most-general representation to single inheritance
+  /vmv                   Set the default most-general representation to virtual inheritance
+  /volatile:iso          Volatile loads and stores have standard semantics
+  /volatile:ms           Volatile loads and stores have acquire and release semantics
+  /W0                    Disable all warnings
+  /W1                    Enable -Wall
+  /W2                    Enable -Wall
+  /W3                    Enable -Wall
+  /W4                    Enable -Wall
+  /Wall                  Enable -Wall
+  /WX-                   Do not treat warnings as errors
+  /WX                    Treat warnings as errors
+  /w                     Disable all warnings
+  /Zc:sizedDealloc-      Disable C++14 sized global deallocation functions
+  /Zc:sizedDealloc       Enable C++14 sized global deallocation functions
+  /Zc:strictStrings      Treat string literals as const
+  /Zc:threadSafeInit-    Disable thread-safe initialization of static variables
+  /Zc:threadSafeInit     Enable thread-safe initialization of static variables
+  /Zc:trigraphs-         Disable trigraphs (default)
+  /Zc:trigraphs          Enable trigraphs
+  /Zi                    Enable debug information
+  /Zp                    Set the default maximum struct packing alignment to 1
+  /Zp<value>             Specify the default maximum struct packing alignment
+  /Zs                    Syntax-check only
+
+OPTIONS:
+  -###                    Print (but do not run) the commands to run for this compilation
+  --analyze               Run the static analyzer
+  -fansi-escape-codes     Use ANSI escape codes for diagnostics
+  -fcolor-diagnostics     Use colors in diagnostics
+  -fdiagnostics-parseable-fixits
+                          Print fix-its in machine parseable form
+  -fms-compatibility-version=<value>
+                          Dot-separated value representing the Microsoft compiler version
+                          number to report in _MSC_VER (0 = don't define it (default))
+  -fmsc-version=<value>   Microsoft compiler version number to report in _MSC_VER (0 = don't
+                          define it (default))
+  -fno-sanitize-coverage=<value>
+                          Disable specified features of coverage instrumentation for Sanitizers
+  -fno-sanitize-recover=<value>
+                          Disable recovery for specified sanitizers
+  -fno-sanitize-trap=<value>
+                          Disable trapping for specified sanitizers
+  -fsanitize-blacklist=<value>
+                          Path to blacklist file for sanitizers
+  -fsanitize-coverage=<value>
+                          Specify the type of coverage instrumentation for Sanitizers
+  -fsanitize-recover=<value>
+                          Enable recovery for specified sanitizers
+  -fsanitize-trap=<value> Enable trapping for specified sanitizers
+  -fsanitize=<check>      Turn on runtime checks for various forms of undefined or suspicious
+                          behavior. See user manual for available checks
+  -mllvm <value>          Additional arguments to forward to LLVM's option processing
+  -Qunused-arguments      Don't emit warning for unused driver arguments
+  -R<remark>              Enable the specified remark
+  --target=<value>        Generate code for the given target
+  -v                      Show commands to run and use verbose output
+  -W<warning>             Enable the specified warning
+  -Xclang <arg>           Pass <arg> to the clang compiler
+</pre></div>
+</div>
+</div></blockquote>
+<div class="section" id="the-fallback-option">
+<h4><a class="toc-backref" href="#id65">The /fallback Option</a><a class="headerlink" href="#the-fallback-option" title="Permalink to this headline">Â¶</a></h4>
+<p>When clang-cl is run with the <tt class="docutils literal"><span class="pre">/fallback</span></tt> option, it will first try to
+compile files itself. For any file that it fails to compile, it will fall back
+and try to compile the file by invoking cl.exe.</p>
+<p>This option is intended to be used as a temporary means to build projects where
+clang-cl cannot successfully compile all the files. clang-cl may fail to compile
+a file either because it cannot generate code for some C++ feature, or because
+it cannot parse some Microsoft language extension.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ReleaseNotes.html">Clang 3.7 Release Notes</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LanguageExtensions.html">Clang Language Extensions</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2015, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.7.0/tools/clang/docs/_images/DriverArchitecture.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/_images/DriverArchitecture.png?rev=246586&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.7.0/tools/clang/docs/_images/DriverArchitecture.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.7.0/tools/clang/docs/_images/PCHLayout.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/_images/PCHLayout.png?rev=246586&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.7.0/tools/clang/docs/_images/PCHLayout.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.7.0/tools/clang/docs/_sources/AddressSanitizer.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/_sources/AddressSanitizer.txt?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/_sources/AddressSanitizer.txt (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/_sources/AddressSanitizer.txt Tue Sep  1 15:55:31 2015
@@ -0,0 +1,272 @@
+================
+AddressSanitizer
+================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+AddressSanitizer is a fast memory error detector. It consists of a compiler
+instrumentation module and a run-time library. The tool can detect the
+following types of bugs:
+
+* Out-of-bounds accesses to heap, stack and globals
+* Use-after-free
+* Use-after-return (to some extent)
+* Double-free, invalid free
+* Memory leaks (experimental)
+
+Typical slowdown introduced by AddressSanitizer is **2x**.
+
+How to build
+============
+
+Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_.
+
+Usage
+=====
+
+Simply compile and link your program with ``-fsanitize=address`` flag.  The
+AddressSanitizer run-time library should be linked to the final executable, so
+make sure to use ``clang`` (not ``ld``) for the final link step.  When linking
+shared libraries, the AddressSanitizer run-time is not linked, so
+``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer).  To
+get a reasonable performance add ``-O1`` or higher.  To get nicer stack traces
+in error messages add ``-fno-omit-frame-pointer``.  To get perfect stack traces
+you may need to disable inlining (just use ``-O1``) and tail call elimination
+(``-fno-optimize-sibling-calls``).
+
+.. code-block:: console
+
+    % cat example_UseAfterFree.cc
+    int main(int argc, char **argv) {
+      int *array = new int[100];
+      delete [] array;
+      return array[argc];  // BOOM
+    }
+
+    # Compile and link
+    % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc
+
+or:
+
+.. code-block:: console
+
+    # Compile
+    % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc
+    # Link
+    % clang -g -fsanitize=address example_UseAfterFree.o
+
+If a bug is detected, the program will print an error message to stderr and
+exit with a non-zero exit code. AddressSanitizer exits on the first detected error.
+This is by design:
+
+* This approach allows AddressSanitizer to produce faster and smaller generated code
+  (both by ~5%).
+* Fixing bugs becomes unavoidable. AddressSanitizer does not produce
+  false alarms. Once a memory corruption occurs, the program is in an inconsistent
+  state, which could lead to confusing results and potentially misleading
+  subsequent reports.
+
+If your process is sandboxed and you are running on OS X 10.10 or earlier, you
+will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to
+the ASan library that is packaged with the compiler used to build the
+executable. (You can find the library by searching for dynamic libraries with
+``asan`` in their name.) If the environment variable is not set, the process will
+try to re-exec. Also keep in mind that when moving the executable to another machine,
+the ASan library will also need to be copied over.
+
+Symbolizing the Reports
+=========================
+
+To make AddressSanitizer symbolize its output
+you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
+the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your
+``$PATH``):
+
+.. code-block:: console
+
+    % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out
+    ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
+    READ of size 4 at 0x7f7ddab8c084 thread T0
+        #0 0x403c8c in main example_UseAfterFree.cc:4
+        #1 0x7f7ddabcac4d in __libc_start_main ??:0
+    0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
+    freed by thread T0 here:
+        #0 0x404704 in operator delete[](void*) ??:0
+        #1 0x403c53 in main example_UseAfterFree.cc:4
+        #2 0x7f7ddabcac4d in __libc_start_main ??:0
+    previously allocated by thread T0 here:
+        #0 0x404544 in operator new[](unsigned long) ??:0
+        #1 0x403c43 in main example_UseAfterFree.cc:2
+        #2 0x7f7ddabcac4d in __libc_start_main ??:0
+    ==9442== ABORTING
+
+If that does not work for you (e.g. your process is sandboxed), you can use a
+separate script to symbolize the result offline (online symbolization can be
+force disabled by setting ``ASAN_OPTIONS=symbolize=0``):
+
+.. code-block:: console
+
+    % ASAN_OPTIONS=symbolize=0 ./a.out 2> log
+    % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+    ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
+    READ of size 4 at 0x7f7ddab8c084 thread T0
+        #0 0x403c8c in main example_UseAfterFree.cc:4
+        #1 0x7f7ddabcac4d in __libc_start_main ??:0
+    ...
+
+Note that on OS X you may need to run ``dsymutil`` on your binary to have the
+file\:line info in the AddressSanitizer reports.
+
+Additional Checks
+=================
+
+Initialization order checking
+-----------------------------
+
+AddressSanitizer can optionally detect dynamic initialization order problems,
+when initialization of globals defined in one translation unit uses
+globals defined in another translation unit. To enable this check at runtime,
+you should set environment variable
+``ASAN_OPTIONS=check_initialization_order=1``.
+
+Note that this option is not supported on OS X.
+
+Memory leak detection
+---------------------
+
+For more information on leak detector in AddressSanitizer, see
+:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux;
+however, it is not yet supported on other platforms.
+
+Issue Suppression
+=================
+
+AddressSanitizer is not expected to produce false positives. If you see one,
+look again; most likely it is a true positive!
+
+Suppressing Reports in External Libraries
+-----------------------------------------
+Runtime interposition allows AddressSanitizer to find bugs in code that is
+not being recompiled. If you run into an issue in external libraries, we
+recommend immediately reporting it to the library maintainer so that it
+gets addressed. However, you can use the following suppression mechanism
+to unblock yourself and continue on with the testing. This suppression
+mechanism should only be used for suppressing issues in external code; it
+does not work on code recompiled with AddressSanitizer. To suppress errors
+in external libraries, set the ``ASAN_OPTIONS`` environment variable to point
+to a suppression file. You can either specify the full path to the file or the
+path of the file relative to the location of your executable.
+
+.. code-block:: bash
+
+    ASAN_OPTIONS=suppressions=MyASan.supp
+
+Use the following format to specify the names of the functions or libraries
+you want to suppress. You can see these in the error report. Remember that
+the narrower the scope of the suppression, the more bugs you will be able to
+catch.
+
+.. code-block:: bash
+
+    interceptor_via_fun:NameOfCFunctionToSuppress
+    interceptor_via_fun:-[ClassName objCMethodToSuppress:]
+    interceptor_via_lib:NameOfTheLibraryToSuppress
+
+Conditional Compilation with ``__has_feature(address_sanitizer)``
+-----------------------------------------------------------------
+
+In some cases one may need to execute different code depending on whether
+AddressSanitizer is enabled.
+:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
+this purpose.
+
+.. code-block:: c
+
+    #if defined(__has_feature)
+    #  if __has_feature(address_sanitizer)
+    // code that builds only under AddressSanitizer
+    #  endif
+    #endif
+
+Disabling Instrumentation with ``__attribute__((no_sanitize("address")))``
+--------------------------------------------------------------------------
+
+Some code should not be instrumented by AddressSanitizer. One may use the
+function attribute ``__attribute__((no_sanitize("address")))``
+(which has deprecated synonyms
+:ref:`no_sanitize_address <langext-address_sanitizer>` and
+`no_address_safety_analysis`) to disable instrumentation of a particular
+function. This attribute may not be supported by other compilers, so we suggest
+to use it together with ``__has_feature(address_sanitizer)``.
+
+Suppressing Errors in Recompiled Code (Blacklist)
+-------------------------------------------------
+
+AddressSanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
+in the specified source files or functions. Additionally, AddressSanitizer
+introduces ``global`` and ``type`` entity types that can be used to
+suppress error reports for out-of-bound access to globals with certain
+names and types (you may only specify class or struct types).
+
+You may use an ``init`` category to suppress reports about initialization-order
+problems happening in certain source files or with certain global variables.
+
+.. code-block:: bash
+
+    # Suppress error reports for code in a file or in a function:
+    src:bad_file.cpp
+    # Ignore all functions with names containing MyFooBar:
+    fun:*MyFooBar*
+    # Disable out-of-bound checks for global:
+    global:bad_array
+    # Disable out-of-bound checks for global instances of a given class ...
+    type:Namespace::BadClassName
+    # ... or a given struct. Use wildcard to deal with anonymous namespace.
+    type:Namespace2::*::BadStructName
+    # Disable initialization-order checks for globals:
+    global:bad_init_global=init
+    type:*BadInitClassSubstring*=init
+    src:bad/init/files/*=init
+
+Limitations
+===========
+
+* AddressSanitizer uses more real memory than a native run. Exact overhead
+  depends on the allocations sizes. The smaller the allocations you make the
+  bigger the overhead is.
+* AddressSanitizer uses more stack memory. We have seen up to 3x increase.
+* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
+  virtual address space. This means that tools like ``ulimit`` may not work as
+  usually expected.
+* Static linking is not supported.
+
+Supported Platforms
+===================
+
+AddressSanitizer is supported on:
+
+* Linux i386/x86\_64 (tested on Ubuntu 12.04)
+* OS X 10.7 - 10.11 (i386/x86\_64)
+* iOS Simulator
+* Android ARM
+* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
+
+Ports to various other platforms are in progress.
+
+Current Status
+==============
+
+AddressSanitizer is fully functional on supported platforms starting from LLVM
+3.1. The test suite is integrated into CMake build and can be run with ``make
+check-asan`` command.
+
+More Information
+================
+
+`http://code.google.com/p/address-sanitizer <http://code.google.com/p/address-sanitizer/>`_
+

Added: www-releases/trunk/3.7.0/tools/clang/docs/_sources/AttributeReference.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/_sources/AttributeReference.txt?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/_sources/AttributeReference.txt (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/_sources/AttributeReference.txt Tue Sep  1 15:55:31 2015
@@ -0,0 +1,1760 @@
+..
+  -------------------------------------------------------------------
+  NOTE: This file is automatically generated by running clang-tblgen
+  -gen-attr-docs. Do not edit this file by hand!!
+  -------------------------------------------------------------------
+
+===================
+Attributes in Clang
+===================
+.. contents::
+   :local:
+
+Introduction
+============
+
+This page lists the attributes currently supported by Clang.
+
+AMD GPU Register Attributes
+===========================
+Clang supports attributes for controlling register usage on AMD GPU
+targets. These attributes may be attached to a kernel function
+definition and is an optimization hint to the backend for the maximum
+number of registers to use. This is useful in cases where register
+limited occupancy is known to be an important factor for the
+performance for the kernel.
+
+The semantics are as follows:
+
+- The backend will attempt to limit the number of used registers to
+  the specified value, but the exact number used is not
+  guaranteed. The number used may be rounded up to satisfy the
+  allocation requirements or ABI constraints of the subtarget. For
+  example, on Southern Islands VGPRs may only be allocated in
+  increments of 4, so requesting a limit of 39 VGPRs will really
+  attempt to use up to 40. Requesting more registers than the
+  subtarget supports will truncate to the maximum allowed. The backend
+  may also use fewer registers than requested whenever possible.
+
+- 0 implies the default no limit on register usage.
+
+- Ignored on older VLIW subtargets which did not have separate scalar
+  and vector registers, R600 through Northern Islands.
+
+amdgpu_num_sgpr
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang supports the
+``__attribute__((amdgpu_num_sgpr(<num_registers>)))`` attribute on AMD
+Southern Islands GPUs and later for controlling the number of scalar
+registers. A typical value would be between 8 and 104 in increments of
+8.
+
+Due to common instruction constraints, an additional 2-4 SGPRs are
+typically required for internal use depending on features used. This
+value is a hint for the total number of SGPRs to use, and not the
+number of user SGPRs, so no special consideration needs to be given
+for these.
+
+
+amdgpu_num_vgpr
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang supports the
+``__attribute__((amdgpu_num_vgpr(<num_registers>)))`` attribute on AMD
+Southern Islands GPUs and later for controlling the number of vector
+registers. A typical value would be between 4 and 256 in increments
+of 4.
+
+
+Function Attributes
+===================
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.
+
+The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: "IRQ",
+"FIQ", "SWI", "ABORT", "UNDEF".
+
+The semantics are as follows:
+
+- If the function is AAPCS, Clang instructs the backend to realign the stack to
+  8 bytes on entry. This is a general requirement of the AAPCS at public
+  interfaces, but may not hold when an exception is taken. Doing this allows
+  other AAPCS functions to be called.
+- If the CPU is M-class this is all that needs to be done since the architecture
+  itself is designed in such a way that functions obeying the normal AAPCS ABI
+  constraints are valid exception handlers.
+- If the CPU is not M-class, the prologue and epilogue are modified to save all
+  non-banked registers that are used, so that upon return the user-mode state
+  will not be corrupted. Note that to avoid unnecessary overhead, only
+  general-purpose (integer) registers are saved in this way. If VFP operations
+  are needed, that state must be saved manually.
+
+  Specifically, interrupt kinds other than "FIQ" will save all core registers
+  except "lr" and "sp". "FIQ" interrupts will save r0-r7.
+- If the CPU is not M-class, the return instruction is changed to one of the
+  canonical sequences permitted by the architecture for exception return. Where
+  possible the function itself will make the necessary "lr" adjustments so that
+  the "preferred return address" is selected.
+
+  Unfortunately the compiler is unable to make this guarantee for an "UNDEF"
+  handler, where the offset from "lr" to the preferred return address depends on
+  the execution state of the code which generated the exception. In this case
+  a sequence equivalent to "movs pc, lr" will be used.
+
+
+acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Marks a function as acquiring a capability.
+
+
+assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)
+-------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.
+
+
+assume_aligned (gnu::assume_aligned)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) has the specified offset, in bytes, from an address with the
+specified alignment. The offset is taken to be zero if omitted.
+
+.. code-block:: c++
+
+  // The returned pointer value has 32-byte alignment.
+  void *a() __attribute__((assume_aligned (32)));
+
+  // The returned pointer value is 4 bytes greater than an address having
+  // 32-byte alignment.
+  void *b() __attribute__((assume_aligned (32, 4)));
+
+Note that this attribute provides information to the compiler regarding a
+condition that the code already ensures is true. It does not cause the compiler
+to enforce the provided alignment assumption.
+
+
+availability
+------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+The ``availability`` attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions.  Consider
+the function declaration for a hypothetical function ``f``:
+
+.. code-block:: c++
+
+  void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+
+The availability attribute states that ``f`` was introduced in Mac OS X 10.4,
+deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7.  This information
+is used by Clang to determine when it is safe to use ``f``: for example, if
+Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
+succeeds.  If Clang is instructed to compile code for Mac OS X 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
+fails because ``f()`` is no longer available.
+
+The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration's lifetime (in any order) along with additional information.  Those
+clauses can be:
+
+introduced=\ *version*
+  The first version in which this declaration was introduced.
+
+deprecated=\ *version*
+  The first version in which this declaration was deprecated, meaning that
+  users should migrate away from this API.
+
+obsoleted=\ *version*
+  The first version in which this declaration was obsoleted, meaning that it
+  was removed completely and can no longer be used.
+
+unavailable
+  This declaration is never available on this platform.
+
+message=\ *string-literal*
+  Additional message text that Clang will provide when emitting a warning or
+  error about use of a deprecated or obsoleted declaration.  Useful to direct
+  users to replacement APIs.
+
+Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms.  Only the availability attribute with the
+platform corresponding to the target platform will be used; any others will be
+ignored.  If no availability attribute specifies availability for the current
+target platform, the availability attributes are ignored.  Supported platforms
+are:
+
+``ios``
+  Apple's iOS operating system.  The minimum deployment target is specified by
+  the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
+  command-line arguments.
+
+``macosx``
+  Apple's Mac OS X operating system.  The minimum deployment target is
+  specified by the ``-mmacosx-version-min=*version*`` command-line argument.
+
+A declaration can be used even when deploying back to a platform version prior
+to when the declaration was introduced.  When this happens, the declaration is
+`weakly linked
+<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
+as if the ``weak_import`` attribute were added to the declaration.  A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.
+
+If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:
+
+.. code-block:: c
+
+  void g(void) __attribute__((availability(macosx,introduced=10.4)));
+  void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches
+  void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
+  void g(void); // okay, inherits both macosx and ios availability from above.
+  void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch
+
+When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
+
+.. code-block:: objc
+
+  @interface A
+  - (id)method __attribute__((availability(macosx,introduced=10.4)));
+  - (id)method2 __attribute__((availability(macosx,introduced=10.4)));
+  @end
+
+  @interface B : A
+  - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later
+  - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4
+  @end
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+A function declared as ``_Noreturn`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``_Noreturn``
+that appears to be capable of returning to its caller.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","X","","", ""
+
+A function declared as ``[[noreturn]]`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``[[noreturn]]``
+that appears to be capable of returning to its caller.
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``carries_dependency`` attribute specifies dependency propagation into and
+out of functions.
+
+When specified on a function or Objective-C method, the ``carries_dependency``
+attribute means that the return value carries a dependency out of the function, 
+so that the implementation need not constrain ordering upon return from that
+function. Implementations of the function and its caller may choose to preserve
+dependencies instead of emitting memory ordering instructions such as fences.
+
+Note, this attribute does not change the meaning of the program, but may result
+in generation of more efficient code.
+
+
+enable_if
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+.. Note:: Some features of this attribute are experimental. The meaning of
+  multiple enable_if attributes on a single declaration is subject to change in
+  a future version of clang. Also, the ABI is not standardized and the name
+  mangling may change in future versions. To avoid that, use asm labels.
+
+The ``enable_if`` attribute can be placed on function declarations to control
+which overload is selected based on the values of the function's arguments.
+When combined with the ``overloadable`` attribute, this feature is also
+available in C.
+
+.. code-block:: c++
+
+  int isdigit(int c);
+  int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF")));
+  
+  void foo(char c) {
+    isdigit(c);
+    isdigit(10);
+    isdigit(-10);  // results in a compile-time error.
+  }
+
+The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.
+
+The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the call site. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.
+
+Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:
+
+.. code-block:: c++
+
+  __attribute__((always_inline))
+  static inline size_t strnlen(const char *s, size_t maxlen)
+    __attribute__((overloadable))
+    __attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
+                             "chosen when the buffer size is known but 'maxlen' is not")))
+  {
+    return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
+  }
+
+Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.
+
+.. code-block:: c++
+
+  void f() __attribute__((enable_if(true, "")));  // #1
+  void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, "")));  // #2
+  
+  void g(int i, int j) __attribute__((enable_if(i, "")));  // #1
+  void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true)));  // #2
+
+In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.
+
+Query for this feature with ``__has_attribute(enable_if)``.
+
+
+flatten (gnu::flatten)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``flatten`` attribute causes calls within the attributed function to
+be inlined unless it is impossible to do so, for example if the body of the
+callee is unavailable or if the callee has the ``noinline`` attribute.
+
+
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Clang supports the ``format`` attribute, which indicates that the function
+accepts a ``printf`` or ``scanf``-like format string and corresponding
+arguments or a ``va_list`` that contains these arguments.
+
+Please see `GCC documentation about format attribute
+<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
+about attribute syntax.
+
+Clang implements two kinds of checks with this attribute.
+
+#. Clang checks that the function with the ``format`` attribute is called with
+   a format string that uses format specifiers that are allowed, and that
+   arguments match the format string.  This is the ``-Wformat`` warning, it is
+   on by default.
+
+#. Clang checks that the format string argument is a literal string.  This is
+   the ``-Wformat-nonliteral`` warning, it is off by default.
+
+   Clang implements this mostly the same way as GCC, but there is a difference
+   for functions that accept a ``va_list`` argument (for example, ``vprintf``).
+   GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
+   functions.  Clang does not warn if the format string comes from a function
+   parameter, where the function is annotated with a compatible attribute,
+   otherwise it warns.  For example:
+
+   .. code-block:: c
+
+     __attribute__((__format__ (__scanf__, 1, 3)))
+     void foo(const char* s, char *buf, ...) {
+       va_list ap;
+       va_start(ap, buf);
+
+       vprintf(s, ap); // warning: format string is not a string literal
+     }
+
+   In this case we warn because ``s`` contains a format string for a
+   ``scanf``-like function, but it is passed to a ``printf``-like function.
+
+   If the attribute is removed, clang still warns, because the format string is
+   not a string literal.
+
+   Another example:
+
+   .. code-block:: c
+
+     __attribute__((__format__ (__printf__, 1, 3)))
+     void foo(const char* s, char *buf, ...) {
+       va_list ap;
+       va_start(ap, buf);
+
+       vprintf(s, ap); // warning
+     }
+
+   In this case Clang does not warn because the format string ``s`` and
+   the corresponding arguments are annotated.  If the arguments are
+   incorrect, the caller of ``foo`` will receive a warning.
+
+
+noduplicate (clang::noduplicate)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``noduplicate`` attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL "barrier" function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+"nodupfunc" in the code below avoids that:
+
+.. code-block:: c
+
+  void nodupfunc() __attribute__((noduplicate));
+  // Setting it as a C++11 attribute is also valid
+  // void nodupfunc() [[clang::noduplicate]];
+  void foo();
+  void bar();
+
+  nodupfunc();
+  if (a > n) {
+    foo();
+  } else {
+    bar();
+  }
+
+gets possibly modified by some optimizations into code similar to this:
+
+.. code-block:: c
+
+  if (a > n) {
+    nodupfunc();
+    foo();
+  } else {
+    nodupfunc();
+    bar();
+  }
+
+where the call to "nodupfunc" is duplicated and sunk into the two branches
+of the condition.
+
+
+no_sanitize (clang::no_sanitize)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Use the ``no_sanitize`` attribute on a function declaration to specify
+that a particular instrumentation or set of instrumentations should not be
+applied to that function. The attribute takes a list of string literals,
+which have the same meaning as values accepted by the ``-fno-sanitize=``
+flag. For example, ``__attribute__((no_sanitize("address", "thread")))``
+specifies that AddressSanitizer and ThreadSanitizer should not be applied
+to the function.
+
+See :ref:`Controlling Code Generation <controlling-code-generation>` for a
+full list of supported sanitizer flags.
+
+
+no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+.. _langext-address_sanitizer:
+
+Use ``__attribute__((no_sanitize_address))`` on a function declaration to
+specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.
+
+
+no_sanitize_thread
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+.. _langext-thread_sanitizer:
+
+Use ``__attribute__((no_sanitize_thread))`` on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.
+
+
+no_sanitize_memory
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+.. _langext-memory_sanitizer:
+
+Use ``__attribute__((no_sanitize_memory))`` on a function declaration to
+specify that checks for uninitialized memory should not be inserted 
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.
+
+
+no_split_stack (gnu::no_split_stack)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``no_split_stack`` attribute disables the emission of the split stack
+preamble for a particular function. It has no effect if ``-fsplit-stack``
+is not specified.
+
+
+objc_boxable
+------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Structs and unions marked with the ``objc_boxable`` attribute can be used 
+with the Objective-C boxed expression syntax, ``@(...)``.
+
+**Usage**: ``__attribute__((objc_boxable))``. This attribute 
+can only be placed on a declaration of a trivially-copyable struct or union:
+
+.. code-block:: objc
+
+  struct __attribute__((objc_boxable)) some_struct {
+    int i;
+  };
+  union __attribute__((objc_boxable)) some_union {
+    int i;
+    float f;
+  };
+  typedef struct __attribute__((objc_boxable)) _some_struct some_struct;
+
+  // ...
+
+  some_struct ss;
+  NSValue *boxed = @(ss);
+
+
+objc_method_family
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the "method family"
+that a method belongs to.
+
+**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
+``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``.  This
+attribute can only be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+  - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
+
+Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (``ns_returns_retained``,
+``ns_returns_not_retained``, etc).
+
+Query for this feature with ``__has_attribute(objc_method_family)``.
+
+
+objc_requires_super
+-------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a "call to ``super``" in the overriding
+method in the subclass.
+
+**Usage**: ``__attribute__((objc_requires_super))``.  This attribute can only
+be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+  - (void)foo __attribute__((objc_requires_super));
+
+This attribute can only be applied the method declarations within a class, and
+not a protocol.  Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+``-dealloc`` where the call must appear at the end).  It checks only that it
+exists.
+
+Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
+attribute:
+
+.. code-block:: objc
+
+  - (void)foo NS_REQUIRES_SUPER;
+
+This macro is conditionally defined depending on the compiler's support for
+this attribute.  If the compiler does not support the attribute the macro
+expands to nothing.
+
+Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super.  For example:
+
+.. code-block:: objc
+
+   warning: method possibly missing a [super AnnotMeth] call
+   - (void) AnnotMeth{};
+                      ^
+
+
+objc_runtime_name
+-----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+By default, the Objective-C interface or protocol identifier is used
+in the metadata name for that object. The `objc_runtime_name`
+attribute allows annotated interfaces or protocols to use the
+specified string argument in the object's metadata name instead of the
+default name.
+        
+**Usage**: ``__attribute__((objc_runtime_name("MyLocalName")))``.  This attribute
+can only be placed before an @protocol or @interface declaration:
+        
+.. code-block:: objc
+        
+  __attribute__((objc_runtime_name("MyLocalName")))
+  @interface Message
+  @end
+
+
+optnone (clang::optnone)
+------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``optnone`` attribute suppresses essentially all optimizations
+on a function or method, regardless of the optimization level applied to
+the compilation unit as a whole.  This is particularly useful when you
+need to debug a particular function, but it is infeasible to build the
+entire application without optimization.  Avoiding optimization on the
+specified function can improve the quality of the debugging information
+for that function.
+
+This attribute is incompatible with the ``always_inline`` and ``minsize``
+attributes.
+
+
+overloadable
+------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang provides support for C++ function overloading in C.  Function overloading
+in C is introduced using the ``overloadable`` attribute.  For example, one
+might provide several overloaded versions of a ``tgsin`` function that invokes
+the appropriate standard function computing the sine of a value with ``float``,
+``double``, or ``long double`` precision:
+
+.. code-block:: c
+
+  #include <math.h>
+  float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+  double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+  long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+
+Given these declarations, one can call ``tgsin`` with a ``float`` value to
+receive a ``float`` result, with a ``double`` to receive a ``double`` result,
+etc.  Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:
+
+* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
+  floating-point promotion (per C99) rather than as a floating-point conversion
+  (as in C++).
+
+* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
+  considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
+  compatible types.
+
+* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
+  and ``U`` are compatible types.  This conversion is given "conversion" rank.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions.  Most importantly, if any function with a given
+name is given the ``overloadable`` attribute, then all function declarations
+and definitions with that name (and in that scope) must have the
+``overloadable`` attribute.  This rule even applies to redeclarations of
+functions whose original declaration had the ``overloadable`` attribute, e.g.,
+
+.. code-block:: c
+
+  int f(int) __attribute__((overloadable));
+  float f(float); // error: declaration of "f" must have the "overloadable" attribute
+
+  int g(int) __attribute__((overloadable));
+  int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+Functions marked ``overloadable`` must have prototypes.  Therefore, the
+following code is ill-formed:
+
+.. code-block:: c
+
+  int h() __attribute__((overloadable)); // error: h does not have a prototype
+
+However, ``overloadable`` functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++).  This feature is particularly
+useful when combined with the ``unavailable`` attribute:
+
+.. code-block:: c++
+
+  void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
+Functions declared with the ``overloadable`` attribute have their names mangled
+according to the same rules as C++ function names.  For example, the three
+``tgsin`` functions in our motivating example get the mangled names
+``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively.  There are two
+caveats to this use of name mangling:
+
+* Future versions of Clang may change the name mangling of functions overloaded
+  in C, so you should not depend on an specific mangling.  To be completely
+  safe, we strongly urge the use of ``static inline`` with ``overloadable``
+  functions.
+
+* The ``overloadable`` attribute has almost no meaning when used in C++,
+  because names will already be mangled and functions are already overloadable.
+  However, when an ``overloadable`` function occurs within an ``extern "C"``
+  linkage specification, it's name *will* be mangled in the same way as it
+  would in C.
+
+Query for this feature with ``__has_extension(attribute_overloadable)``.
+
+
+release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Marks a function as releasing a capability.
+
+
+target (gnu::target)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Clang supports the GNU style ``__attribute__((target("OPTIONS")))`` attribute.
+This attribute may be attached to a function definition and instructs
+the backend to use different code generation options than were passed on the
+command line.
+
+The current set of options correspond to the existing "subtarget features" for
+the target with or without a "-mno-" in front corresponding to the absence
+of the feature, as well as ``arch="CPU"`` which will change the default "CPU"
+for the function.
+
+Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
+"avx", "xop" and largely correspond to the machine specific options handled by
+the front end.
+
+
+try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)
+---------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).
+
+
+Variable Attributes
+===================
+
+
+init_seg
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","", "X"
+
+The attribute applied by ``pragma init_seg()`` controls the section into
+which global initialization function pointers are emitted.  It is only
+available with ``-fms-extensions``.  Typically, this function pointer is
+emitted into ``.CRT$XCU`` on Windows.  The user can change the order of
+initialization by using a different section name with the same
+``.CRT$XC`` prefix and a suffix that sorts lexicographically before or
+after the standard ``.CRT$XCU`` sections.  See the init_seg_
+documentation on MSDN for more information.
+
+.. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx
+
+
+section (gnu::section, __declspec(allocate))
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","X","", ""
+
+The ``section`` attribute allows you to specify a specific section a
+global variable or function should be in after translation.
+
+
+tls_model (gnu::tls_model)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``tls_model`` attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:
+
+* global-dynamic
+* local-dynamic
+* initial-exec
+* local-exec
+
+TLS models are mutually exclusive.
+
+
+thread
+------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","X","", ""
+
+The ``__declspec(thread)`` attribute declares a variable with thread local
+storage.  It is available under the ``-fms-extensions`` flag for MSVC
+compatibility.  See the documentation for `__declspec(thread)`_ on MSDN.
+
+.. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx
+
+In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the
+GNU ``__thread`` keyword.  The variable must not have a destructor and must have
+a constant initializer, if any.  The attribute only applies to variables
+declared with static storage duration, such as globals, class static data
+members, and static locals.
+
+
+Type Attributes
+===============
+
+
+align_value
+-----------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+The align_value attribute can be added to the typedef of a pointer type or the
+declaration of a variable of pointer or reference type. It specifies that the
+pointer will point to, or the reference will bind to, only objects with at
+least the provided alignment. This alignment value must be some positive power
+of 2.
+
+   .. code-block:: c
+
+     typedef double * aligned_double_ptr __attribute__((align_value(64)));
+     void foo(double & x  __attribute__((align_value(128)),
+              aligned_double_ptr y) { ... }
+
+If the pointer value does not have the specified alignment at runtime, the
+behavior of the program is undefined.
+
+
+flag_enum
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+This attribute can be added to an enumerator to signal to the compiler that it
+is intended to be used as a flag type. This will cause the compiler to assume
+that the range of the type includes all of the values that you can get by
+manipulating bits of the enumerator when issuing warnings.
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+This collection of keywords is enabled under ``-fms-extensions`` and controls
+the pointer-to-member representation used on ``*-*-win32`` targets.
+
+The ``*-*-win32`` targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.
+
+However, this is problematic when a forward declaration is only available and
+no definition has been made yet.  In such cases, Clang is forced to utilize the
+most general representation that is available to it.
+
+These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.
+
+This family of keywords belong between the ``class-key`` and ``class-name``:
+
+.. code-block:: c++
+
+  struct __single_inheritance S;
+  int S::*i;
+  struct S {};
+
+This keyword can be applied to class templates but only has an effect when used
+on full specializations:
+
+.. code-block:: c++
+
+  template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
+  template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
+  template <> struct __single_inheritance A<int, float>;
+
+Note that choosing an inheritance model less general than strictly necessary is
+an error:
+
+.. code-block:: c++
+
+  struct __multiple_inheritance S; // error: inheritance model does not match definition
+  int S::*i;
+  struct S {};
+
+
+novtable
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","X","", ""
+
+This attribute can be added to a class declaration or definition to signal to
+the compiler that constructors and destructors will not reference the virtual
+function table.
+
+
+Statement Attributes
+====================
+
+
+fallthrough (clang::fallthrough)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","X","","", ""
+
+The ``clang::fallthrough`` attribute is used along with the
+``-Wimplicit-fallthrough`` argument to annotate intentional fall-through
+between switch labels.  It can only be applied to a null statement placed at a
+point of execution between any statement and the next switch label.  It is
+common to mark these places with a specific comment, but this attribute is
+meant to replace comments with a more strict annotation, which can be checked
+by the compiler.  This attribute doesn't change semantics of the code and can
+be used wherever an intended fall-through occurs.  It is designed to mimic
+control-flow statements like ``break;``, so it can be placed in most places
+where ``break;`` can, but only if there are no statements on the execution path
+between it and the next switch label.
+
+Here is an example:
+
+.. code-block:: c++
+
+  // compile with -Wimplicit-fallthrough
+  switch (n) {
+  case 22:
+  case 33:  // no warning: no statements between case labels
+    f();
+  case 44:  // warning: unannotated fall-through
+    g();
+    [[clang::fallthrough]];
+  case 55:  // no warning
+    if (x) {
+      h();
+      break;
+    }
+    else {
+      i();
+      [[clang::fallthrough]];
+    }
+  case 66:  // no warning
+    p();
+    [[clang::fallthrough]]; // warning: fallthrough annotation does not
+                            //          directly precede case label
+    q();
+  case 77:  // warning: unannotated fall-through
+    r();
+  }
+
+
+#pragma clang loop
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","", "X"
+
+The ``#pragma clang loop`` directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows vectorization,
+interleaving, and unrolling to be enabled or disabled. Vector width as well
+as interleave and unrolling count can be manually specified. See
+`language extensions
+<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
+for details.
+
+
+#pragma unroll, #pragma nounroll
+--------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","", "X"
+
+Loop unrolling optimization hints can be specified with ``#pragma unroll`` and
+``#pragma nounroll``. The pragma is placed immediately before a for, while,
+do-while, or c++11 range-based for loop.
+
+Specifying ``#pragma unroll`` without a parameter directs the loop unroller to
+attempt to fully unroll the loop if the trip count is known at compile time:
+
+.. code-block:: c++
+
+  #pragma unroll
+  for (...) {
+    ...
+  }
+
+Specifying the optional parameter, ``#pragma unroll _value_``, directs the
+unroller to unroll the loop ``_value_`` times.  The parameter may optionally be
+enclosed in parentheses:
+
+.. code-block:: c++
+
+  #pragma unroll 16
+  for (...) {
+    ...
+  }
+
+  #pragma unroll(16)
+  for (...) {
+    ...
+  }
+
+Specifying ``#pragma nounroll`` indicates that the loop should not be unrolled:
+
+.. code-block:: c++
+
+  #pragma nounroll
+  for (...) {
+    ...
+  }
+
+``#pragma unroll`` and ``#pragma unroll _value_`` have identical semantics to
+``#pragma clang loop unroll(full)`` and
+``#pragma clang loop unroll_count(_value_)`` respectively. ``#pragma nounroll``
+is equivalent to ``#pragma clang loop unroll(disable)``.  See
+`language extensions
+<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
+for further details including limitations of the unroll hints.
+
+
+Calling Conventions
+===================
+Clang supports several different calling conventions, depending on the target
+platform and architecture. The calling convention used for a function determines
+how parameters are passed, how results are returned to the caller, and other
+low-level details of calling a function.
+
+fastcall (gnu::fastcall, __fastcall, _fastcall)
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","X", ""
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX and EDX as register parameters and clear parameters off of
+the stack on return. This convention does not support variadic calls or
+unprototyped functions in C, and has no effect on x86_64 targets. This calling
+convention is supported primarily for compatibility with existing code. Users
+seeking register parameters should use the ``regparm`` attribute, which does
+not require callee-cleanup.  See the documentation for `__fastcall`_ on MSDN.
+
+.. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx
+
+
+ms_abi (gnu::ms_abi)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+On non-Windows x86_64 targets, this attribute changes the calling convention of
+a function to match the default convention used on Windows x86_64. This
+attribute has no effect on Windows targets or non-x86_64 targets.
+
+
+pcs (gnu::pcs)
+--------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+On ARM targets, this attribute can be used to select calling conventions
+similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and
+"aapcs-vfp".
+
+
+regparm (gnu::regparm)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+On 32-bit x86 targets, the regparm attribute causes the compiler to pass
+the first three integer parameters in EAX, EDX, and ECX instead of on the
+stack. This attribute has no effect on variadic functions, and all parameters
+are passed via the stack as normal.
+
+
+stdcall (gnu::stdcall, __stdcall, _stdcall)
+-------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","X", ""
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to clear parameters off of the stack on return. This convention does
+not support variadic calls or unprototyped functions in C, and has no effect on
+x86_64 targets. This calling convention is used widely by the Windows API and
+COM applications.  See the documentation for `__stdcall`_ on MSDN.
+
+.. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx
+
+
+thiscall (gnu::thiscall, __thiscall, _thiscall)
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","X", ""
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX for the first parameter (typically the implicit ``this``
+parameter of C++ methods) and clear parameters off of the stack on return. This
+convention does not support variadic calls or unprototyped functions in C, and
+has no effect on x86_64 targets. See the documentation for `__thiscall`_ on
+MSDN.
+
+.. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx
+
+
+vectorcall (__vectorcall, _vectorcall)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","X", ""
+
+On 32-bit x86 *and* x86_64 targets, this attribute changes the calling
+convention of a function to pass vector parameters in SSE registers.
+
+On 32-bit x86 targets, this calling convention is similar to ``__fastcall``.
+The first two integer parameters are passed in ECX and EDX. Subsequent integer
+parameters are passed in memory, and callee clears the stack.  On x86_64
+targets, the callee does *not* clear the stack, and integer parameters are
+passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
+convention.
+
+On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
+passed in XMM0-XMM5. Homogenous vector aggregates of up to four elements are
+passed in sequential SSE registers if enough are available. If AVX is enabled,
+256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
+cannot be passed in registers for any reason is passed by reference, which
+allows the caller to align the parameter memory.
+
+See the documentation for `__vectorcall`_ on MSDN for more details.
+
+.. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx
+
+
+Consumed Annotation Checking
+============================
+Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although **the implementation
+for these annotations is currently in development and are subject to change.**
+
+callable_when
+-------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Use ``__attribute__((callable_when(...)))`` to indicate what states a method
+may be called in.  Valid states are unconsumed, consumed, or unknown.  Each
+argument to this attribute must be a quoted string.  E.g.:
+
+``__attribute__((callable_when("unconsumed", "unknown")))``
+
+
+consumable
+----------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Each ``class`` that uses any of the typestate annotations must first be marked
+using the ``consumable`` attribute.  Failure to do so will result in a warning.
+
+This attribute accepts a single parameter that must be one of the following:
+``unknown``, ``consumed``, or ``unconsumed``.
+
+
+param_typestate
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+This attribute specifies expectations about function parameters.  Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn't in the expected state.  The attribute is also used to set the
+initial state of the parameter when analyzing the function's body.
+
+
+return_typestate
+----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+The ``return_typestate`` attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value.  The function's body is checked to ensure that it always returns a value
+in the specified state.  On the caller side, values returned by the annotated
+function are initialized to the given state.
+
+When applied to a function parameter it modifies the state of an argument after
+a call to the function returns.  The function's body is checked to ensure that
+the parameter is in the expected state before returning.
+
+
+set_typestate
+-------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Annotate methods that transition an object into a new state with
+``__attribute__((set_typestate(new_state)))``.  The new state must be
+unconsumed, consumed, or unknown.
+
+
+test_typestate
+--------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
+returns true if the object is in the specified state..
+
+
+Type Safety Checking
+====================
+Clang supports additional attributes to enable checking type safety properties
+that can't be enforced by the C type system.  Use cases include:
+
+* MPI library implementations, where these attributes enable checking that
+  the buffer type matches the passed ``MPI_Datatype``;
+* for HDF5 library there is a similar use case to MPI;
+* checking types of variadic functions' arguments for functions like
+  ``fcntl()`` and ``ioctl()``.
+
+You can detect support for these attributes with ``__has_attribute()``.  For
+example:
+
+.. code-block:: c++
+
+  #if defined(__has_attribute)
+  #  if __has_attribute(argument_with_type_tag) && \
+        __has_attribute(pointer_with_type_tag) && \
+        __has_attribute(type_tag_for_datatype)
+  #    define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
+  /* ... other macros ...  */
+  #  endif
+  #endif
+
+  #if !defined(ATTR_MPI_PWT)
+  # define ATTR_MPI_PWT(buffer_idx, type_idx)
+  #endif
+
+  int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+      ATTR_MPI_PWT(1,3);
+
+argument_with_type_tag
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
+type_tag_idx)))`` on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.
+``arg_kind`` is an identifier that should be used when annotating all
+applicable type tags.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most non-variadic cases).
+
+For example:
+
+.. code-block:: c++
+
+  int fcntl(int fd, int cmd, ...)
+      __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+
+
+pointer_with_type_tag
+---------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.
+
+For example:
+
+.. code-block:: c++
+
+  int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+      __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+
+type_tag_for_datatype
+---------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang supports annotating type tags of two forms.
+
+* **Type tag that is an expression containing a reference to some declared
+  identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a
+  declaration with that identifier:
+
+  .. code-block:: c++
+
+    extern struct mpi_datatype mpi_datatype_int
+        __attribute__(( type_tag_for_datatype(mpi,int) ));
+    #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+
+* **Type tag that is an integral literal.** Introduce a ``static const``
+  variable with a corresponding initializer value and attach
+  ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration,
+  for example:
+
+  .. code-block:: c++
+
+    #define MPI_INT ((MPI_Datatype) 42)
+    static const MPI_Datatype mpi_datatype_int
+        __attribute__(( type_tag_for_datatype(mpi,int) )) = 42
+
+The attribute also accepts an optional third argument that determines how the
+expression is compared to the type tag.  There are two supported flags:
+
+* ``layout_compatible`` will cause types to be compared according to
+  layout-compatibility rules (C++11 [class.mem] p 17, 18).  This is
+  implemented to support annotating types like ``MPI_DOUBLE_INT``.
+
+  For example:
+
+  .. code-block:: c++
+
+    /* In mpi.h */
+    struct internal_mpi_double_int { double d; int i; };
+    extern struct mpi_datatype mpi_datatype_double_int
+        __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) ));
+
+    #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
+
+    /* In user code */
+    struct my_pair { double a; int b; };
+    struct my_pair *buffer;
+    MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ...  */); // no warning
+
+    struct my_int_pair { int a; int b; }
+    struct my_int_pair *buffer2;
+    MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ...  */); // warning: actual buffer element
+                                                      // type 'struct my_int_pair'
+                                                      // doesn't match specified MPI_Datatype
+
+* ``must_be_null`` specifies that the expression should be a null pointer
+  constant, for example:
+
+  .. code-block:: c++
+
+    /* In mpi.h */
+    extern struct mpi_datatype mpi_datatype_null
+        __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
+
+    #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
+
+    /* In user code */
+    MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ...  */); // warning: MPI_DATATYPE_NULL
+                                                        // was specified but buffer
+                                                        // is not a null pointer
+
+
+OpenCL Address Spaces
+=====================
+The address space qualifier may be used to specify the region of memory that is
+used to allocate the object. OpenCL supports the following address spaces:
+__generic(generic), __global(global), __local(local), __private(private),
+__constant(constant).
+
+  .. code-block:: c
+
+    __constant int c = ...;
+
+    __generic int* foo(global int* g) {
+      __local int* l;
+      private int p;
+      ...
+      return l;
+    }
+
+More details can be found in the OpenCL C language Spec v2.0, Section 6.5.
+
+__constant(constant)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+The constant address space attribute signals that an object is located in
+a constant (non-modifiable) memory region. It is available to all work items.
+Any type can be annotated with the constant address space attribute. Objects
+with the constant address space qualifier can be declared in any scope and must
+have an initializer.
+
+
+__generic(generic)
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+The generic address space attribute is only available with OpenCL v2.0 and later.
+It can be used with pointer types. Variables in global and local scope and
+function parameters in non-kernel functions can have the generic address space
+type attribute. It is intended to be a placeholder for any other address space
+except for '__constant' in OpenCL code which can be used with multiple address
+spaces.
+
+
+__global(global)
+----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+The global address space attribute specifies that an object is allocated in
+global memory, which is accessible by all work items. The content stored in this
+memory area persists between kernel executions. Pointer types to the global
+address space are allowed as function parameters or local variables. Starting
+with OpenCL v2.0, the global address space can be used with global (program
+scope) variables and static local variable as well.
+
+
+__local(local)
+--------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+The local address space specifies that an object is allocated in the local (work
+group) memory area, which is accessible to all work items in the same work
+group. The content stored in this memory region is not accessible after
+the kernel execution ends. In a kernel function scope, any variable can be in
+the local address space. In other scopes, only pointer types to the local address
+space are allowed. Local address space variables cannot have an initializer.
+
+
+__private(private)
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+The private address space specifies that an object is allocated in the private
+(work item) memory. Other work items cannot access the same memory area and its
+content is destroyed after work item execution ends. Local variables can be
+declared in the private address space. Function arguments are always in the
+private address space. Kernel function arguments of a pointer or an array type
+cannot point to the private address space.
+
+
+Nullability Attributes
+======================
+Whether a particular pointer may be "null" is an important concern when working with pointers in the C family of languages. The various nullability attributes indicate whether a particular pointer can be null or not, which makes APIs more expressive and can help static analysis tools identify bugs involving null pointers. Clang supports several kinds of nullability attributes: the ``nonnull`` and ``returns_nonnull`` attributes indicate which function or method parameters and result types can never be null, while nullability type qualifiers indicate which pointer types can be null (``_Nullable``) or cannot be null (``_Nonnull``). 
+
+The nullability (type) qualifiers express whether a value of a given pointer type can be null (the ``_Nullable`` qualifier), doesn't have a defined meaning for null (the ``_Nonnull`` qualifier), or for which the purpose of null is unclear (the ``_Null_unspecified`` qualifier). Because nullability qualifiers are expressed within the type system, they are more general than the ``nonnull`` and ``returns_nonnull`` attributes, allowing one to express (for example) a nullable pointer to an array of nonnull pointers. Nullability qualifiers are written to the right of the pointer to which they apply. For example:
+
+  .. code-block:: c
+
+    // No meaningful result when 'ptr' is null (here, it happens to be undefined behavior).
+    int fetch(int * _Nonnull ptr) { return *ptr; }
+
+    // 'ptr' may be null.
+    int fetch_or_zero(int * _Nullable ptr) {
+      return ptr ? *ptr : 0;
+    }
+
+    // A nullable pointer to non-null pointers to const characters.
+    const char *join_strings(const char * _Nonnull * _Nullable strings, unsigned n);
+
+In Objective-C, there is an alternate spelling for the nullability qualifiers that can be used in Objective-C methods and properties using context-sensitive, non-underscored keywords. For example:
+
+  .. code-block:: objective-c
+
+    @interface NSView : NSResponder
+      - (nullable NSView *)ancestorSharedWithView:(nonnull NSView *)aView;
+      @property (assign, nullable) NSView *superview;
+      @property (readonly, nonnull) NSArray *subviews;
+    @end
+
+nonnull
+-------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``nonnull`` attribute indicates that some function parameters must not be null, and can be used in several different ways. It's original usage (`from GCC <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes>`_) is as a function (or Objective-C method) attribute that specifies which parameters of the function are nonnull in a comma-separated list. For example:
+
+  .. code-block:: c
+
+    extern void * my_memcpy (void *dest, const void *src, size_t len)
+                    __attribute__((nonnull (1, 2)));
+
+Here, the ``nonnull`` attribute indicates that parameters 1 and 2
+cannot have a null value. Omitting the parenthesized list of parameter indices means that all parameters of pointer type cannot be null:
+
+  .. code-block:: c
+
+    extern void * my_memcpy (void *dest, const void *src, size_t len)
+                    __attribute__((nonnull));
+
+Clang also allows the ``nonnull`` attribute to be placed directly on a function (or Objective-C method) parameter, eliminating the need to specify the parameter index ahead of type. For example:
+
+  .. code-block:: c
+
+    extern void * my_memcpy (void *dest __attribute__((nonnull)),
+                             const void *src __attribute__((nonnull)), size_t len);
+
+Note that the ``nonnull`` attribute indicates that passing null to a non-null parameter is undefined behavior, which the optimizer may take advantage of to, e.g., remove null checks. The ``_Nonnull`` type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable.
+
+
+returns_nonnull
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``returns_nonnull`` attribute indicates that a particular function (or Objective-C method) always returns a non-null pointer. For example, a particular system ``malloc`` might be defined to terminate a process when memory is not available rather than returning a null pointer:
+
+  .. code-block:: c
+
+    extern void * malloc (size_t size) __attribute__((returns_nonnull));
+
+The ``returns_nonnull`` attribute implies that returning a null pointer is undefined behavior, which the optimizer may take advantage of. The ``_Nonnull`` type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable
+
+
+_Nonnull
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+The ``_Nonnull`` nullability qualifier indicates that null is not a meaningful value for a value of the ``_Nonnull`` pointer type. For example, given a declaration such as:
+
+  .. code-block:: c
+
+    int fetch(int * _Nonnull ptr);
+
+a caller of ``fetch`` should not provide a null value, and the compiler will produce a warning if it sees a literal null value passed to ``fetch``. Note that, unlike the declaration attribute ``nonnull``, the presence of ``_Nonnull`` does not imply that passing null is undefined behavior: ``fetch`` is free to consider null undefined behavior or (perhaps for backward-compatibility reasons) defensively handle null.
+
+
+_Null_unspecified
+-----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+The ``_Null_unspecified`` nullability qualifier indicates that neither the ``_Nonnull`` nor ``_Nullable`` qualifiers make sense for a particular pointer type. It is used primarily to indicate that the role of null with specific pointers in a nullability-annotated header is unclear, e.g., due to overly-complex implementations or historical factors with a long-lived API.
+
+
+_Nullable
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+The ``_Nullable`` nullability qualifier indicates that a value of the ``_Nullable`` pointer type can be null. For example, given:
+
+  .. code-block:: c
+
+    int fetch_or_zero(int * _Nullable ptr);
+
+a caller of ``fetch_or_zero`` can provide null.
+
+

Added: www-releases/trunk/3.7.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.7.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt?rev=246586&view=auto
==============================================================================
--- www-releases/trunk/3.7.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt (added)
+++ www-releases/trunk/3.7.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt Tue Sep  1 15:55:31 2015
@@ -0,0 +1,2291 @@
+.. FIXME: move to the stylesheet or Sphinx plugin
+
+.. raw:: html
+
+  <style>
+    .arc-term { font-style: italic; font-weight: bold; }
+    .revision { font-style: italic; }
+    .when-revised { font-weight: bold; font-style: normal; }
+
+    /*
+     * Automatic numbering is described in this article:
+     * http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
+     */
+    /*
+     * Automatic numbering for the TOC.
+     * This is wrong from the semantics point of view, since it is an ordered
+     * list, but uses "ul" tag.
+     */
+    div#contents.contents.local ul {
+      counter-reset: toc-section;
+      list-style-type: none;
+    }
+    div#contents.contents.local ul li {
+      counter-increment: toc-section;
+      background: none; // Remove bullets
+    }
+    div#contents.contents.local ul li a.reference:before {
+      content: counters(toc-section, ".") " ";
+    }
+
+    /* Automatic numbering for the body. */
+    body {
+      counter-reset: section subsection subsubsection;
+    }
+    .section h2 {
+      counter-reset: subsection subsubsection;
+      counter-increment: section;
+    }
+    .section h2 a.toc-backref:before {
+      content: counter(section) " ";
+    }
+    .section h3 {
+      counter-reset: subsubsection;
+      counter-increment: subsection;
+    }
+    .section h3 a.toc-backref:before {
+      content: counter(section) "." counter(subsection) " ";
+    }
+    .section h4 {
+      counter-increment: subsubsection;
+    }
+    .section h4 a.toc-backref:before {
+      content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
+    }
+  </style>
+
+.. role:: arc-term
+.. role:: revision
+.. role:: when-revised
+
+==============================================
+Objective-C Automatic Reference Counting (ARC)
+==============================================
+
+.. contents::
+   :local:
+
+.. _arc.meta:
+
+About this document
+===================
+
+.. _arc.meta.purpose:
+
+Purpose
+-------
+
+The first and primary purpose of this document is to serve as a complete
+technical specification of Automatic Reference Counting.  Given a core
+Objective-C compiler and runtime, it should be possible to write a compiler and
+runtime which implements these new semantics.
+
+The secondary purpose is to act as a rationale for why ARC was designed in this
+way.  This should remain tightly focused on the technical design and should not
+stray into marketing speculation.
+
+.. _arc.meta.background:
+
+Background
+----------
+
+This document assumes a basic familiarity with C.
+
+:arc-term:`Blocks` are a C language extension for creating anonymous functions.
+Users interact with and transfer block objects using :arc-term:`block
+pointers`, which are represented like a normal pointer.  A block may capture
+values from local variables; when this occurs, memory must be dynamically
+allocated.  The initial allocation is done on the stack, but the runtime
+provides a ``Block_copy`` function which, given a block pointer, either copies
+the underlying block object to the heap, setting its reference count to 1 and
+returning the new block pointer, or (if the block object is already on the
+heap) increases its reference count by 1.  The paired function is
+``Block_release``, which decreases the reference count by 1 and destroys the
+object if the count reaches zero and is on the heap.
+
+Objective-C is a set of language extensions, significant enough to be
+considered a different language.  It is a strict superset of C.  The extensions
+can also be imposed on C++, producing a language called Objective-C++.  The
+primary feature is a single-inheritance object system; we briefly describe the
+modern dialect.
+
+Objective-C defines a new type kind, collectively called the :arc-term:`object
+pointer types`.  This kind has two notable builtin members, ``id`` and
+``Class``; ``id`` is the final supertype of all object pointers.  The validity
+of conversions between object pointer types is not checked at runtime.  Users
+may define :arc-term:`classes`; each class is a type, and the pointer to that
+type is an object pointer type.  A class may have a superclass; its pointer
+type is a subtype of its superclass's pointer type.  A class has a set of
+:arc-term:`ivars`, fields which appear on all instances of that class.  For
+every class *T* there's an associated metaclass; it has no fields, its
+superclass is the metaclass of *T*'s superclass, and its metaclass is a global
+class.  Every class has a global object whose class is the class's metaclass;
+metaclasses have no associated type, so pointers to this object have type
+``Class``.
+
+A class declaration (``@interface``) declares a set of :arc-term:`methods`.  A
+method has a return type, a list of argument types, and a :arc-term:`selector`:
+a name like ``foo:bar:baz:``, where the number of colons corresponds to the
+number of formal arguments.  A method may be an instance method, in which case
+it can be invoked on objects of the class, or a class method, in which case it
+can be invoked on objects of the metaclass.  A method may be invoked by
+providing an object (called the :arc-term:`receiver`) and a list of formal
+arguments interspersed with the selector, like so:
+
+.. code-block:: objc
+
+  [receiver foo: fooArg bar: barArg baz: bazArg]
+
+This looks in the dynamic class of the receiver for a method with this name,
+then in that class's superclass, etc., until it finds something it can execute.
+The receiver "expression" may also be the name of a class, in which case the
+actual receiver is the class object for that class, or (within method
+definitions) it may be ``super``, in which case the lookup algorithm starts
+with the static superclass instead of the dynamic class.  The actual methods
+dynamically found in a class are not those declared in the ``@interface``, but
+those defined in a separate ``@implementation`` declaration; however, when
+compiling a call, typechecking is done based on the methods declared in the
+``@interface``.
+
+Method declarations may also be grouped into :arc-term:`protocols`, which are not
+inherently associated with any class, but which classes may claim to follow.
+Object pointer types may be qualified with additional protocols that the object
+is known to support.
+
+:arc-term:`Class extensions` are collections of ivars and methods, designed to
+allow a class's ``@interface`` to be split across multiple files; however,
+there is still a primary implementation file which must see the
+``@interface``\ s of all class extensions.  :arc-term:`Categories` allow
+methods (but not ivars) to be declared *post hoc* on an arbitrary class; the
+methods in the category's ``@implementation`` will be dynamically added to that
+class's method tables which the category is loaded at runtime, replacing those
+methods in case of a collision.
+
+In the standard environment, objects are allocated on the heap, and their
+lifetime is manually managed using a reference count.  This is done using two
+instance methods which all classes are expected to implement: ``retain``
+increases the object's reference count by 1, whereas ``release`` decreases it
+by 1 and calls the instance method ``dealloc`` if the count reaches 0.  To
+simplify certain operations, there is also an :arc-term:`autorelease pool`, a
+thread-local list of objects to call ``release`` on later; an object can be
+added to this pool by calling ``autorelease`` on it.
+
+Block pointers may be converted to type ``id``; block objects are laid out in a
+way that makes them compatible with Objective-C objects.  There is a builtin
+class that all block objects are considered to be objects of; this class
+implements ``retain`` by adjusting the reference count, not by calling
+``Block_copy``.
+
+.. _arc.meta.evolution:
+
+Evolution
+---------
+
+ARC is under continual evolution, and this document must be updated as the
+language progresses.
+
+If a change increases the expressiveness of the language, for example by
+lifting a restriction or by adding new syntax, the change will be annotated
+with a revision marker, like so:
+
+  ARC applies to Objective-C pointer types, block pointer types, and
+  :when-revised:`[beginning Apple 8.0, LLVM 3.8]` :revision:`BPTRs declared
+  within` ``extern "BCPL"`` blocks.
+
+For now, it is sensible to version this document by the releases of its sole
+implementation (and its host project), clang.  "LLVM X.Y" refers to an
+open-source release of clang from the LLVM project.  "Apple X.Y" refers to an
+Apple-provided release of the Apple LLVM Compiler.  Other organizations that
+prepare their own, separately-versioned clang releases and wish to maintain
+similar information in this document should send requests to cfe-dev.
+
+If a change decreases the expressiveness of the language, for example by
+imposing a new restriction, this should be taken as an oversight in the
+original specification and something to be avoided in all versions.  Such
+changes are generally to be avoided.
+
+.. _arc.general:
+
+General
+=======
+
+Automatic Reference Counting implements automatic memory management for
+Objective-C objects and blocks, freeing the programmer from the need to
+explicitly insert retains and releases.  It does not provide a cycle collector;
+users must explicitly manage the lifetime of their objects, breaking cycles
+manually or with weak or unsafe references.
+
+ARC may be explicitly enabled with the compiler flag ``-fobjc-arc``.  It may
+also be explicitly disabled with the compiler flag ``-fno-objc-arc``.  The last
+of these two flags appearing on the compile line "wins".
+
+If ARC is enabled, ``__has_feature(objc_arc)`` will expand to 1 in the
+preprocessor.  For more information about ``__has_feature``, see the
+:ref:`language extensions <langext-__has_feature-__has_extension>` document.
+
+.. _arc.objects:
+
+Retainable object pointers
+==========================
+
+This section describes retainable object pointers, their basic operations, and
+the restrictions imposed on their use under ARC.  Note in particular that it
+covers the rules for pointer *values* (patterns of bits indicating the location
+of a pointed-to object), not pointer *objects* (locations in memory which store
+pointer values).  The rules for objects are covered in the next section.
+
+A :arc-term:`retainable object pointer` (or "retainable pointer") is a value of
+a :arc-term:`retainable object pointer type` ("retainable type").  There are
+three kinds of retainable object pointer types:
+
+* block pointers (formed by applying the caret (``^``) declarator sigil to a
+  function type)
+* Objective-C object pointers (``id``, ``Class``, ``NSFoo*``, etc.)
+* typedefs marked with ``__attribute__((NSObject))``
+
+Other pointer types, such as ``int*`` and ``CFStringRef``, are not subject to
+ARC's semantics and restrictions.
+
+.. admonition:: Rationale
+
+  We are not at liberty to require all code to be recompiled with ARC;
+  therefore, ARC must interoperate with Objective-C code which manages retains
+  and releases manually.  In general, there are three requirements in order for
+  a compiler-supported reference-count system to provide reliable
+  interoperation:
+
+  * The type system must reliably identify which objects are to be managed.  An
+    ``int*`` might be a pointer to a ``malloc``'ed array, or it might be an
+    interior pointer to such an array, or it might point to some field or local
+    variable.  In contrast, values of the retainable object pointer types are
+    never interior.
+
+  * The type system must reliably indicate how to manage objects of a type.
+    This usually means that the type must imply a procedure for incrementing
+    and decrementing retain counts.  Supporting single-ownership objects
+    requires a lot more explicit mediation in the language.
+
+  * There must be reliable conventions for whether and when "ownership" is
+    passed between caller and callee, for both arguments and return values.
+    Objective-C methods follow such a convention very reliably, at least for
+    system libraries on Mac OS X, and functions always pass objects at +0.  The
+    C-based APIs for Core Foundation objects, on the other hand, have much more
+    varied transfer semantics.
+
+The use of ``__attribute__((NSObject))`` typedefs is not recommended.  If it's
+absolutely necessary to use this attribute, be very explicit about using the
+typedef, and do not assume that it will be preserved by language features like
+``__typeof`` and C++ template argument substitution.
+
+.. admonition:: Rationale
+
+  Any compiler operation which incidentally strips type "sugar" from a type
+  will yield a type without the attribute, which may result in unexpected
+  behavior.
+
+.. _arc.objects.retains:
+
+Retain count semantics
+----------------------
+
+A retainable object pointer is either a :arc-term:`null pointer` or a pointer
+to a valid object.  Furthermore, if it has block pointer type and is not
+``null`` then it must actually be a pointer to a block object, and if it has
+``Class`` type (possibly protocol-qualified) then it must actually be a pointer
+to a class object.  Otherwise ARC does not enforce the Objective-C type system
+as long as the implementing methods follow the signature of the static type.
+It is undefined behavior if ARC is exposed to an invalid pointer.
+
+For ARC's purposes, a valid object is one with "well-behaved" retaining
+operations.  Specifically, the object must be laid out such that the
+Objective-C message send machinery can successfully send it the following
+messages:
+
+* ``retain``, taking no arguments and returning a pointer to the object.
+* ``release``, taking no arguments and returning ``void``.
+* ``autorelease``, taking no arguments and returning a pointer to the object.
+
+The behavior of these methods is constrained in the following ways.  The term
+:arc-term:`high-level semantics` is an intentionally vague term; the intent is
+that programmers must implement these methods in a way such that the compiler,
+modifying code in ways it deems safe according to these constraints, will not
+violate their requirements.  For example, if the user puts logging statements
+in ``retain``, they should not be surprised if those statements are executed
+more or less often depending on optimization settings.  These constraints are
+not exhaustive of the optimization opportunities: values held in local
+variables are subject to additional restrictions, described later in this
+document.
+
+It is undefined behavior if a computation history featuring a send of
+``retain`` followed by a send of ``release`` to the same object, with no
+intervening ``release`` on that object, is not equivalent under the high-level
+semantics to a computation history in which these sends are removed.  Note that
+this implies that these methods may not raise exceptions.
+
+It is undefined behavior if a computation history features any use whatsoever
+of an object following the completion of a send of ``release`` that is not
+preceded by a send of ``retain`` to the same object.
+
+The behavior of ``autorelease`` must be equivalent to sending ``release`` when
+one of the autorelease pools currently in scope is popped.  It may not throw an
+exception.
+
+When the semantics call for performing one of these operations on a retainable
+object pointer, if that pointer is ``null`` then the effect is a no-op.
+
+All of the semantics described in this document are subject to additional
+:ref:`optimization rules <arc.optimization>` which permit the removal or
+optimization of operations based on local knowledge of data flow.  The
+semantics describe the high-level behaviors that the compiler implements, not
+an exact sequence of operations that a program will be compiled into.
+
+.. _arc.objects.operands:
+
+Retainable object pointers as operands and arguments
+----------------------------------------------------
+
+In general, ARC does not perform retain or release operations when simply using
+a retainable object pointer as an operand within an expression.  This includes:
+
+* loading a retainable pointer from an object with non-weak :ref:`ownership
+  <arc.ownership>`,
+* passing a retainable pointer as an argument to a function or method, and
+* receiving a retainable pointer as the result of a function or method call.
+
+.. admonition:: Rationale
+
+  While this might seem uncontroversial, it is actually unsafe when multiple
+  expressions are evaluated in "parallel", as with binary operators and calls,
+  because (for example) one expression might load from an object while another
+  writes to it.  However, C and C++ already call this undefined behavior
+  because the evaluations are unsequenced, and ARC simply exploits that here to
+  avoid needing to retain arguments across a large number of calls.
+
+The remainder of this section describes exceptions to these rules, how those
+exceptions are detected, and what those exceptions imply semantically.
+
+.. _arc.objects.operands.consumed:
+
+Consumed parameters
+^^^^^^^^^^^^^^^^^^^
+
+A function or method parameter of retainable object pointer type may be marked
+as :arc-term:`consumed`, signifying that the callee expects to take ownership
+of a +1 retain count.  This is done by adding the ``ns_consumed`` attribute to
+the parameter declaration, like so:
+
+.. code-block:: objc
+
+  void foo(__attribute((ns_consumed)) id x);
+  - (void) foo: (id) __attribute((ns_consumed)) x;
+
+This attribute is part of the type of the function or method, not the type of
+the parameter.  It controls only how the argument is passed and received.
+
+When passing such an argument, ARC retains the argument prior to making the
+call.
+
+When receiving such an argument, ARC releases the argument at the end of the
+function, subject to the usual optimizations for local values.
+
+.. admonition:: Rationale
+
+  This formalizes direct transfers of ownership from a caller to a callee.  The
+  most common scenario here is passing the ``self`` parameter to ``init``, but
+  it is useful to generalize.  Typically, local optimization will remove any
+  extra retains and releases: on the caller side the retain will be merged with
+  a +1 source, and on the callee side the release will be rolled into the
+  initialization of the parameter.
+
+The implicit ``self`` parameter of a method may be marked as consumed by adding
+``__attribute__((ns_consumes_self))`` to the method declaration.  Methods in
+the ``init`` :ref:`family <arc.method-families>` are treated as if they were
+implicitly marked with this attribute.
+
+It is undefined behavior if an Objective-C message send to a method with
+``ns_consumed`` parameters (other than self) is made with a null receiver.  It
+is undefined behavior if the method to which an Objective-C message send
+statically resolves to has a different set of ``ns_consumed`` parameters than
+the method it dynamically resolves to.  It is undefined behavior if a block or
+function call is made through a static type with a different set of
+``ns_consumed`` parameters than the implementation of the called block or
+function.
+
+.. admonition:: Rationale
+
+  Consumed parameters with null receiver are a guaranteed leak.  Mismatches
+  with consumed parameters will cause over-retains or over-releases, depending
+  on the direction.  The rule about function calls is really just an
+  application of the existing C/C++ rule about calling functions through an
+  incompatible function type, but it's useful to state it explicitly.
+
+.. _arc.object.operands.retained-return-values:
+
+Retained return values
+^^^^^^^^^^^^^^^^^^^^^^
+
+A function or method which returns a retainable object pointer type may be
+marked as returning a retained value, signifying that the caller expects to take
+ownership of a +1 retain count.  This is done by adding the
+``ns_returns_retained`` attribute to the function or method declaration, like
+so:
+
+.. code-block:: objc
+
+  id foo(void) __attribute((ns_returns_retained));
+  - (id) foo __attribute((ns_returns_retained));
+
+This attribute is part of the type of the function or method.
+
+When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, before leaving all local scopes.
+
+When receiving a return result from such a function or method, ARC releases the
+value at the end of the full-expression it is contained within, subject to the
+usual optimizations for local values.
+
+.. admonition:: Rationale
+
+  This formalizes direct transfers of ownership from a callee to a caller.  The
+  most common scenario this models is the retained return from ``init``,
+  ``alloc``, ``new``, and ``copy`` methods, but there are other cases in the
+  frameworks.  After optimization there are typically no extra retains and
+  releases required.
+
+Methods in the ``alloc``, ``copy``, ``init``, ``mutableCopy``, and ``new``
+:ref:`families <arc.method-families>` are implicitly marked
+``__attribute__((ns_returns_retained))``.  This may be suppressed by explicitly
+marking the method ``__attribute__((ns_returns_not_retained))``.
+
+It is undefined behavior if the method to which an Objective-C message send
+statically resolves has different retain semantics on its result from the
+method it dynamically resolves to.  It is undefined behavior if a block or
+function call is made through a static type with different retain semantics on
+its result from the implementation of the called block or function.
+
+.. admonition:: Rationale
+
+  Mismatches with returned results will cause over-retains or over-releases,
+  depending on the direction.  Again, the rule about function calls is really
+  just an application of the existing C/C++ rule about calling functions
+  through an incompatible function type.
+
+.. _arc.objects.operands.unretained-returns:
+
+Unretained return values
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A method or function which returns a retainable object type but does not return
+a retained value must ensure that the object is still valid across the return
+boundary.
+
+When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, then leaves all local scopes, and
+then balances out the retain while ensuring that the value lives across the
+call boundary.  In the worst case, this may involve an ``autorelease``, but
+callers must not assume that the value is actually in the autorelease pool.
+
+ARC performs no extra mandatory work on the caller side, although it may elect
+to do something to shorten the lifetime of the returned value.
+
+.. admonition:: Rationale
+
+  It is common in non-ARC code to not return an autoreleased value; therefore
+  the convention does not force either path.  It is convenient to not be
+  required to do unnecessary retains and autoreleases; this permits
+  optimizations such as eliding retain/autoreleases when it can be shown that
+  the original pointer will still be valid at the point of return.
+
+A method or function may be marked with
+``__attribute__((ns_returns_autoreleased))`` to indicate that it returns a
+pointer which is guaranteed to be valid at least as long as the innermost
+autorelease pool.  There are no additional semantics enforced in the definition
+of such a method; it merely enables optimizations in callers.
+
+.. _arc.objects.operands.casts:
+
+Bridged casts
+^^^^^^^^^^^^^
+
+A :arc-term:`bridged cast` is a C-style cast annotated with one of three
+keywords:
+
+* ``(__bridge T) op`` casts the operand to the destination type ``T``.  If
+  ``T`` is a retainable object pointer type, then ``op`` must have a
+  non-retainable pointer type.  If ``T`` is a non-retainable pointer type,
+  then ``op`` must have a retainable object pointer type.  Otherwise the cast
+  is ill-formed.  There is no transfer of ownership, and ARC inserts no retain
+  operations.
+* ``(__bridge_retained T) op`` casts the operand, which must have retainable
+  object pointer type, to the destination type, which must be a non-retainable
+  pointer type.  ARC retains the value, subject to the usual optimizations on
+  local values, and the recipient is responsible for balancing that +1.
+* ``(__bridge_transfer T) op`` casts the operand, which must have
+  non-retainable pointer type, to the destination type, which must be a
+  retainable object pointer type.  ARC will release the value at the end of
+  the enclosing full-expression, subject to the usual optimizations on local
+  values.
+
+These casts are required in order to transfer objects in and out of ARC
+control; see the rationale in the section on :ref:`conversion of retainable
+object pointers <arc.objects.restrictions.conversion>`.
+
+Using a ``__bridge_retained`` or ``__bridge_transfer`` cast purely to convince
+ARC to emit an unbalanced retain or release, respectively, is poor form.
+
+.. _arc.objects.restrictions:
+
+Restrictions
+------------
+
+.. _arc.objects.restrictions.conversion:
+
+Conversion of retainable object pointers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In general, a program which attempts to implicitly or explicitly convert a
+value of retainable object pointer type to any non-retainable type, or
+vice-versa, is ill-formed.  For example, an Objective-C object pointer shall
+not be converted to ``void*``.  As an exception, cast to ``intptr_t`` is
+allowed because such casts are not transferring ownership.  The :ref:`bridged
+casts <arc.objects.operands.casts>` may be used to perform these conversions
+where necessary.
+
+.. admonition:: Rationale
+
+  We cannot ensure the correct management of the lifetime of objects if they
+  may be freely passed around as unmanaged types.  The bridged casts are
+  provided so that the programmer may explicitly describe whether the cast
+  transfers control into or out of ARC.
+
+However, the following exceptions apply.
+
+.. _arc.objects.restrictions.conversion.with.known.semantics:
+
+Conversion to retainable object pointer type of expressions with known semantics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+:revision:`These exceptions have been greatly expanded; they previously applied
+only to a much-reduced subset which is difficult to categorize but which
+included null pointers, message sends (under the given rules), and the various
+global constants.`
+
+An unbridged conversion to a retainable object pointer type from a type other
+than a retainable object pointer type is ill-formed, as discussed above, unless
+the operand of the cast has a syntactic form which is known retained, known
+unretained, or known retain-agnostic.
+
+An expression is :arc-term:`known retain-agnostic` if it is:
+
+* an Objective-C string literal,
+* a load from a ``const`` system global variable of :ref:`C retainable pointer
+  type <arc.misc.c-retainable>`, or
+* a null pointer constant.
+
+An expression is :arc-term:`known unretained` if it is an rvalue of :ref:`C
+retainable pointer type <arc.misc.c-retainable>` and it is:
+
+* a direct call to a function, and either that function has the
+  ``cf_returns_not_retained`` attribute or it is an :ref:`audited
+  <arc.misc.c-retainable.audit>` function that does not have the
+  ``cf_returns_retained`` attribute and does not follow the create/copy naming
+  convention,
+* a message send, and the declared method either has the
+  ``cf_returns_not_retained`` attribute or it has neither the
+  ``cf_returns_retained`` attribute nor a :ref:`selector family
+  <arc.method-families>` that implies a retained result, or
+* :when-revised:`[beginning LLVM 3.6]` :revision:`a load from a` ``const``
+  :revision:`non-system global variable.`
+
+An expression is :arc-term:`known retained` if it is an rvalue of :ref:`C
+retainable pointer type <arc.misc.c-retainable>` and it is:
+
+* a message send, and the declared method either has the
+  ``cf_returns_retained`` attribute, or it does not have the
+  ``cf_returns_not_retained`` attribute but it does have a :ref:`selector
+  family <arc.method-families>` that implies a retained result.
+
+Furthermore:
+
+* a comma expression is classified according to its right-hand side,
+* a statement expression is classified according to its result expression, if
+  it has one,
+* an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
+  classified according to the underlying message send, and
+* a conditional operator is classified according to its second and third
+  operands, if they agree in classification, or else the other if one is known
+  retain-agnostic.
+
+If the cast operand is known retained, the conversion is treated as a
+``__bridge_transfer`` cast.  If the cast operand is known unretained or known
+retain-agnostic, the conversion is treated as a ``__bridge`` cast.
+
+.. admonition:: Rationale
+
+  Bridging casts are annoying.  Absent the ability to completely automate the
+  management of CF objects, however, we are left with relatively poor attempts
+  to reduce the need for a glut of explicit bridges.  Hence these rules.
+
+  We've so far consciously refrained from implicitly turning retained CF
+  results from function calls into ``__bridge_transfer`` casts.  The worry is
+  that some code patterns  ---  for example, creating a CF value, assigning it
+  to an ObjC-typed local, and then calling ``CFRelease`` when done  ---  are a
+  bit too likely to be accidentally accepted, leading to mysterious behavior.
+
+  For loads from ``const`` global variables of :ref:`C retainable pointer type
+  <arc.misc.c-retainable>`, it is reasonable to assume that global system
+  constants were initialitzed with true constants (e.g. string literals), but
+  user constants might have been initialized with something dynamically
+  allocated, using a global initializer.
+
+.. _arc.objects.restrictions.conversion-exception-contextual:
+
+Conversion from retainable object pointer type in certain contexts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+
+If an expression of retainable object pointer type is explicitly cast to a
+:ref:`C retainable pointer type <arc.misc.c-retainable>`, the program is
+ill-formed as discussed above unless the result is immediately used:
+
+* to initialize a parameter in an Objective-C message send where the parameter
+  is not marked with the ``cf_consumed`` attribute, or
+* to initialize a parameter in a direct call to an
+  :ref:`audited <arc.misc.c-retainable.audit>` function where the parameter is
+  not marked with the ``cf_consumed`` attribute.
+
+.. admonition:: Rationale
+
+  Consumed parameters are left out because ARC would naturally balance them
+  with a retain, which was judged too treacherous.  This is in part because
+  several of the most common consuming functions are in the ``Release`` family,
+  and it would be quite unfortunate for explicit releases to be silently
+  balanced out in this way.
+
+.. _arc.ownership:
+
+Ownership qualification
+=======================
+
+This section describes the behavior of *objects* of retainable object pointer
+type; that is, locations in memory which store retainable object pointers.
+
+A type is a :arc-term:`retainable object owner type` if it is a retainable
+object pointer type or an array type whose element type is a retainable object
+owner type.
+
+An :arc-term:`ownership qualifier` is a type qualifier which applies only to
+retainable object owner types.  An array type is ownership-qualified according
+to its element type, and adding an ownership qualifier to an array type so
+qualifies its element type.
+
+A program is ill-formed if it attempts to apply an ownership qualifier to a
+type which is already ownership-qualified, even if it is the same qualifier.
+There is a single exception to this rule: an ownership qualifier may be applied
+to a substituted template type parameter, which overrides the ownership
+qualifier provided by the template argument.
+
+When forming a function type, the result type is adjusted so that any
+top-level ownership qualifier is deleted.
+
+Except as described under the :ref:`inference rules <arc.ownership.inference>`,
+a program is ill-formed if it attempts to form a pointer or reference type to a
+retainable object owner type which lacks an ownership qualifier.
+
+.. admonition:: Rationale
+
+  These rules, together with the inference rules, ensure that all objects and
+  lvalues of retainable object pointer type have an ownership qualifier.  The
+  ability to override an ownership qualifier during template substitution is
+  required to counteract the :ref:`inference of __strong for template type
+  arguments <arc.ownership.inference.template.arguments>`.  Ownership qualifiers
+  on return types are dropped because they serve no purpose there except to
+  cause spurious problems with overloading and templates.
+
+There are four ownership qualifiers:
+
+* ``__autoreleasing``
+* ``__strong``
+* ``__unsafe_unretained``
+* ``__weak``
+
+A type is :arc-term:`nontrivially ownership-qualified` if it is qualified with
+``__autoreleasing``, ``__strong``, or ``__weak``.
+
+.. _arc.ownership.spelling:
+
+Spelling
+--------
+
+The names of the ownership qualifiers are reserved for the implementation.  A
+program may not assume that they are or are not implemented with macros, or
+what those macros expand to.
+
+An ownership qualifier may be written anywhere that any other type qualifier
+may be written.
+
+If an ownership qualifier appears in the *declaration-specifiers*, the
+following rules apply:
+
+* if the type specifier is a retainable object owner type, the qualifier
+  initially applies to that type;
+
+* otherwise, if the outermost non-array declarator is a pointer
+  or block pointer declarator, the qualifier initially applies to
+  that type;
+
+* otherwise the program is ill-formed.
+
+* If the qualifier is so applied at a position in the declaration
+  where the next-innermost declarator is a function declarator, and
+  there is an block declarator within that function declarator, then
+  the qualifier applies instead to that block declarator and this rule
+  is considered afresh beginning from the new position.
+
+If an ownership qualifier appears on the declarator name, or on the declared
+object, it is applied to the innermost pointer or block-pointer type.
+
+If an ownership qualifier appears anywhere else in a declarator, it applies to
+the type there.
+
+.. admonition:: Rationale
+
+  Ownership qualifiers are like ``const`` and ``volatile`` in the sense
+  that they may sensibly apply at multiple distinct positions within a
+  declarator.  However, unlike those qualifiers, there are many
+  situations where they are not meaningful, and so we make an effort
+  to "move" the qualifier to a place where it will be meaningful.  The
+  general goal is to allow the programmer to write, say, ``__strong``
+  before the entire declaration and have it apply in the leftmost
+  sensible place.
+
+.. _arc.ownership.spelling.property:
+
+Property declarations
+^^^^^^^^^^^^^^^^^^^^^
+
+A property of retainable object pointer type may have ownership.  If the
+property's type is ownership-qualified, then the property has that ownership.
+If the property has one of the following modifiers, then the property has the
+corresponding ownership.  A property is ill-formed if it has conflicting
+sources of ownership, or if it has redundant ownership modifiers, or if it has
+``__autoreleasing`` ownership.
+
+* ``assign`` implies ``__unsafe_unretained`` ownership.
+* ``copy`` implies ``__strong`` ownership, as well as the usual behavior of
+  copy semantics on the setter.
+* ``retain`` implies ``__strong`` ownership.
+* ``strong`` implies ``__strong`` ownership.
+* ``unsafe_unretained`` implies ``__unsafe_unretained`` ownership.
+* ``weak`` implies ``__weak`` ownership.
+
+With the exception of ``weak``, these modifiers are available in non-ARC
+modes.
+
+A property's specified ownership is preserved in its metadata, but otherwise
+the meaning is purely conventional unless the property is synthesized.  If a
+property is synthesized, then the :arc-term:`associated instance variable` is
+the instance variable which is named, possibly implicitly, by the
+``@synthesize`` declaration.  If the associated instance variable already
+exists, then its ownership qualification must equal the ownership of the
+property; otherwise, the instance variable is created with that ownership
+qualification.
+
+A property of retainable object pointer type which is synthesized without a
+source of ownership has the ownership of its associated instance variable, if it
+already exists; otherwise, :when-revised:`[beginning Apple 3.1, LLVM 3.1]`
+:revision:`its ownership is implicitly` ``strong``.  Prior to this revision, it
+was ill-formed to synthesize such a property.
+
+.. admonition:: Rationale
+
+  Using ``strong`` by default is safe and consistent with the generic ARC rule
+  about :ref:`inferring ownership <arc.ownership.inference.variables>`.  It is,
+  unfortunately, inconsistent with the non-ARC rule which states that such
+  properties are implicitly ``assign``.  However, that rule is clearly
+  untenable in ARC, since it leads to default-unsafe code.  The main merit to
+  banning the properties is to avoid confusion with non-ARC practice, which did
+  not ultimately strike us as sufficient to justify requiring extra syntax and
+  (more importantly) forcing novices to understand ownership rules just to
+  declare a property when the default is so reasonable.  Changing the rule away
+  from non-ARC practice was acceptable because we had conservatively banned the
+  synthesis in order to give ourselves exactly this leeway.
+
+Applying ``__attribute__((NSObject))`` to a property not of retainable object
+pointer type has the same behavior it does outside of ARC: it requires the
+property type to be some sort of pointer and permits the use of modifiers other
+than ``assign``.  These modifiers only affect the synthesized getter and
+setter; direct accesses to the ivar (even if synthesized) still have primitive
+semantics, and the value in the ivar will not be automatically released during
+deallocation.
+
+.. _arc.ownership.semantics:
+
+Semantics
+---------
+
+There are five :arc-term:`managed operations` which may be performed on an
+object of retainable object pointer type.  Each qualifier specifies different
+semantics for each of these operations.  It is still undefined behavior to
+access an object outside of its lifetime.
+
+A load or store with "primitive semantics" has the same semantics as the
+respective operation would have on an ``void*`` lvalue with the same alignment
+and non-ownership qualification.
+
+:arc-term:`Reading` occurs when performing a lvalue-to-rvalue conversion on an
+object lvalue.
+
+* For ``__weak`` objects, the current pointee is retained and then released at
+  the end of the current full-expression.  This must execute atomically with
+  respect to assignments and to the final release of the pointee.
+* For all other objects, the lvalue is loaded with primitive semantics.
+
+:arc-term:`Assignment` occurs when evaluating an assignment operator.  The
+semantics vary based on the qualification:
+
+* For ``__strong`` objects, the new pointee is first retained; second, the
+  lvalue is loaded with primitive semantics; third, the new pointee is stored
+  into the lvalue with primitive semantics; and finally, the old pointee is
+  released.  This is not performed atomically; external synchronization must be
+  used to make this safe in the face of concurrent loads and stores.
+* For ``__weak`` objects, the lvalue is updated to point to the new pointee,
+  unless the new pointee is an object currently undergoing deallocation, in
+  which case the lvalue is updated to a null pointer.  This must execute
+  atomically with respect to other assignments to the object, to reads from the
+  object, and to the final release of the new pointee.
+* For ``__unsafe_unretained`` objects, the new pointee is stored into the
+  lvalue using primitive semantics.
+* For ``__autoreleasing`` objects, the new pointee is retained, autoreleased,
+  and stored into the lvalue using primitive semantics.
+
+:arc-term:`Initialization` occurs when an object's lifetime begins, which
+depends on its storage duration.  Initialization proceeds in two stages:
+
+#. First, a null pointer is stored into the lvalue using primitive semantics.
+   This step is skipped if the object is ``__unsafe_unretained``.
+#. Second, if the object has an initializer, that expression is evaluated and
+   then assigned into the object using the usual assignment semantics.
+
+:arc-term:`Destruction` occurs when an object's lifetime ends.  In all cases it
+is semantically equivalent to assigning a null pointer to the object, with the
+proviso that of course the object cannot be legally read after the object's
+lifetime ends.
+
+:arc-term:`Moving` occurs in specific situations where an lvalue is "moved
+from", meaning that its current pointee will be used but the object may be left
+in a different (but still valid) state.  This arises with ``__block`` variables
+and rvalue references in C++.  For ``__strong`` lvalues, moving is equivalent
+to loading the lvalue with primitive semantics, writing a null pointer to it
+with primitive semantics, and then releasing the result of the load at the end
+of the current full-expression.  For all other lvalues, moving is equivalent to
+reading the object.
+
+.. _arc.ownership.restrictions:
+
+Restrictions
+------------
+
+.. _arc.ownership.restrictions.weak:
+
+Weak-unavailable types
+^^^^^^^^^^^^^^^^^^^^^^
+
+It is explicitly permitted for Objective-C classes to not support ``__weak``
+references.  It is undefined behavior to perform an operation with weak
+assignment semantics with a pointer to an Objective-C object whose class does
+not support ``__weak`` references.
+
+.. admonition:: Rationale
+
+  Historically, it has been possible for a class to provide its own
+  reference-count implementation by overriding ``retain``, ``release``, etc.
+  However, weak references to an object require coordination with its class's
+  reference-count implementation because, among other things, weak loads and
+  stores must be atomic with respect to the final release.  Therefore, existing
+  custom reference-count implementations will generally not support weak
+  references without additional effort.  This is unavoidable without breaking
+  binary compatibility.
+
+A class may indicate that it does not support weak references by providing the
+``objc_arc_weak_unavailable`` attribute on the class's interface declaration.  A
+retainable object pointer type is **weak-unavailable** if
+is a pointer to an (optionally protocol-qualified) Objective-C class ``T`` where
+``T`` or one of its superclasses has the ``objc_arc_weak_unavailable``
+attribute.  A program is ill-formed if it applies the ``__weak`` ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.
+
+.. _arc.ownership.restrictions.autoreleasing:
+
+Storage duration of ``__autoreleasing`` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares an ``__autoreleasing`` object of
+non-automatic storage duration.  A program is ill-formed if it captures an
+``__autoreleasing`` object in a block or, unless by reference, in a C++11
+lambda.
+
+.. admonition:: Rationale
+
+  Autorelease pools are tied to the current thread and scope by their nature.
+  While it is possible to have temporary objects whose instance variables are
+  filled with autoreleased objects, there is no way that ARC can provide any
+  sort of safety guarantee there.
+
+It is undefined behavior if a non-null pointer is assigned to an
+``__autoreleasing`` object while an autorelease pool is in scope and then that
+object is read after the autorelease pool's scope is left.
+
+.. _arc.ownership.restrictions.conversion.indirect:
+
+Conversion of pointers to ownership-qualified types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if an expression of type ``T*`` is converted,
+explicitly or implicitly, to the type ``U*``, where ``T`` and ``U`` have
+different ownership qualification, unless:
+
+* ``T`` is qualified with ``__strong``, ``__autoreleasing``, or
+  ``__unsafe_unretained``, and ``U`` is qualified with both ``const`` and
+  ``__unsafe_unretained``; or
+* either ``T`` or ``U`` is ``cv void``, where ``cv`` is an optional sequence
+  of non-ownership qualifiers; or
+* the conversion is requested with a ``reinterpret_cast`` in Objective-C++; or
+* the conversion is a well-formed :ref:`pass-by-writeback
+  <arc.ownership.restrictions.pass_by_writeback>`.
+
+The analogous rule applies to ``T&`` and ``U&`` in Objective-C++.
+
+.. admonition:: Rationale
+
+  These rules provide a reasonable level of type-safety for indirect pointers,
+  as long as the underlying memory is not deallocated.  The conversion to
+  ``const __unsafe_unretained`` is permitted because the semantics of reads are
+  equivalent across all these ownership semantics, and that's a very useful and
+  common pattern.  The interconversion with ``void*`` is useful for allocating
+  memory or otherwise escaping the type system, but use it carefully.
+  ``reinterpret_cast`` is considered to be an obvious enough sign of taking
+  responsibility for any problems.
+
+It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-``__weak`` object
+may be read through an ``__unsafe_unretained`` lvalue.
+
+It is undefined behavior if a managed operation is performed on a ``__strong``
+or ``__weak`` object without a guarantee that it contains a primitive zero
+bit-pattern, or if the storage for such an object is freed or reused without the
+object being first assigned a null pointer.
+
+.. admonition:: Rationale
+
+  ARC cannot differentiate between an assignment operator which is intended to
+  "initialize" dynamic memory and one which is intended to potentially replace
+  a value.  Therefore the object's pointer must be valid before letting ARC at
+  it.  Similarly, C and Objective-C do not provide any language hooks for
+  destroying objects held in dynamic memory, so it is the programmer's
+  responsibility to avoid leaks (``__strong`` objects) and consistency errors
+  (``__weak`` objects).
+
+These requirements are followed automatically in Objective-C++ when creating
+objects of retainable object owner type with ``new`` or ``new[]`` and destroying
+them with ``delete``, ``delete[]``, or a pseudo-destructor expression.  Note
+that arrays of nontrivially-ownership-qualified type are not ABI compatible with
+non-ARC code because the element type is non-POD: such arrays that are
+``new[]``'d in ARC translation units cannot be ``delete[]``'d in non-ARC
+translation units and vice-versa.
+
+.. _arc.ownership.restrictions.pass_by_writeback:
+
+Passing to an out parameter by writeback
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the argument passed to a parameter of type ``T __autoreleasing *`` has type
+``U oq *``, where ``oq`` is an ownership qualifier, then the argument is a
+candidate for :arc-term:`pass-by-writeback`` if:
+
+* ``oq`` is ``__strong`` or ``__weak``, and
+* it would be legal to initialize a ``T __strong *`` with a ``U __strong *``.
+
+For purposes of overload resolution, an implicit conversion sequence requiring
+a pass-by-writeback is always worse than an implicit conversion sequence not
+requiring a pass-by-writeback.
+
+The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:
+
+* ``&var``, where ``var`` is a scalar variable of automatic storage duration
+  with retainable object pointer type
+* a conditional expression where the second and third operands are both legal
+  forms
+* a cast whose operand is a legal form
+* a null pointer constant
+
+.. admonition:: Rationale
+
+  The restriction in the form of the argument serves two purposes.  First, it
+  makes it impossible to pass the address of an array to the argument, which
+  serves to protect against an otherwise serious risk of mis-inferring an
+  "array" argument as an out-parameter.  Second, it makes it much less likely
+  that the user will see confusing aliasing problems due to the implementation,
+  below, where their store to the writeback temporary is not immediately seen
+  in the original argument variable.
+
+A pass-by-writeback is evaluated as follows:
+
+#. The argument is evaluated to yield a pointer ``p`` of type ``U oq *``.
+#. If ``p`` is a null pointer, then a null pointer is passed as the argument,
+   and no further work is required for the pass-by-writeback.
+#. Otherwise, a temporary of type ``T __autoreleasing`` is created and
+   initialized to a null pointer.
+#. If the parameter is not an Objective-C method parameter marked ``out``,
+   then ``*p`` is read, and the result is written into the temporary with
+   primitive semantics.
+#. The address of the temporary is passed as the argument to the actual call.
+#. After the call completes, the temporary is loaded with primitive
+   semantics, and that value is assigned into ``*p``.
+
+.. admonition:: Rationale
+
+  This is all admittedly convoluted.  In an ideal world, we would see that a
+  local variable is being passed to an out-parameter and retroactively modify
+  its type to be ``__autoreleasing`` rather than ``__strong``.  This would be
+  remarkably difficult and not always well-founded under the C type system.
+  However, it was judged unacceptably invasive to require programmers to write
+  ``__autoreleasing`` on all the variables they intend to use for
+  out-parameters.  This was the least bad solution.
+
+.. _arc.ownership.restrictions.records:
+
+Ownership-qualified fields of structs and unions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.
+
+.. admonition:: Rationale
+
+  The resulting type would be non-POD in the C++ sense, but C does not give us
+  very good language tools for managing the lifetime of aggregates, so it is
+  more convenient to simply forbid them.  It is still possible to manage this
+  with a ``void*`` or an ``__unsafe_unretained`` object.
+
+This restriction does not apply in Objective-C++.  However, nontrivally
+ownership-qualified types are considered non-POD: in C++11 terms, they are not
+trivially default constructible, copy constructible, move constructible, copy
+assignable, move assignable, or destructible.  It is a violation of C++'s One
+Definition Rule to use a class outside of ARC that, under ARC, would have a
+nontrivially ownership-qualified member.
+
+.. admonition:: Rationale
+
+  Unlike in C, we can express all the necessary ARC semantics for
+  ownership-qualified subobjects as suboperations of the (default) special
+  member functions for the class.  These functions then become non-trivial.
+  This has the non-obvious result that the class will have a non-trivial copy
+  constructor and non-trivial destructor; if this would not normally be true
+  outside of ARC, objects of the type will be passed and returned in an
+  ABI-incompatible manner.
+
+.. _arc.ownership.inference:
+
+Ownership inference
+-------------------
+
+.. _arc.ownership.inference.variables:
+
+Objects
+^^^^^^^
+
+If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+``__strong`` qualification.
+
+As a special case, if the object's base type is ``Class`` (possibly
+protocol-qualified), the type is adjusted to have ``__unsafe_unretained``
+qualification instead.
+
+.. _arc.ownership.inference.indirect_parameters:
+
+Indirect parameters
+^^^^^^^^^^^^^^^^^^^
+
+If a function or method parameter has type ``T*``, where ``T`` is an
+ownership-unqualified retainable object pointer type, then:
+
+* if ``T`` is ``const``-qualified or ``Class``, then it is implicitly
+  qualified with ``__unsafe_unretained``;
+* otherwise, it is implicitly qualified with ``__autoreleasing``.
+
+.. admonition:: Rationale
+
+  ``__autoreleasing`` exists mostly for this case, the Cocoa convention for
+  out-parameters.  Since a pointer to ``const`` is obviously not an
+  out-parameter, we instead use a type more useful for passing arrays.  If the
+  user instead intends to pass in a *mutable* array, inferring
+  ``__autoreleasing`` is the wrong thing to do; this directs some of the
+  caution in the following rules about writeback.
+
+Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.
+
+This rule does not apply in Objective-C++ if a parameter's type is dependent in
+a template pattern and is only *instantiated* to a type which would be a
+pointer to an unqualified retainable object pointer type.  Such code is still
+ill-formed.
+
+.. admonition:: Rationale
+
+  The convention is very unlikely to be intentional in template code.
+
+.. _arc.ownership.inference.template.arguments:
+
+Template arguments
+^^^^^^^^^^^^^^^^^^
+
+If a template argument for a template type parameter is an retainable object
+owner type that does not have an explicit ownership qualifier, it is adjusted
+to have ``__strong`` qualification.  This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.
+
+.. admonition:: Rationale
+
+  ``__strong`` is a useful default for containers (e.g., ``std::vector<id>``),
+  which would otherwise require explicit qualification.  Moreover, unqualified
+  retainable object pointer types are unlikely to be useful within templates,
+  since they generally need to have a qualifier applied to the before being
+  used.
+
+.. _arc.method-families:
+
+Method families
+===============
+
+An Objective-C method may fall into a :arc-term:`method family`, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.
+
+A method is in a certain method family if:
+
+* it has a ``objc_method_family`` attribute placing it in that family; or if
+  not that,
+* it does not have an ``objc_method_family`` attribute placing it in a
+  different or no family, and
+* its selector falls into the corresponding selector family, and
+* its signature obeys the added restrictions of the method family.
+
+A selector is in a certain selector family if, ignoring any leading
+underscores, the first component of the selector either consists entirely of
+the name of the method family or it begins with that name followed by a
+character other than a lowercase letter.  For example, ``_perform:with:`` and
+``performWith:`` would fall into the ``perform`` family (if we recognized one),
+but ``performing:with`` would not.
+
+The families and their added restrictions are:
+
+* ``alloc`` methods must return a retainable object pointer type.
+* ``copy`` methods must return a retainable object pointer type.
+* ``mutableCopy`` methods must return a retainable object pointer type.
+* ``new`` methods must return a retainable object pointer type.
+* ``init`` methods must be instance methods and must return an Objective-C
+  pointer type.  Additionally, a program is ill-formed if it declares or
+  contains a call to an ``init`` method whose return type is neither ``id`` nor
+  a pointer to a super-class or sub-class of the declaring class (if the method
+  was declared on a class) or the static receiver type of the call (if it was
+  declared on a protocol).
+
+  .. admonition:: Rationale
+
+    There are a fair number of existing methods with ``init``-like selectors
+    which nonetheless don't follow the ``init`` conventions.  Typically these
+    are either accidental naming collisions or helper methods called during
+    initialization.  Because of the peculiar retain/release behavior of
+    ``init`` methods, it's very important not to treat these methods as
+    ``init`` methods if they aren't meant to be.  It was felt that implicitly
+    defining these methods out of the family based on the exact relationship
+    between the return type and the declaring class would be much too subtle
+    and fragile.  Therefore we identify a small number of legitimate-seeming
+    return types and call everything else an error.  This serves the secondary
+    purpose of encouraging programmers not to accidentally give methods names
+    in the ``init`` family.
+
+    Note that a method with an ``init``-family selector which returns a
+    non-Objective-C type (e.g. ``void``) is perfectly well-formed; it simply
+    isn't in the ``init`` family.
+
+A program is ill-formed if a method's declarations, implementations, and
+overrides do not all have the same method family.
+
+.. _arc.family.attribute:
+
+Explicit method family control
+------------------------------
+
+A method may be annotated with the ``objc_method_family`` attribute to
+precisely control which method family it belongs to.  If a method in an
+``@implementation`` does not have this attribute, but there is a method
+declared in the corresponding ``@interface`` that does, then the attribute is
+copied to the declaration in the ``@implementation``.  The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+``__has_attribute(objc_method_family)``.
+
+The attribute is spelled
+``__attribute__((objc_method_family(`` *family* ``)))``.  If *family* is
+``none``, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type.  Otherwise, *family* must be one of
+``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``, in which case the
+method is considered to belong to the corresponding family regardless of its
+selector.  It is an error if a method that is explicitly added to a family in
+this way does not meet the requirements of the family other than the selector
+naming convention.
+
+.. admonition:: Rationale
+
+  The rules codified in this document describe the standard conventions of
+  Objective-C.  However, as these conventions have not heretofore been enforced
+  by an unforgiving mechanical system, they are only imperfectly kept,
+  especially as they haven't always even been precisely defined.  While it is
+  possible to define low-level ownership semantics with attributes like
+  ``ns_returns_retained``, this attribute allows the user to communicate
+  semantic intent, which is of use both to ARC (which, e.g., treats calls to
+  ``init`` specially) and the static analyzer.
+
+.. _arc.family.semantics:
+
+Semantics of method families
+----------------------------
+
+A method's membership in a method family may imply non-standard semantics for
+its parameters and return type.
+
+Methods in the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families ---
+that is, methods in all the currently-defined families except ``init`` ---
+implicitly :ref:`return a retained object
+<arc.object.operands.retained-return-values>` as if they were annotated with
+the ``ns_returns_retained`` attribute.  This can be overridden by annotating
+the method with either of the ``ns_returns_autoreleased`` or
+``ns_returns_not_retained`` attributes.
+
+Properties also follow same naming rules as methods.  This means that those in
+the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families provide access
+to :ref:`retained objects <arc.object.operands.retained-return-values>`.  This
+can be overridden by annotating the property with ``ns_returns_not_retained``
+attribute.
+
+.. _arc.family.semantics.init:
+
+Semantics of ``init``
+^^^^^^^^^^^^^^^^^^^^^
+
+Methods in the ``init`` family implicitly :ref:`consume
+<arc.objects.operands.consumed>` their ``self`` parameter and :ref:`return a
+retained object <arc.object.operands.retained-return-values>`.  Neither of
+these properties can be altered through attributes.
+
+A call to an ``init`` method with a receiver that is either ``self`` (possibly
+parenthesized or casted) or ``super`` is called a :arc-term:`delegate init
+call`.  It is an error for a delegate init call to be made except from an
+``init`` method, and excluding blocks within such methods.
+
+As an exception to the :ref:`usual rule <arc.misc.self>`, the variable ``self``
+is mutable in an ``init`` method and has the usual semantics for a ``__strong``
+variable.  However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an ``init`` method attempts to use the previous value
+of ``self`` after the completion of a delegate init call.  It is conventional,
+but not required, for an ``init`` method to return ``self``.
+
+It is undefined behavior for a program to cause two or more calls to ``init``
+methods on the same object, except that each ``init`` method invocation may
+perform at most one delegate init call.
+
+.. _arc.family.semantics.result_type:
+
+Related result types
+^^^^^^^^^^^^^^^^^^^^
+
+Certain methods are candidates to have :arc-term:`related result types`:
+
+* class methods in the ``alloc`` and ``new`` method families
+* instance methods in the ``init`` family
+* the instance method ``self``
+* outside of ARC, the instance methods ``retain`` and ``autorelease``
+
+If the formal result type of such a method is ``id`` or protocol-qualified
+``id``, or a type equal to the declaring class or a superclass, then it is said
+to have a related result type.  In this case, when invoked in an explicit
+message send, it is assumed to return a type related to the type of the
+receiver:
+
+* if it is a class method, and the receiver is a class name ``T``, the message
+  send expression has type ``T*``; otherwise
+* if it is an instance method, and the receiver has type ``T``, the message
+  send expression has type ``T``; otherwise
+* the message send expression has the normal result type of the method.
+
+This is a new rule of the Objective-C language and applies outside of ARC.
+
+.. admonition:: Rationale
+
+  ARC's automatic code emission is more prone than most code to signature
+  errors, i.e. errors where a call was emitted against one method signature,
+  but the implementing method has an incompatible signature.  Having more
+  precise type information helps drastically lower this risk, as well as
+  catching a number of latent bugs.
+
+.. _arc.optimization:
+
+Optimization
+============
+
+Within this section, the word :arc-term:`function` will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.
+
+This specification describes ARC as performing specific ``retain`` and
+``release`` operations on retainable object pointers at specific
+points during the execution of a program.  These operations make up a
+non-contiguous subsequence of the computation history of the program.
+The portion of this sequence for a particular retainable object
+pointer for which a specific function execution is directly
+responsible is the :arc-term:`formal local retain history` of the
+object pointer.  The corresponding actual sequence executed is the
+`dynamic local retain history`.
+
+However, under certain circumstances, ARC is permitted to re-order and
+eliminate operations in a manner which may alter the overall
+computation history beyond what is permitted by the general "as if"
+rule of C/C++ and the :ref:`restrictions <arc.objects.retains>` on
+the implementation of ``retain`` and ``release``.
+
+.. admonition:: Rationale
+
+  Specifically, ARC is sometimes permitted to optimize ``release``
+  operations in ways which might cause an object to be deallocated
+  before it would otherwise be.  Without this, it would be almost
+  impossible to eliminate any ``retain``/``release`` pairs.  For
+  example, consider the following code:
+
+  .. code-block:: objc
+
+    id x = _ivar;
+    [x foo];
+
+  If we were not permitted in any event to shorten the lifetime of the
+  object in ``x``, then we would not be able to eliminate this retain
+  and release unless we could prove that the message send could not
+  modify ``_ivar`` (or deallocate ``self``).  Since message sends are
+  opaque to the optimizer, this is not possible, and so ARC's hands
+  would be almost completely tied.
+
+ARC makes no guarantees about the execution of a computation history
+which contains undefined behavior.  In particular, ARC makes no
+guarantees in the presence of race conditions.
+
+ARC may assume that any retainable object pointers it receives or
+generates are instantaneously valid from that point until a point
+which, by the concurrency model of the host language, happens-after
+the generation of the pointer and happens-before a release of that
+object (possibly via an aliasing pointer or indirectly due to
+destruction of a different object).
+
+.. admonition:: Rationale
+
+  There is very little point in trying to guarantee correctness in the
+  presence of race conditions.  ARC does not have a stack-scanning
+  garbage collector, and guaranteeing the atomicity of every load and
+  store operation would be prohibitive and preclude a vast amount of
+  optimization.
+
+ARC may assume that non-ARC code engages in sensible balancing
+behavior and does not rely on exact or minimum retain count values
+except as guaranteed by ``__strong`` object invariants or +1 transfer
+conventions.  For example, if an object is provably double-retained
+and double-released, ARC may eliminate the inner retain and release;
+it does not need to guard against code which performs an unbalanced
+release followed by a "balancing" retain.
+
+.. _arc.optimization.liveness:
+
+Object liveness
+---------------
+
+ARC may not allow a retainable object ``X`` to be deallocated at a
+time ``T`` in a computation history if:
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+  :ref:`precise lifetime semantics <arc.optimization.precise>`, or
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+  imprecise lifetime semantics and, at some point after ``T`` but
+  before the next store to ``S``, the computation history features a
+  load from ``S`` and in some way depends on the value loaded, or
+
+* ``X`` is a value described as being released at the end of the
+  current full-expression and, at some point after ``T`` but before
+  the end of the full-expression, the computation history depends
+  on that value.
+
+.. admonition:: Rationale
+
+  The intent of the second rule is to say that objects held in normal
+  ``__strong`` local variables may be released as soon as the value in
+  the variable is no longer being used: either the variable stops
+  being used completely or a new value is stored in the variable.
+
+  The intent of the third rule is to say that return values may be
+  released after they've been used.
+
+A computation history depends on a pointer value ``P`` if it:
+
+* performs a pointer comparison with ``P``,
+* loads from ``P``,
+* stores to ``P``,
+* depends on a pointer value ``Q`` derived via pointer arithmetic
+  from ``P`` (including an instance-variable or field access), or
+* depends on a pointer value ``Q`` loaded from ``P``.
+
+Dependency applies only to values derived directly or indirectly from
+a particular expression result and does not occur merely because a
+separate pointer value dynamically aliases ``P``.  Furthermore, this
+dependency is not carried by values that are stored to objects.
+
+.. admonition:: Rationale
+
+  The restrictions on dependency are intended to make this analysis
+  feasible by an optimizer with only incomplete information about a
+  program.  Essentially, dependence is carried to "obvious" uses of a
+  pointer.  Merely passing a pointer argument to a function does not
+  itself cause dependence, but since generally the optimizer will not
+  be able to prove that the function doesn't depend on that parameter,
+  it will be forced to conservatively assume it does.
+
+  Dependency propagates to values loaded from a pointer because those
+  values might be invalidated by deallocating the object.  For
+  example, given the code ``__strong id x = p->ivar;``, ARC must not
+  move the release of ``p`` to between the load of ``p->ivar`` and the
+  retain of that value for storing into ``x``.
+
+  Dependency does not propagate through stores of dependent pointer
+  values because doing so would allow dependency to outlive the
+  full-expression which produced the original value.  For example, the
+  address of an instance variable could be written to some global
+  location and then freely accessed during the lifetime of the local,
+  or a function could return an inner pointer of an object and store
+  it to a local.  These cases would be potentially impossible to
+  reason about and so would basically prevent any optimizations based
+  on imprecise lifetime.  There are also uncommon enough to make it
+  reasonable to require the precise-lifetime annotation if someone
+  really wants to rely on them.
+
+  Dependency does propagate through return values of pointer type.
+  The compelling source of need for this rule is a property accessor
+  which returns an un-autoreleased result; the calling function must
+  have the chance to operate on the value, e.g. to retain it, before
+  ARC releases the original pointer.  Note again, however, that
+  dependence does not survive a store, so ARC does not guarantee the
+  continued validity of the return value past the end of the
+  full-expression.
+
+.. _arc.optimization.object_lifetime:
+
+No object lifetime extension
+----------------------------
+
+If, in the formal computation history of the program, an object ``X``
+has been deallocated by the time of an observable side-effect, then
+ARC must cause ``X`` to be deallocated by no later than the occurrence
+of that side-effect, except as influenced by the re-ordering of the
+destruction of objects.
+
+.. admonition:: Rationale
+
+  This rule is intended to prohibit ARC from observably extending the
+  lifetime of a retainable object, other than as specified in this
+  document.  Together with the rule limiting the transformation of
+  releases, this rule requires ARC to eliminate retains and release
+  only in pairs.
+
+  ARC's power to reorder the destruction of objects is critical to its
+  ability to do any optimization, for essentially the same reason that
+  it must retain the power to decrease the lifetime of an object.
+  Unfortunately, while it's generally poor style for the destruction
+  of objects to have arbitrary side-effects, it's certainly possible.
+  Hence the caveat.
+
+.. _arc.optimization.precise:
+
+Precise lifetime semantics
+--------------------------
+
+In general, ARC maintains an invariant that a retainable object pointer held in
+a ``__strong`` object will be retained for the full formal lifetime of the
+object.  Objects subject to this invariant have :arc-term:`precise lifetime
+semantics`.
+
+By default, local variables of automatic storage duration do not have precise
+lifetime semantics.  Such objects are simply strong references which hold
+values of retainable object pointer type, and these values are still fully
+subject to the optimizations on values under local control.
+
+.. admonition:: Rationale
+
+  Applying these precise-lifetime semantics strictly would be prohibitive.
+  Many useful optimizations that might theoretically decrease the lifetime of
+  an object would be rendered impossible.  Essentially, it promises too much.
+
+A local variable of retainable object owner type and automatic storage duration
+may be annotated with the ``objc_precise_lifetime`` attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.
+
+.. admonition:: Rationale
+
+  Nonetheless, it is sometimes useful to be able to force an object to be
+  released at a precise time, even if that object does not appear to be used.
+  This is likely to be uncommon enough that the syntactic weight of explicitly
+  requesting these semantics will not be burdensome, and may even make the code
+  clearer.
+
+.. _arc.misc:
+
+Miscellaneous
+=============
+
+.. _arc.misc.special_methods:
+
+Special methods
+---------------
+
+.. _arc.misc.special_methods.retain:
+
+Memory management methods
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it contains a method definition, message send, or
+``@selector`` expression for any of the following selectors:
+
+* ``autorelease``
+* ``release``
+* ``retain``
+* ``retainCount``
+
+.. admonition:: Rationale
+
+  ``retainCount`` is banned because ARC robs it of consistent semantics.  The
+  others were banned after weighing three options for how to deal with message
+  sends:
+
+  **Honoring** them would work out very poorly if a programmer naively or
+  accidentally tried to incorporate code written for manual retain/release code
+  into an ARC program.  At best, such code would do twice as much work as
+  necessary; quite frequently, however, ARC and the explicit code would both
+  try to balance the same retain, leading to crashes.  The cost is losing the
+  ability to perform "unrooted" retains, i.e. retains not logically
+  corresponding to a strong reference in the object graph.
+
+  **Ignoring** them would badly violate user expectations about their code.
+  While it *would* make it easier to develop code simultaneously for ARC and
+  non-ARC, there is very little reason to do so except for certain library
+  developers.  ARC and non-ARC translation units share an execution model and
+  can seamlessly interoperate.  Within a translation unit, a developer who
+  faithfully maintains their code in non-ARC mode is suffering all the
+  restrictions of ARC for zero benefit, while a developer who isn't testing the
+  non-ARC mode is likely to be unpleasantly surprised if they try to go back to
+  it.
+
+  **Banning** them has the disadvantage of making it very awkward to migrate
+  existing code to ARC.  The best answer to that, given a number of other
+  changes and restrictions in ARC, is to provide a specialized tool to assist
+  users in that migration.
+
+  Implementing these methods was banned because they are too integral to the
+  semantics of ARC; many tricks which worked tolerably under manual reference
+  counting will misbehave if ARC performs an ephemeral extra retain or two.  If
+  absolutely required, it is still possible to implement them in non-ARC code,
+  for example in a category; the implementations must obey the :ref:`semantics
+  <arc.objects.retains>` laid out elsewhere in this document.
+
+.. _arc.misc.special_methods.dealloc:
+
+``dealloc``
+^^^^^^^^^^^
+
+A program is ill-formed if it contains a message send or ``@selector``
+expression for the selector ``dealloc``.
+
+.. admonition:: Rationale
+
+  There are no legitimate reasons to call ``dealloc`` directly.
+
+A class may provide a method definition for an instance method named
+``dealloc``.  This method will be called after the final ``release`` of the
+object but before it is deallocated or any of its instance variables are
+destroyed.  The superclass's implementation of ``dealloc`` will be called
+automatically when the method returns.
+
+.. admonition:: Rationale
+
+  Even though ARC destroys instance variables automatically, there are still
+  legitimate reasons to write a ``dealloc`` method, such as freeing
+  non-retainable resources.  Failing to call ``[super dealloc]`` in such a
+  method is nearly always a bug.  Sometimes, the object is simply trying to
+  prevent itself from being destroyed, but ``dealloc`` is really far too late
+  for the object to be raising such objections.  Somewhat more legitimately, an
+  object may have been pool-allocated and should not be deallocated with
+  ``free``; for now, this can only be supported with a ``dealloc``
+  implementation outside of ARC.  Such an implementation must be very careful
+  to do all the other work that ``NSObject``'s ``dealloc`` would, which is
+  outside the scope of this document to describe.
+
+The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the ``dealloc`` method for the root class of the
+class.  The ordering of the destruction of instance variables is unspecified,
+both within a single class and between subclasses and superclasses.
+
+.. admonition:: Rationale
+
+  The traditional, non-ARC pattern for destroying instance variables is to
+  destroy them immediately before calling ``[super dealloc]``.  Unfortunately,
+  message sends from the superclass are quite capable of reaching methods in
+  the subclass, and those methods may well read or write to those instance
+  variables.  Making such message sends from dealloc is generally discouraged,
+  since the subclass may well rely on other invariants that were broken during
+  ``dealloc``, but it's not so inescapably dangerous that we felt comfortable
+  calling it undefined behavior.  Therefore we chose to delay destroying the
+  instance variables to a point at which message sends are clearly disallowed:
+  the point at which the root class's deallocation routines take over.
+
+  In most code, the difference is not observable.  It can, however, be observed
+  if an instance variable holds a strong reference to an object whose
+  deallocation will trigger a side-effect which must be carefully ordered with
+  respect to the destruction of the super class.  Such code violates the design
+  principle that semantically important behavior should be explicit.  A simple
+  fix is to clear the instance variable manually during ``dealloc``; a more
+  holistic solution is to move semantically important side-effects out of
+  ``dealloc`` and into a separate teardown phase which can rely on working with
+  well-formed objects.
+
+.. _arc.misc.autoreleasepool:
+
+``@autoreleasepool``
+--------------------
+
+To simplify the use of autorelease pools, and to bring them under the control
+of the compiler, a new kind of statement is available in Objective-C.  It is
+written ``@autoreleasepool`` followed by a *compound-statement*, i.e.  by a new
+scope delimited by curly braces.  Upon entry to this block, the current state
+of the autorelease pool is captured.  When the block is exited normally,
+whether by fallthrough or directed control flow (such as ``return`` or
+``break``), the autorelease pool is restored to the saved state, releasing all
+the objects in it.  When the block is exited with an exception, the pool is not
+drained.
+
+``@autoreleasepool`` may be used in non-ARC translation units, with equivalent
+semantics.
+
+A program is ill-formed if it refers to the ``NSAutoreleasePool`` class.
+
+.. admonition:: Rationale
+
+  Autorelease pools are clearly important for the compiler to reason about, but
+  it is far too much to expect the compiler to accurately reason about control
+  dependencies between two calls.  It is also very easy to accidentally forget
+  to drain an autorelease pool when using the manual API, and this can
+  significantly inflate the process's high-water-mark.  The introduction of a
+  new scope is unfortunate but basically required for sane interaction with the
+  rest of the language.  Not draining the pool during an unwind is apparently
+  required by the Objective-C exceptions implementation.
+
+.. _arc.misc.self:
+
+``self``
+--------
+
+The ``self`` parameter variable of an Objective-C method is never actually
+retained by the implementation.  It is undefined behavior, or at least
+dangerous, to cause an object to be deallocated during a message send to that
+object.
+
+To make this safe, for Objective-C instance methods ``self`` is implicitly
+``const`` unless the method is in the :ref:`init family
+<arc.family.semantics.init>`.  Further, ``self`` is **always** implicitly
+``const`` within a class method.
+
+.. admonition:: Rationale
+
+  The cost of retaining ``self`` in all methods was found to be prohibitive, as
+  it tends to be live across calls, preventing the optimizer from proving that
+  the retain and release are unnecessary --- for good reason, as it's quite
+  possible in theory to cause an object to be deallocated during its execution
+  without this retain and release.  Since it's extremely uncommon to actually
+  do so, even unintentionally, and since there's no natural way for the
+  programmer to remove this retain/release pair otherwise (as there is for
+  other parameters by, say, making the variable ``__unsafe_unretained``), we
+  chose to make this optimizing assumption and shift some amount of risk to the
+  user.
+
+.. _arc.misc.enumeration:
+
+Fast enumeration iteration variables
+------------------------------------
+
+If a variable is declared in the condition of an Objective-C fast enumeration
+loop, and the variable has no explicit ownership qualifier, then it is
+qualified with ``const __strong`` and objects encountered during the
+enumeration are not actually retained.
+
+.. admonition:: Rationale
+
+  This is an optimization made possible because fast enumeration loops promise
+  to keep the objects retained during enumeration, and the collection itself
+  cannot be synchronously modified.  It can be overridden by explicitly
+  qualifying the variable with ``__strong``, which will make the variable
+  mutable again and cause the loop to retain the objects it encounters.
+
+.. _arc.misc.blocks:
+
+Blocks
+------
+
+The implicit ``const`` capture variables created when evaluating a block
+literal expression have the same ownership semantics as the local variables
+they capture.  The capture is performed by reading from the captured variable
+and initializing the capture variable with that value; the capture variable is
+destroyed when the block literal is, i.e. at the end of the enclosing scope.
+
+The :ref:`inference <arc.ownership.inference>` rules apply equally to
+``__block`` variables, which is a shift in semantics from non-ARC, where
+``__block`` variables did not implicitly retain during capture.
+
+``__block`` variables of retainable object owner type are moved off the stack
+by initializing the heap copy with the result of moving from the stack copy.
+
+With the exception of retains done as part of initializing a ``__strong``
+parameter variable or reading a ``__weak`` variable, whenever these semantics
+call for retaining a value of block-pointer type, it has the effect of a
+``Block_copy``.  The optimizer may remove such copies when it sees that the
+result is used only as an argument to a call.
+
+.. _arc.misc.exceptions:
+
+Exceptions
+----------
+
+By default in Objective C, ARC is not exception-safe for normal releases:
+
+* It does not end the lifetime of ``__strong`` variables when their scopes are
+  abnormally terminated by an exception.
+* It does not perform releases which would occur at the end of a
+  full-expression if that full-expression throws an exception.
+
+A program may be compiled with the option ``-fobjc-arc-exceptions`` in order to
+enable these, or with the option ``-fno-objc-arc-exceptions`` to explicitly
+disable them, with the last such argument "winning".
+
+.. admonition:: Rationale
+
+  The standard Cocoa convention is that exceptions signal programmer error and
+  are not intended to be recovered from.  Making code exceptions-safe by
+  default would impose severe runtime and code size penalties on code that
+  typically does not actually care about exceptions safety.  Therefore,
+  ARC-generated code leaks by default on exceptions, which is just fine if the
+  process is going to be immediately terminated anyway.  Programs which do care
+  about recovering from exceptions should enable the option.
+
+In Objective-C++, ``-fobjc-arc-exceptions`` is enabled by default.
+
+.. admonition:: Rationale
+
+  C++ already introduces pervasive exceptions-cleanup code of the sort that ARC
+  introduces.  C++ programmers who have not already disabled exceptions are
+  much more likely to actual require exception-safety.
+
+ARC does end the lifetimes of ``__weak`` objects when an exception terminates
+their scope unless exceptions are disabled in the compiler.
+
+.. admonition:: Rationale
+
+  The consequence of a local ``__weak`` object not being destroyed is very
+  likely to be corruption of the Objective-C runtime, so we want to be safer
+  here.  Of course, potentially massive leaks are about as likely to take down
+  the process as this corruption is if the program does try to recover from
+  exceptions.
+
+.. _arc.misc.interior:
+
+Interior pointers
+-----------------
+
+An Objective-C method returning a non-retainable pointer may be annotated with
+the ``objc_returns_inner_pointer`` attribute to indicate that it returns a
+handle to the internal data of an object, and that this reference will be
+invalidated if the object is destroyed.  When such a message is sent to an
+object, the object's lifetime will be extended until at least the earliest of:
+
+* the last use of the returned pointer, or any pointer derived from it, in the
+  calling function or
+* the autorelease pool is restored to a previous state.
+
+.. admonition:: Rationale
+
+  Rationale: not all memory and resources are managed with reference counts; it
+  is common for objects to manage private resources in their own, private way.
+  Typically these resources are completely encapsulated within the object, but
+  some classes offer their users direct access for efficiency.  If ARC is not
+  aware of methods that return such "interior" pointers, its optimizations can
+  cause the owning object to be reclaimed too soon.  This attribute informs ARC
+  that it must tread lightly.
+
+  The extension rules are somewhat intentionally vague.  The autorelease pool
+  limit is there to permit a simple implementation to simply retain and
+  autorelease the receiver.  The other limit permits some amount of
+  optimization.  The phrase "derived from" is intended to encompass the results
+  both of pointer transformations, such as casts and arithmetic, and of loading
+  from such derived pointers; furthermore, it applies whether or not such
+  derivations are applied directly in the calling code or by other utility code
+  (for example, the C library routine ``strchr``).  However, the implementation
+  never need account for uses after a return from the code which calls the
+  method returning an interior pointer.
+
+As an exception, no extension is required if the receiver is loaded directly
+from a ``__strong`` object with :ref:`precise lifetime semantics
+<arc.optimization.precise>`.
+
+.. admonition:: Rationale
+
+  Implicit autoreleases carry the risk of significantly inflating memory use,
+  so it's important to provide users a way of avoiding these autoreleases.
+  Tying this to precise lifetime semantics is ideal, as for local variables
+  this requires a very explicit annotation, which allows ARC to trust the user
+  with good cheer.
+
+.. _arc.misc.c-retainable:
+
+C retainable pointer types
+--------------------------
+
+A type is a :arc-term:`C retainable pointer type` if it is a pointer to
+(possibly qualified) ``void`` or a pointer to a (possibly qualifier) ``struct``
+or ``class`` type.
+
+.. admonition:: Rationale
+
+  ARC does not manage pointers of CoreFoundation type (or any of the related
+  families of retainable C pointers which interoperate with Objective-C for
+  retain/release operation).  In fact, ARC does not even know how to
+  distinguish these types from arbitrary C pointer types.  The intent of this
+  concept is to filter out some obviously non-object types while leaving a hook
+  for later tightening if a means of exhaustively marking CF types is made
+  available.
+
+.. _arc.misc.c-retainable.audit:
+
+Auditing of C retainable pointer interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+
+A C function may be marked with the ``cf_audited_transfer`` attribute to
+express that, except as otherwise marked with attributes, it obeys the
+parameter (consuming vs. non-consuming) and return (retained vs. non-retained)
+conventions for a C function of its name, namely:
+
+* A parameter of C retainable pointer type is assumed to not be consumed
+  unless it is marked with the ``cf_consumed`` attribute, and
+* A result of C retainable pointer type is assumed to not be returned retained
+  unless the function is either marked ``cf_returns_retained`` or it follows
+  the create/copy naming convention and is not marked
+  ``cf_returns_not_retained``.
+
+A function obeys the :arc-term:`create/copy` naming convention if its name
+contains as a substring:
+
+* either "Create" or "Copy" not followed by a lowercase letter, or
+* either "create" or "copy" not followed by a lowercase letter and
+  not preceded by any letter, whether uppercase or lowercase.
+
+A second attribute, ``cf_unknown_transfer``, signifies that a function's
+transfer semantics cannot be accurately captured using any of these
+annotations.  A program is ill-formed if it annotates the same function with
+both ``cf_audited_transfer`` and ``cf_unknown_transfer``.
+
+A pragma is provided to facilitate the mass annotation of interfaces:
+
+.. code-block:: objc
+
+  #pragma clang arc_cf_code_audited begin
+  ...
+  #pragma clang arc_cf_code_audited end
+
+All C functions declared within the extent of this pragma are treated as if
+annotated with the ``cf_audited_transfer`` attribute unless they otherwise have
+the ``cf_unknown_transfer`` attribute.  The pragma is accepted in all language
+modes.  A program is ill-formed if it attempts to change files, whether by
+including a file or ending the current file, within the extent of this pragma.
+
+It is possible to test for all the features in this section with
+``__has_feature(arc_cf_code_audited)``.
+
+.. admonition:: Rationale
+
+  A significant inconvenience in ARC programming is the necessity of
+  interacting with APIs based around C retainable pointers.  These features are
+  designed to make it relatively easy for API authors to quickly review and
+  annotate their interfaces, in turn improving the fidelity of tools such as
+  the static analyzer and ARC.  The single-file restriction on the pragma is
+  designed to eliminate the risk of accidentally annotating some other header's
+  interfaces.
+
+.. _arc.runtime:
+
+Runtime support
+===============
+
+This section describes the interaction between the ARC runtime and the code
+generated by the ARC compiler.  This is not part of the ARC language
+specification; instead, it is effectively a language-specific ABI supplement,
+akin to the "Itanium" generic ABI for C++.
+
+Ownership qualification does not alter the storage requirements for objects,
+except that it is undefined behavior if a ``__weak`` object is inadequately
+aligned for an object of type ``id``.  The other qualifiers may be used on
+explicitly under-aligned memory.
+
+The runtime tracks ``__weak`` objects which holds non-null values.  It is
+undefined behavior to direct modify a ``__weak`` object which is being tracked
+by the runtime except through an
+:ref:`objc_storeWeak <arc.runtime.objc_storeWeak>`,
+:ref:`objc_destroyWeak <arc.runtime.objc_destroyWeak>`, or
+:ref:`objc_moveWeak <arc.runtime.objc_moveWeak>` call.
+
+The runtime must provide a number of new entrypoints which the compiler may
+emit, which are described in the remainder of this section.
+
+.. admonition:: Rationale
+
+  Several of these functions are semantically equivalent to a message send; we
+  emit calls to C functions instead because:
+
+  * the machine code to do so is significantly smaller,
+  * it is much easier to recognize the C functions in the ARC optimizer, and
+  * a sufficient sophisticated runtime may be able to avoid the message send in
+    common cases.
+
+  Several other of these functions are "fused" operations which can be
+  described entirely in terms of other operations.  We use the fused operations
+  primarily as a code-size optimization, although in some cases there is also a
+  real potential for avoiding redundant operations in the runtime.
+
+.. _arc.runtime.objc_autorelease:
+
+``id objc_autorelease(id value);``
+----------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect.  Otherwise, it adds the object
+to the innermost autorelease pool exactly as if the object had been sent the
+``autorelease`` message.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_autoreleasePoolPop:
+
+``void objc_autoreleasePoolPop(void *pool);``
+---------------------------------------------
+
+*Precondition:* ``pool`` is the result of a previous call to
+:ref:`objc_autoreleasePoolPush <arc.runtime.objc_autoreleasePoolPush>` on the
+current thread, where neither ``pool`` nor any enclosing pool have previously
+been popped.
+
+Releases all the objects added to the given autorelease pool and any
+autorelease pools it encloses, then sets the current autorelease pool to the
+pool directly enclosing ``pool``.
+
+.. _arc.runtime.objc_autoreleasePoolPush:
+
+``void *objc_autoreleasePoolPush(void);``
+-----------------------------------------
+
+Creates a new autorelease pool that is enclosed by the current pool, makes that
+the current pool, and returns an opaque "handle" to it.
+
+.. admonition:: Rationale
+
+  While the interface is described as an explicit hierarchy of pools, the rules
+  allow the implementation to just keep a stack of objects, using the stack
+  depth as the opaque pool handle.
+
+.. _arc.runtime.objc_autoreleaseReturnValue:
+
+``id objc_autoreleaseReturnValue(id value);``
+---------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect.  Otherwise, it makes a best
+effort to hand off ownership of a retain count on the object to a call to
+:ref:`objc_retainAutoreleasedReturnValue
+<arc.runtime.objc_retainAutoreleasedReturnValue>` for the same object in an
+enclosing call frame.  If this is not possible, the object is autoreleased as
+above.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_copyWeak:
+
+``void objc_copyWeak(id *dest, id *src);``
+------------------------------------------
+
+*Precondition:* ``src`` is a valid pointer which either contains a null pointer
+or has been registered as a ``__weak`` object.  ``dest`` is a valid pointer
+which has not been registered as a ``__weak`` object.
+
+``dest`` is initialized to be equivalent to ``src``, potentially registering it
+with the runtime.  Equivalent to the following code:
+
+.. code-block:: objc
+
+  void objc_copyWeak(id *dest, id *src) {
+    objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
+  }
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``.
+
+.. _arc.runtime.objc_destroyWeak:
+
+``void objc_destroyWeak(id *object);``
+--------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+``object`` is unregistered as a weak object, if it ever was.  The current value
+of ``object`` is left unspecified; otherwise, equivalent to the following code:
+
+.. code-block:: objc
+
+  void objc_destroyWeak(id *object) {
+    objc_storeWeak(object, nil);
+  }
+
+Does not need to be atomic with respect to calls to ``objc_storeWeak`` on
+``object``.
+
+.. _arc.runtime.objc_initWeak:
+
+``id objc_initWeak(id *object, id value);``
+-------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which has not been registered as
+a ``__weak`` object.  ``value`` is null or a pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is zero-initialized.  Otherwise, ``object`` is
+registered as a ``__weak`` object pointing to ``value``.  Equivalent to the
+following code:
+
+.. code-block:: objc
+
+  id objc_initWeak(id *object, id value) {
+    *object = nil;
+    return objc_storeWeak(object, value);
+  }
+
+Returns the value of ``object`` after the call.
+
+Does not need to be atomic with respect to calls to ``objc_storeWeak`` on
+``object``.
+
+.. _arc.runtime.objc_loadWeak:
+
+``id objc_loadWeak(id *object);``
+---------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+If ``object`` is registered as a ``__weak`` object, and the last value stored
+into ``object`` has not yet been deallocated or begun deallocation, retains and
+autoreleases that value and returns it.  Otherwise returns null.  Equivalent to
+the following code:
+
+.. code-block:: objc
+
+  id objc_loadWeak(id *object) {
+    return objc_autorelease(objc_loadWeakRetained(object));
+  }
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``.
+
+.. admonition:: Rationale
+
+  Loading weak references would be inherently prone to race conditions without
+  the retain.
+
+.. _arc.runtime.objc_loadWeakRetained:
+
+``id objc_loadWeakRetained(id *object);``
+-----------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+If ``object`` is registered as a ``__weak`` object, and the last value stored
+into ``object`` has not yet been deallocated or begun deallocation, retains
+that value and returns it.  Otherwise returns null.
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``.
+
+.. _arc.runtime.objc_moveWeak:
+
+``void objc_moveWeak(id *dest, id *src);``
+------------------------------------------
+
+*Precondition:* ``src`` is a valid pointer which either contains a null pointer
+or has been registered as a ``__weak`` object.  ``dest`` is a valid pointer
+which has not been registered as a ``__weak`` object.
+
+``dest`` is initialized to be equivalent to ``src``, potentially registering it
+with the runtime.  ``src`` may then be left in its original state, in which
+case this call is equivalent to :ref:`objc_copyWeak
+<arc.runtime.objc_copyWeak>`, or it may be left as null.
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``.
+
+.. _arc.runtime.objc_release:
+
+``void objc_release(id value);``
+--------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect.  Otherwise, it performs a
+release operation exactly as if the object had been sent the ``release``
+message.
+
+.. _arc.runtime.objc_retain:
+
+``id objc_retain(id value);``
+-----------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect.  Otherwise, it performs a retain
+operation exactly as if the object had been sent the ``retain`` message.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutorelease:
+
+``id objc_retainAutorelease(id value);``
+----------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect.  Otherwise, it performs a retain
+operation followed by an autorelease operation.  Equivalent to the following
+code:
+
+.. code-block:: objc
+
+  id objc_retainAutorelease(id value) {
+    return objc_autorelease(objc_retain(value));
+  }
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutoreleaseReturnValue:
+
+``id objc_retainAutoreleaseReturnValue(id value);``
+---------------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect.  Otherwise, it performs a retain
+operation followed by the operation described in
+:ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>`.
+Equivalent to the following code:
+
+.. code-block:: objc
+
+  id objc_retainAutoreleaseReturnValue(id value) {
+    return objc_autoreleaseReturnValue(objc_retain(value));
+  }
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutoreleasedReturnValue:
+
+``id objc_retainAutoreleasedReturnValue(id value);``
+----------------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect.  Otherwise, it attempts to
+accept a hand off of a retain count from a call to
+:ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>` on
+``value`` in a recently-called function or something it calls.  If that fails,
+it performs a retain operation exactly like :ref:`objc_retain
+<arc.runtime.objc_retain>`.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainBlock:
+
+``id objc_retainBlock(id value);``
+----------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid block object.
+
+If ``value`` is null, this call has no effect.  Otherwise, if the block pointed
+to by ``value`` is still on the stack, it is copied to the heap and the address
+of the copy is returned.  Otherwise a retain operation is performed on the
+block exactly as if it had been sent the ``retain`` message.
+
+.. _arc.runtime.objc_storeStrong:
+
+``id objc_storeStrong(id *object, id value);``
+----------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer to a ``__strong`` object which is
+adequately aligned for a pointer.  ``value`` is null or a pointer to a valid
+object.
+
+Performs the complete sequence for assigning to a ``__strong`` object of
+non-block type [*]_.  Equivalent to the following code:
+
+.. code-block:: objc
+
+  id objc_storeStrong(id *object, id value) {
+    value = [value retain];
+    id oldValue = *object;
+    *object = value;
+    [oldValue release];
+    return value;
+  }
+
+Always returns ``value``.
+
+.. [*] This does not imply that a ``__strong`` object of block type is an
+   invalid argument to this function. Rather it implies that an ``objc_retain``
+   and not an ``objc_retainBlock`` operation will be emitted if the argument is
+   a block.
+
+.. _arc.runtime.objc_storeWeak:
+
+``id objc_storeWeak(id *object, id value);``
+--------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.  ``value`` is null or a
+pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is assigned null and unregistered as a ``__weak``
+object.  Otherwise, ``object`` is registered as a ``__weak`` object or has its
+registration updated to point to ``value``.
+
+Returns the value of ``object`` after the call.
+


