[www-releases] r326992 - 6.0.0 files
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Thu Mar 8 02:24:48 PST 2018
Added: www-releases/trunk/6.0.0/tools/clang/docs/Modules.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/Modules.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/Modules.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/Modules.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,964 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="MSVC compatibility" href="MSVCCompatibility.html" />
+ <link rel="prev" title="Source-based Code Coverage" href="SourceBasedCodeCoverage.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Modules</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="SourceBasedCodeCoverage.html">Source-based Code Coverage</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="#re-export-declaration" id="id30">Re-export Declaration</a></li>
+<li><a class="reference internal" href="#use-declaration" id="id31">Use declaration</a></li>
+<li><a class="reference internal" href="#link-declaration" id="id32">Link declaration</a></li>
+<li><a class="reference internal" href="#configuration-macros-declaration" id="id33">Configuration macros declaration</a></li>
+<li><a class="reference internal" href="#conflict-declarations" id="id34">Conflict declarations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#attributes" id="id35">Attributes</a></li>
+<li><a class="reference internal" href="#private-module-map-files" id="id36">Private Module Map Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#modularizing-a-platform" id="id37">Modularizing a Platform</a></li>
+<li><a class="reference internal" href="#future-directions" id="id38">Future Directions</a></li>
+<li><a class="reference internal" href="#where-to-learn-more-about-modules" id="id39">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></span><span class="cp">#include</span> <span class="cpf"><SomeLib.h></span><span class="cp"></span>
+</pre></div>
+</div>
+<p>The implementation is handled separately by linking against the appropriate library. For example, by passing <code class="docutils literal"><span class="pre">-lSomeLib</span></code> 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 <code class="docutils literal"><span class="pre">#include</span></code> 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>: <code class="docutils literal"><span class="pre">#include</span></code> 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,
+<code 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></code> 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
+<code class="docutils literal"><span class="pre">#include</span></code> directives or introduce <code class="docutils literal"><span class="pre">#undef</span></code> 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
+<code class="docutils literal"><span class="pre">LONG_PREFIXED_UPPERCASE_IDENTIFIERS</span></code> to avoid collisions, and some
+library/framework developers even use <code class="docutils literal"><span class="pre">__underscored</span></code> 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 <code class="docutils literal"><span class="pre">import</span></code> declaration rather than a <code class="docutils literal"><span class="pre">#include</span></code> preprocessor directive:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">#include</span> <span class="pre"><stdio.h></span></code>: when the compiler sees the module import above, it loads a binary representation of the <code class="docutils literal"><span class="pre">std.io</span></code> 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 <code class="docutils literal"><span class="pre">std.io</span></code>, because the module itself was compiled as a separate, standalone module. Additionally, any linker flags required to use the <code class="docutils literal"><span class="pre">std.io</span></code> 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 <code class="docutils literal"><span class="pre">std.io</span></code> 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 <code class="docutils literal"><span class="pre">__underscored</span></code> 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 <code class="docutils literal"><span class="pre">-fmodules</span></code>. 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-default"><div class="highlight"><pre><span></span><span class="nd">@import</span> <span class="n">std</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal"><span class="pre">@import</span></code> declaration above imports the entire contents of the <code class="docutils literal"><span class="pre">std</span></code> 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-default"><div class="highlight"><pre><span></span><span class="nd">@import</span> <span class="n">std</span><span class="o">.</span><span class="n">io</span><span class="p">;</span>
+</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 <code class="docutils literal"><span class="pre">#include</span></code>, and it is unrealistic to assume that all of this code will change overnight. Instead, modules automatically translate <code class="docutils literal"><span class="pre">#include</span></code> directives into the corresponding module import. For example, the include directive</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
+</pre></div>
+</div>
+<p>will be automatically mapped to an import of the module <code class="docutils literal"><span class="pre">std.io</span></code>. Even with specific <code class="docutils literal"><span class="pre">import</span></code> syntax in the language, this particular feature is important for both adoption and backward compatibility: automatic translation of <code class="docutils literal"><span class="pre">#include</span></code> to <code class="docutils literal"><span class="pre">import</span></code> 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 <code class="docutils literal"><span class="pre">#include</span></code> to <code class="docutils literal"><span class="pre">import</span></code> also solves an implementation problem: importing a module with a definition of some entity (say, a <code class="docutils literal"><span class="pre">struct</span> <span class="pre">Point</span></code>) and then parsing a header containing another definition of <code class="docutils literal"><span class="pre">struct</span> <span class="pre">Point</span></code> would cause a redefinition error, even if it is the same <code class="docutils literal"><span class="pre">struct</span> <span class="pre">Point</span></code>. By mapping <code class="docutils literal"><span class="pre">#include</span></code> to <code class="docutils literal"><span class="pre">import</span></code>, the compiler can guarantee that it always sees just the already-parsed definition from the module.</p>
+</div>
+<p>While building a module, <code class="docutils literal"><span class="pre">#include_next</span></code> is also supported, with one caveat.
+The usual behavior of <code class="docutils literal"><span class="pre">#include_next</span></code> 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 <code class="docutils literal"><span class="pre">#include_next</span></code> 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. <code class="docutils literal"><span class="pre">#include_next</span></code> 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 <code class="docutils literal"><span class="pre">#include_next</span></code>
+directive is translated into an import, just like for a <code class="docutils literal"><span class="pre">#include</span></code>
+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 <code class="docutils literal"><span class="pre">std</span></code> covering the C standard library. Each of the C standard library headers (<code class="docutils literal"><span class="pre"><stdio.h></span></code>, <code class="docutils literal"><span class="pre"><stdlib.h></span></code>, <code class="docutils literal"><span class="pre"><math.h></span></code>, etc.) would contribute to the <code class="docutils literal"><span class="pre">std</span></code> module, by placing their respective APIs into the corresponding submodule (<code class="docutils literal"><span class="pre">std.io</span></code>, <code class="docutils literal"><span class="pre">std.lib</span></code>, <code class="docutils literal"><span class="pre">std.math</span></code>, etc.). Having a list of the headers that are part of the <code class="docutils literal"><span class="pre">std</span></code> module allows the compiler to build the <code class="docutils literal"><span class="pre">std</span></code> module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of <code class="docutils literal"><span class="pre">#include</span></code> directives to module imports.</p>
+<p>Module maps are specified as separate files (each named <code class="docutils literal"><span class="pre">module.modulemap</span></code>) 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 <code class="docutils literal"><span class="pre">-fimplicit-module-maps</span></code> option instead of the <code class="docutils literal"><span class="pre">-fmodules</span></code> option, or use <code class="docutils literal"><span class="pre">-fmodule-map-file=</span></code> 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 <code class="docutils literal"><span class="pre">#include</span></code> 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><code class="docutils literal"><span class="pre">-fmodules</span></code></dt>
+<dd>Enable the modules feature.</dd>
+<dt><code class="docutils literal"><span class="pre">-fbuiltin-module-map</span></code></dt>
+<dd>Load the Clang builtins module map file. (Equivalent to <code class="docutils literal"><span class="pre">-fmodule-map-file=<resource</span> <span class="pre">dir>/include/module.modulemap</span></code>)</dd>
+<dt><code class="docutils literal"><span class="pre">-fimplicit-module-maps</span></code></dt>
+<dd>Enable implicit search for module map files named <code class="docutils literal"><span class="pre">module.modulemap</span></code> and similar. This option is implied by <code class="docutils literal"><span class="pre">-fmodules</span></code>. If this is disabled with <code class="docutils literal"><span class="pre">-fno-implicit-module-maps</span></code>, module map files will only be loaded if they are explicitly specified via <code class="docutils literal"><span class="pre">-fmodule-map-file</span></code> or transitively used by another module map file.</dd>
+<dt><code class="docutils literal"><span class="pre">-fmodules-cache-path=<directory></span></code></dt>
+<dd>Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default.</dd>
+<dt><code class="docutils literal"><span class="pre">-fno-autolink</span></code></dt>
+<dd>Disable automatic linking against the libraries associated with imported modules.</dd>
+<dt><code class="docutils literal"><span class="pre">-fmodules-ignore-macro=macroname</span></code></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><code class="docutils literal"><span class="pre">-fmodules-prune-interval=seconds</span></code></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><code class="docutils literal"><span class="pre">-fmodules-prune-after=seconds</span></code></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><code 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></code></dt>
+<dd>Debugging aid that prints information about a given module file (with a <code class="docutils literal"><span class="pre">.pcm</span></code> extension), including the language and preprocessor options that particular module variant was built with.</dd>
+<dt><code class="docutils literal"><span class="pre">-fmodules-decluse</span></code></dt>
+<dd>Enable checking of module <code class="docutils literal"><span class="pre">use</span></code> declarations.</dd>
+<dt><code class="docutils literal"><span class="pre">-fmodule-name=module-id</span></code></dt>
+<dd>Consider a source file as a part of the given module.</dd>
+<dt><code class="docutils literal"><span class="pre">-fmodule-map-file=<file></span></code></dt>
+<dd>Load the given module map file if a header from its directory or one of its subdirectories is loaded.</dd>
+<dt><code class="docutils literal"><span class="pre">-fmodules-search-all</span></code></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><code class="docutils literal"><span class="pre">-fno-implicit-modules</span></code></dt>
+<dd>All modules used by the build must be specified with <code class="docutils literal"><span class="pre">-fmodule-file</span></code>.</dd>
+<dt><code class="docutils literal"><span class="pre">-fmodule-file=[<name>=]<file></span></code></dt>
+<dd>Specify the mapping of module names to precompiled module files. If the
+name is omitted, then the module file is loaded whether actually required
+or not. If the name is specified, then the mapping is treated as another
+prebuilt module search mechanism (in addition to <code class="docutils literal"><span class="pre">-fprebuilt-module-path</span></code>)
+and the module is only loaded if required. Note that in this case the
+specified file also overrides this module’s paths that might be embedded
+in other precompiled module files.</dd>
+<dt><code class="docutils literal"><span class="pre">-fprebuilt-module-path=<directory></span></code></dt>
+<dd>Specify the path to the prebuilt modules. If specified, we will look for modules in this directory for a given top-level module name. We don’t need a module map for loading prebuilt modules in this directory and the compiler will not try to rebuild these modules. This can be specified multiple times.</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 <code class="docutils literal"><span class="pre">#define</span></code>s a macro and the other <code class="docutils literal"><span class="pre">#undef</span></code>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 <code class="docutils literal"><span class="pre">#define</span> <span class="pre">X</span></code> or <code class="docutils literal"><span class="pre">#undef</span> <span class="pre">X</span></code> directive <em>overrides</em> all definitions of <code class="docutils literal"><span class="pre">X</span></code> that are visible at the point of the directive.</li>
+<li>A <code class="docutils literal"><span class="pre">#define</span></code> or <code class="docutils literal"><span class="pre">#undef</span></code> 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 <code class="docutils literal"><span class="pre">#undef</span></code> directives, or if all <code class="docutils literal"><span class="pre">#define</span></code> 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><code class="docutils literal"><span class="pre"><stdio.h></span></code> defines a macro <code class="docutils literal"><span class="pre">getc</span></code> (and exports its <code class="docutils literal"><span class="pre">#define</span></code>)</li>
+<li><code class="docutils literal"><span class="pre"><cstdio></span></code> imports the <code class="docutils literal"><span class="pre"><stdio.h></span></code> module and undefines the macro (and exports its <code class="docutils literal"><span class="pre">#undef</span></code>)</li>
+</ul>
+<p>The <code class="docutils literal"><span class="pre">#undef</span></code> overrides the <code class="docutils literal"><span class="pre">#define</span></code>, and a source file that imports both modules <em>in any order</em> will not see <code class="docutils literal"><span class="pre">getc</span></code> 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 <code class="docutils literal"><span class="pre">module.modulemap</span></code> file for that library. The
+<code class="docutils literal"><span class="pre">module.modulemap</span></code> 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
+<code class="docutils literal"><span class="pre">module.modulemap</span></code> is not found, Clang will also search for a file named
+<code class="docutils literal"><span class="pre">module.map</span></code>. 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-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">std</span> <span class="p">[</span><span class="n">system</span><span class="p">]</span> <span class="p">[</span><span class="n">extern_c</span><span class="p">]</span> <span class="p">{</span>
+ <span class="n">module</span> <span class="k">assert</span> <span class="p">{</span>
+ <span class="n">textual</span> <span class="n">header</span> <span class="s2">"assert.h"</span>
+ <span class="n">header</span> <span class="s2">"bits/assert-decls.h"</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+
+ <span class="n">module</span> <span class="nb">complex</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"complex.h"</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+
+ <span class="n">module</span> <span class="n">ctype</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"ctype.h"</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+
+ <span class="n">module</span> <span class="n">errno</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"errno.h"</span>
+ <span class="n">header</span> <span class="s2">"sys/errno.h"</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+
+ <span class="n">module</span> <span class="n">fenv</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"fenv.h"</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+
+ <span class="o">//</span> <span class="o">...</span><span class="n">more</span> <span class="n">headers</span> <span class="n">follow</span><span class="o">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here, the top-level module <code class="docutils literal"><span class="pre">std</span></code> encompasses the whole C standard library. It has a number of submodules containing different parts of the standard library: <code class="docutils literal"><span class="pre">complex</span></code> for complex numbers, <code class="docutils literal"><span class="pre">ctype</span></code> for character types, etc. Each submodule lists one of more headers that provide the contents for that submodule. Finally, the <code class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></code> 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, <code class="docutils literal"><span class="pre">/*</span> <span class="pre">*/</span></code> and <code class="docutils literal"><span class="pre">//</span></code> comments. The module map language has the following reserved words; all other C identifiers are valid identifiers.</p>
+<pre class="literal-block">
+<code class="docutils literal"><span class="pre">config_macros</span></code> <code class="docutils literal"><span class="pre">export_as</span></code> <code class="docutils literal"><span class="pre">private</span></code>
+<code class="docutils literal"><span class="pre">conflict</span></code> <code class="docutils literal"><span class="pre">framework</span></code> <code class="docutils literal"><span class="pre">requires</span></code>
+<code class="docutils literal"><span class="pre">exclude</span></code> <code class="docutils literal"><span class="pre">header</span></code> <code class="docutils literal"><span class="pre">textual</span></code>
+<code class="docutils literal"><span class="pre">explicit</span></code> <code class="docutils literal"><span class="pre">link</span></code> <code class="docutils literal"><span class="pre">umbrella</span></code>
+<code class="docutils literal"><span class="pre">extern</span></code> <code class="docutils literal"><span class="pre">module</span></code> <code class="docutils literal"><span class="pre">use</span></code>
+<code class="docutils literal"><span class="pre">export</span></code>
+</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>:
+ <code class="docutils literal"><span class="pre">explicit</span></code><span class="subscript">opt</span> <code class="docutils literal"><span class="pre">framework</span></code><span class="subscript">opt</span> <code class="docutils literal"><span class="pre">module</span></code> <em>module-id</em> <em>attributes</em><span class="subscript">opt</span> '{' <em>module-member*</em> '}'
+ <code class="docutils literal"><span class="pre">extern</span></code> <code class="docutils literal"><span class="pre">module</span></code> <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 <code class="docutils literal"><span class="pre">explicit</span></code> 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 <code class="docutils literal"><span class="pre">framework</span></code> 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 <code class="docutils literal"><span class="pre">Name.framework</span></code>, where <code class="docutils literal"><span class="pre">Name</span></code> is the name of the framework (and, therefore, the name of the module). That directory has the following layout:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Name</span><span class="o">.</span><span class="n">framework</span><span class="o">/</span>
+ <span class="n">Modules</span><span class="o">/</span><span class="n">module</span><span class="o">.</span><span class="n">modulemap</span> <span class="n">Module</span> <span class="nb">map</span> <span class="k">for</span> <span class="n">the</span> <span class="n">framework</span>
+ <span class="n">Headers</span><span class="o">/</span> <span class="n">Subdirectory</span> <span class="n">containing</span> <span class="n">framework</span> <span class="n">headers</span>
+ <span class="n">PrivateHeaders</span><span class="o">/</span> <span class="n">Subdirectory</span> <span class="n">containing</span> <span class="n">framework</span> <span class="n">private</span> <span class="n">headers</span>
+ <span class="n">Frameworks</span><span class="o">/</span> <span class="n">Subdirectory</span> <span class="n">containing</span> <span class="n">embedded</span> <span class="n">frameworks</span>
+ <span class="n">Resources</span><span class="o">/</span> <span class="n">Subdirectory</span> <span class="n">containing</span> <span class="n">additional</span> <span class="n">resources</span>
+ <span class="n">Name</span> <span class="n">Symbolic</span> <span class="n">link</span> <span class="n">to</span> <span class="n">the</span> <span class="n">shared</span> <span class="n">library</span> <span class="k">for</span> <span class="n">the</span> <span class="n">framework</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal"><span class="pre">system</span></code> 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 <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">GCC</span> <span class="pre">system_header</span></code> 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 <code class="docutils literal"><span class="pre">extern_c</span></code> 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 <code class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></code> block. An import for a module with this attribute can appear within an <code class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></code> block. No other restrictions are lifted, however: the module currently cannot be imported within an <code class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></code> block in a namespace.</p>
+<p>The <code class="docutils literal"><span class="pre">no_undeclared_includes</span></code> attribute specifies that the module can only reach non-modular headers and headers from used modules. Since some headers could be present in more than one search path and map to different modules in each path, this mechanism helps clang to find the right header, i.e., prefer the one for the current module or in a submodule instead of the first usual match in the search paths.</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>export-as-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>:
+ <code class="docutils literal"><span class="pre">requires</span></code> <em>feature-list</em>
+
+<em>feature-list</em>:
+ <em>feature</em> (',' <em>feature</em>)*
+
+<em>feature</em>:
+ <code class="docutils literal"><span class="pre">!</span></code><span class="subscript">opt</span> <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. When building a module for use by a compilation, submodules requiring unavailable features are ignored. The optional <code class="docutils literal"><span class="pre">!</span></code> 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>coroutines</dt>
+<dd>Support for the coroutines TS is available.</dd>
+<dt>cplusplus</dt>
+<dd>C++ support is available.</dd>
+<dt>cplusplus11</dt>
+<dd>C++11 support is available.</dd>
+<dt>freestanding</dt>
+<dd>A freestanding environment is available.</dd>
+<dt>gnuinlineasm</dt>
+<dd>GNU inline ASM 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., <code class="docutils literal"><span class="pre">sse4</span></code>, <code class="docutils literal"><span class="pre">avx</span></code>, <code class="docutils literal"><span class="pre">neon</span></code>) is available.</dd>
+</dl>
+<p><strong>Example:</strong> The <code class="docutils literal"><span class="pre">std</span></code> module can be extended to also include C++ and C++11 headers using a <em>requires-declaration</em>:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">std</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">C</span> <span class="n">standard</span> <span class="n">library</span><span class="o">...</span>
+
+ <span class="n">module</span> <span class="n">vector</span> <span class="p">{</span>
+ <span class="n">requires</span> <span class="n">cplusplus</span>
+ <span class="n">header</span> <span class="s2">"vector"</span>
+ <span class="p">}</span>
+
+ <span class="n">module</span> <span class="n">type_traits</span> <span class="p">{</span>
+ <span class="n">requires</span> <span class="n">cplusplus11</span>
+ <span class="n">header</span> <span class="s2">"type_traits"</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+</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>:
+ <code class="docutils literal"><span class="pre">private</span></code><span class="subscript">opt</span> <code class="docutils literal"><span class="pre">textual</span></code><span class="subscript">opt</span> <code class="docutils literal"><span class="pre">header</span></code> <em>string-literal</em> <em>header-attrs</em><span class="subscript">opt</span>
+ <code class="docutils literal"><span class="pre">umbrella</span></code> <code class="docutils literal"><span class="pre">header</span></code> <em>string-literal</em> <em>header-attrs</em><span class="subscript">opt</span>
+ <code class="docutils literal"><span class="pre">exclude</span></code> <code class="docutils literal"><span class="pre">header</span></code> <em>string-literal</em> <em>header-attrs</em><span class="subscript">opt</span>
+
+<em>header-attrs</em>:
+ '{' <em>header-attr*</em> '}'
+
+<em>header-attr</em>:
+ <code class="docutils literal"><span class="pre">size</span></code> <em>integer-literal</em>
+ <code class="docutils literal"><span class="pre">mtime</span></code> <em>integer-literal</em>
+</pre>
+<p>A header declaration that does not contain <code class="docutils literal"><span class="pre">exclude</span></code> nor <code class="docutils literal"><span class="pre">textual</span></code> 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 <code class="docutils literal"><span class="pre">umbrella</span></code> 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 <code class="docutils literal"><span class="pre">#include</span></code> 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 <code class="docutils literal"><span class="pre">header</span></code> 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 <code class="docutils literal"><span class="pre">header</span></code> declarations. Use the
+<code class="docutils literal"><span class="pre">-Wincomplete-umbrella</span></code> 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 <code class="docutils literal"><span class="pre">private</span></code> specifier may not be included from outside the module itself.</p>
+<p>A header with the <code class="docutils literal"><span class="pre">textual</span></code> specifier will not be compiled when the module is
+built, and will be textually included if it is named by a <code class="docutils literal"><span class="pre">#include</span></code>
+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 <code class="docutils literal"><span class="pre">exclude</span></code> 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 <code class="docutils literal"><span class="pre">umbrella</span></code> header or directory would otherwise make it part of the module.</p>
+<p><strong>Example:</strong> The C header <code class="docutils literal"><span class="pre">assert.h</span></code> is an excellent candidate for a textual header, because it is meant to be included multiple times (possibly with different <code class="docutils literal"><span class="pre">NDEBUG</span></code> settings). However, declarations within it should typically be split into a separate modular header.</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">std</span> <span class="p">[</span><span class="n">system</span><span class="p">]</span> <span class="p">{</span>
+ <span class="n">textual</span> <span class="n">header</span> <span class="s2">"assert.h"</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A given header shall not be referenced by more than one <em>header-declaration</em>.</p>
+<p>Two <em>header-declaration</em>s, or a <em>header-declaration</em> and a <code class="docutils literal"><span class="pre">#include</span></code>, are
+considered to refer to the same file if the paths resolve to the same file
+and the specified <em>header-attr</em>s (if any) match the attributes of that file,
+even if the file is named differently (for instance, by a relative path or
+via symlinks).</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The use of <em>header-attr</em>s avoids the need for Clang to speculatively
+<code class="docutils literal"><span class="pre">stat</span></code> every header referenced by a module map. It is recommended that
+<em>header-attr</em>s only be used in machine-generated module maps, to avoid
+mismatches between attribute values and the corresponding files.</p>
+</div>
+</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>:
+ <code class="docutils literal"><span class="pre">umbrella</span></code> <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 <code class="docutils literal"><span class="pre">framework</span></code> specifier, the enclosing module shall have a <code class="docutils literal"><span class="pre">framework</span></code> specifier; the submodule’s contents shall be contained within the subdirectory <code class="docutils literal"><span class="pre">Frameworks/SubName.framework</span></code>, where <code class="docutils literal"><span class="pre">SubName</span></code> 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>:
+ <code class="docutils literal"><span class="pre">explicit</span></code><span class="subscript">opt</span> <code class="docutils literal"><span class="pre">framework</span></code><span class="subscript">opt</span> <code class="docutils literal"><span class="pre">module</span></code> '*' <em>attributes</em><span class="subscript">opt</span> '{' <em>inferred-submodule-member*</em> '}'
+
+<em>inferred-submodule-member</em>:
+ <code class="docutils literal"><span class="pre">export</span></code> '*'
+</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 <code class="docutils literal"><span class="pre">explicit</span></code> specifier, if the <em>inferred-submodule-declaration</em> has the <code class="docutils literal"><span class="pre">explicit</span></code> specifier</li>
+<li>Have the <code class="docutils literal"><span class="pre">framework</span></code> specifier, if the
+<em>inferred-submodule-declaration</em> has the <code class="docutils literal"><span class="pre">framework</span></code> 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> <code class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></code>, if the <em>inferred-submodule-declaration</em> contains the <em>inferred-submodule-member</em> <code class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></code></li>
+</ul>
+<p><strong>Example:</strong> If the subdirectory “MyLib” contains the headers <code class="docutils literal"><span class="pre">A.h</span></code> and <code class="docutils literal"><span class="pre">B.h</span></code>, then the following module map:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">MyLib</span> <span class="p">{</span>
+ <span class="n">umbrella</span> <span class="s2">"MyLib"</span>
+ <span class="n">explicit</span> <span class="n">module</span> <span class="o">*</span> <span class="p">{</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>is equivalent to the (more verbose) module map:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">MyLib</span> <span class="p">{</span>
+ <span class="n">explicit</span> <span class="n">module</span> <span class="n">A</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"A.h"</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+
+ <span class="n">explicit</span> <span class="n">module</span> <span class="n">B</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"B.h"</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</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>:
+ <code class="docutils literal"><span class="pre">export</span></code> <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 <code class="docutils literal"><span class="pre">*</span></code> will be re-exported.</p>
+<p><strong>Example:</strong> In the following example, importing <code class="docutils literal"><span class="pre">MyLib.Derived</span></code> also provides the API for <code class="docutils literal"><span class="pre">MyLib.Base</span></code>:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">MyLib</span> <span class="p">{</span>
+ <span class="n">module</span> <span class="n">Base</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"Base.h"</span>
+ <span class="p">}</span>
+
+ <span class="n">module</span> <span class="n">Derived</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"Derived.h"</span>
+ <span class="n">export</span> <span class="n">Base</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that, if <code class="docutils literal"><span class="pre">Derived.h</span></code> includes <code class="docutils literal"><span class="pre">Base.h</span></code>, one can simply use a wildcard export to re-export everything <code class="docutils literal"><span class="pre">Derived.h</span></code> includes:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">MyLib</span> <span class="p">{</span>
+ <span class="n">module</span> <span class="n">Base</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"Base.h"</span>
+ <span class="p">}</span>
+
+ <span class="n">module</span> <span class="n">Derived</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"Derived.h"</span>
+ <span class="n">export</span> <span class="o">*</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The wildcard export syntax <code class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></code> re-exports all of the
+modules that were imported in the actual header file. Because
+<code class="docutils literal"><span class="pre">#include</span></code> directives are automatically mapped to module imports,
+<code class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></code> 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 <code class="docutils literal"><span class="pre">export</span> <span class="pre">*</span></code> provides excellent backward
+compatibility for programs that rely on transitive inclusion (i.e.,
+all of them).</p>
+</div>
+</div>
+<div class="section" id="re-export-declaration">
+<h4><a class="toc-backref" href="#id30">Re-export Declaration</a><a class="headerlink" href="#re-export-declaration" title="Permalink to this headline">¶</a></h4>
+<p>An <em>export-as-declaration</em> specifies that the current module will have
+its interface re-exported by the named module.</p>
+<pre class="literal-block">
+<em>export-as-declaration</em>:
+ <code class="docutils literal"><span class="pre">export_as</span></code> <em>identifier</em>
+</pre>
+<p>The <em>export-as-declaration</em> names the module that the current
+module will be re-exported through. Only top-level modules
+can be re-exported, and any given module may only be re-exported
+through a single module.</p>
+<p><strong>Example:</strong> In the following example, the module <code class="docutils literal"><span class="pre">MyFrameworkCore</span></code>
+will be re-exported via the module <code class="docutils literal"><span class="pre">MyFramework</span></code>:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">MyFrameworkCore</span> <span class="p">{</span>
+ <span class="n">export_as</span> <span class="n">MyFramework</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="use-declaration">
+<h4><a class="toc-backref" href="#id31">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>:
+ <code class="docutils literal"><span class="pre">use</span></code> <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-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">A</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"a.h"</span>
+<span class="p">}</span>
+
+<span class="n">module</span> <span class="n">B</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"b.h"</span>
+<span class="p">}</span>
+
+<span class="n">module</span> <span class="n">C</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"c.h"</span>
+ <span class="n">use</span> <span class="n">B</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>When compiling a source file that implements a module, use the option
+<code class="docutils literal"><span class="pre">-fmodule-name=module-id</span></code> 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="#id32">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>:
+ <code class="docutils literal"><span class="pre">link</span></code> <code class="docutils literal"><span class="pre">framework</span></code><span class="subscript">opt</span> <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 <code class="docutils literal"><span class="pre">-lclangBasic</span></code> for a Unix-style linker.</p>
+<p>A <em>link-declaration</em> with the <code class="docutils literal"><span class="pre">framework</span></code> specifies that the linker should link against the named framework, e.g., with <code class="docutils literal"><span class="pre">-framework</span> <span class="pre">MyFramework</span></code>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Automatic linking with the <code class="docutils literal"><span class="pre">link</span></code> 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 <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">comment(lib...)</span></code>.</p>
+</div>
+</div>
+<div class="section" id="configuration-macros-declaration">
+<h4><a class="toc-backref" href="#id33">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>:
+ <code class="docutils literal"><span class="pre">config_macros</span></code> <em>attributes</em><span class="subscript">opt</span> <em>config-macro-list</em><span class="subscript">opt</span>
+
+<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 <code class="docutils literal"><span class="pre">exhaustive</span></code> 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 <code class="docutils literal"><span class="pre">exhaustive</span></code> 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 <code class="docutils literal"><span class="pre">-Wconfig-macros</span></code>).</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 <code class="docutils literal"><span class="pre">NDEBUG</span></code> macro setting:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">MyLogger</span> <span class="p">{</span>
+ <span class="n">umbrella</span> <span class="n">header</span> <span class="s2">"MyLogger.h"</span>
+ <span class="n">config_macros</span> <span class="p">[</span><span class="n">exhaustive</span><span class="p">]</span> <span class="n">NDEBUG</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="conflict-declarations">
+<h4><a class="toc-backref" href="#id34">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>:
+ <code class="docutils literal"><span class="pre">conflict</span></code> <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 <code class="docutils literal"><span class="pre">-Wmodule-conflict</span></code>)
+when a module conflict is discovered.</p>
+</div>
+<p><strong>Example:</strong></p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">Conflicts</span> <span class="p">{</span>
+ <span class="n">explicit</span> <span class="n">module</span> <span class="n">A</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"conflict_a.h"</span>
+ <span class="n">conflict</span> <span class="n">B</span><span class="p">,</span> <span class="s2">"we just don't like B"</span>
+ <span class="p">}</span>
+
+ <span class="n">module</span> <span class="n">B</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"conflict_b.h"</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="attributes">
+<h3><a class="toc-backref" href="#id35">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><span class="subscript">opt</span>
+
+<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="#id36">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 <code class="docutils literal"><span class="pre">module.modulemap</span></code> 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
+<code class="docutils literal"><span class="pre">Foo.h</span></code> and <code class="docutils literal"><span class="pre">Foo_Private.h</span></code>, providing public and private APIs,
+respectively. Additionally, <code class="docutils literal"><span class="pre">Foo_Private.h</span></code> 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-default"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="n">Foo</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"Foo.h"</span>
+ <span class="o">...</span>
+<span class="p">}</span>
+
+<span class="n">module</span> <span class="n">Foo_Private</span> <span class="p">{</span>
+ <span class="n">header</span> <span class="s2">"Foo_Private.h"</span>
+ <span class="o">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>because the header <code class="docutils literal"><span class="pre">Foo_Private.h</span></code> won’t always be available. The
+module map file could be customized based on whether
+<code class="docutils literal"><span class="pre">Foo_Private.h</span></code> is available or not, but doing so requires custom
+build machinery.</p>
+<p>Private module map files, which are named <code class="docutils literal"><span class="pre">module.private.modulemap</span></code>
+(or, for backward compatibility, <code class="docutils literal"><span class="pre">module_private.map</span></code>), allow one to
+augment the primary module map file with an additional modules. 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></span><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">module</span> <span class="n">Foo_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 <code class="docutils literal"><span class="pre">module.private.modulemap</span></code> file is found alongside a
+<code class="docutils literal"><span class="pre">module.modulemap</span></code> file, it is loaded after the <code class="docutils literal"><span class="pre">module.modulemap</span></code>
+file. In our example library, the <code class="docutils literal"><span class="pre">module.private.modulemap</span></code> file
+would be available when <code class="docutils literal"><span class="pre">Foo_Private.h</span></code> is available, making it
+easier to split a library’s public and private APIs along header
+boundaries.</p>
+<p>When writing a private module as part of a <em>framework</em>, it’s recommended that:</p>
+<ul class="simple">
+<li>Headers for this module are present in the <code class="docutils literal"><span class="pre">PrivateHeaders</span></code> framework
+subdirectory.</li>
+<li>The private module is defined as a <em>top level module</em> with the name of the
+public framework prefixed, like <code class="docutils literal"><span class="pre">Foo_Private</span></code> above. Clang has extra logic
+to work with this naming, using <code class="docutils literal"><span class="pre">FooPrivate</span></code> or <code class="docutils literal"><span class="pre">Foo.Private</span></code> (submodule)
+trigger warnings and might not work as expected.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="modularizing-a-platform">
+<h2><a class="toc-backref" href="#id37">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 <code class="docutils literal"><span class="pre">/usr/include</span></code>, 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 <code class="docutils literal"><span class="pre">size_t</span></code> 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-default"><div class="highlight"><pre><span></span><span class="c1">#ifndef _SIZE_T</span>
+<span class="c1">#define _SIZE_T</span>
+<span class="n">typedef</span> <span class="n">__SIZE_TYPE__</span> <span class="n">size_t</span><span class="p">;</span>
+<span class="c1">#endif</span>
+</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 <code class="docutils literal"><span class="pre">size_t</span></code> 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 <code class="docutils literal"><span class="pre">size_t</span></code>. Importing the submodule corresponding to one of those headers will therefore not yield <code class="docutils literal"><span class="pre">size_t</span></code> 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 <code class="docutils literal"><span class="pre">size_t</span></code> is part of the API, or to eliminate the <code class="docutils literal"><span class="pre">#ifndef</span></code> and redefine the <code class="docutils literal"><span class="pre">size_t</span></code> type. The latter works for C++ headers and C11, but will cause an error for non-modules C90/C99, where redefinition of <code class="docutils literal"><span class="pre">typedefs</span></code> 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 <code class="docutils literal"><span class="pre">#include</span></code> 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 <code class="docutils literal"><span class="pre">size_t</span></code> only when the macro <code class="docutils literal"><span class="pre">__need_size_t</span></code> is defined before that header is included, and also vend <code class="docutils literal"><span class="pre">wchar_t</span></code> only when the macro <code class="docutils literal"><span class="pre">__need_wchar_t</span></code> 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 <code class="docutils literal"><span class="pre">exclude</span></code> it in the module map.</dd>
+</dl>
+<p>To detect and help address some of these problems, the <code class="docutils literal"><span class="pre">clang-tools-extra</span></code> repository contains a <code class="docutils literal"><span class="pre">modularize</span></code> 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="#id38">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 <code class="docutils literal"><span class="pre">#include</span></code> directives, it should be fairly simple to track whether a directly-imported module has ever been used. By doing so, Clang can emit <code class="docutils literal"><span class="pre">unused</span> <span class="pre">import</span></code> or <code class="docutils literal"><span class="pre">unused</span> <span class="pre">#include</span></code> 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="#id39">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><code class="docutils literal"><span class="pre">clang/lib/Headers/module.modulemap</span></code></dt>
+<dd>Module map for Clang’s compiler-specific header files.</dd>
+<dt><code class="docutils literal"><span class="pre">clang/test/Modules/</span></code></dt>
+<dd>Tests specifically related to modules functionality.</dd>
+<dt><code class="docutils literal"><span class="pre">clang/include/clang/Basic/Module.h</span></code></dt>
+<dd>The <code class="docutils literal"><span class="pre">Module</span></code> class in this header describes a module, and is used throughout the compiler to implement modules.</dd>
+<dt><code class="docutils literal"><span class="pre">clang/include/clang/Lex/ModuleMap.h</span></code></dt>
+<dd>The <code class="docutils literal"><span class="pre">ModuleMap</span></code> 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 <code class="docutils literal"><span class="pre">clangSerialization</span></code> 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 <code class="docutils literal"><span class="pre">-D</span></code> 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" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="SourceBasedCodeCoverage.html">Source-based Code Coverage</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="MSVCCompatibility.html">MSVC compatibility</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/ObjectiveCLiterals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/ObjectiveCLiterals.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/ObjectiveCLiterals.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/ObjectiveCLiterals.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,599 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Language Specification for Blocks" href="BlockLanguageSpec.html" />
+ <link rel="prev" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Objective-C Literals</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <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 <code class="docutils literal"><span class="pre">NSNumber</span></code> 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 <code class="docutils literal"><span class="pre">NSNumber</span></code> is used to wrap scalar values inside
+objects: signed and unsigned integers (<code class="docutils literal"><span class="pre">char</span></code>, <code class="docutils literal"><span class="pre">short</span></code>, <code class="docutils literal"><span class="pre">int</span></code>,
+<code class="docutils literal"><span class="pre">long</span></code>, <code class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></code>), floating point numbers (<code class="docutils literal"><span class="pre">float</span></code>,
+<code class="docutils literal"><span class="pre">double</span></code>), and boolean values (<code class="docutils literal"><span class="pre">BOOL</span></code>, C++ <code class="docutils literal"><span class="pre">bool</span></code>). 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 <code class="docutils literal"><span class="pre">'@'</span></code> character will evaluate to a pointer to an <code class="docutils literal"><span class="pre">NSNumber</span></code>
+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 <code class="docutils literal"><span class="pre">NSNumber</span></code> literals:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="kt">void</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">// character literals.</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">theLetterZ</span> <span class="o">=</span> <span class="sc">@'Z'</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithChar:'Z']</span>
+
+ <span class="c1">// integral literals.</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">fortyTwo</span> <span class="o">=</span> <span class="mi">@42</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithInt:42]</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">fortyTwoUnsigned</span> <span class="o">=</span> <span class="mi">@42</span><span class="n">U</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithUnsignedInt:42U]</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">fortyTwoLong</span> <span class="o">=</span> <span class="mi">@42L</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithLong:42L]</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">fortyTwoLongLong</span> <span class="o">=</span> <span class="mi">@42L</span><span class="n">L</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithLongLong:42LL]</span>
+
+ <span class="c1">// floating point literals.</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">piFloat</span> <span class="o">=</span> <span class="mf">@3.141592654F</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithFloat:3.141592654F]</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">piDouble</span> <span class="o">=</span> <span class="mf">@3.1415926535</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithDouble:3.1415926535]</span>
+
+ <span class="c1">// BOOL literals.</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">yesNumber</span> <span class="o">=</span> <span class="m">@YES</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithBool:YES]</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">noNumber</span> <span class="o">=</span> <span class="m">@NO</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithBool:NO]</span>
+
+<span class="cp">#ifdef __cplusplus</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">trueNumber</span> <span class="o">=</span> <span class="p">@</span><span class="nb">true</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithBool:(BOOL)true]</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">falseNumber</span> <span class="o">=</span> <span class="p">@</span><span class="nb">false</span><span class="p">;</span> <span class="c1">// equivalent to [NSNumber numberWithBool:(BOOL)false]</span>
+<span class="cp">#endif</span>
+<span class="p">}</span>
+</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 <code class="docutils literal"><span class="pre">'@'</span></code>.
+Consequently, <code class="docutils literal"><span class="pre">@INT_MAX</span></code> works, but <code class="docutils literal"><span class="pre">@INT_MIN</span></code> does not, because
+they are defined like this:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">INT_MIN</span></code> 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 <code class="docutils literal"><span class="pre">NSNumber</span></code> does not currently support wrapping <code class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></code>
+values, the use of a <code class="docutils literal"><span class="pre">long</span> <span class="pre">double</span> <span class="pre">NSNumber</span></code> literal (e.g.
+<code class="docutils literal"><span class="pre">@123.23L</span></code>) will be rejected by the compiler.</p>
+<p>Previously, the <code class="docutils literal"><span class="pre">BOOL</span></code> type was simply a typedef for <code class="docutils literal"><span class="pre">signed</span> <span class="pre">char</span></code>,
+and <code class="docutils literal"><span class="pre">YES</span></code> and <code class="docutils literal"><span class="pre">NO</span></code> were macros that expand to <code class="docutils literal"><span class="pre">(BOOL)1</span></code> and
+<code class="docutils literal"><span class="pre">(BOOL)0</span></code> respectively. To support <code class="docutils literal"><span class="pre">@YES</span></code> and <code class="docutils literal"><span class="pre">@NO</span></code> expressions,
+these macros are now defined using new language keywords in
+<code class="docutils literal"><span class="pre"><objc/objc.h></span></code>:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">__objc_yes</span></code> and <code class="docutils literal"><span class="pre">__objc_no</span></code> to
+<code class="docutils literal"><span class="pre">(BOOL)1</span></code> and <code class="docutils literal"><span class="pre">(BOOL)0</span></code>. The keywords are used to disambiguate
+<code class="docutils literal"><span class="pre">BOOL</span></code> and integer literals.</p>
+<p>Objective-C++ also supports <code class="docutils literal"><span class="pre">@true</span></code> and <code class="docutils literal"><span class="pre">@false</span></code> expressions, which
+are equivalent to <code class="docutils literal"><span class="pre">@YES</span></code> and <code class="docutils literal"><span class="pre">@NO</span></code>.</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><span></span><span class="l">@(</span> <span class="o"><</span><span class="n">expression</span><span class="o">></span> <span class="l">)</span>
+</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><span></span><span class="c1">// numbers.</span>
+<span class="bp">NSNumber</span> <span class="o">*</span><span class="n">smallestInt</span> <span class="o">=</span> <span class="l">@(</span><span class="o">-</span><span class="n">INT_MAX</span> <span class="o">-</span> <span class="mi">1</span><span class="l">)</span><span class="p">;</span> <span class="c1">// [NSNumber numberWithInt:(-INT_MAX - 1)]</span>
+<span class="bp">NSNumber</span> <span class="o">*</span><span class="n">piOverTwo</span> <span class="o">=</span> <span class="l">@(</span><span class="n">M_PI</span> <span class="o">/</span> <span class="mi">2</span><span class="l">)</span><span class="p">;</span> <span class="c1">// [NSNumber numberWithDouble:(M_PI / 2)]</span>
+
+<span class="c1">// enumerated types.</span>
+<span class="k">typedef</span> <span class="k">enum</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>
+<span class="bp">NSNumber</span> <span class="o">*</span><span class="n">favoriteColor</span> <span class="o">=</span> <span class="l">@(</span><span class="n">Green</span><span class="l">)</span><span class="p">;</span> <span class="c1">// [NSNumber numberWithInt:((int)Green)]</span>
+
+<span class="c1">// strings.</span>
+<span class="bp">NSString</span> <span class="o">*</span><span class="n">path</span> <span class="o">=</span> <span class="l">@(</span><span class="n">getenv</span><span class="p">(</span><span class="s">"PATH"</span><span class="p">)</span><span class="l">)</span><span class="p">;</span> <span class="c1">// [NSString stringWithUTF8String:(getenv("PATH"))]</span>
+<span class="bp">NSArray</span> <span class="o">*</span><span class="n">pathComponents</span> <span class="o">=</span> <span class="p">[</span><span class="n">path</span> <span class="nl">componentsSeparatedByString</span><span class="p">:</span><span class="s">@":"</span><span class="p">];</span>
+
+<span class="c1">// structs.</span>
+<span class="bp">NSValue</span> <span class="o">*</span><span class="n">center</span> <span class="o">=</span> <span class="l">@(</span><span class="n">view</span><span class="p">.</span><span class="n">center</span><span class="l">)</span><span class="p">;</span> <span class="c1">// Point p = view.center;</span>
+ <span class="c1">// [NSValue valueWithBytes:&p objCType:@encode(Point)];</span>
+<span class="bp">NSValue</span> <span class="o">*</span><span class="n">frame</span> <span class="o">=</span> <span class="l">@(</span><span class="n">view</span><span class="p">.</span><span class="n">frame</span><span class="l">)</span><span class="p">;</span> <span class="c1">// Rect r = view.frame;</span>
+ <span class="c1">// [NSValue valueWithBytes:&r objCType:@encode(Rect)];</span>
+</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 <code class="docutils literal"><span class="pre">'@'</span></code>-prefixed
+Objective-C keywords). Instead, an enum value must be placed inside a
+boxed expression. The following example demonstrates configuring an
+<code class="docutils literal"><span class="pre">AVAudioRecorder</span></code> using a dictionary that contains a boxed enumeration
+value:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="p">{</span>
+ <span class="n">AVAudioQualityMin</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
+ <span class="n">AVAudioQualityLow</span> <span class="o">=</span> <span class="mh">0x20</span><span class="p">,</span>
+ <span class="n">AVAudioQualityMedium</span> <span class="o">=</span> <span class="mh">0x40</span><span class="p">,</span>
+ <span class="n">AVAudioQualityHigh</span> <span class="o">=</span> <span class="mh">0x60</span><span class="p">,</span>
+ <span class="n">AVAudioQualityMax</span> <span class="o">=</span> <span class="mh">0x7F</span>
+<span class="p">};</span>
+
+<span class="p">-</span> <span class="p">(</span><span class="bp">AVAudioRecorder</span> <span class="o">*</span><span class="p">)</span><span class="nf">recordToFile:</span><span class="p">(</span><span class="bp">NSURL</span> <span class="o">*</span><span class="p">)</span><span class="nv">fileURL</span> <span class="p">{</span>
+ <span class="bp">NSDictionary</span> <span class="o">*</span><span class="n">settings</span> <span class="o">=</span> <span class="l">@{</span> <span class="nl">AVEncoderAudioQualityKey</span> <span class="p">:</span> <span class="l">@(</span><span class="n">AVAudioQualityMax</span><span class="l">)</span> <span class="l">}</span><span class="p">;</span>
+ <span class="k">return</span> <span class="p">[[</span><span class="bp">AVAudioRecorder</span> <span class="n">alloc</span><span class="p">]</span> <span class="nl">initWithURL</span><span class="p">:</span><span class="n">fileURL</span> <span class="nl">settings</span><span class="p">:</span><span class="n">settings</span> <span class="nl">error</span><span class="p">:</span><span class="nb">NULL</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The expression <code class="docutils literal"><span class="pre">@(AVAudioQualityMax)</span></code> converts <code class="docutils literal"><span class="pre">AVAudioQualityMax</span></code>
+to an integer type, and boxes the value accordingly. If the enum has a
+<a class="reference internal" href="LanguageExtensions.html#objc-fixed-enum"><span class="std std-ref">fixed underlying type</span></a> as in:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">enum</span> <span class="o">:</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="p">{</span> <span class="n">Red</span><span class="p">,</span> <span class="n">Green</span><span class="p">,</span> <span class="n">Blue</span> <span class="p">}</span> <span class="n">Color</span><span class="p">;</span>
+<span class="bp">NSNumber</span> <span class="o">*</span><span class="n">red</span> <span class="o">=</span> <span class="l">@(</span><span class="n">Red</span><span class="l">)</span><span class="p">,</span> <span class="o">*</span><span class="n">green</span> <span class="o">=</span> <span class="l">@(</span><span class="n">Green</span><span class="l">)</span><span class="p">,</span> <span class="o">*</span><span class="n">blue</span> <span class="o">=</span> <span class="l">@(</span><span class="n">Blue</span><span class="l">)</span><span class="p">;</span> <span class="c1">// => [NSNumber numberWithUnsignedChar:]</span>
+</pre></div>
+</div>
+<p>then the fixed underlying type will be used to select the correct
+<code class="docutils literal"><span class="pre">NSNumber</span></code> creation method.</p>
+<p>Boxing a value of enum type will result in a <code class="docutils literal"><span class="pre">NSNumber</span></code> 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"><span class="std std-ref">fixed underlying type</span></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><span></span><span class="k">typedef</span> <span class="k">enum</span> <span class="o">:</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="p">{</span> <span class="n">Red</span><span class="p">,</span> <span class="n">Green</span><span class="p">,</span> <span class="n">Blue</span> <span class="p">}</span> <span class="n">Color</span><span class="p">;</span>
+<span class="n">Color</span> <span class="n">col</span> <span class="o">=</span> <span class="n">Red</span><span class="p">;</span>
+<span class="bp">NSNumber</span> <span class="o">*</span><span class="n">nsCol</span> <span class="o">=</span> <span class="l">@(</span><span class="n">col</span><span class="l">)</span><span class="p">;</span> <span class="c1">// => [NSNumber numberWithUnsignedChar:]</span>
+</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 <code class="docutils literal"><span class="pre">'@'</span></code> token denotes an <code class="docutils literal"><span class="pre">NSString</span></code>
+literal in the same way a numeric literal prefixed by the <code class="docutils literal"><span class="pre">'@'</span></code> token
+denotes an <code class="docutils literal"><span class="pre">NSNumber</span></code> literal. When the type of the parenthesized
+expression is <code class="docutils literal"><span class="pre">(char</span> <span class="pre">*)</span></code> or <code class="docutils literal"><span class="pre">(const</span> <span class="pre">char</span> <span class="pre">*)</span></code>, the result of the
+boxed expression is a pointer to an <code class="docutils literal"><span class="pre">NSString</span></code> 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 <code class="docutils literal"><span class="pre">NSString</span></code> objects.</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="c1">// Partition command line arguments into positional and option arguments.</span>
+<span class="bp">NSMutableArray</span> <span class="o">*</span><span class="n">args</span> <span class="o">=</span> <span class="p">[</span><span class="bp">NSMutableArray</span> <span class="n">new</span><span class="p">];</span>
+<span class="bp">NSMutableDictionary</span> <span class="o">*</span><span class="n">options</span> <span class="o">=</span> <span class="p">[</span><span class="bp">NSMutableDictionary</span> <span class="n">new</span><span class="p">];</span>
+<span class="k">while</span> <span class="p">(</span><span class="o">--</span><span class="n">argc</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">arg</span> <span class="o">=</span> <span class="o">*++</span><span class="n">argv</span><span class="p">;</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">strncmp</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="s">"--"</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">options</span><span class="p">[</span><span class="l">@(</span><span class="n">arg</span> <span class="o">+</span> <span class="mi">2</span><span class="l">)</span><span class="p">]</span> <span class="o">=</span> <span class="l">@(</span><span class="o">*++</span><span class="n">argv</span><span class="l">)</span><span class="p">;</span> <span class="c1">// --key value</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="p">[</span><span class="n">args</span> <span class="nl">addObject</span><span class="p">:</span><span class="l">@(</span><span class="n">arg</span><span class="l">)</span><span class="p">];</span> <span class="c1">// positional argument</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</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 <code class="docutils literal"><span class="pre">NULL</span></code> as the character pointer will
+raise an exception at runtime. When possible, the compiler will reject
+<code class="docutils literal"><span class="pre">NULL</span></code> 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 <code class="docutils literal"><span class="pre">objc_boxable</span></code> attribute.
+To support older version of frameworks and/or third-party libraries
+you may need to add the attribute via <code class="docutils literal"><span class="pre">typedef</span></code>.</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">objc_boxable</span><span class="p">))</span> <span class="n">Point</span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+<span class="p">};</span>
+
+<span class="k">typedef</span> <span class="k">struct</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">objc_boxable</span><span class="p">))</span> <span class="n">_Size</span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span> <span class="n">Size</span><span class="p">;</span>
+
+<span class="k">typedef</span> <span class="k">struct</span> <span class="n">_Rect</span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span> <span class="n">Rect</span><span class="p">;</span>
+
+<span class="k">struct</span> <span class="n">Point</span> <span class="n">p</span><span class="p">;</span>
+<span class="bp">NSValue</span> <span class="o">*</span><span class="n">point</span> <span class="o">=</span> <span class="l">@(</span><span class="n">p</span><span class="l">)</span><span class="p">;</span> <span class="c1">// ok</span>
+<span class="n">Size</span> <span class="n">s</span><span class="p">;</span>
+<span class="bp">NSValue</span> <span class="o">*</span><span class="n">size</span> <span class="o">=</span> <span class="l">@(</span><span class="n">s</span><span class="l">)</span><span class="p">;</span> <span class="c1">// ok</span>
+
+<span class="n">Rect</span> <span class="n">r</span><span class="p">;</span>
+<span class="bp">NSValue</span> <span class="o">*</span><span class="n">bad_rect</span> <span class="o">=</span> <span class="l">@(</span><span class="n">r</span><span class="l">)</span><span class="p">;</span> <span class="c1">// error</span>
+
+<span class="k">typedef</span> <span class="k">struct</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">objc_boxable</span><span class="p">))</span> <span class="n">_Rect</span> <span class="n">Rect</span><span class="p">;</span>
+
+<span class="bp">NSValue</span> <span class="o">*</span><span class="n">good_rect</span> <span class="o">=</span> <span class="l">@(</span><span class="n">r</span><span class="l">)</span><span class="p">;</span> <span class="c1">// ok</span>
+</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><span></span><span class="bp">NSArray</span> <span class="o">*</span><span class="n">array</span> <span class="o">=</span> <span class="l">@[</span> <span class="s">@"Hello"</span><span class="p">,</span> <span class="n">NSApp</span><span class="p">,</span> <span class="p">[</span><span class="bp">NSNumber</span> <span class="nl">numberWithInt</span><span class="p">:</span><span class="mi">42</span><span class="p">]</span> <span class="l">]</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This creates an <code class="docutils literal"><span class="pre">NSArray</span></code> 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><span></span><span class="bp">NSDictionary</span> <span class="o">*</span><span class="n">dictionary</span> <span class="o">=</span> <span class="l">@{</span>
+ <span class="s">@"name"</span> <span class="o">:</span> <span class="n">NSUserName</span><span class="p">(),</span>
+ <span class="s">@"date"</span> <span class="o">:</span> <span class="p">[</span><span class="bp">NSDate</span> <span class="n">date</span><span class="p">],</span>
+ <span class="s">@"processInfo"</span> <span class="o">:</span> <span class="p">[</span><span class="bp">NSProcessInfo</span> <span class="n">processInfo</span><span class="p">]</span>
+<span class="l">}</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This creates an <code class="docutils literal"><span class="pre">NSDictionary</span></code> 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
+<code class="docutils literal"><span class="pre"><NSCopying></span></code> 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 <code class="docutils literal"><span class="pre">nil</span></code> in containers. If the
+compiler can prove that a key or value is <code class="docutils literal"><span class="pre">nil</span></code> 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 <code class="docutils literal"><span class="pre">+[NSArray</span> <span class="pre">arrayWithObjects:count:]</span></code>, which validates that all
+objects are non-<code class="docutils literal"><span class="pre">nil</span></code>. The variadic form,
+<code class="docutils literal"><span class="pre">+[NSArray</span> <span class="pre">arrayWithObjects:]</span></code> uses <code class="docutils literal"><span class="pre">nil</span></code> as an argument list
+terminator, which can lead to malformed array objects. Dictionary
+literals are similarly created with
+<code class="docutils literal"><span class="pre">+[NSDictionary</span> <span class="pre">dictionaryWithObjects:forKeys:count:]</span></code> which validates
+all objects and keys, unlike
+<code class="docutils literal"><span class="pre">+[NSDictionary</span> <span class="pre">dictionaryWithObjectsAndKeys:]</span></code> which also uses a
+<code class="docutils literal"><span class="pre">nil</span></code> 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 <code class="docutils literal"><span class="pre">NSMutableArray</span></code> and <code class="docutils literal"><span class="pre">NSMutableDictionary</span></code> objects:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="bp">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="bp">NSMutableDictionary</span> <span class="o">*</span><span class="n">dictionary</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="bp">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></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">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 <code class="docutils literal"><span class="pre">objectAtIndexedSubscript:</span></code></p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><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="nl">objectAtIndexedSubscript</span><span class="p">:</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></span><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 <code class="docutils literal"><span class="pre">setObject:atIndexedSubscript:</span></code></p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">object</span> <span class="nl">setObject</span><span class="p">:</span><span class="n">newValue</span> <span class="nl">atIndexedSubscript</span><span class="p">:</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 <code class="docutils literal"><span class="pre">NSArray</span></code>, reading an
+element using an index outside the range <code class="docutils literal"><span class="pre">[0,</span> <span class="pre">array.count)</span></code> will raise
+an exception. For an instance of <code class="docutils literal"><span class="pre">NSMutableArray</span></code>, 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 <code class="docutils literal"><span class="pre">NSArray</span></code> declares only
+<code class="docutils literal"><span class="pre">objectAtIndexedSubscript:</span></code>, so that assignments to elements will fail
+to type-check; moreover, its subclass <code class="docutils literal"><span class="pre">NSMutableArray</span></code> declares
+<code class="docutils literal"><span class="pre">setObject:atIndexedSubscript:</span></code>.</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></span><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 <code class="docutils literal"><span class="pre">objectForKeyedSubscript:</span></code> method:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><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="nl">objectForKeyedSubscript</span><span class="p">:</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></span><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 <code class="docutils literal"><span class="pre">setObject:forKeyedSubscript:</span></code></p>
+<div class="highlight-objc"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">object</span> <span class="nl">setObject</span><span class="p">:</span><span class="n">newValue</span> <span class="nl">forKeyedSubscript</span><span class="p">:</span><span class="n">key</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>The behavior of <code class="docutils literal"><span class="pre">setObject:forKeyedSubscript:</span></code> 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 <code class="docutils literal"><span class="pre">id</span></code>. 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 <code class="docutils literal"><span class="pre">==</span></code>, <code class="docutils literal"><span class="pre">!=</span></code>, <code class="docutils literal"><span class="pre"><</span></code>,
+<code class="docutils literal"><span class="pre"><=</span></code>, <code class="docutils literal"><span class="pre">></span></code>, or <code class="docutils literal"><span class="pre">>=</span></code>) is not well-defined. This is usually a simple
+mistake in code that intended to call the <code class="docutils literal"><span class="pre">isEqual:</span></code> method (or the
+<code class="docutils literal"><span class="pre">compare:</span></code> method).</p>
+<p>This caveat applies to compile-time string literals as well.
+Historically, string literals (using the <code class="docutils literal"><span class="pre">@"..."</span></code> 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
+(<code 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></code>) or use <code class="docutils literal"><span class="pre">isEqual:</span></code>.</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
+<code class="docutils literal"><span class="pre">@</span></code>-expression grammar has the following new productions:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span>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: <code class="docutils literal"><span class="pre">@true</span></code> and <code class="docutils literal"><span class="pre">@false</span></code> 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><span></span><span class="cp">#if __has_feature(objc_array_literals)</span>
+ <span class="c1">// new way.</span>
+ <span class="bp">NSArray</span> <span class="o">*</span><span class="n">elements</span> <span class="o">=</span> <span class="l">@[</span> <span class="s">@"H"</span><span class="p">,</span> <span class="s">@"He"</span><span class="p">,</span> <span class="s">@"O"</span><span class="p">,</span> <span class="s">@"C"</span> <span class="l">]</span><span class="p">;</span>
+<span class="cp">#else</span>
+ <span class="c1">// old way (equivalent).</span>
+ <span class="kt">id</span> <span class="n">objects</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="s">@"H"</span><span class="p">,</span> <span class="s">@"He"</span><span class="p">,</span> <span class="s">@"O"</span><span class="p">,</span> <span class="s">@"C"</span> <span class="p">};</span>
+ <span class="bp">NSArray</span> <span class="o">*</span><span class="n">elements</span> <span class="o">=</span> <span class="p">[</span><span class="bp">NSArray</span> <span class="nl">arrayWithObjects</span><span class="p">:</span><span class="n">objects</span> <span class="nl">count</span><span class="p">:</span><span class="mi">4</span><span class="p">];</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if __has_feature(objc_dictionary_literals)</span>
+ <span class="c1">// new way.</span>
+ <span class="bp">NSDictionary</span> <span class="o">*</span><span class="n">masses</span> <span class="o">=</span> <span class="l">@{</span> <span class="s">@"H"</span> <span class="o">:</span> <span class="mf">@1.0078</span><span class="p">,</span> <span class="s">@"He"</span> <span class="o">:</span> <span class="mf">@4.0026</span><span class="p">,</span> <span class="s">@"O"</span> <span class="o">:</span> <span class="mf">@15.9990</span><span class="p">,</span> <span class="s">@"C"</span> <span class="o">:</span> <span class="mf">@12.0096</span> <span class="l">}</span><span class="p">;</span>
+<span class="cp">#else</span>
+ <span class="c1">// old way (equivalent).</span>
+ <span class="kt">id</span> <span class="n">keys</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="s">@"H"</span><span class="p">,</span> <span class="s">@"He"</span><span class="p">,</span> <span class="s">@"O"</span><span class="p">,</span> <span class="s">@"C"</span> <span class="p">};</span>
+ <span class="kt">id</span> <span class="n">values</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="p">[</span><span class="bp">NSNumber</span> <span class="nl">numberWithDouble</span><span class="p">:</span><span class="mf">1.0078</span><span class="p">],</span> <span class="p">[</span><span class="bp">NSNumber</span> <span class="nl">numberWithDouble</span><span class="p">:</span><span class="mf">4.0026</span><span class="p">],</span>
+ <span class="p">[</span><span class="bp">NSNumber</span> <span class="nl">numberWithDouble</span><span class="p">:</span><span class="mf">15.9990</span><span class="p">],</span> <span class="p">[</span><span class="bp">NSNumber</span> <span class="nl">numberWithDouble</span><span class="p">:</span><span class="mf">12.0096</span><span class="p">]</span> <span class="p">};</span>
+ <span class="bp">NSDictionary</span> <span class="o">*</span><span class="n">masses</span> <span class="o">=</span> <span class="p">[</span><span class="bp">NSDictionary</span> <span class="nl">dictionaryWithObjects</span><span class="p">:</span><span class="n">objects</span> <span class="nl">forKeys</span><span class="p">:</span><span class="n">keys</span> <span class="nl">count</span><span class="p">:</span><span class="mi">4</span><span class="p">];</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if __has_feature(objc_subscripting)</span>
+ <span class="n">NSUInteger</span> <span class="n">i</span><span class="p">,</span> <span class="n">count</span> <span class="o">=</span> <span class="n">elements</span><span class="p">.</span><span class="n">count</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">count</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="bp">NSString</span> <span class="o">*</span><span class="n">element</span> <span class="o">=</span> <span class="n">elements</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">mass</span> <span class="o">=</span> <span class="n">masses</span><span class="p">[</span><span class="n">element</span><span class="p">];</span>
+ <span class="n">NSLog</span><span class="p">(</span><span class="s">@"the mass of %@ is %@"</span><span class="p">,</span> <span class="n">element</span><span class="p">,</span> <span class="n">mass</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="cp">#else</span>
+ <span class="n">NSUInteger</span> <span class="n">i</span><span class="p">,</span> <span class="n">count</span> <span class="o">=</span> <span class="p">[</span><span class="n">elements</span> <span class="n">count</span><span class="p">];</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">count</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="bp">NSString</span> <span class="o">*</span><span class="n">element</span> <span class="o">=</span> <span class="p">[</span><span class="n">elements</span> <span class="nl">objectAtIndex</span><span class="p">:</span><span class="n">i</span><span class="p">];</span>
+ <span class="bp">NSNumber</span> <span class="o">*</span><span class="n">mass</span> <span class="o">=</span> <span class="p">[</span><span class="n">masses</span> <span class="nl">objectForKey</span><span class="p">:</span><span class="n">element</span><span class="p">];</span>
+ <span class="n">NSLog</span><span class="p">(</span><span class="s">@"the mass of %@ is %@"</span><span class="p">,</span> <span class="n">element</span><span class="p">,</span> <span class="n">mass</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if __has_attribute(objc_boxable)</span>
+ <span class="k">typedef</span> <span class="k">struct</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_boxable</span><span class="p">))</span> <span class="n">_Rect</span> <span class="n">Rect</span><span class="p">;</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if __has_feature(objc_boxed_nsvalue_expressions)</span>
+ <span class="bp">CABasicAnimation</span> <span class="n">animation</span> <span class="o">=</span> <span class="p">[</span><span class="bp">CABasicAnimation</span> <span class="nl">animationWithKeyPath</span><span class="p">:</span><span class="s">@"position"</span><span class="p">];</span>
+ <span class="n">animation</span><span class="p">.</span><span class="n">fromValue</span> <span class="o">=</span> <span class="l">@(</span><span class="n">layer</span><span class="p">.</span><span class="n">position</span><span class="l">)</span><span class="p">;</span>
+ <span class="n">animation</span><span class="p">.</span><span class="n">toValue</span> <span class="o">=</span> <span class="l">@(</span><span class="n">newPosition</span><span class="l">)</span><span class="p">;</span>
+ <span class="p">[</span><span class="n">layer</span> <span class="nl">addAnimation</span><span class="p">:</span><span class="n">animation</span> <span class="nl">forKey</span><span class="p">:</span><span class="s">@"move"</span><span class="p">];</span>
+<span class="cp">#else</span>
+ <span class="bp">CABasicAnimation</span> <span class="n">animation</span> <span class="o">=</span> <span class="p">[</span><span class="bp">CABasicAnimation</span> <span class="nl">animationWithKeyPath</span><span class="p">:</span><span class="s">@"position"</span><span class="p">];</span>
+ <span class="n">animation</span><span class="p">.</span><span class="n">fromValue</span> <span class="o">=</span> <span class="p">[</span><span class="bp">NSValue</span> <span class="nl">valueWithCGPoint</span><span class="p">:</span><span class="n">layer</span><span class="p">.</span><span class="n">position</span><span class="p">];</span>
+ <span class="n">animation</span><span class="p">.</span><span class="n">toValue</span> <span class="o">=</span> <span class="p">[</span><span class="bp">NSValue</span> <span class="nl">valueWithCGPoint</span><span class="p">:</span><span class="n">newPosition</span><span class="p">];</span>
+ <span class="p">[</span><span class="n">layer</span> <span class="nl">addAnimation</span><span class="p">:</span><span class="n">animation</span> <span class="nl">forKey</span><span class="p">:</span><span class="s">@"move"</span><span class="p">];</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>Code can use also <code class="docutils literal"><span class="pre">__has_feature(objc_bool)</span></code> to check for the
+availability of numeric literals support. This checks for the new
+<code class="docutils literal"><span class="pre">__objc_yes</span> <span class="pre">/</span> <span class="pre">__objc_no</span></code> keywords, which enable the use of
+<code class="docutils literal"><span class="pre">@YES</span> <span class="pre">/</span> <span class="pre">@NO</span></code> literals.</p>
+<p>To check whether boxed expressions are supported, use
+<code class="docutils literal"><span class="pre">__has_feature(objc_boxed_expressions)</span></code> feature macro.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <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" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/OpenMPSupport.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/OpenMPSupport.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/OpenMPSupport.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/OpenMPSupport.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,115 @@
+<!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>OpenMP Support — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="ThinLTO" href="ThinLTO.html" />
+ <link rel="prev" title="MSVC compatibility" href="MSVCCompatibility.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>OpenMP Support</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="MSVCCompatibility.html">MSVC compatibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ThinLTO.html">ThinLTO</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="openmp-support">
+<h1>OpenMP Support<a class="headerlink" href="#openmp-support" title="Permalink to this headline">¶</a></h1>
+<p>Clang fully supports OpenMP 3.1 + some elements of OpenMP 4.5. Clang supports offloading to X86_64, AArch64 and PPC64[LE] devices.
+Support for Cuda devices is not ready yet.
+The status of major OpenMP 4.5 features support in Clang.</p>
+<div class="section" id="standalone-directives">
+<h2>Standalone directives<a class="headerlink" href="#standalone-directives" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>#pragma omp [for] simd: <span class="good">Complete</span>.</li>
+<li>#pragma omp declare simd: <span class="partial">Partial</span>. We support parsing/semantic
+analysis + generation of special attributes for X86 target, but still
+missing the LLVM pass for vectorization.</li>
+<li>#pragma omp taskloop [simd]: <span class="good">Complete</span>.</li>
+<li>#pragma omp target [enter|exit] data: <span class="good">Complete</span>.</li>
+<li>#pragma omp target update: <span class="good">Complete</span>.</li>
+<li>#pragma omp target: <span class="partial">Partial</span>. No support for the <cite>depend</cite> clauses.</li>
+<li>#pragma omp declare target: <span class="partial">Partial</span>. No full codegen support.</li>
+<li>#pragma omp teams: <span class="good">Complete</span>.</li>
+<li>#pragma omp distribute [simd]: <span class="good">Complete</span>.</li>
+<li>#pragma omp distribute parallel for [simd]: <span class="good">Complete</span>.</li>
+</ul>
+</div>
+<div class="section" id="combined-directives">
+<h2>Combined directives<a class="headerlink" href="#combined-directives" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>#pragma omp parallel for simd: <span class="good">Complete</span>.</li>
+<li>#pragma omp target parallel: <span class="partial">Partial</span>. No support for the <cite>depend</cite> clauses.</li>
+<li>#pragma omp target parallel for [simd]: <span class="partial">Partial</span>. No support for the <cite>depend</cite> clauses.</li>
+<li>#pragma omp target simd: <span class="partial">Partial</span>. No support for the <cite>depend</cite> clauses.</li>
+<li>#pragma omp target teams: <span class="partial">Partial</span>. No support for the <cite>depend</cite> clauses.</li>
+<li>#pragma omp teams distribute [simd]: <span class="good">Complete</span>.</li>
+<li>#pragma omp target teams distribute [simd]: <span class="partial">Partial</span>. No support for the and <cite>depend</cite> clauses.</li>
+<li>#pragma omp teams distribute parallel for [simd]: <span class="good">Complete</span>.</li>
+<li>#pragma omp target teams distribute parallel for [simd]: <span class="partial">Partial</span>. No full codegen support.</li>
+</ul>
+<p>Clang does not support any constructs/updates from upcoming OpenMP 5.0 except for <cite>reduction</cite>-based clauses in the <cite>task</cite> and <cite>target</cite>-based directives.
+In addition, the LLVM OpenMP runtime <cite>libomp</cite> supports the OpenMP Tools Interface (OMPT) on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and mac OS.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="MSVCCompatibility.html">MSVC compatibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ThinLTO.html">ThinLTO</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/PCHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/PCHInternals.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/PCHInternals.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/PCHInternals.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,592 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="ABI tags" href="ItaniumMangleAbiTags.html" />
+ <link rel="prev" title="Pretokenized Headers (PTH)" href="PTHInternals.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Precompiled Header and Modules Internals</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ItaniumMangleAbiTags.html">ABI tags</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 <code class="docutils literal"><span class="pre">clang</span></code></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"><span class="std std-ref">User’s Manual</span></a>.</p>
+<div class="section" id="using-precompiled-headers-with-clang">
+<h2><a class="toc-backref" href="#id1">Using Precompiled Headers with <code class="docutils literal"><span class="pre">clang</span></code></a><a class="headerlink" href="#using-precompiled-headers-with-clang" title="Permalink to this headline">¶</a></h2>
+<p>The Clang compiler frontend, <code class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></code>, supports two command line options
+for generating and using PCH files.</p>
+<p>To generate PCH files using <code class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></code>, use the option <cite>-emit-pch</cite>:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>$ clang -cc1 test.h -emit-pch -o test.h.pch
+</pre></div>
+</div>
+<p>This option is transparently used by <code class="docutils literal"><span class="pre">clang</span></code> 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 <cite>-include-pch</cite>
+option:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></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"><span class="std std-ref">modules</span></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 <cite>-print-stats</cite> 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 <code class="docutils literal"><span class="pre">Cocoa.h</span></code> 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><span></span>*** 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"><span class="std std-ref">later
+section</span></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 <code class="docutils literal"><span class="pre">clangast</span></code>
+(COFF) or <code class="docutils literal"><span class="pre">__clangast</span></code> (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 <code class="docutils literal"><span class="pre">clangast</span></code> 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 <code class="docutils literal"><span class="pre">llvm-objdump</span></code> utility provides a <code class="docutils literal"><span class="pre">-raw-clang-ast</span></code> 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 “<code class="docutils literal"><span class="pre">//</span></code>” comments). The contents of this record correspond to
+the <code class="docutils literal"><span class="pre">LangOptions</span></code> 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., <code class="docutils literal"><span class="pre">i386-apple-darwin9</span></code>.</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 “<code class="docutils literal"><span class="pre">#define</span> <span class="pre">__STDC__</span> <span class="pre">1</span></code>” when we
+are compiling C without Microsoft extensions. The predefines buffer itself
+is stored within the <a class="reference internal" href="#pchinternals-sourcemgr"><span class="std std-ref">Source Manager Block</span></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"><span class="std std-ref">SourceManager</span></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
+<code class="docutils literal"><span class="pre">LLVM_CLANG_SOURCEMANAGER_H</span></code>).</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"><span class="std std-ref">identifier table</span></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 (<code class="docutils literal"><span class="pre">PointerType</span></code>,
+<code class="docutils literal"><span class="pre">FunctionProtoType</span></code>, 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
+<code class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></code> represent predefined types (<code class="docutils literal"><span class="pre">void</span></code>, <code class="docutils literal"><span class="pre">float</span></code>, etc.),
+while other “user-defined” type IDs are assigned consecutively from
+<code class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></code> 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 <code class="docutils literal"><span class="pre">const</span></code>, <code class="docutils literal"><span class="pre">volatile</span></code>,
+and <code class="docutils literal"><span class="pre">restrict</span></code> qualifiers, as in Clang’s <a class="reference internal" href="InternalsManual.html#qualtype"><span class="std std-ref">QualType</span></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
+(<code class="docutils literal"><span class="pre">VarDecl</span></code>, <code class="docutils literal"><span class="pre">FunctionDecl</span></code>, 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 <code class="docutils literal"><span class="pre">Decl</span></code> 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 (<code class="docutils literal"><span class="pre">TranslationUnitDecl</span></code>),
+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"><span class="std std-ref">declaration
+context</span></a>, as represented by the <code class="docutils literal"><span class="pre">DeclContext</span></code> class.
+Declaration contexts provide the mechanism to perform name lookup within a
+given declaration (e.g., find the member named <code class="docutils literal"><span class="pre">x</span></code> 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
+<code class="docutils literal"><span class="pre">DeclContext</span></code> 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 <code class="docutils literal"><span class="pre">x</span></code> within a given
+declaration context (for example, during semantic analysis of the expression
+<code class="docutils literal"><span class="pre">p->x</span></code>, where <code class="docutils literal"><span class="pre">p</span></code>‘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"><span class="std std-ref">types</span></a> and the <a class="reference internal" href="#pchinternals-decls"><span class="std std-ref">declarations</span></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 (<code class="docutils literal"><span class="pre">ForStmt</span></code>, <code class="docutils literal"><span class="pre">CallExpr</span></code>, 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 <code 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></code> would be represented as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="100%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">IntegerLiteral(5)</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">IntegerLiteral(4)</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">IntegerLiteral(3)</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">IntegerLiteral(-)</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">IntegerLiteral(+)</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">STOP</span></code></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 —
+<code class="docutils literal"><span class="pre">BinaryOperator</span></code> 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 <code class="docutils literal"><span class="pre">IdentifierInfo</span></code> 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"><span class="std std-ref">Preprocessor Block</span></a>.</li>
+<li>If the identifier names one or more declarations visible from translation
+unit scope, the <a class="reference internal" href="#pchinternals-decls"><span class="std std-ref">declaration IDs</span></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 <code class="docutils literal"><span class="pre">IdentifierInfo</span></code> 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"><span class="std std-ref">identifier table</span></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
+(<code class="docutils literal"><span class="pre">Sema::InstanceMethodPool</span></code> and <code class="docutils literal"><span class="pre">Sema::FactoryMethodPool</span></code> 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 <code class="docutils literal"><span class="pre">ASTReader</span></code> 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. <code class="docutils literal"><span class="pre">ASTReader</span></code> implements the
+following abstract classes:</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">ExternalSLocEntrySource</span></code></dt>
+<dd>This abstract interface is associated with the <code class="docutils literal"><span class="pre">SourceManager</span></code> class, and
+is used whenever the <a class="reference internal" href="#pchinternals-sourcemgr"><span class="std std-ref">source manager</span></a> needs to
+load the details of a file, buffer, or macro instantiation.</dd>
+<dt><code class="docutils literal"><span class="pre">IdentifierInfoLookup</span></code></dt>
+<dd>This abstract interface is associated with the <code class="docutils literal"><span class="pre">IdentifierTable</span></code> 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"><span class="std std-ref">identifier table</span></a> to load any top-level
+declarations or macros associated with that identifier.</dd>
+<dt><code class="docutils literal"><span class="pre">ExternalASTSource</span></code></dt>
+<dd>This abstract interface is associated with the <code class="docutils literal"><span class="pre">ASTContext</span></code> 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><code class="docutils literal"><span class="pre">ExternalSemaSource</span></code></dt>
+<dd>This abstract interface is associated with the <code class="docutils literal"><span class="pre">Sema</span></code> class, and is used
+whenever semantic analysis needs to read information from the <a class="reference internal" href="#pchinternals-method-pool"><span class="std std-ref">global
+method pool</span></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
+<code class="docutils literal"><span class="pre">#include</span></code>. 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 <code class="docutils literal"><span class="pre">#include</span></code>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
+<code class="docutils literal"><span class="pre">B.h</span></code> that includes another header <code class="docutils literal"><span class="pre">A.h</span></code> can modify the state produced by
+parsing <code class="docutils literal"><span class="pre">A.h</span></code>, e.g., by <code class="docutils literal"><span class="pre">#undef</span></code>‘ing a macro defined in <code class="docutils literal"><span class="pre">A.h</span></code>.</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"><span class="std std-ref">identifier table</span></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 <code class="docutils literal"><span class="pre">printf</span></code> or could forward-declare
+<code class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></code>. 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 <code class="docutils literal"><span class="pre">printf</span></code> or <code class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></code> 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" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ItaniumMangleAbiTags.html">ABI tags</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/PTHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/PTHInternals.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/PTHInternals.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/PTHInternals.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,216 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Precompiled Header and Modules Internals" href="PCHInternals.html" />
+ <link rel="prev" title="Driver Design & Internals" href="DriverInternals.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Pretokenized Headers (PTH)</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <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"><span class="std std-ref">User’s Manual</span></a>.</p>
+<div class="section" id="using-pretokenized-headers-with-clang-low-level-interface">
+<h2>Using Pretokenized Headers with <code class="docutils literal"><span class="pre">clang</span></code> (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, <code class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></code>, supports three command line
+options for generating and using PTH files.</p>
+<p>To generate PTH files using <code class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></code>, use the option <code class="docutils literal"><span class="pre">-emit-pth</span></code>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -cc1 test.h -emit-pth -o test.h.pth
+</pre></div>
+</div>
+<p>This option is transparently used by <code class="docutils literal"><span class="pre">clang</span></code> when generating PTH
+files. Similarly, PTH files can be used as prefix headers using the
+<code class="docutils literal"><span class="pre">-include-pth</span></code> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></code> to process a
+source file. This is done by specifying the <code class="docutils literal"><span class="pre">-token-cache</span></code> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">stdio.h</span></code> (and the files it includes)
+will be retrieved from <code class="docutils literal"><span class="pre">test.h.pth</span></code>, as the PTH file is being used in
+this case as a raw cache of the contents of <code class="docutils literal"><span class="pre">test.h</span></code>. 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., <code class="docutils literal"><span class="pre">mmap</span></code>). Clang, however,
+memory maps PTH files as read-only, meaning that multiple invocations
+of <code class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></code> 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><code class="docutils literal"><span class="pre">stat</span></code> caching: PTH files cache information obtained via calls to
+<code class="docutils literal"><span class="pre">stat</span></code> that <code class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></code> uses to resolve which files are included
+by <code class="docutils literal"><span class="pre">#include</span></code> directives. This greatly reduces the overhead
+involved in context-switching to the kernel to resolve included
+files.</li>
+<li>Fast skipping of <code class="docutils literal"><span class="pre">#ifdef</span></code> ... <code class="docutils literal"><span class="pre">#endif</span></code> 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" role="navigation" aria-label="bottom navigation">
+
+ <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" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/RAVFrontendAction.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/RAVFrontendAction.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/RAVFrontendAction.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/RAVFrontendAction.html Thu Mar 8 02:24:44 2018
@@ -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>How to write RecursiveASTVisitor based ASTFrontendActions. — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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 role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>How to write RecursiveASTVisitor based ASTFrontendActions.</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <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-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">FindNamedClassAction</span> <span class="p">:</span> <span class="n">public</span> <span class="n">clang</span><span class="p">::</span><span class="n">ASTFrontendAction</span> <span class="p">{</span>
+<span class="n">public</span><span class="p">:</span>
+ <span class="n">virtual</span> <span class="n">std</span><span class="p">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">clang</span><span class="p">::</span><span class="n">ASTConsumer</span><span class="o">></span> <span class="n">CreateASTConsumer</span><span class="p">(</span>
+ <span class="n">clang</span><span class="p">::</span><span class="n">CompilerInstance</span> <span class="o">&</span><span class="n">Compiler</span><span class="p">,</span> <span class="n">llvm</span><span class="p">::</span><span class="n">StringRef</span> <span class="n">InFile</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">std</span><span class="p">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">clang</span><span class="p">::</span><span class="n">ASTConsumer</span><span class="o">></span><span class="p">(</span>
+ <span class="n">new</span> <span class="n">FindNamedClassConsumer</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</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-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">FindNamedClassConsumer</span> <span class="p">:</span> <span class="n">public</span> <span class="n">clang</span><span class="p">::</span><span class="n">ASTConsumer</span> <span class="p">{</span>
+<span class="n">public</span><span class="p">:</span>
+ <span class="n">virtual</span> <span class="n">void</span> <span class="n">HandleTranslationUnit</span><span class="p">(</span><span class="n">clang</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="p">{</span>
+ <span class="o">//</span> <span class="n">Traversing</span> <span class="n">the</span> <span class="n">translation</span> <span class="n">unit</span> <span class="n">decl</span> <span class="n">via</span> <span class="n">a</span> <span class="n">RecursiveASTVisitor</span>
+ <span class="o">//</span> <span class="n">will</span> <span class="n">visit</span> <span class="nb">all</span> <span class="n">nodes</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">AST</span><span class="o">.</span>
+ <span class="n">Visitor</span><span class="o">.</span><span class="n">TraverseDecl</span><span class="p">(</span><span class="n">Context</span><span class="o">.</span><span class="n">getTranslationUnitDecl</span><span class="p">());</span>
+ <span class="p">}</span>
+<span class="n">private</span><span class="p">:</span>
+ <span class="o">//</span> <span class="n">A</span> <span class="n">RecursiveASTVisitor</span> <span class="n">implementation</span><span class="o">.</span>
+ <span class="n">FindNamedClassVisitor</span> <span class="n">Visitor</span><span class="p">;</span>
+<span class="p">};</span>
+</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-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">FindNamedClassVisitor</span>
+ <span class="p">:</span> <span class="n">public</span> <span class="n">RecursiveASTVisitor</span><span class="o"><</span><span class="n">FindNamedClassVisitor</span><span class="o">></span> <span class="p">{</span>
+<span class="n">public</span><span class="p">:</span>
+ <span class="nb">bool</span> <span class="n">VisitCXXRecordDecl</span><span class="p">(</span><span class="n">CXXRecordDecl</span> <span class="o">*</span><span class="n">Declaration</span><span class="p">)</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">For</span> <span class="n">debugging</span><span class="p">,</span> <span class="n">dumping</span> <span class="n">the</span> <span class="n">AST</span> <span class="n">nodes</span> <span class="n">will</span> <span class="n">show</span> <span class="n">which</span> <span class="n">nodes</span> <span class="n">are</span> <span class="n">already</span>
+ <span class="o">//</span> <span class="n">being</span> <span class="n">visited</span><span class="o">.</span>
+ <span class="n">Declaration</span><span class="o">-></span><span class="n">dump</span><span class="p">();</span>
+
+ <span class="o">//</span> <span class="n">The</span> <span class="k">return</span> <span class="n">value</span> <span class="n">indicates</span> <span class="n">whether</span> <span class="n">we</span> <span class="n">want</span> <span class="n">the</span> <span class="n">visitation</span> <span class="n">to</span> <span class="n">proceed</span><span class="o">.</span>
+ <span class="o">//</span> <span class="n">Return</span> <span class="n">false</span> <span class="n">to</span> <span class="n">stop</span> <span class="n">the</span> <span class="n">traversal</span> <span class="n">of</span> <span class="n">the</span> <span class="n">AST</span><span class="o">.</span>
+ <span class="k">return</span> <span class="n">true</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</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-default"><div class="highlight"><pre><span></span><span class="nb">bool</span> <span class="n">VisitCXXRecordDecl</span><span class="p">(</span><span class="n">CXXRecordDecl</span> <span class="o">*</span><span class="n">Declaration</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Declaration</span><span class="o">-></span><span class="n">getQualifiedNameAsString</span><span class="p">()</span> <span class="o">==</span> <span class="s2">"n::m::C"</span><span class="p">)</span>
+ <span class="n">Declaration</span><span class="o">-></span><span class="n">dump</span><span class="p">();</span>
+ <span class="k">return</span> <span class="n">true</span><span class="p">;</span>
+<span class="p">}</span>
+</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-default"><div class="highlight"><pre><span></span><span class="n">virtual</span> <span class="n">std</span><span class="p">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">clang</span><span class="p">::</span><span class="n">ASTConsumer</span><span class="o">></span> <span class="n">CreateASTConsumer</span><span class="p">(</span>
+ <span class="n">clang</span><span class="p">::</span><span class="n">CompilerInstance</span> <span class="o">&</span><span class="n">Compiler</span><span class="p">,</span> <span class="n">llvm</span><span class="p">::</span><span class="n">StringRef</span> <span class="n">InFile</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">std</span><span class="p">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">clang</span><span class="p">::</span><span class="n">ASTConsumer</span><span class="o">></span><span class="p">(</span>
+ <span class="n">new</span> <span class="n">FindNamedClassConsumer</span><span class="p">(</span><span class="o">&</span><span class="n">Compiler</span><span class="o">.</span><span class="n">getASTContext</span><span class="p">()));</span>
+<span class="p">}</span>
+</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-default"><div class="highlight"><pre><span></span><span class="nb">bool</span> <span class="n">VisitCXXRecordDecl</span><span class="p">(</span><span class="n">CXXRecordDecl</span> <span class="o">*</span><span class="n">Declaration</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Declaration</span><span class="o">-></span><span class="n">getQualifiedNameAsString</span><span class="p">()</span> <span class="o">==</span> <span class="s2">"n::m::C"</span><span class="p">)</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">getFullLoc</span> <span class="n">uses</span> <span class="n">the</span> <span class="n">ASTContext</span><span class="s1">'s SourceManager to resolve the source</span>
+ <span class="o">//</span> <span class="n">location</span> <span class="ow">and</span> <span class="k">break</span> <span class="n">it</span> <span class="n">up</span> <span class="n">into</span> <span class="n">its</span> <span class="n">line</span> <span class="ow">and</span> <span class="n">column</span> <span class="n">parts</span><span class="o">.</span>
+ <span class="n">FullSourceLoc</span> <span class="n">FullLocation</span> <span class="o">=</span> <span class="n">Context</span><span class="o">-></span><span class="n">getFullLoc</span><span class="p">(</span><span class="n">Declaration</span><span class="o">-></span><span class="n">getLocStart</span><span class="p">());</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">FullLocation</span><span class="o">.</span><span class="n">isValid</span><span class="p">())</span>
+ <span class="n">llvm</span><span class="p">::</span><span class="n">outs</span><span class="p">()</span> <span class="o"><<</span> <span class="s2">"Found declaration at "</span>
+ <span class="o"><<</span> <span class="n">FullLocation</span><span class="o">.</span><span class="n">getSpellingLineNumber</span><span class="p">()</span> <span class="o"><<</span> <span class="s2">":"</span>
+ <span class="o"><<</span> <span class="n">FullLocation</span><span class="o">.</span><span class="n">getSpellingColumnNumber</span><span class="p">()</span> <span class="o"><<</span> <span class="s2">"</span><span class="se">\n</span><span class="s2">"</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="n">true</span><span class="p">;</span>
+<span class="p">}</span>
+</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-default"><div class="highlight"><pre><span></span><span class="c1">#include "clang/AST/ASTConsumer.h"</span>
+<span class="c1">#include "clang/AST/RecursiveASTVisitor.h"</span>
+<span class="c1">#include "clang/Frontend/CompilerInstance.h"</span>
+<span class="c1">#include "clang/Frontend/FrontendAction.h"</span>
+<span class="c1">#include "clang/Tooling/Tooling.h"</span>
+
+<span class="n">using</span> <span class="n">namespace</span> <span class="n">clang</span><span class="p">;</span>
+
+<span class="k">class</span> <span class="nc">FindNamedClassVisitor</span>
+ <span class="p">:</span> <span class="n">public</span> <span class="n">RecursiveASTVisitor</span><span class="o"><</span><span class="n">FindNamedClassVisitor</span><span class="o">></span> <span class="p">{</span>
+<span class="n">public</span><span class="p">:</span>
+ <span class="n">explicit</span> <span class="n">FindNamedClassVisitor</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="p">:</span> <span class="n">Context</span><span class="p">(</span><span class="n">Context</span><span class="p">)</span> <span class="p">{}</span>
+
+ <span class="nb">bool</span> <span class="n">VisitCXXRecordDecl</span><span class="p">(</span><span class="n">CXXRecordDecl</span> <span class="o">*</span><span class="n">Declaration</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Declaration</span><span class="o">-></span><span class="n">getQualifiedNameAsString</span><span class="p">()</span> <span class="o">==</span> <span class="s2">"n::m::C"</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">FullSourceLoc</span> <span class="n">FullLocation</span> <span class="o">=</span> <span class="n">Context</span><span class="o">-></span><span class="n">getFullLoc</span><span class="p">(</span><span class="n">Declaration</span><span class="o">-></span><span class="n">getLocStart</span><span class="p">());</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">FullLocation</span><span class="o">.</span><span class="n">isValid</span><span class="p">())</span>
+ <span class="n">llvm</span><span class="p">::</span><span class="n">outs</span><span class="p">()</span> <span class="o"><<</span> <span class="s2">"Found declaration at "</span>
+ <span class="o"><<</span> <span class="n">FullLocation</span><span class="o">.</span><span class="n">getSpellingLineNumber</span><span class="p">()</span> <span class="o"><<</span> <span class="s2">":"</span>
+ <span class="o"><<</span> <span class="n">FullLocation</span><span class="o">.</span><span class="n">getSpellingColumnNumber</span><span class="p">()</span> <span class="o"><<</span> <span class="s2">"</span><span class="se">\n</span><span class="s2">"</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="n">true</span><span class="p">;</span>
+ <span class="p">}</span>
+
+<span class="n">private</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="p">};</span>
+
+<span class="k">class</span> <span class="nc">FindNamedClassConsumer</span> <span class="p">:</span> <span class="n">public</span> <span class="n">clang</span><span class="p">::</span><span class="n">ASTConsumer</span> <span class="p">{</span>
+<span class="n">public</span><span class="p">:</span>
+ <span class="n">explicit</span> <span class="n">FindNamedClassConsumer</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="p">:</span> <span class="n">Visitor</span><span class="p">(</span><span class="n">Context</span><span class="p">)</span> <span class="p">{}</span>
+
+ <span class="n">virtual</span> <span class="n">void</span> <span class="n">HandleTranslationUnit</span><span class="p">(</span><span class="n">clang</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="p">{</span>
+ <span class="n">Visitor</span><span class="o">.</span><span class="n">TraverseDecl</span><span class="p">(</span><span class="n">Context</span><span class="o">.</span><span class="n">getTranslationUnitDecl</span><span class="p">());</span>
+ <span class="p">}</span>
+<span class="n">private</span><span class="p">:</span>
+ <span class="n">FindNamedClassVisitor</span> <span class="n">Visitor</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">FindNamedClassAction</span> <span class="p">:</span> <span class="n">public</span> <span class="n">clang</span><span class="p">::</span><span class="n">ASTFrontendAction</span> <span class="p">{</span>
+<span class="n">public</span><span class="p">:</span>
+ <span class="n">virtual</span> <span class="n">std</span><span class="p">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">clang</span><span class="p">::</span><span class="n">ASTConsumer</span><span class="o">></span> <span class="n">CreateASTConsumer</span><span class="p">(</span>
+ <span class="n">clang</span><span class="p">::</span><span class="n">CompilerInstance</span> <span class="o">&</span><span class="n">Compiler</span><span class="p">,</span> <span class="n">llvm</span><span class="p">::</span><span class="n">StringRef</span> <span class="n">InFile</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">std</span><span class="p">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">clang</span><span class="p">::</span><span class="n">ASTConsumer</span><span class="o">></span><span class="p">(</span>
+ <span class="n">new</span> <span class="n">FindNamedClassConsumer</span><span class="p">(</span><span class="o">&</span><span class="n">Compiler</span><span class="o">.</span><span class="n">getASTContext</span><span class="p">()));</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="nb">int</span> <span class="n">main</span><span class="p">(</span><span class="nb">int</span> <span class="n">argc</span><span class="p">,</span> <span class="n">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">argc</span> <span class="o">></span> <span class="mi">1</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">clang</span><span class="p">::</span><span class="n">tooling</span><span class="p">::</span><span class="n">runToolOnCode</span><span class="p">(</span><span class="n">new</span> <span class="n">FindNamedClassAction</span><span class="p">,</span> <span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">]);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</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-default"><div class="highlight"><pre><span></span><span class="n">add_clang_executable</span><span class="p">(</span><span class="n">find</span><span class="o">-</span><span class="n">class</span><span class="o">-</span><span class="n">decls</span> <span class="n">FindClassDecls</span><span class="o">.</span><span class="n">cpp</span><span class="p">)</span>
+
+<span class="n">target_link_libraries</span><span class="p">(</span><span class="n">find</span><span class="o">-</span><span class="n">class</span><span class="o">-</span><span class="n">decls</span> <span class="n">clangTooling</span><span class="p">)</span>
+</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-default"><div class="highlight"><pre><span></span>$ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }"
+Found declaration at 1:29
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <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" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/RefactoringEngine.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/RefactoringEngine.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/RefactoringEngine.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/RefactoringEngine.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,294 @@
+<!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âs refactoring engine — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Overview" href="ClangTools.html" />
+ <link rel="prev" title="JSON Compilation Database Format Specification" href="JSONCompilationDatabase.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Clangâs refactoring engine</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ClangTools.html">Overview</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="clang-s-refactoring-engine">
+<h1>Clang’s refactoring engine<a class="headerlink" href="#clang-s-refactoring-engine" title="Permalink to this headline">¶</a></h1>
+<p>This document describes the design of Clang’s refactoring engine and provides
+a couple of examples that show how various primitives in the refactoring API
+can be used to implement different refactoring actions. The <a class="reference internal" href="LibTooling.html"><span class="doc">LibTooling</span></a>
+library provides several other APIs that are used when developing a
+refactoring action.</p>
+<p>Refactoring engine can be used to implement local refactorings that are
+initiated using a selection in an editor or an IDE. You can combine
+<a class="reference internal" href="LibASTMatchers.html"><span class="doc">AST matchers</span></a> and the refactoring engine to implement
+refactorings that don’t lend themselves well to source selection and/or have to
+query ASTs for some particular nodes.</p>
+<p>We assume basic knowledge about the Clang AST. See the <a class="reference internal" href="IntroductionToTheClangAST.html"><span class="doc">Introduction
+to the Clang AST</span></a> if you want to learn more
+about how the AST is structured.</p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang’s refactoring engine defines a set refactoring actions that implement
+a number of different source transformations. The <code class="docutils literal"><span class="pre">clang-refactor</span></code>
+command-line tool can be used to perform these refactorings. Certain
+refactorings are also available in other clients like text editors and IDEs.</p>
+<p>A refactoring action is a class that defines a list of related refactoring
+operations (rules). These rules are grouped under a common umbrella - a single
+<code class="docutils literal"><span class="pre">clang-refactor</span></code> command. In addition to rules, the refactoring action
+provides the action’s command name and description to <code class="docutils literal"><span class="pre">clang-refactor</span></code>.
+Each action must implement the <code class="docutils literal"><span class="pre">RefactoringAction</span></code> interface. Here’s an
+outline of a <code class="docutils literal"><span class="pre">local-rename</span></code> action:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">LocalRename</span> <span class="k">final</span> <span class="o">:</span> <span class="k">public</span> <span class="n">RefactoringAction</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">StringRef</span> <span class="n">getCommand</span><span class="p">()</span> <span class="k">const</span> <span class="k">override</span> <span class="p">{</span> <span class="k">return</span> <span class="s">"local-rename"</span><span class="p">;</span> <span class="p">}</span>
+
+ <span class="n">StringRef</span> <span class="n">getDescription</span><span class="p">()</span> <span class="k">const</span> <span class="k">override</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="s">"Finds and renames symbols in code with no indexer support"</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">RefactoringActionRules</span> <span class="n">createActionRules</span><span class="p">()</span> <span class="k">const</span> <span class="k">override</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="refactoring-action-rules">
+<h2>Refactoring Action Rules<a class="headerlink" href="#refactoring-action-rules" title="Permalink to this headline">¶</a></h2>
+<p>An individual refactoring action is responsible for creating the set of
+grouped refactoring action rules that represent one refactoring operation.
+Although the rules in one action may have a number of different implementations,
+they should strive to produce a similar result. It should be easy for users to
+identify which refactoring action produced the result regardless of which
+refactoring action rule was used.</p>
+<p>The distinction between actions and rules enables the creation of actions
+that define a set of different rules that produce similar results. For example,
+the “add missing switch cases” refactoring operation typically adds missing
+cases to one switch at a time. However, it could be useful to have a
+refactoring that works on all switches that operate on a particular enum, as
+one could then automatically update all of them after adding a new enum
+constant. To achieve that, we can create two different rules that will use one
+<code class="docutils literal"><span class="pre">clang-refactor</span></code> subcommand. The first rule will describe a local operation
+that’s initiated when the user selects a single switch. The second rule will
+describe a global operation that works across translation units and is initiated
+when the user provides the name of the enum to clang-refactor (or the user could
+select the enum declaration instead). The clang-refactor tool will then analyze
+the selection and other options passed to the refactoring action, and will pick
+the most appropriate rule for the given selection and other options.</p>
+<div class="section" id="rule-types">
+<h3>Rule Types<a class="headerlink" href="#rule-types" title="Permalink to this headline">¶</a></h3>
+<p>Clang’s refactoring engine supports several different refactoring rules:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">SourceChangeRefactoringRule</span></code> produces source replacements that are applied
+to the source files. Subclasses that choose to implement this rule have to
+implement the <code class="docutils literal"><span class="pre">createSourceReplacements</span></code> member function. This type of
+rule is typically used to implement local refactorings that transform the
+source in one translation unit only.</li>
+<li><code class="docutils literal"><span class="pre">FindSymbolOccurrencesRefactoringRule</span></code> produces a “partial” refactoring
+result: a set of occurrences that refer to a particular symbol. This type
+of rule is typically used to implement an interactive renaming action that
+allows users to specify which occurrences should be renamed during the
+refactoring. Subclasses that choose to implement this rule have to implement
+the <code class="docutils literal"><span class="pre">findSymbolOccurrences</span></code> member function.</li>
+</ul>
+<p>The following set of quick checks might help if you are unsure about the type
+of rule you should use:</p>
+<ol class="arabic simple">
+<li>If you would like to transform the source in one translation unit and if
+you don’t need any cross-TU information, then the
+<code class="docutils literal"><span class="pre">SourceChangeRefactoringRule</span></code> should work for you.</li>
+<li>If you would like to implement a rename-like operation with potential
+interactive components, then <code class="docutils literal"><span class="pre">FindSymbolOccurrencesRefactoringRule</span></code> might
+work for you.</li>
+</ol>
+</div>
+<div class="section" id="how-to-create-a-rule">
+<h3>How to Create a Rule<a class="headerlink" href="#how-to-create-a-rule" title="Permalink to this headline">¶</a></h3>
+<p>Once you determine which type of rule is suitable for your needs you can
+implement the refactoring by subclassing the rule and implementing its
+interface. The subclass should have a constructor that takes the inputs that
+are needed to perform the refactoring. For example, if you want to implement a
+rule that simply deletes a selection, you should create a subclass of
+<code class="docutils literal"><span class="pre">SourceChangeRefactoringRule</span></code> with a constructor that accepts the selection
+range:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">DeleteSelectedRange</span> <span class="k">final</span> <span class="o">:</span> <span class="k">public</span> <span class="n">SourceChangeRefactoringRule</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">DeleteSelection</span><span class="p">(</span><span class="n">SourceRange</span> <span class="n">Selection</span><span class="p">)</span> <span class="o">:</span> <span class="n">Selection</span><span class="p">(</span><span class="n">Selection</span><span class="p">)</span> <span class="p">{}</span>
+
+ <span class="n">Expected</span><span class="o"><</span><span class="n">AtomicChanges</span><span class="o">></span>
+ <span class="n">createSourceReplacements</span><span class="p">(</span><span class="n">RefactoringRuleContext</span> <span class="o">&</span><span class="n">Context</span><span class="p">)</span> <span class="k">override</span> <span class="p">{</span>
+ <span class="n">AtomicChange</span> <span class="n">Replacement</span><span class="p">(</span><span class="n">Context</span><span class="p">.</span><span class="n">getSources</span><span class="p">(),</span> <span class="n">Selection</span><span class="p">.</span><span class="n">getBegin</span><span class="p">());</span>
+ <span class="n">Replacement</span><span class="p">.</span><span class="n">replace</span><span class="p">(</span><span class="n">Context</span><span class="p">.</span><span class="n">getSource</span><span class="p">,</span>
+ <span class="n">CharSourceRange</span><span class="o">::</span><span class="n">getCharRange</span><span class="p">(</span><span class="n">Selection</span><span class="p">),</span> <span class="s">""</span><span class="p">);</span>
+ <span class="k">return</span> <span class="p">{</span> <span class="n">Replacement</span> <span class="p">};</span>
+ <span class="p">}</span>
+<span class="k">private</span><span class="o">:</span>
+ <span class="n">SourceRange</span> <span class="n">Selection</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The rule’s subclass can then be added to the list of refactoring action’s
+rules for a particular action using the <code class="docutils literal"><span class="pre">createRefactoringActionRule</span></code>
+function. For example, the class that’s shown above can be added to the
+list of action rules using the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">RefactoringActionRules</span> <span class="n">Rules</span><span class="p">;</span>
+<span class="n">Rules</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span>
+ <span class="n">createRefactoringActionRule</span><span class="o"><</span><span class="n">DeleteSelectedRange</span><span class="o">></span><span class="p">(</span>
+ <span class="n">SourceRangeSelectionRequirement</span><span class="p">())</span>
+<span class="p">);</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal"><span class="pre">createRefactoringActionRule</span></code> function takes in a list of refactoring
+action rule requirement values. These values describe the initiation
+requirements that have to be satisfied by the refactoring engine before the
+provided action rule can be constructed and invoked. The next section
+describes how these requirements are evaluated and lists all the possible
+requirements that can be used to construct a refactoring action rule.</p>
+</div>
+</div>
+<div class="section" id="refactoring-action-rule-requirements">
+<h2>Refactoring Action Rule Requirements<a class="headerlink" href="#refactoring-action-rule-requirements" title="Permalink to this headline">¶</a></h2>
+<p>A refactoring action rule requirement is a value whose type derives from the
+<code class="docutils literal"><span class="pre">RefactoringActionRuleRequirement</span></code> class. The type must define an
+<code class="docutils literal"><span class="pre">evaluate</span></code> member function that returns a value of type <code class="docutils literal"><span class="pre">Expected<...></span></code>.
+When a requirement value is used as an argument to
+<code class="docutils literal"><span class="pre">createRefactoringActionRule</span></code>, that value is evaluated during the initiation
+of the action rule. The evaluated result is then passed to the rule’s
+constructor unless the evaluation produced an error. For example, the
+<code class="docutils literal"><span class="pre">DeleteSelectedRange</span></code> sample rule that’s defined in the previous section
+will be evaluated using the following steps:</p>
+<ol class="arabic simple">
+<li><code class="docutils literal"><span class="pre">SourceRangeSelectionRequirement</span></code>‘s <code class="docutils literal"><span class="pre">evaluate</span></code> member function will be
+called first. It will return an <code class="docutils literal"><span class="pre">Expected<SourceRange></span></code>.</li>
+<li>If the return value is an error the initiation will fail and the error
+will be reported to the client. Note that the client may not report the
+error to the user.</li>
+<li>Otherwise the source range return value will be used to construct the
+<code class="docutils literal"><span class="pre">DeleteSelectedRange</span></code> rule. The rule will then be invoked as the initiation
+succeeded (all requirements were evaluated successfully).</li>
+</ol>
+<p>The same series of steps applies to any refactoring rule. Firstly, the engine
+will evaluate all of the requirements. Then it will check if these requirements
+are satisfied (they should not produce an error). Then it will construct the
+rule and invoke it.</p>
+<p>The separation of requirements, their evaluation and the invocation of the
+refactoring action rule allows the refactoring clients to:</p>
+<ul class="simple">
+<li>Disable refactoring action rules whose requirements are not supported.</li>
+<li>Gather the set of options and define a command-line / visual interface
+that allows users to input these options without ever invoking the
+action.</li>
+</ul>
+<div class="section" id="selection-requirements">
+<h3>Selection Requirements<a class="headerlink" href="#selection-requirements" title="Permalink to this headline">¶</a></h3>
+<p>The refactoring rule requirements that require some form of source selection
+are listed below:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">SourceRangeSelectionRequirement</span></code> evaluates to a source range when the
+action is invoked with some sort of selection. This requirement should be
+satisfied when a refactoring is initiated in an editor, even when the user
+has not selected anything (the range will contain the cursor’s location in
+that case).</li>
+</ul>
+</div>
+<div class="section" id="other-requirements">
+<h3>Other Requirements<a class="headerlink" href="#other-requirements" title="Permalink to this headline">¶</a></h3>
+<p>There are several other requirements types that can be used when creating
+a refactoring rule:</p>
+<ul class="simple">
+<li>The <code class="docutils literal"><span class="pre">RefactoringOptionsRequirement</span></code> requirement is an abstract class that
+should be subclassed by requirements working with options. The more
+concrete <code class="docutils literal"><span class="pre">OptionRequirement</span></code> requirement is a simple implementation of the
+aforementioned class that returns the value of the specified option when
+it’s evaluated. The next section talks more about refactoring options and
+how they can be used when creating a rule.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="refactoring-options">
+<h2>Refactoring Options<a class="headerlink" href="#refactoring-options" title="Permalink to this headline">¶</a></h2>
+<p>Refactoring options are values that affect a refactoring operation and are
+specified either using command-line options or another client-specific
+mechanism. Options should be created using a class that derives either from
+the <code class="docutils literal"><span class="pre">OptionalRequiredOption</span></code> or <code class="docutils literal"><span class="pre">RequiredRefactoringOption</span></code>. The following
+example shows how one can created a required string option that corresponds to
+the <code class="docutils literal"><span class="pre">-new-name</span></code> command-line option in clang-refactor:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">NewNameOption</span> <span class="o">:</span> <span class="k">public</span> <span class="n">RequiredRefactoringOption</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="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">StringRef</span> <span class="n">getName</span><span class="p">()</span> <span class="k">const</span> <span class="k">override</span> <span class="p">{</span> <span class="k">return</span> <span class="s">"new-name"</span><span class="p">;</span> <span class="p">}</span>
+ <span class="n">StringRef</span> <span class="n">getDescription</span><span class="p">()</span> <span class="k">const</span> <span class="k">override</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="s">"The new name to change the symbol to"</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The option that’s shown in the example above can then be used to create
+a requirement for a refactoring rule using a requirement like
+<code class="docutils literal"><span class="pre">OptionRequirement</span></code>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">createRefactoringActionRule</span><span class="o"><</span><span class="n">RenameOccurrences</span><span class="o">></span><span class="p">(</span>
+ <span class="p">...,</span>
+ <span class="n">OptionRequirement</span><span class="o"><</span><span class="n">NewNameOption</span><span class="o">></span><span class="p">())</span>
+<span class="p">);</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ClangTools.html">Overview</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/ReleaseNotes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/ReleaseNotes.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/ReleaseNotes.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/ReleaseNotes.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,471 @@
+<!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 6.0.0 Release Notes — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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 role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Clang 6.0.0 Release Notes</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <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-6-0-0-release-notes">
+<h1>Clang 6.0.0 Release Notes<a class="headerlink" href="#clang-6-0-0-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="id2">Introduction</a></li>
+<li><a class="reference internal" href="#what-s-new-in-clang-6-0-0" id="id3">What’s New in Clang 6.0.0?</a><ul>
+<li><a class="reference internal" href="#non-comprehensive-list-of-changes-in-this-release" id="id4">Non-comprehensive list of changes in this release</a></li>
+<li><a class="reference internal" href="#improvements-to-clang-s-diagnostics" id="id5">Improvements to Clang’s diagnostics</a></li>
+<li><a class="reference internal" href="#new-compiler-flags" id="id6">New Compiler Flags</a></li>
+<li><a class="reference internal" href="#attribute-changes-in-clang" id="id7">Attribute Changes in Clang</a></li>
+<li><a class="reference internal" href="#windows-support" id="id8">Windows Support</a></li>
+<li><a class="reference internal" href="#c-language-changes-in-clang" id="id9">C++ Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#opencl-c-language-changes-in-clang" id="id10">OpenCL C Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#openmp-support-in-clang" id="id11">OpenMP Support in Clang</a></li>
+<li><a class="reference internal" href="#ast-matchers" id="id12">AST Matchers</a></li>
+<li><a class="reference internal" href="#clang-format" id="id13">clang-format</a></li>
+<li><a class="reference internal" href="#static-analyzer" id="id14">Static Analyzer</a></li>
+<li><a class="reference internal" href="#undefined-behavior-sanitizer-ubsan" id="id15">Undefined Behavior Sanitizer (UBSan)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-information" id="id16">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="#id2">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 6.0.0. 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 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-6-0-0">
+<h2><a class="toc-backref" href="#id3">What’s New in Clang 6.0.0?</a><a class="headerlink" href="#what-s-new-in-clang-6-0-0" 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="non-comprehensive-list-of-changes-in-this-release">
+<h3><a class="toc-backref" href="#id4">Non-comprehensive list of changes in this release</a><a class="headerlink" href="#non-comprehensive-list-of-changes-in-this-release" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Support for <a class="reference external" href="https://support.google.com/faqs/answer/7625886">retpolines</a>
+was added to help mitigate “branch target injection” (variant #2) of the
+“Spectre” speculative side channels described by <a class="reference external" href="https://googleprojectzero.blogspot.com/2018/01/reading-privileged-memory-with-side.html">Project Zero</a>
+and the <a class="reference external" href="https://spectreattack.com/spectre.pdf">Spectre paper</a>.</li>
+<li>Bitrig OS was merged back into OpenBSD, so Bitrig support has been
+removed from Clang/LLVM.</li>
+<li>The default value of <code class="docutils literal"><span class="pre">_MSC_VER</span></code> was raised from 1800 to 1911, making it
+compatible with the Visual Studio 2015 and 2017 C++ standard library headers.
+Users should generally expect this to be regularly raised to match the most
+recently released version of the Visual C++ compiler.</li>
+<li>clang now defaults to <code class="docutils literal"><span class="pre">.init_array</span></code> if no gcc installation can be found.
+If a gcc installation is found, it still prefers <code class="docutils literal"><span class="pre">.ctors</span></code> if the found
+gcc is older than 4.7.0.</li>
+<li>The new builtin preprocessor macros <code class="docutils literal"><span class="pre">__is_target_arch</span></code>,
+<code class="docutils literal"><span class="pre">__is_target_vendor</span></code>, <code class="docutils literal"><span class="pre">__is_target_os</span></code>, and <code class="docutils literal"><span class="pre">__is_target_environment</span></code>
+can be used to to examine the individual components of the target triple.</li>
+</ul>
+</div>
+<div class="section" id="improvements-to-clang-s-diagnostics">
+<h3><a class="toc-backref" href="#id5">Improvements to Clang’s diagnostics</a><a class="headerlink" href="#improvements-to-clang-s-diagnostics" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">-Wpragma-pack</span></code> is a new warning that warns in the following cases:<ul>
+<li>When a translation unit is missing terminating <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">pack</span> <span class="pre">(pop)</span></code>
+directives.</li>
+<li>When leaving an included file that changes the current alignment value,
+i.e. when the alignment before <code class="docutils literal"><span class="pre">#include</span></code> is different to the alignment
+after <code class="docutils literal"><span class="pre">#include</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">-Wpragma-pack-suspicious-include</span></code> (disabled by default) warns on an
+<code class="docutils literal"><span class="pre">#include</span></code> when the included file contains structures or unions affected by
+a non-default alignment that has been specified using a <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">pack</span></code>
+directive prior to the <code class="docutils literal"><span class="pre">#include</span></code>.</li>
+</ul>
+</li>
+<li><code class="docutils literal"><span class="pre">-Wobjc-messaging-id</span></code> is a new, non-default warning that warns about
+message sends to unqualified <code class="docutils literal"><span class="pre">id</span></code> in Objective-C. This warning is useful
+for projects that would like to avoid any potential future compiler
+errors/warnings, as the system frameworks might add a method with the same
+selector which could make the message send to <code class="docutils literal"><span class="pre">id</span></code> ambiguous.</li>
+<li><code class="docutils literal"><span class="pre">-Wtautological-compare</span></code> now warns when comparing an unsigned integer and 0
+regardless of whether the constant is signed or unsigned.</li>
+<li><code class="docutils literal"><span class="pre">-Wtautological-compare</span></code> now warns about comparing a signed integer and 0
+when the signed integer is coerced to an unsigned type for the comparison.
+<code class="docutils literal"><span class="pre">-Wsign-compare</span></code> was adjusted not to warn in this case.</li>
+<li><code class="docutils literal"><span class="pre">-Wtautological-constant-compare</span></code> is a new warning that warns on
+tautological comparisons between integer variable of the type <code class="docutils literal"><span class="pre">T</span></code> and the
+largest/smallest possible integer constant of that same type.</li>
+<li>For C code, <code class="docutils literal"><span class="pre">-Wsign-compare</span></code>, <code class="docutils literal"><span class="pre">-Wsign-conversion</span></code>,
+<code class="docutils literal"><span class="pre">-Wtautological-constant-compare</span></code> and
+<code class="docutils literal"><span class="pre">-Wtautological-constant-out-of-range-compare</span></code> were adjusted to use the
+underlying datatype of <code class="docutils literal"><span class="pre">enum</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">-Wnull-pointer-arithmetic</span></code> now warns about performing pointer arithmetic
+on a null pointer. Such pointer arithmetic has an undefined behavior if the
+offset is nonzero. It also now warns about arithmetic on a null pointer
+treated as a cast from integer to pointer (GNU extension).</li>
+<li><code class="docutils literal"><span class="pre">-Wzero-as-null-pointer-constant</span></code> was adjusted not to warn on null pointer
+constants that originate from system macros, except <code class="docutils literal"><span class="pre">NULL</span></code> macro.</li>
+<li><code class="docutils literal"><span class="pre">-Wdelete-non-virtual-dtor</span></code> can now fire in system headers, so that
+<code class="docutils literal"><span class="pre">std::unique_ptr<></span></code> deleting through a non-virtual dtor is now diagnosed.</li>
+<li><code class="docutils literal"><span class="pre">-Wunreachable-code</span></code> can now reason about <code class="docutils literal"><span class="pre">__try</span></code>, <code class="docutils literal"><span class="pre">__except</span></code> and
+<code class="docutils literal"><span class="pre">__leave</span></code>.</li>
+</ul>
+</div>
+<div class="section" id="new-compiler-flags">
+<h3><a class="toc-backref" href="#id6">New Compiler Flags</a><a class="headerlink" href="#new-compiler-flags" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Clang supports the <code class="docutils literal"><span class="pre">-mretpoline</span></code> flag to enable <a class="reference external" href="https://support.google.com/faqs/answer/7625886">retpolines</a>. Code compiled with this
+flag will be hardened against variant #2 of the Spectre attack. Indirect
+branches from switches or gotos removed from the code, and indirect calls
+will be made through a “retpoline” thunk. The necessary thunks will
+automatically be inserted into the generated code. Clang also supports
+<code class="docutils literal"><span class="pre">-mretpoline-external-thunk</span></code> which works like <code class="docutils literal"><span class="pre">-mretpoline</span></code> but requires
+the user to provide their own thunk definitions. The external thunk names
+start with <code class="docutils literal"><span class="pre">__x86_indirect_thunk_</span></code> and end in a register name. For 64-bit
+platforms, only an <code class="docutils literal"><span class="pre">r11</span></code> thunk is used, but for 32-bit platforms <code class="docutils literal"><span class="pre">eax</span></code>,
+<code class="docutils literal"><span class="pre">ecx</span></code>, <code class="docutils literal"><span class="pre">edx</span></code>, and <code class="docutils literal"><span class="pre">edi</span></code> thunks are used.</li>
+<li>Clang now supports configuration files. These are collections of driver
+options, which can be applied by specifying the configuration file, either
+using command line option <code class="docutils literal"><span class="pre">--config</span> <span class="pre">foo.cfg</span></code> or encoding it into executable
+name <code class="docutils literal"><span class="pre">foo-clang</span></code>. Clang behaves as if the options from this file were inserted
+before the options specified in command line. This feature is primary intended
+to facilitate cross compilation. Details can be found in
+<a class="reference external" href="UsersManual.html#configuration-files">Clang Compiler User’s Manual</a>.</li>
+<li>The <code class="docutils literal"><span class="pre">-fdouble-square-bracket-attributes</span></code> and corresponding
+<code class="docutils literal"><span class="pre">-fno-double-square-bracket-attributes</span></code> flags were added to enable or
+disable <code class="docutils literal"><span class="pre">[[]]</span></code> attributes in any language mode. Currently, only a limited
+number of attributes are supported outside of C++ mode. See the Clang
+<a class="reference external" href="AttributeReference.html">attribute documentation</a> for more information
+about which attributes are supported for each syntax.</li>
+<li>Added the <code class="docutils literal"><span class="pre">-std=c17</span></code>, <code class="docutils literal"><span class="pre">-std=gnu17</span></code>, and <code class="docutils literal"><span class="pre">-std=iso9899:2017</span></code> language
+mode flags for compatibility with GCC. This enables support for the next
+version of the C standard, expected to be published by ISO in 2018. The only
+difference between the <code class="docutils literal"><span class="pre">-std=c17</span></code> and <code class="docutils literal"><span class="pre">-std=c11</span></code> language modes is the
+value of the <code class="docutils literal"><span class="pre">__STDC_VERSION__</span></code> macro, as C17 is a bug fix release.</li>
+<li>Added the <code class="docutils literal"><span class="pre">-fexperimental-isel</span></code> and <code class="docutils literal"><span class="pre">-fno-experimental-isel</span></code> flags to
+enable/disable the new GlobalISel instruction selection framework. This
+feature is enabled by default for AArch64 at the <code class="docutils literal"><span class="pre">-O0</span></code> optimization level.
+Support for other targets or optimization levels is currently incomplete.</li>
+<li>New <code class="docutils literal"><span class="pre">-nostdlib++</span></code> flag to disable linking the C++ standard library. Similar
+to using <code class="docutils literal"><span class="pre">clang</span></code> instead of <code class="docutils literal"><span class="pre">clang++</span></code> but doesn’t disable <code class="docutils literal"><span class="pre">-lm</span></code>.</li>
+</ul>
+</div>
+<div class="section" id="attribute-changes-in-clang">
+<h3><a class="toc-backref" href="#id7">Attribute Changes in Clang</a><a class="headerlink" href="#attribute-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Clang now supports the majority of its attributes under both the GNU-style
+spelling (<code class="docutils literal"><span class="pre">__attribute((name))</span></code>) and the double square-bracket spelling
+in the <code class="docutils literal"><span class="pre">clang</span></code> vendor namespace (<code class="docutils literal"><span class="pre">[[clang::name]]</span></code>). Attributes whose
+syntax is specified by some other standard (such as CUDA and OpenCL
+attributes) continue to follow their respective specification.</li>
+<li>Added the <code class="docutils literal"><span class="pre">__has_c_attribute()</span></code> builtin preprocessor macro which allows
+users to dynamically detect whether a double square-bracket attribute is
+supported in C mode. This attribute syntax can be enabled with the
+<code class="docutils literal"><span class="pre">-fdouble-square-bracket-attributes</span></code> flag.</li>
+<li>The presence of <code class="docutils literal"><span class="pre">__attribute__((availability(...)))</span></code> on a declaration no
+longer implies default visibility for that declaration on macOS.</li>
+</ul>
+</div>
+<div class="section" id="windows-support">
+<h3><a class="toc-backref" href="#id8">Windows Support</a><a class="headerlink" href="#windows-support" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Clang now has initial, preliminary support for targeting Windows on
+ARM64.</li>
+<li>clang-cl now exposes the <code class="docutils literal"><span class="pre">--version</span></code> flag.</li>
+</ul>
+</div>
+<div class="section" id="c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id9">C++ Language Changes in Clang</a><a class="headerlink" href="#c-language-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first">Clang’s default C++ dialect is now <code class="docutils literal"><span class="pre">gnu++14</span></code> instead of <code class="docutils literal"><span class="pre">gnu++98</span></code>. This
+means Clang will by default accept code using features from C++14 and
+conforming GNU extensions. Projects incompatible with C++14 can add
+<code class="docutils literal"><span class="pre">-std=gnu++98</span></code> to their build settings to restore the previous behaviour.</p>
+</li>
+<li><p class="first">Added support for some features from the C++ standard after C++17
+(provisionally known as C++2a but expected to be C++20). This support can be
+enabled with the <code class="docutils literal"><span class="pre">-std=c++2a</span></code> flag. This enables:</p>
+<ul class="simple">
+<li>Support for <code class="docutils literal"><span class="pre">__VA_OPT__</span></code>, to allow variadic macros to easily provide
+different expansions when they are invoked without variadic arguments.</li>
+<li>Recognition of the <code class="docutils literal"><span class="pre"><=></span></code> token (the C++2a three-way comparison operator).</li>
+<li>Support for default member initializers for bit-fields.</li>
+<li>Lambda capture of <code class="docutils literal"><span class="pre">*this</span></code>.</li>
+<li>Pointer-to-member calls using <code class="docutils literal"><span class="pre">const</span> <span class="pre">&</span></code>-qualified pointers on temporary objects.</li>
+</ul>
+<p>All of these features other than <code class="docutils literal"><span class="pre">__VA_OPT__</span></code> and <code class="docutils literal"><span class="pre"><=></span></code> are made
+available with a warning in earlier C++ language modes.</p>
+</li>
+<li><p class="first">A warning has been added for a <code class="docutils literal"><span class="pre"><=</span></code> token followed immediately by a <code class="docutils literal"><span class="pre">></span></code>
+character. Code containing such constructs will change meaning in C++2a due
+to the addition of the <code class="docutils literal"><span class="pre"><=></span></code> operator.</p>
+</li>
+<li><p class="first">Clang implements the “destroying operator delete” feature described in C++
+committee paper <cite>P0722R1
+<http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0722r1.html></cite>,
+which is targeting inclusion in C++2a but has not yet been voted into the C++
+working draft. Support for this feature is enabled by the presence of the
+standard library type <code class="docutils literal"><span class="pre">std::destroying_delete_t</span></code>.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="opencl-c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id10">OpenCL C Language Changes in Clang</a><a class="headerlink" href="#opencl-c-language-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Added subgroup builtins to enqueue kernel support.</li>
+<li>Added CL2.0 atomics as Clang builtins that now accept
+an additional memory scope parameter propagated to atomic IR instructions
+(this is to align with the corresponding change in LLVM IR) (see <a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/opencl-2.0-openclc.pdf#107">spec s6.13.11.4</a>).</li>
+<li>Miscellaneous fixes in the CL header.</li>
+<li>Allow per target selection of address space during CodeGen of certain OpenCL types.
+Default target implementation is provided mimicking old behavior.</li>
+<li>Macro <code class="docutils literal"><span class="pre">__IMAGE_SUPPORT__</span></code> is now automatically added (as per <a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/opencl-2.0-openclc.pdf#55">spec s6.10</a>).</li>
+<li>Added <code class="docutils literal"><span class="pre">cl_intel_subgroups</span></code> and <code class="docutils literal"><span class="pre">cl_intel_subgroups_short</span></code> extensions.</li>
+<li>All function calls are marked by <a class="reference external" href="https://clang.llvm.org/docs/AttributeReference.html#convergent-clang-convergent">the convergent attribute</a>
+to prevent optimizations that break SPMD program semantics. This will be removed
+by LLVM passes if it can be proved that the function does not use convergent
+operations.</li>
+<li>Create a kernel wrapper for enqueued blocks, which simplifies enqueue support by
+providing common functionality.</li>
+<li>Added private address space explicitly in AST and refactored address space support
+with several simplifications and bug fixes (<a class="reference external" href="https://llvm.org/pr33419">PR33419</a>
+and <a class="reference external" href="https://llvm.org/pr33420">PR33420</a>).</li>
+<li>OpenCL now allows functions with empty parameters to be treated as if they had a
+void parameter list (inspired from C++ support). OpenCL C spec update to follow.</li>
+<li>General miscellaneous refactoring and cleanup of blocks support for OpenCL to
+remove unused parts inherited from Objective C implementation.</li>
+<li>Miscellaneous improvements in vector diagnostics.</li>
+<li>Added half float load and store builtins without enabling half as a legal type
+(<code class="docutils literal"><span class="pre">__builtin_store_half</span></code> for double, <code class="docutils literal"><span class="pre">__builtin_store_halff</span></code> for float,
+<code class="docutils literal"><span class="pre">__builtin_load_half</span></code> for double, <code class="docutils literal"><span class="pre">__builtin_load_halff</span></code> for float).</li>
+</ul>
+</div>
+<div class="section" id="openmp-support-in-clang">
+<h3><a class="toc-backref" href="#id11">OpenMP Support in Clang</a><a class="headerlink" href="#openmp-support-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Added options <code class="docutils literal"><span class="pre">-f[no]-openmp-simd</span></code> that support code emission only for OpenMP
+SIMD-based directives, like <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">simd</span></code>, <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">parallel</span> <span class="pre">for</span> <span class="pre">simd</span></code>
+etc. The code is emitted only for SIMD-based part of the combined directives
+and clauses.</li>
+<li>Added support for almost all target-based directives except for
+<code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">target</span> <span class="pre">teams</span> <span class="pre">distribute</span> <span class="pre">parallel</span> <span class="pre">for</span> <span class="pre">[simd]</span></code>. Although, please
+note that <code class="docutils literal"><span class="pre">depend</span></code> clauses on target-based directives are not supported yet.
+Clang supports offloading to X86_64, AArch64 and PPC64[LE] devices.</li>
+<li>Added support for <code class="docutils literal"><span class="pre">reduction</span></code>-based clauses on <code class="docutils literal"><span class="pre">task</span></code>-based directives from
+upcoming OpenMP 5.0.</li>
+<li>The LLVM OpenMP runtime <code class="docutils literal"><span class="pre">libomp</span></code> now supports the OpenMP Tools Interface (OMPT)
+on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and macOS. If you observe
+a measurable performance impact on one of your applications without a tool
+attached, please rebuild the runtime library with <code class="docutils literal"><span class="pre">-DLIBOMP_OMPT_SUPPORT=OFF</span></code> and
+file a bug at <a class="reference external" href="https://bugs.llvm.org/">LLVM’s Bugzilla</a> or send a message to the
+<a class="reference external" href="http://lists.llvm.org/cgi-bin/mailman/listinfo/openmp-dev">OpenMP development list</a>.</li>
+</ul>
+</div>
+<div class="section" id="ast-matchers">
+<h3><a class="toc-backref" href="#id12">AST Matchers</a><a class="headerlink" href="#ast-matchers" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal"><span class="pre">hasDeclaration</span></code> matcher now works the same for <code class="docutils literal"><span class="pre">Type</span></code> and <code class="docutils literal"><span class="pre">QualType</span></code> and only
+ever looks through one level of sugaring in a limited number of cases.</p>
+<p>There are two main patterns affected by this:</p>
+<ul>
+<li><p class="first"><code class="docutils literal"><span class="pre">qualType(hasDeclaration(recordDecl(...)))</span></code>: previously, we would look through
+sugar like <code class="docutils literal"><span class="pre">TypedefType</span></code> to get at the underlying <code class="docutils literal"><span class="pre">recordDecl</span></code>; now, we need
+to explicitly remove the sugaring:
+<code class="docutils literal"><span class="pre">qualType(hasUnqualifiedDesugaredType(hasDeclaration(recordDecl(...))))</span></code></p>
+</li>
+<li><p class="first"><code class="docutils literal"><span class="pre">hasType(recordDecl(...))</span></code>: <code class="docutils literal"><span class="pre">hasType</span></code> internally uses <code class="docutils literal"><span class="pre">hasDeclaration</span></code>; previously,
+this matcher used to match for example <code class="docutils literal"><span class="pre">TypedefTypes</span></code> of the <code class="docutils literal"><span class="pre">RecordType</span></code>, but
+after the change they don’t; to fix, use:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">hasType</span><span class="p">(</span><span class="n">hasUnqualifiedDesugaredType</span><span class="p">(</span>
+ <span class="n">recordType</span><span class="p">(</span><span class="n">hasDeclaration</span><span class="p">(</span><span class="n">recordDecl</span><span class="p">(...)))))</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><code class="docutils literal"><span class="pre">templateSpecializationType(hasDeclaration(classTemplateDecl(...)))</span></code>:
+previously, we would directly match the underlying <code class="docutils literal"><span class="pre">ClassTemplateDecl</span></code>;
+now, we can explicitly match the <code class="docutils literal"><span class="pre">ClassTemplateSpecializationDecl</span></code>, but that
+requires to explicitly get the <code class="docutils literal"><span class="pre">ClassTemplateDecl</span></code>:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">templateSpecializationType</span><span class="p">(</span><span class="n">hasDeclaration</span><span class="p">(</span>
+ <span class="n">classTemplateSpecializationDecl</span><span class="p">(</span>
+ <span class="n">hasSpecializedTemplate</span><span class="p">(</span><span class="n">classTemplateDecl</span><span class="p">(...)))))</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="clang-format">
+<h3><a class="toc-backref" href="#id13">clang-format</a><a class="headerlink" href="#clang-format" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first">Option <code class="docutils literal"><span class="pre">IndentPPDirectives</span></code> added to indent preprocessor directives on
+conditionals.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Before</th>
+<th class="head">After</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="first last highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#if FOO</span>
+<span class="cp">#if BAR</span>
+<span class="cp">#include</span> <span class="cpf"><foo></span><span class="cp"></span>
+<span class="cp">#endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</td>
+<td><div class="first last highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#if FOO</span>
+<span class="cp"># if BAR</span>
+<span class="cp"># include <foo></span>
+<span class="cp"># endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</td>
+</tr>
+</tbody>
+</table>
+</li>
+<li><p class="first">Option <code class="docutils literal"><span class="pre">-verbose</span></code> added to the command line.
+Shows the list of processed files.</p>
+</li>
+<li><p class="first">Option <code class="docutils literal"><span class="pre">IncludeBlocks</span></code> added to merge and regroup multiple <code class="docutils literal"><span class="pre">#include</span></code> blocks during sorting.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="33%" />
+<col width="33%" />
+<col width="33%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Before (Preserve)</th>
+<th class="head">Merge</th>
+<th class="head">Regroup</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="first last highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"b.h"</span><span class="cp"></span>
+
+<span class="cp">#include</span> <span class="cpf">"a.b"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf"><lib/main.h></span><span class="cp"></span>
+</pre></div>
+</div>
+</td>
+<td><div class="first last highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"a.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"b.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf"><lib/main.h></span><span class="cp"></span>
+</pre></div>
+</div>
+</td>
+<td><div class="first last highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"a.h"</span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"b.h"</span><span class="cp"></span>
+
+<span class="cp">#include</span> <span class="cpf"><lib/main.h></span><span class="cp"></span>
+</pre></div>
+</div>
+</td>
+</tr>
+</tbody>
+</table>
+</li>
+</ul>
+</div>
+<div class="section" id="static-analyzer">
+<h3><a class="toc-backref" href="#id14">Static Analyzer</a><a class="headerlink" href="#static-analyzer" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>The Static Analyzer can now properly detect and diagnose unary pre-/post-
+increment/decrement on an uninitialized value.</li>
+</ul>
+</div>
+<div class="section" id="undefined-behavior-sanitizer-ubsan">
+<h3><a class="toc-backref" href="#id15">Undefined Behavior Sanitizer (UBSan)</a><a class="headerlink" href="#undefined-behavior-sanitizer-ubsan" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>A minimal runtime is now available. It is suitable for use in production
+environments, and has a small attack surface. It only provides very basic
+issue logging and deduplication, and does not support <code class="docutils literal"><span class="pre">-fsanitize=vptr</span></code>
+checking.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="additional-information">
+<h2><a class="toc-backref" href="#id16">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 “<code class="docutils literal"><span class="pre">clang/docs/</span></code>” 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" role="navigation" aria-label="bottom navigation">
+
+ <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" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/SafeStack.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/SafeStack.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/SafeStack.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/SafeStack.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,270 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Source-based Code Coverage" href="SourceBasedCodeCoverage.html" />
+ <link rel="prev" title="LTO Visibility" href="LTOVisibility.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>SafeStack</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="LTOVisibility.html">LTO Visibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SourceBasedCodeCoverage.html">Source-based Code Coverage</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"><code class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></code></a></li>
+<li><a class="reference internal" href="#attribute-no-sanitize-safe-stack" id="id11"><code class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></code></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-ptr" id="id12"><code class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></code></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-start" id="id13"><code class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></code></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#design" id="id14">Design</a><ul>
+<li><a class="reference internal" href="#setjmp-and-exception-handling" id="id15">setjmp and exception handling</a></li>
+<li><a class="reference internal" href="#publications" id="id16">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 <code class="docutils literal"><span class="pre">sigaltstack()</span></code> must not use the unsafe stack (see
+<code class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></code> below).</p>
+<p>Programs that use APIs from <code class="docutils literal"><span class="pre">ucontext.h</span></code> 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"><span class="doc">C++ virtual
+calls</span></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 <code class="docutils literal"><span class="pre">swapcontext</span></code>, exception
+handling mechanisms, intrinsics such as <code class="docutils literal"><span class="pre">__builtin_frame_address</span></code>, 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 <code class="docutils literal"><span class="pre">setjmp</span></code>/<code class="docutils literal"><span class="pre">longjmp</span></code>
+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 <code class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></code> 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"><code class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></code></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 <code class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></code> can
+be used for this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><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"><code class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></code></a><a class="headerlink" href="#attribute-no-sanitize-safe-stack" title="Permalink to this headline">¶</a></h4>
+<p>Use <code class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></code> on a function declaration
+to specify that the safe stack instrumentation should not be applied to that
+function, even if enabled globally (see <code class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></code> 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"><code class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></code></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"><code class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></code></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="setjmp-and-exception-handling">
+<h3><a class="toc-backref" href="#id15">setjmp and exception handling</a><a class="headerlink" href="#setjmp-and-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">OSDI‘14 paper</a> mentions that
+on Linux the instrumentation pass finds calls to setjmp or functions that
+may throw an exception, and inserts required instrumentation at their call
+sites. Specifically, the instrumentation pass saves the shadow stack pointer
+on the safe stack before the call site, and restores it either after the
+call to setjmp or after an exception has been caught. This is implemented
+in the function <code class="docutils literal"><span class="pre">SafeStack::createStackRestorePoints</span></code>.</p>
+</div>
+<div class="section" id="publications">
+<h3><a class="toc-backref" href="#id16">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" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="LTOVisibility.html">LTO Visibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SourceBasedCodeCoverage.html">Source-based Code Coverage</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/SanitizerCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/SanitizerCoverage.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/SanitizerCoverage.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/SanitizerCoverage.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,426 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="SanitizerStats" href="SanitizerStats.html" />
+ <link rel="prev" title="LeakSanitizer" href="LeakSanitizer.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>SanitizerCoverage</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="LeakSanitizer.html">LeakSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerStats.html">SanitizerStats</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="#tracing-pcs-with-guards" id="id2">Tracing PCs with guards</a></li>
+<li><a class="reference internal" href="#inline-8bit-counters" id="id3">Inline 8bit-counters</a></li>
+<li><a class="reference internal" href="#pc-table" id="id4">PC-Table</a></li>
+<li><a class="reference internal" href="#tracing-pcs" id="id5">Tracing PCs</a></li>
+<li><a class="reference internal" href="#instrumentation-points" id="id6">Instrumentation points</a><ul>
+<li><a class="reference internal" href="#edge-coverage" id="id7">Edge coverage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tracing-data-flow" id="id8">Tracing data flow</a></li>
+<li><a class="reference internal" href="#default-implementation" id="id9">Default implementation</a><ul>
+<li><a class="reference internal" href="#sancov-data-format" id="id10">Sancov data format</a></li>
+<li><a class="reference internal" href="#sancov-tool" id="id11">Sancov Tool</a></li>
+<li><a class="reference internal" href="#coverage-reports" id="id12">Coverage Reports</a></li>
+<li><a class="reference internal" href="#output-directory" id="id13">Output directory</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>LLVM has a simple code coverage instrumentation built in (SanitizerCoverage).
+It inserts calls to user-defined functions on function-, basic-block-, and edge- levels.
+Default implementations of those callbacks are provided and implement
+simple coverage reporting and visualization,
+however if you need <em>just</em> coverage visualization you may want to use
+<a class="reference internal" href="SourceBasedCodeCoverage.html"><span class="doc">SourceBasedCodeCoverage</span></a> instead.</p>
+</div>
+<div class="section" id="tracing-pcs-with-guards">
+<h2><a class="toc-backref" href="#id2">Tracing PCs with guards</a><a class="headerlink" href="#tracing-pcs-with-guards" title="Permalink to this headline">¶</a></h2>
+<p>With <code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc-guard</span></code> the compiler will insert the following code
+on every edge:</p>
+<div class="highlight-none"><div class="highlight"><pre><span></span>__sanitizer_cov_trace_pc_guard(&guard_variable)
+</pre></div>
+</div>
+<p>Every edge will have its own <cite>guard_variable</cite> (uint32_t).</p>
+<p>The compler will also insert calls to a module constructor:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="c1">// The guards are [start, stop).</span>
+<span class="c1">// This function will be called at least once per DSO and may be called</span>
+<span class="c1">// more than once with the same values of start/stop.</span>
+<span class="n">__sanitizer_cov_trace_pc_guard_init</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">start</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">stop</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>With an additional <code class="docutils literal"><span class="pre">...=trace-pc,indirect-calls</span></code> flag
+<code class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc_indirect(void</span> <span class="pre">*callee)</span></code> will be inserted on every indirect call.</p>
+<p>The functions <cite>__sanitizer_cov_trace_pc_*</cite> should be defined by the user.</p>
+<p>Example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="c1">// trace-pc-guard-cb.cc</span>
+<span class="cp">#include</span> <span class="cpf"><stdint.h></span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf"><sanitizer/coverage_interface.h></span><span class="cp"></span>
+
+<span class="c1">// This callback is inserted by the compiler as a module constructor</span>
+<span class="c1">// into every DSO. 'start' and 'stop' correspond to the</span>
+<span class="c1">// beginning and end of the section with the guards for the entire</span>
+<span class="c1">// binary (executable or DSO). The callback will be called at least</span>
+<span class="c1">// once per DSO and may be called multiple times with the same parameters.</span>
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">__sanitizer_cov_trace_pc_guard_init</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">start</span><span class="p">,</span>
+ <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">stop</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">uint64_t</span> <span class="n">N</span><span class="p">;</span> <span class="c1">// Counter for the guards.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">start</span> <span class="o">==</span> <span class="n">stop</span> <span class="o">||</span> <span class="o">*</span><span class="n">start</span><span class="p">)</span> <span class="k">return</span><span class="p">;</span> <span class="c1">// Initialize only once.</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"INIT: %p %p</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">start</span><span class="p">,</span> <span class="n">stop</span><span class="p">);</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">x</span> <span class="o">=</span> <span class="n">start</span><span class="p">;</span> <span class="n">x</span> <span class="o"><</span> <span class="n">stop</span><span class="p">;</span> <span class="n">x</span><span class="o">++</span><span class="p">)</span>
+ <span class="o">*</span><span class="n">x</span> <span class="o">=</span> <span class="o">++</span><span class="n">N</span><span class="p">;</span> <span class="c1">// Guards should start from 1.</span>
+<span class="p">}</span>
+
+<span class="c1">// This callback is inserted by the compiler on every edge in the</span>
+<span class="c1">// control flow (some optimizations apply).</span>
+<span class="c1">// Typically, the compiler will emit the code like this:</span>
+<span class="c1">// if(*guard)</span>
+<span class="c1">// __sanitizer_cov_trace_pc_guard(guard);</span>
+<span class="c1">// But for large functions it will emit a simple call:</span>
+<span class="c1">// __sanitizer_cov_trace_pc_guard(guard);</span>
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">__sanitizer_cov_trace_pc_guard</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">guard</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">guard</span><span class="p">)</span> <span class="k">return</span><span class="p">;</span> <span class="c1">// Duplicate the guard check.</span>
+ <span class="c1">// If you set *guard to 0 this code will not be called again for this edge.</span>
+ <span class="c1">// Now you can get the PC and do whatever you want:</span>
+ <span class="c1">// store it somewhere or symbolize it and print right away.</span>
+ <span class="c1">// The values of `*guard` are as you set them in</span>
+ <span class="c1">// __sanitizer_cov_trace_pc_guard_init and so you can make them consecutive</span>
+ <span class="c1">// and use them to dereference an array or a bit vector.</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">PC</span> <span class="o">=</span> <span class="n">__builtin_return_address</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="kt">char</span> <span class="n">PcDescr</span><span class="p">[</span><span class="mi">1024</span><span class="p">];</span>
+ <span class="c1">// This function is a part of the sanitizer run-time.</span>
+ <span class="c1">// To use it, link with AddressSanitizer or other sanitizer.</span>
+ <span class="n">__sanitizer_symbolize_pc</span><span class="p">(</span><span class="n">PC</span><span class="p">,</span> <span class="s">"%p %F %L"</span><span class="p">,</span> <span class="n">PcDescr</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">PcDescr</span><span class="p">));</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"guard: %p %x PC %s</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">guard</span><span class="p">,</span> <span class="o">*</span><span class="n">guard</span><span class="p">,</span> <span class="n">PcDescr</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="c1">// trace-pc-guard-example.cc</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</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="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">argc</span> <span class="o">></span> <span class="mi">1</span><span class="p">)</span> <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">clang++ -g -fsanitize-coverage=trace-pc-guard trace-pc-guard-example.cc -c</span>
+<span class="go">clang++ trace-pc-guard-cb.cc trace-pc-guard-example.o -fsanitize=address</span>
+<span class="go">ASAN_OPTIONS=strip_path_prefix=`pwd`/ ./a.out</span>
+</pre></div>
+</div>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">INIT: 0x71bcd0 0x71bce0</span>
+<span class="go">guard: 0x71bcd4 2 PC 0x4ecd5b in main trace-pc-guard-example.cc:2</span>
+<span class="go">guard: 0x71bcd8 3 PC 0x4ecd9e in main trace-pc-guard-example.cc:3:7</span>
+</pre></div>
+</div>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">ASAN_OPTIONS=strip_path_prefix=`pwd`/ ./a.out with-foo</span>
+</pre></div>
+</div>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">INIT: 0x71bcd0 0x71bce0</span>
+<span class="go">guard: 0x71bcd4 2 PC 0x4ecd5b in main trace-pc-guard-example.cc:3</span>
+<span class="go">guard: 0x71bcdc 4 PC 0x4ecdc7 in main trace-pc-guard-example.cc:4:17</span>
+<span class="go">guard: 0x71bcd0 1 PC 0x4ecd20 in foo() trace-pc-guard-example.cc:2:14</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="inline-8bit-counters">
+<h2><a class="toc-backref" href="#id3">Inline 8bit-counters</a><a class="headerlink" href="#inline-8bit-counters" title="Permalink to this headline">¶</a></h2>
+<p><strong>Experimental, may change or disappear in future</strong></p>
+<p>With <code class="docutils literal"><span class="pre">-fsanitize-coverage=inline-8bit-counters</span></code> the compiler will insert
+inline counter increments on every edge.
+This is similar to <code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc-guard</span></code> but instead of a
+callback the instrumentation simply increments a counter.</p>
+<p>Users need to implement a single function to capture the counters at startup.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="s">"C"</span>
+<span class="kt">void</span> <span class="n">__sanitizer_cov_8bit_counters_init</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">start</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">end</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// [start,end) is the array of 8-bit counters created for the current DSO.</span>
+ <span class="c1">// Capture this array in order to read/modify the counters.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pc-table">
+<h2><a class="toc-backref" href="#id4">PC-Table</a><a class="headerlink" href="#pc-table" title="Permalink to this headline">¶</a></h2>
+<p><strong>Experimental, may change or disappear in future</strong></p>
+<p>With <code class="docutils literal"><span class="pre">-fsanitize-coverage=pc-table</span></code> the compiler will create a table of
+instrumented PCs. Requires either <code class="docutils literal"><span class="pre">-fsanitize-coverage=inline-8bit-counters</span></code> or
+<code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc-guard</span></code>.</p>
+<p>Users need to implement a single function to capture the PC table at startup:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="s">"C"</span>
+<span class="kt">void</span> <span class="n">__sanitizer_cov_pcs_init</span><span class="p">(</span><span class="k">const</span> <span class="kt">uintptr_t</span> <span class="o">*</span><span class="n">pcs_beg</span><span class="p">,</span>
+ <span class="k">const</span> <span class="kt">uintptr_t</span> <span class="o">*</span><span class="n">pcs_end</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// [pcs_beg,pcs_end) is the array of ptr-sized integers representing</span>
+ <span class="c1">// pairs [PC,PCFlags] for every instrumented block in the current DSO.</span>
+ <span class="c1">// Capture this array in order to read the PCs and their Flags.</span>
+ <span class="c1">// The number of PCs and PCFlags for a given DSO is the same as the number</span>
+ <span class="c1">// of 8-bit counters (-fsanitize-coverage=inline-8bit-counters) or</span>
+ <span class="c1">// trace_pc_guard callbacks (-fsanitize-coverage=trace-pc-guard)</span>
+ <span class="c1">// A PCFlags describes the basic block:</span>
+ <span class="c1">// * bit0: 1 if the block is the function entry block, 0 otherwise.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tracing-pcs">
+<h2><a class="toc-backref" href="#id5">Tracing PCs</a><a class="headerlink" href="#tracing-pcs" title="Permalink to this headline">¶</a></h2>
+<p>With <code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc</span></code> the compiler will insert
+<code class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc()</span></code> on every edge.
+With an additional <code class="docutils literal"><span class="pre">...=trace-pc,indirect-calls</span></code> flag
+<code class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc_indirect(void</span> <span class="pre">*callee)</span></code> will be inserted on every indirect call.
+These callbacks are not implemented in the Sanitizer run-time and should be defined
+by the user.
+This mechanism is used for fuzzing the Linux kernel
+(<a class="reference external" href="https://github.com/google/syzkaller">https://github.com/google/syzkaller</a>).</p>
+</div>
+<div class="section" id="instrumentation-points">
+<h2><a class="toc-backref" href="#id6">Instrumentation points</a><a class="headerlink" href="#instrumentation-points" title="Permalink to this headline">¶</a></h2>
+<p>Sanitizer Coverage offers different levels of instrumentation.</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">edge</span></code> (default): edges are instrumented (see below).</li>
+<li><code class="docutils literal"><span class="pre">bb</span></code>: basic blocks are instrumented.</li>
+<li><code class="docutils literal"><span class="pre">func</span></code>: only the entry block of every function will be instrumented.</li>
+</ul>
+<p>Use these flags together with <code class="docutils literal"><span class="pre">trace-pc-guard</span></code> or <code class="docutils literal"><span class="pre">trace-pc</span></code>,
+like this: <code class="docutils literal"><span class="pre">-fsanitize-coverage=func,trace-pc-guard</span></code>.</p>
+<p>When <code class="docutils literal"><span class="pre">edge</span></code> or <code class="docutils literal"><span class="pre">bb</span></code> is used, some of the edges/blocks may still be left
+uninstrumented (pruned) if such instrumentation is considered redundant.
+Use <code class="docutils literal"><span class="pre">no-prune</span></code> (e.g. <code class="docutils literal"><span class="pre">-fsanitize-coverage=bb,no-prune,trace-pc-guard</span></code>)
+to disable pruning. This could be useful for better coverage visualization.</p>
+<div class="section" id="edge-coverage">
+<h3><a class="toc-backref" href="#id7">Edge coverage</a><a class="headerlink" href="#edge-coverage" title="Permalink to this headline">¶</a></h3>
+<p>Consider this code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><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><span></span>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 simply splits all critical
+edges by introducing new dummy blocks and then instruments those blocks:</p>
+<div class="highlight-none"><div class="highlight"><pre><span></span>A
+|\
+| \
+D B
+| /
+|/
+C
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="tracing-data-flow">
+<h2><a class="toc-backref" href="#id8">Tracing data flow</a><a class="headerlink" href="#tracing-data-flow" title="Permalink to this headline">¶</a></h2>
+<p>Support for data-flow-guided fuzzing.
+With <code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-cmp</span></code> the compiler will insert extra instrumentation
+around comparison instructions and switch statements.
+Similarly, with <code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-div</span></code> the compiler will instrument
+integer division instructions (to capture the right argument of division)
+and with <code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-gep</span></code> –
+the <a class="reference external" href="http://llvm.org/docs/GetElementPtr.html">LLVM GEP instructions</a>
+(to capture array indices).</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="c1">// Called before a comparison instruction.</span>
+<span class="c1">// Arg1 and Arg2 are arguments of the comparison.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp1</span><span class="p">(</span><span class="kt">uint8_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint8_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp2</span><span class="p">(</span><span class="kt">uint16_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint16_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp4</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp8</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="n">Arg2</span><span class="p">);</span>
+
+<span class="c1">// Called before a comparison instruction if exactly one of the arguments is constant.</span>
+<span class="c1">// Arg1 and Arg2 are arguments of the comparison, Arg1 is a compile-time constant.</span>
+<span class="c1">// These callbacks are emitted by -fsanitize-coverage=trace-cmp since 2017-08-11</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_const_cmp1</span><span class="p">(</span><span class="kt">uint8_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint8_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_const_cmp2</span><span class="p">(</span><span class="kt">uint16_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint16_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_const_cmp4</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_const_cmp8</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="n">Arg2</span><span class="p">);</span>
+
+<span class="c1">// Called before a switch statement.</span>
+<span class="c1">// Val is the switch operand.</span>
+<span class="c1">// Cases[0] is the number of case constants.</span>
+<span class="c1">// Cases[1] is the size of Val in bits.</span>
+<span class="c1">// Cases[2:] are the case constants.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_switch</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">Val</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="o">*</span><span class="n">Cases</span><span class="p">);</span>
+
+<span class="c1">// Called before a division statement.</span>
+<span class="c1">// Val is the second argument of division.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_div4</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="n">Val</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_div8</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">Val</span><span class="p">);</span>
+
+<span class="c1">// Called before a GetElemementPtr (GEP) instruction</span>
+<span class="c1">// for every non-constant array index.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_gep</span><span class="p">(</span><span class="kt">uintptr_t</span> <span class="n">Idx</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="default-implementation">
+<h2><a class="toc-backref" href="#id9">Default implementation</a><a class="headerlink" href="#default-implementation" title="Permalink to this headline">¶</a></h2>
+<p>The sanitizer run-time (AddressSanitizer, MemorySanitizer, etc) provide a
+default implementations of some of the coverage callbacks.
+You may use this implementation to dump the coverage on disk at the process
+exit.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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>trace-pc-guard
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span><span class="m">1</span> ./a.out<span class="p">;</span> wc -c *.sancov
+<span class="go">main</span>
+<span class="go">SanitizerCoverage: ./a.out.7312.sancov 2 PCs written</span>
+<span class="go">24 a.out.7312.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><span class="m">1</span> ./a.out foo <span class="p">;</span> wc -c *.sancov
+<span class="go">foo</span>
+<span class="go">main</span>
+<span class="go">SanitizerCoverage: ./a.out.7316.sancov 3 PCs written</span>
+<span class="go">24 a.out.7312.sancov</span>
+<span class="go">32 a.out.7316.sancov</span>
+</pre></div>
+</div>
+<p>Every time you run an executable instrumented with SanitizerCoverage
+one <code class="docutils literal"><span class="pre">*.sancov</span></code> file is created during the process shutdown.
+If the executable is dynamically linked against instrumented DSOs,
+one <code class="docutils literal"><span class="pre">*.sancov</span></code> file will be also created for every DSO.</p>
+<div class="section" id="sancov-data-format">
+<h3><a class="toc-backref" href="#id10">Sancov data format</a><a class="headerlink" href="#sancov-data-format" title="Permalink to this headline">¶</a></h3>
+<p>The format of <code class="docutils literal"><span class="pre">*.sancov</span></code> files is very simple: the first 8 bytes is the magic,
+one of <code class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF64</span></code> and <code class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF32</span></code>. 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>
+</div>
+<div class="section" id="sancov-tool">
+<h3><a class="toc-backref" href="#id11">Sancov Tool</a><a class="headerlink" href="#sancov-tool" title="Permalink to this headline">¶</a></h3>
+<p>An simple <code class="docutils literal"><span class="pre">sancov</span></code> tool is provided to process coverage files.
+The tool is part of LLVM project and is currently supported only on Linux.
+It can handle symbolization tasks autonomously without any extra support
+from the environment. You need to pass .sancov files (named
+<code class="docutils literal"><span class="pre"><module_name>.<pid>.sancov</span></code> and paths to all corresponding binary elf files.
+Sancov matches these files using module names and binaries file names.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">USAGE: sancov [options] <action> (<binary file>|<.sancov file>)...</span>
+
+<span class="go">Action (required)</span>
+<span class="go"> -print - Print coverage addresses</span>
+<span class="go"> -covered-functions - Print all covered functions.</span>
+<span class="go"> -not-covered-functions - Print all not covered functions.</span>
+<span class="go"> -symbolize - Symbolizes the report.</span>
+
+<span class="go">Options</span>
+<span class="go"> -blacklist=<string> - Blacklist file (sanitizer blacklist format).</span>
+<span class="go"> -demangle - Print demangled function name.</span>
+<span class="go"> -strip_path_prefix=<string> - Strip this prefix from file paths in reports</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="coverage-reports">
+<h3><a class="toc-backref" href="#id12">Coverage Reports</a><a class="headerlink" href="#coverage-reports" title="Permalink to this headline">¶</a></h3>
+<p><strong>Experimental</strong></p>
+<p><code class="docutils literal"><span class="pre">.sancov</span></code> files do not contain enough information to generate a source-level
+coverage report. The missing information is contained
+in debug info of the binary. Thus the <code class="docutils literal"><span class="pre">.sancov</span></code> has to be symbolized
+to produce a <code class="docutils literal"><span class="pre">.symcov</span></code> file first:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">sancov -symbolize my_program.123.sancov my_program > my_program.123.symcov</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal"><span class="pre">.symcov</span></code> file can be browsed overlayed over the source code by
+running <code class="docutils literal"><span class="pre">tools/sancov/coverage-report-server.py</span></code> script that will start
+an HTTP server.</p>
+</div>
+<div class="section" id="output-directory">
+<h3><a class="toc-backref" href="#id13">Output directory</a><a class="headerlink" href="#output-directory" title="Permalink to this headline">¶</a></h3>
+<p>By default, .sancov files are created in the current working directory.
+This can be changed with <code class="docutils literal"><span class="pre">ASAN_OPTIONS=coverage_dir=/path</span></code>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="LeakSanitizer.html">LeakSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerStats.html">SanitizerStats</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/SanitizerSpecialCaseList.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/SanitizerSpecialCaseList.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/SanitizerSpecialCaseList.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/SanitizerSpecialCaseList.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,165 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Control Flow Integrity" href="ControlFlowIntegrity.html" />
+ <link rel="prev" title="SanitizerStats" href="SanitizerStats.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Sanitizer special case list</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="SanitizerStats.html">SanitizerStats</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"><span class="doc">AddressSanitizer</span></a>, <a class="reference internal" href="ThreadSanitizer.html"><span class="doc">ThreadSanitizer</span></a>
+or <a class="reference internal" href="MemorySanitizer.html"><span class="doc">MemorySanitizer</span></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
+<code class="docutils literal"><span class="pre">-fsanitize-blacklist</span></code> flag. See <a class="reference internal" href="UsersManual.html"><span class="doc">Clang Compiler User’s Manual</span></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></span>$ cat foo.c
+<span class="c1">#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><span class="m">40</span><span class="o">)</span><span class="p">;</span>
+ a<span class="o">[</span><span class="m">10</span><span class="o">]</span> <span class="o">=</span> <span class="m">1</span><span class="p">;</span>
+<span class="o">}</span>
+int main<span class="o">()</span> <span class="o">{</span> bad_foo<span class="o">()</span><span class="p">;</span> <span class="o">}</span>
+$ cat blacklist.txt
+<span class="c1"># Ignore reports from bad_foo function.</span>
+fun:bad_foo
+$ clang -fsanitize<span class="o">=</span>address foo.c <span class="p">;</span> ./a.out
+<span class="c1"># AddressSanitizer prints an error report.</span>
+$ clang -fsanitize<span class="o">=</span>address -fsanitize-blacklist<span class="o">=</span>blacklist.txt foo.c <span class="p">;</span> ./a.out
+<span class="c1"># 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>Blacklists consist of entries, optionally grouped into sections. Empty lines and
+lines starting with “#” are ignored.</p>
+<p>Section names are regular expressions written in square brackets that denote
+which sanitizer the following entries apply to. For example, <code class="docutils literal"><span class="pre">[address]</span></code>
+specifies AddressSanitizer while <code class="docutils literal"><span class="pre">[cfi-vcall|cfi-icall]</span></code> specifies Control
+Flow Integrity virtual and indirect call checking. Entries without a section
+will be placed under the <code class="docutils literal"><span class="pre">[*]</span></code> section applying to all enabled sanitizers.</p>
+<p>Entries contain 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, e.g. <code class="docutils literal"><span class="pre">fun:*ExampleFunc=example_category</span></code>. The
+meaning of <code class="docutils literal"><span class="pre">*</span></code> in regular expression for entity names is different - it is
+treated as in shell wildcarding. Two generic entity types are <code class="docutils literal"><span class="pre">src</span></code> and
+<code class="docutils literal"><span class="pre">fun</span></code>, which allow users to specify source files and functions, respectively.
+Some sanitizer tools may introduce custom entity types and categories - refer to
+tool-specific docs.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="c1"># Lines starting with # are ignored.</span>
+<span class="c1"># Turn off checks for the source file (use absolute path or path relative</span>
+<span class="c1"># to the current working directory):</span>
+src:/path/to/source/file.c
+<span class="c1"># Turn off checks for a particular functions (use mangled names):</span>
+fun:MyFooBar
+fun:_Z8MyFooBarv
+<span class="c1"># Extended regular expressions are supported:</span>
+fun:bad_<span class="o">(</span>foo<span class="p">|</span>bar<span class="o">)</span>
+src:bad_source<span class="o">[</span><span class="m">1</span>-9<span class="o">]</span>.c
+<span class="c1"># Shell like usage of * is supported (* is treated as .*):</span>
+src:bad/sources/*
+fun:*BadFunction*
+<span class="c1"># Specific sanitizer tools may introduce categories.</span>
+src:/special/path/*<span class="o">=</span>special_sources
+<span class="c1"># Sections can be used to limit blacklist entries to specific sanitizers</span>
+<span class="o">[</span>address<span class="o">]</span>
+fun:*BadASanFunc*
+<span class="c1"># Section names are regular expressions</span>
+<span class="o">[</span>cfi-vcall<span class="p">|</span>cfi-icall<span class="o">]</span>
+fun:*BadCfiCall
+<span class="c1"># Entries without sections are placed into [*] and apply to all sanitizers</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="SanitizerStats.html">SanitizerStats</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ControlFlowIntegrity.html">Control Flow Integrity</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/SanitizerStats.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/SanitizerStats.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/SanitizerStats.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/SanitizerStats.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,132 @@
+<!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>SanitizerStats — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Sanitizer special case list" href="SanitizerSpecialCaseList.html" />
+ <link rel="prev" title="SanitizerCoverage" href="SanitizerCoverage.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>SanitizerStats</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="SanitizerCoverage.html">SanitizerCoverage</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="sanitizerstats">
+<h1>SanitizerStats<a class="headerlink" href="#sanitizerstats" 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>
+</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>The sanitizers support a simple mechanism for gathering profiling statistics
+to help understand the overhead associated with sanitizers.</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>SanitizerStats can currently only be used with <a class="reference internal" href="ControlFlowIntegrity.html"><span class="doc">Control Flow Integrity</span></a>.
+In addition to <code class="docutils literal"><span class="pre">-fsanitize=cfi*</span></code>, pass the <code class="docutils literal"><span class="pre">-fsanitize-stats</span></code> flag.
+This will cause the program to count the number of times that each control
+flow integrity check in the program fires.</p>
+<p>At run time, set the <code class="docutils literal"><span class="pre">SANITIZER_STATS_PATH</span></code> environment variable to direct
+statistics output to a file. The file will be written on process exit.
+The following substitutions will be applied to the environment variable:</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal"><span class="pre">%b</span></code> – The executable basename.</li>
+<li><code class="docutils literal"><span class="pre">%p</span></code> – The process ID.</li>
+</ul>
+</div></blockquote>
+<p>You can also send the <code class="docutils literal"><span class="pre">SIGUSR2</span></code> signal to a process to make it write
+sanitizer statistics immediately.</p>
+<p>The <code class="docutils literal"><span class="pre">sanstats</span></code> program can be used to dump statistics. It takes as a
+command line argument the path to a statistics file produced by a program
+compiled with <code class="docutils literal"><span class="pre">-fsanitize-stats</span></code>.</p>
+<p>The output of <code class="docutils literal"><span class="pre">sanstats</span></code> is in four columns, separated by spaces. The first
+column is the file and line number of the call site. The second column is
+the function name. The third column is the type of statistic gathered (in
+this case, the type of control flow integrity check). The fourth column is
+the call count.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cat -n vcall.cc
+<span class="go"> 1 struct A {</span>
+<span class="go"> 2 virtual void f() {}</span>
+<span class="go"> 3 };</span>
+<span class="go"> 4</span>
+<span class="go"> 5 __attribute__((noinline)) void g(A *a) {</span>
+<span class="go"> 6 a->f();</span>
+<span class="go"> 7 }</span>
+<span class="go"> 8</span>
+<span class="go"> 9 int main() {</span>
+<span class="go"> 10 A a;</span>
+<span class="go"> 11 g(&a);</span>
+<span class="go"> 12 }</span>
+<span class="gp">$</span> clang++ -fsanitize<span class="o">=</span>cfi -flto -fuse-ld<span class="o">=</span>gold vcall.cc -fsanitize-stats -g
+<span class="gp">$</span> <span class="nv">SANITIZER_STATS_PATH</span><span class="o">=</span>a.stats ./a.out
+<span class="gp">$</span> sanstats a.stats
+<span class="go">vcall.cc:6 _Z1gP1A cfi-vcall 1</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="SanitizerCoverage.html">SanitizerCoverage</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/SourceBasedCodeCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/SourceBasedCodeCoverage.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/SourceBasedCodeCoverage.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/SourceBasedCodeCoverage.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,344 @@
+<!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>Source-based Code Coverage — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Modules" href="Modules.html" />
+ <link rel="prev" title="SafeStack" href="SafeStack.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Source-based Code Coverage</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="SafeStack.html">SafeStack</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Modules.html">Modules</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="source-based-code-coverage">
+<h1>Source-based Code Coverage<a class="headerlink" href="#source-based-code-coverage" 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="#the-code-coverage-workflow" id="id2">The code coverage workflow</a></li>
+<li><a class="reference internal" href="#compiling-with-coverage-enabled" id="id3">Compiling with coverage enabled</a></li>
+<li><a class="reference internal" href="#running-the-instrumented-program" id="id4">Running the instrumented program</a></li>
+<li><a class="reference internal" href="#creating-coverage-reports" id="id5">Creating coverage reports</a></li>
+<li><a class="reference internal" href="#exporting-coverage-data" id="id6">Exporting coverage data</a></li>
+<li><a class="reference internal" href="#interpreting-reports" id="id7">Interpreting reports</a></li>
+<li><a class="reference internal" href="#format-compatibility-guarantees" id="id8">Format compatibility guarantees</a></li>
+<li><a class="reference internal" href="#using-the-profiling-runtime-without-static-initializers" id="id9">Using the profiling runtime without static initializers</a></li>
+<li><a class="reference internal" href="#collecting-coverage-reports-for-the-llvm-project" id="id10">Collecting coverage reports for the llvm project</a></li>
+<li><a class="reference internal" href="#drawbacks-and-limitations" id="id11">Drawbacks and limitations</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 explains how to use clang’s source-based code coverage feature.
+It’s called “source-based” because it operates on AST and preprocessor
+information directly. This allows it to generate very precise coverage data.</p>
+<p>Clang ships two other code coverage implementations:</p>
+<ul class="simple">
+<li><a class="reference internal" href="SanitizerCoverage.html"><span class="doc">SanitizerCoverage</span></a> - A low-overhead tool meant for use alongside the
+various sanitizers. It can provide up to edge-level coverage.</li>
+<li>gcov - A GCC-compatible coverage implementation which operates on DebugInfo.
+This is enabled by <code class="docutils literal"><span class="pre">-ftest-coverage</span></code> or <code class="docutils literal"><span class="pre">--coverage</span></code>.</li>
+</ul>
+<p>From this point onwards “code coverage” will refer to the source-based kind.</p>
+</div>
+<div class="section" id="the-code-coverage-workflow">
+<h2><a class="toc-backref" href="#id2">The code coverage workflow</a><a class="headerlink" href="#the-code-coverage-workflow" title="Permalink to this headline">¶</a></h2>
+<p>The code coverage workflow consists of three main steps:</p>
+<ul class="simple">
+<li>Compiling with coverage enabled.</li>
+<li>Running the instrumented program.</li>
+<li>Creating coverage reports.</li>
+</ul>
+<p>The next few sections work through a complete, copy-‘n-paste friendly example
+based on this program:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">cat</span> <span class="o"><<</span><span class="n">EOF</span> <span class="o">></span> <span class="n">foo</span><span class="p">.</span><span class="n">cc</span>
+<span class="cp">#define BAR(x) ((x) || (x))</span>
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">T</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</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="mi">10</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span> <span class="n">BAR</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">int</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="n">foo</span><span class="o"><</span><span class="kt">float</span><span class="o">></span><span class="p">(</span><span class="mi">0</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="n">EOF</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="compiling-with-coverage-enabled">
+<h2><a class="toc-backref" href="#id3">Compiling with coverage enabled</a><a class="headerlink" href="#compiling-with-coverage-enabled" title="Permalink to this headline">¶</a></h2>
+<p>To compile code with coverage enabled, pass <code class="docutils literal"><span class="pre">-fprofile-instr-generate</span>
+<span class="pre">-fcoverage-mapping</span></code> to the compiler:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">#</span> Step <span class="m">1</span>: Compile with coverage enabled.
+<span class="gp">%</span> clang++ -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo
+</pre></div>
+</div>
+<p>Note that linking together code with and without coverage instrumentation is
+supported. Uninstrumented code simply won’t be accounted for in reports.</p>
+</div>
+<div class="section" id="running-the-instrumented-program">
+<h2><a class="toc-backref" href="#id4">Running the instrumented program</a><a class="headerlink" href="#running-the-instrumented-program" title="Permalink to this headline">¶</a></h2>
+<p>The next step is to run the instrumented program. When the program exits it
+will write a <strong>raw profile</strong> to the path specified by the <code class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></code>
+environment variable. If that variable does not exist, the profile is written
+to <code class="docutils literal"><span class="pre">default.profraw</span></code> in the current directory of the program. If
+<code class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></code> contains a path to a non-existent directory, the missing
+directory structure will be created. Additionally, the following special
+<strong>pattern strings</strong> are rewritten:</p>
+<ul class="simple">
+<li>“%p” expands out to the process ID.</li>
+<li>“%h” expands out to the hostname of the machine running the program.</li>
+<li>“%Nm” expands out to the instrumented binary’s signature. When this pattern
+is specified, the runtime creates a pool of N raw profiles which are used for
+on-line profile merging. The runtime takes care of selecting a raw profile
+from the pool, locking it, and updating it before the program exits. If N is
+not specified (i.e the pattern is “%m”), it’s assumed that <code class="docutils literal"><span class="pre">N</span> <span class="pre">=</span> <span class="pre">1</span></code>. N must
+be between 1 and 9. The merge pool specifier can only occur once per filename
+pattern.</li>
+</ul>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">#</span> Step <span class="m">2</span>: Run the program.
+<span class="gp">%</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"foo.profraw"</span> ./foo
+</pre></div>
+</div>
+</div>
+<div class="section" id="creating-coverage-reports">
+<h2><a class="toc-backref" href="#id5">Creating coverage reports</a><a class="headerlink" href="#creating-coverage-reports" title="Permalink to this headline">¶</a></h2>
+<p>Raw profiles have to be <strong>indexed</strong> before they can be used to generate
+coverage reports. This is done using the “merge” tool in <code class="docutils literal"><span class="pre">llvm-profdata</span></code>
+(which can combine multiple raw profiles and index them at the same time):</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">#</span> Step <span class="m">3</span><span class="o">(</span>a<span class="o">)</span>: Index the raw profile.
+<span class="gp">%</span> llvm-profdata merge -sparse foo.profraw -o foo.profdata
+</pre></div>
+</div>
+<p>There are multiple different ways to render coverage reports. The simplest
+option is to generate a line-oriented report:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">#</span> Step <span class="m">3</span><span class="o">(</span>b<span class="o">)</span>: Create a line-oriented coverage report.
+<span class="gp">%</span> llvm-cov show ./foo -instr-profile<span class="o">=</span>foo.profdata
+</pre></div>
+</div>
+<p>This report includes a summary view as well as dedicated sub-views for
+templated functions and their instantiations. For our example program, we get
+distinct views for <code class="docutils literal"><span class="pre">foo<int>(...)</span></code> and <code class="docutils literal"><span class="pre">foo<float>(...)</span></code>. If
+<code class="docutils literal"><span class="pre">-show-line-counts-or-regions</span></code> is enabled, <code class="docutils literal"><span class="pre">llvm-cov</span></code> displays sub-line
+region counts (even in macro expansions):</p>
+<div class="highlight-none"><div class="highlight"><pre><span></span> 1| 20|#define BAR(x) ((x) || (x))
+ ^20 ^2
+ 2| 2|template <typename T> void foo(T x) {
+ 3| 22| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+ ^22 ^20 ^20^20
+ 4| 2|}
+------------------
+| void foo<int>(int):
+| 2| 1|template <typename T> void foo(T x) {
+| 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+| ^11 ^10 ^10^10
+| 4| 1|}
+------------------
+| void foo<float>(int):
+| 2| 1|template <typename T> void foo(T x) {
+| 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+| ^11 ^10 ^10^10
+| 4| 1|}
+------------------
+</pre></div>
+</div>
+<p>To generate a file-level summary of coverage statistics instead of a
+line-oriented report, try:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">#</span> Step <span class="m">3</span><span class="o">(</span>c<span class="o">)</span>: Create a coverage summary.
+<span class="gp">%</span> llvm-cov report ./foo -instr-profile<span class="o">=</span>foo.profdata
+<span class="go">Filename Regions Missed Regions Cover Functions Missed Functions Executed Lines Missed Lines Cover</span>
+<span class="go">--------------------------------------------------------------------------------------------------------------------------------------</span>
+<span class="go">/tmp/foo.cc 13 0 100.00% 3 0 100.00% 13 0 100.00%</span>
+<span class="go">--------------------------------------------------------------------------------------------------------------------------------------</span>
+<span class="go">TOTAL 13 0 100.00% 3 0 100.00% 13 0 100.00%</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal"><span class="pre">llvm-cov</span></code> tool supports specifying a custom demangler, writing out
+reports in a directory structure, and generating html reports. For the full
+list of options, please refer to the <a class="reference external" href="http://llvm.org/docs/CommandGuide/llvm-cov.html">command guide</a>.</p>
+<p>A few final notes:</p>
+<ul>
+<li><p class="first">The <code class="docutils literal"><span class="pre">-sparse</span></code> flag is optional but can result in dramatically smaller
+indexed profiles. This option should not be used if the indexed profile will
+be reused for PGO.</p>
+</li>
+<li><p class="first">Raw profiles can be discarded after they are indexed. Advanced use of the
+profile runtime library allows an instrumented program to merge profiling
+information directly into an existing raw profile on disk. The details are
+out of scope.</p>
+</li>
+<li><p class="first">The <code class="docutils literal"><span class="pre">llvm-profdata</span></code> tool can be used to merge together multiple raw or
+indexed profiles. To combine profiling data from multiple runs of a program,
+try e.g:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">%</span> llvm-profdata merge -sparse foo1.profraw foo2.profdata -o foo3.profdata
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="exporting-coverage-data">
+<h2><a class="toc-backref" href="#id6">Exporting coverage data</a><a class="headerlink" href="#exporting-coverage-data" title="Permalink to this headline">¶</a></h2>
+<p>Coverage data can be exported into JSON using the <code class="docutils literal"><span class="pre">llvm-cov</span> <span class="pre">export</span></code>
+sub-command. There is a comprehensive reference which defines the structure of
+the exported data at a high level in the llvm-cov source code.</p>
+</div>
+<div class="section" id="interpreting-reports">
+<h2><a class="toc-backref" href="#id7">Interpreting reports</a><a class="headerlink" href="#interpreting-reports" title="Permalink to this headline">¶</a></h2>
+<p>There are four statistics tracked in a coverage summary:</p>
+<ul class="simple">
+<li>Function coverage is the percentage of functions which have been executed at
+least once. A function is considered to be executed if any of its
+instantiations are executed.</li>
+<li>Instantiation coverage is the percentage of function instantiations which
+have been executed at least once. Template functions and static inline
+functions from headers are two kinds of functions which may have multiple
+instantiations.</li>
+<li>Line coverage is the percentage of code lines which have been executed at
+least once. Only executable lines within function bodies are considered to be
+code lines.</li>
+<li>Region coverage is the percentage of code regions which have been executed at
+least once. A code region may span multiple lines (e.g in a large function
+body with no control flow). However, it’s also possible for a single line to
+contain multiple code regions (e.g in “return x || y && z”).</li>
+</ul>
+<p>Of these four statistics, function coverage is usually the least granular while
+region coverage is the most granular. The project-wide totals for each
+statistic are listed in the summary.</p>
+</div>
+<div class="section" id="format-compatibility-guarantees">
+<h2><a class="toc-backref" href="#id8">Format compatibility guarantees</a><a class="headerlink" href="#format-compatibility-guarantees" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>There are no backwards or forwards compatibility guarantees for the raw
+profile format. Raw profiles may be dependent on the specific compiler
+revision used to generate them. It’s inadvisable to store raw profiles for
+long periods of time.</li>
+<li>Tools must retain <strong>backwards</strong> compatibility with indexed profile formats.
+These formats are not forwards-compatible: i.e, a tool which uses format
+version X will not be able to understand format version (X+k).</li>
+<li>Tools must also retain <strong>backwards</strong> compatibility with the format of the
+coverage mappings emitted into instrumented binaries. These formats are not
+forwards-compatible.</li>
+<li>The JSON coverage export format has a (major, minor, patch) version triple.
+Only a major version increment indicates a backwards-incompatible change. A
+minor version increment is for added functionality, and patch version
+increments are for bugfixes.</li>
+</ul>
+</div>
+<div class="section" id="using-the-profiling-runtime-without-static-initializers">
+<h2><a class="toc-backref" href="#id9">Using the profiling runtime without static initializers</a><a class="headerlink" href="#using-the-profiling-runtime-without-static-initializers" title="Permalink to this headline">¶</a></h2>
+<p>By default the compiler runtime uses a static initializer to determine the
+profile output path and to register a writer function. To collect profiles
+without using static initializers, do this manually:</p>
+<ul class="simple">
+<li>Export a <code class="docutils literal"><span class="pre">int</span> <span class="pre">__llvm_profile_runtime</span></code> symbol from each instrumented shared
+library and executable. When the linker finds a definition of this symbol, it
+knows to skip loading the object which contains the profiling runtime’s
+static initializer.</li>
+<li>Forward-declare <code class="docutils literal"><span class="pre">void</span> <span class="pre">__llvm_profile_initialize_file(void)</span></code> and call it
+once from each instrumented executable. This function parses
+<code class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></code>, sets the output path, and truncates any existing files
+at that path. To get the same behavior without truncating existing files,
+pass a filename pattern string to <code class="docutils literal"><span class="pre">void</span> <span class="pre">__llvm_profile_set_filename(char</span>
+<span class="pre">*)</span></code>. These calls can be placed anywhere so long as they precede all calls
+to <code class="docutils literal"><span class="pre">__llvm_profile_write_file</span></code>.</li>
+<li>Forward-declare <code class="docutils literal"><span class="pre">int</span> <span class="pre">__llvm_profile_write_file(void)</span></code> and call it to write
+out a profile. This function returns 0 when it succeeds, and a non-zero value
+otherwise. Calling this function multiple times appends profile data to an
+existing on-disk raw profile.</li>
+</ul>
+<p>In C++ files, declare these as <code class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></code>.</p>
+</div>
+<div class="section" id="collecting-coverage-reports-for-the-llvm-project">
+<h2><a class="toc-backref" href="#id10">Collecting coverage reports for the llvm project</a><a class="headerlink" href="#collecting-coverage-reports-for-the-llvm-project" title="Permalink to this headline">¶</a></h2>
+<p>To prepare a coverage report for llvm (and any of its sub-projects), add
+<code class="docutils literal"><span class="pre">-DLLVM_BUILD_INSTRUMENTED_COVERAGE=On</span></code> to the cmake configuration. Raw
+profiles will be written to <code class="docutils literal"><span class="pre">$BUILD_DIR/profiles/</span></code>. To prepare an html
+report, run <code class="docutils literal"><span class="pre">llvm/utils/prepare-code-coverage-artifact.py</span></code>.</p>
+<p>To specify an alternate directory for raw profiles, use
+<code class="docutils literal"><span class="pre">-DLLVM_PROFILE_DATA_DIR</span></code>. To change the size of the profile merge pool, use
+<code class="docutils literal"><span class="pre">-DLLVM_PROFILE_MERGE_POOL_SIZE</span></code>.</p>
+</div>
+<div class="section" id="drawbacks-and-limitations">
+<h2><a class="toc-backref" href="#id11">Drawbacks and limitations</a><a class="headerlink" href="#drawbacks-and-limitations" title="Permalink to this headline">¶</a></h2>
+<ul>
+<li><p class="first">Prior to version 2.26, the GNU binutils BFD linker is not able link programs
+compiled with <code class="docutils literal"><span class="pre">-fcoverage-mapping</span></code> in its <code class="docutils literal"><span class="pre">--gc-sections</span></code> mode. Possible
+workarounds include disabling <code class="docutils literal"><span class="pre">--gc-sections</span></code>, upgrading to a newer version
+of BFD, or using the Gold linker.</p>
+</li>
+<li><p class="first">Code coverage does not handle unpredictable changes in control flow or stack
+unwinding in the presence of exceptions precisely. Consider the following
+function:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">may_throw</span><span class="p">();</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the call to <code class="docutils literal"><span class="pre">may_throw()</span></code> propagates an exception into <code class="docutils literal"><span class="pre">f</span></code>, the code
+coverage tool may mark the <code class="docutils literal"><span class="pre">return</span></code> statement as executed even though it is
+not. A call to <code class="docutils literal"><span class="pre">longjmp()</span></code> can have similar effects.</p>
+</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="SafeStack.html">SafeStack</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Modules.html">Modules</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/ThinLTO.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/ThinLTO.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/ThinLTO.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/ThinLTO.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,301 @@
+<!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>ThinLTO — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Clang âmanâ pages" href="CommandGuide/index.html" />
+ <link rel="prev" title="OpenMP Support" href="OpenMPSupport.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>ThinLTO</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="OpenMPSupport.html">OpenMP Support</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="CommandGuide/index.html">Clang “man” pages</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="thinlto">
+<h1>ThinLTO<a class="headerlink" href="#thinlto" 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="id4">Introduction</a></li>
+<li><a class="reference internal" href="#current-status" id="id5">Current Status</a><ul>
+<li><a class="reference internal" href="#clang-llvm" id="id6">Clang/LLVM</a></li>
+<li><a class="reference internal" href="#linkers" id="id7">Linkers</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#usage" id="id8">Usage</a><ul>
+<li><a class="reference internal" href="#basic" id="id9">Basic</a></li>
+<li><a class="reference internal" href="#controlling-backend-parallelism" id="id10">Controlling Backend Parallelism</a></li>
+<li><a class="reference internal" href="#incremental" id="id11">Incremental</a></li>
+<li><a class="reference internal" href="#cache-pruning" id="id12">Cache Pruning</a></li>
+<li><a class="reference internal" href="#clang-bootstrap" id="id13">Clang Bootstrap</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#more-information" id="id14">More Information</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id4">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p><em>ThinLTO</em> compilation is a new type of LTO that is both scalable and
+incremental. <em>LTO</em> (Link Time Optimization) achieves better
+runtime performance through whole-program analysis and cross-module
+optimization. However, monolithic LTO implements this by merging all
+input into a single module, which is not scalable
+in time or memory, and also prevents fast incremental compiles.</p>
+<p>In ThinLTO mode, as with regular LTO, clang emits LLVM bitcode after the
+compile phase. The ThinLTO bitcode is augmented with a compact summary
+of the module. During the link step, only the summaries are read and
+merged into a combined summary index, which includes an index of function
+locations for later cross-module function importing. Fast and efficient
+whole-program analysis is then performed on the combined summary index.</p>
+<p>However, all transformations, including function importing, occur
+later when the modules are optimized in fully parallel backends.
+By default, <a class="reference internal" href="#id1">linkers</a> that support ThinLTO are set up to launch
+the ThinLTO backends in threads. So the usage model is not affected
+as the distinction between the fast serial thin link step and the backends
+is transparent to the user.</p>
+<p>For more information on the ThinLTO design and current performance,
+see the LLVM blog post <a class="reference external" href="http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html">ThinLTO: Scalable and Incremental LTO</a>.
+While tuning is still in progress, results in the blog post show that
+ThinLTO already performs well compared to LTO, in many cases matching
+the performance improvement.</p>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id5">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="clang-llvm">
+<h3><a class="toc-backref" href="#id6">Clang/LLVM</a><a class="headerlink" href="#clang-llvm" title="Permalink to this headline">¶</a></h3>
+<p id="compiler">The 3.9 release of clang includes ThinLTO support. However, ThinLTO
+is under active development, and new features, improvements and bugfixes
+are being added for the next release. For the latest ThinLTO support,
+<a class="reference external" href="http://llvm.org/docs/CMake.html">build a recent version of clang and LLVM</a>.</p>
+</div>
+<div class="section" id="linkers">
+<h3><a class="toc-backref" href="#id7">Linkers</a><a class="headerlink" href="#linkers" title="Permalink to this headline">¶</a></h3>
+<p id="linker"><span id="id1"></span>ThinLTO is currently supported for the following linkers:</p>
+<ul class="simple">
+<li><strong>gold (via the gold-plugin)</strong>:
+Similar to monolithic LTO, this requires using
+a <a class="reference external" href="http://llvm.org/docs/GoldPlugin.html">gold linker configured with plugins enabled</a>.</li>
+<li><strong>ld64</strong>:
+Starting with <a class="reference external" href="https://developer.apple.com/xcode/">Xcode 8</a>.</li>
+<li><strong>lld</strong>:
+Starting with r284050 for ELF, r298942 for COFF.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id8">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="basic">
+<h3><a class="toc-backref" href="#id9">Basic</a><a class="headerlink" href="#basic" title="Permalink to this headline">¶</a></h3>
+<p>To utilize ThinLTO, simply add the -flto=thin option to compile and link. E.g.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">%</span> clang -flto<span class="o">=</span>thin -O2 file1.c file2.c -c
+<span class="gp">%</span> clang -flto<span class="o">=</span>thin -O2 file1.o file2.o -o a.out
+</pre></div>
+</div>
+<p>When using lld-link, the -flto option need only be added to the compile step:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">%</span> clang-cl -flto<span class="o">=</span>thin -O2 -c file1.c file2.c
+<span class="gp">%</span> lld-link /out:a.exe file1.obj file2.obj
+</pre></div>
+</div>
+<p>As mentioned earlier, by default the linkers will launch the ThinLTO backend
+threads in parallel, passing the resulting native object files back to the
+linker for the final native link. As such, the usage model the same as
+non-LTO.</p>
+<p>With gold, if you see an error during the link of the form:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">/usr/bin/ld: error: /path/to/clang/bin/../lib/LLVMgold.so: could not load plugin library: /path/to/clang/bin/../lib/LLVMgold.so: cannot open shared object file: No such file or directory</span>
+</pre></div>
+</div>
+<p>Then either gold was not configured with plugins enabled, or clang
+was not built with <code class="docutils literal"><span class="pre">-DLLVM_BINUTILS_INCDIR</span></code> set properly. See
+the instructions for the
+<a class="reference external" href="http://llvm.org/docs/GoldPlugin.html#how-to-build-it">LLVM gold plugin</a>.</p>
+</div>
+<div class="section" id="controlling-backend-parallelism">
+<h3><a class="toc-backref" href="#id10">Controlling Backend Parallelism</a><a class="headerlink" href="#controlling-backend-parallelism" title="Permalink to this headline">¶</a></h3>
+<p id="parallelism">By default, the ThinLTO link step will launch up to
+<code class="docutils literal"><span class="pre">std::thread::hardware_concurrency</span></code> number of threads in parallel.
+For machines with hyper-threading, this is the total number of
+virtual cores. For some applications and machine configurations this
+may be too aggressive, in which case the amount of parallelism can
+be reduced to <code class="docutils literal"><span class="pre">N</span></code> via:</p>
+<ul class="simple">
+<li>gold:
+<code class="docutils literal"><span class="pre">-Wl,-plugin-opt,jobs=N</span></code></li>
+<li>ld64:
+<code class="docutils literal"><span class="pre">-Wl,-mllvm,-threads=N</span></code></li>
+<li>lld:
+<code class="docutils literal"><span class="pre">-Wl,--thinlto-jobs=N</span></code></li>
+<li>lld-link:
+<code class="docutils literal"><span class="pre">/opt:lldltojobs=N</span></code></li>
+</ul>
+</div>
+<div class="section" id="incremental">
+<h3><a class="toc-backref" href="#id11">Incremental</a><a class="headerlink" href="#incremental" title="Permalink to this headline">¶</a></h3>
+<p id="id2">ThinLTO supports fast incremental builds through the use of a cache,
+which currently must be enabled through a linker option.</p>
+<ul class="simple">
+<li>gold (as of LLVM 4.0):
+<code class="docutils literal"><span class="pre">-Wl,-plugin-opt,cache-dir=/path/to/cache</span></code></li>
+<li>ld64 (support in clang 3.9 and Xcode 8):
+<code class="docutils literal"><span class="pre">-Wl,-cache_path_lto,/path/to/cache</span></code></li>
+<li>ELF lld (as of LLVM 5.0):
+<code class="docutils literal"><span class="pre">-Wl,--thinlto-cache-dir=/path/to/cache</span></code></li>
+<li>COFF lld-link (as of LLVM 6.0):
+<code class="docutils literal"><span class="pre">/lldltocache:/path/to/cache</span></code></li>
+</ul>
+</div>
+<div class="section" id="cache-pruning">
+<h3><a class="toc-backref" href="#id12">Cache Pruning</a><a class="headerlink" href="#cache-pruning" title="Permalink to this headline">¶</a></h3>
+<p>To help keep the size of the cache under control, ThinLTO supports cache
+pruning. Cache pruning is supported with gold, ld64 and ELF and COFF lld, but
+currently only gold, ELF and COFF lld allow you to control the policy with a
+policy string. The cache policy must be specified with a linker option.</p>
+<ul class="simple">
+<li>gold (as of LLVM 6.0):
+<code class="docutils literal"><span class="pre">-Wl,-plugin-opt,cache-policy=POLICY</span></code></li>
+<li>ELF lld (as of LLVM 5.0):
+<code class="docutils literal"><span class="pre">-Wl,--thinlto-cache-policy,POLICY</span></code></li>
+<li>COFF lld-link (as of LLVM 6.0):
+<code class="docutils literal"><span class="pre">/lldltocachepolicy:POLICY</span></code></li>
+</ul>
+<p>A policy string is a series of key-value pairs separated by <code class="docutils literal"><span class="pre">:</span></code> characters.
+Possible key-value pairs are:</p>
+<ul>
+<li><p class="first"><code class="docutils literal"><span class="pre">cache_size=X%</span></code>: The maximum size for the cache directory is <code class="docutils literal"><span class="pre">X</span></code> percent
+of the available space on the the disk. Set to 100 to indicate no limit,
+50 to indicate that the cache size will not be left over half the available
+disk space. A value over 100 is invalid. A value of 0 disables the percentage
+size-based pruning. The default is 75%.</p>
+</li>
+<li><p class="first"><code class="docutils literal"><span class="pre">cache_size_bytes=X</span></code>, <code class="docutils literal"><span class="pre">cache_size_bytes=Xk</span></code>, <code class="docutils literal"><span class="pre">cache_size_bytes=Xm</span></code>,
+<code class="docutils literal"><span class="pre">cache_size_bytes=Xg</span></code>:
+Sets the maximum size for the cache directory to <code class="docutils literal"><span class="pre">X</span></code> bytes (or KB, MB,
+GB respectively). A value over the amount of available space on the disk
+will be reduced to the amount of available space. A value of 0 disables
+the byte size-based pruning. The default is no byte size-based pruning.</p>
+<p>Note that ThinLTO will apply both size-based pruning policies simultaneously,
+and changing one does not affect the other. For example, a policy of
+<code class="docutils literal"><span class="pre">cache_size_bytes=1g</span></code> on its own will cause both the 1GB and default 75%
+policies to be applied unless the default <code class="docutils literal"><span class="pre">cache_size</span></code> is overridden.</p>
+</li>
+<li><p class="first"><code class="docutils literal"><span class="pre">cache_size_files=X</span></code>:
+Set the maximum number of files in the cache directory. Set to 0 to indicate
+no limit. The default is 1000000 files.</p>
+</li>
+<li><p class="first"><code class="docutils literal"><span class="pre">prune_after=Xs</span></code>, <code class="docutils literal"><span class="pre">prune_after=Xm</span></code>, <code class="docutils literal"><span class="pre">prune_after=Xh</span></code>: Sets the
+expiration time for cache files to <code class="docutils literal"><span class="pre">X</span></code> seconds (or minutes, hours
+respectively). When a file hasn’t been accessed for <code class="docutils literal"><span class="pre">prune_after</span></code> seconds,
+it is removed from the cache. A value of 0 disables the expiration-based
+pruning. The default is 1 week.</p>
+</li>
+<li><p class="first"><code class="docutils literal"><span class="pre">prune_interval=Xs</span></code>, <code class="docutils literal"><span class="pre">prune_interval=Xm</span></code>, <code class="docutils literal"><span class="pre">prune_interval=Xh</span></code>:
+Sets the pruning interval to <code class="docutils literal"><span class="pre">X</span></code> seconds (or minutes, hours
+respectively). This is intended to be used to avoid scanning the directory
+too often. It does not impact the decision of which files to prune. A
+value of 0 forces the scan to occur. The default is every 20 minutes.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="clang-bootstrap">
+<h3><a class="toc-backref" href="#id13">Clang Bootstrap</a><a class="headerlink" href="#clang-bootstrap" title="Permalink to this headline">¶</a></h3>
+<p>To bootstrap clang/LLVM with ThinLTO, follow these steps:</p>
+<ol class="arabic simple">
+<li>The host <a class="reference internal" href="#compiler">compiler</a> must be a version of clang that supports ThinLTO.</li>
+<li>The host <a class="reference internal" href="#linker">linker</a> must support ThinLTO (and in the case of gold, must be
+<a class="reference external" href="http://llvm.org/docs/GoldPlugin.html">configured with plugins enabled</a>.</li>
+<li>Use the following additional <a class="reference external" href="http://llvm.org/docs/CMake.html#options-and-variables">CMake variables</a>
+when configuring the bootstrap compiler build:</li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal"><span class="pre">-DLLVM_ENABLE_LTO=Thin</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_C_COMPILER=/path/to/host/clang</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_CXX_COMPILER=/path/to/host/clang++</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_RANLIB=/path/to/host/llvm-ranlib</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_AR=/path/to/host/llvm-ar</span></code></li>
+</ul>
+<p>Or, on Windows:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">-DLLVM_ENABLE_LTO=Thin</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_C_COMPILER=/path/to/host/clang-cl.exe</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_CXX_COMPILER=/path/to/host/clang-cl.exe</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_LINKER=/path/to/host/lld-link.exe</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_RANLIB=/path/to/host/llvm-ranlib.exe</span></code></li>
+<li><code class="docutils literal"><span class="pre">-DCMAKE_AR=/path/to/host/llvm-ar.exe</span></code></li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple">
+<li>To use additional linker arguments for controlling the backend
+<a class="reference internal" href="#parallelism">parallelism</a> or enabling <a class="reference internal" href="#id2">incremental</a> builds of the bootstrap compiler,
+after configuring the build, modify the resulting CMakeCache.txt file in the
+build directory. Specify any additional linker options after
+<code class="docutils literal"><span class="pre">CMAKE_EXE_LINKER_FLAGS:STRING=</span></code>. Note the configure may fail if
+linker plugin options are instead specified directly in the previous step.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id14">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>From LLVM project blog:
+<a class="reference external" href="http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html">ThinLTO: Scalable and Incremental LTO</a></li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="OpenMPSupport.html">OpenMP Support</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="CommandGuide/index.html">Clang “man” pages</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/ThreadSafetyAnalysis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/ThreadSafetyAnalysis.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/ThreadSafetyAnalysis.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/ThreadSafetyAnalysis.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,909 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="AddressSanitizer" href="AddressSanitizer.html" />
+ <link rel="prev" title="Cross-compilation using Clang" href="CrossCompilation.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Thread Safety Analysis</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <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. <code class="docutils literal"><span class="pre">int</span></code>, <code class="docutils literal"><span class="pre">float</span></code>,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment. For example, if <code class="docutils literal"><span class="pre">foo</span></code> is
+<em>guarded by</em> the mutex <code class="docutils literal"><span class="pre">mu</span></code>, then the analysis will issue a warning whenever
+a piece of code reads or writes to <code class="docutils literal"><span class="pre">foo</span></code> without first locking <code class="docutils literal"><span class="pre">mu</span></code>.
+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></span><span class="cp">#include</span> <span class="cpf">"mutex.h"</span><span class="cp"></span>
+
+<span class="k">class</span> <span class="nc">BankAccount</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</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="k">public</span><span class="o">:</span>
+ <span class="kt">void</span> <span class="n">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="n">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
+<code class="docutils literal"><span class="pre">GUARDED_BY</span></code> attribute declares that a thread must lock <code class="docutils literal"><span class="pre">mu</span></code> before it can
+read or write to <code class="docutils literal"><span class="pre">balance</span></code>, thus ensuring that the increment and decrement
+operations are atomic. Similarly, <code class="docutils literal"><span class="pre">REQUIRES</span></code> declares that
+the calling thread must lock <code class="docutils literal"><span class="pre">mu</span></code> before calling <code class="docutils literal"><span class="pre">withdrawImpl</span></code>.
+Because the caller is assumed to have locked <code class="docutils literal"><span class="pre">mu</span></code>, it is safe to modify
+<code class="docutils literal"><span class="pre">balance</span></code> within the body of the method.</p>
+<p>The <code class="docutils literal"><span class="pre">depositImpl()</span></code> method does not have <code class="docutils literal"><span class="pre">REQUIRES</span></code>, 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 <code class="docutils literal"><span class="pre">transferFrom()</span></code>, because although the method
+locks <code class="docutils literal"><span class="pre">this->mu</span></code>, it does not lock <code class="docutils literal"><span class="pre">b.mu</span></code>. The analysis understands
+that these are two separate mutexes, in two different objects.</p>
+<p>Finally, there is a warning in the <code class="docutils literal"><span class="pre">withdraw()</span></code> method, because it fails to
+unlock <code class="docutils literal"><span class="pre">mu</span></code>. 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 <code class="docutils literal"><span class="pre">ACQUIRE</span></code>/<code class="docutils literal"><span class="pre">RELEASE</span></code>).</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 <code class="docutils literal"><span class="pre">-Wthread-safety</span></code> flag, e.g.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>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"><span class="std std-ref">mutex.h</span></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 <code class="docutils literal"><span class="pre">mu</span></code> is a mutex, then calling <code class="docutils literal"><span class="pre">mu.Lock()</span></code> causes the calling thread
+to acquire the capability to access data that is protected by <code class="docutils literal"><span class="pre">mu</span></code>. Similarly,
+calling <code class="docutils literal"><span class="pre">mu.Unlock()</span></code> 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"><span class="std std-ref">mutex.h</span></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><code class="docutils literal"><span class="pre">GUARDED_BY</span></code> 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><code class="docutils literal"><span class="pre">PT_GUARDED_BY</span></code> 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></span><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>: <code class="docutils literal"><span class="pre">EXCLUSIVE_LOCKS_REQUIRED</span></code>, <code class="docutils literal"><span class="pre">SHARED_LOCKS_REQUIRED</span></code></p>
+<p><code class="docutils literal"><span class="pre">REQUIRES</span></code> 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><code class="docutils literal"><span class="pre">REQUIRES_SHARED</span></code> is similar, but requires only shared access.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><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>: <code class="docutils literal"><span class="pre">EXCLUSIVE_LOCK_FUNCTION</span></code>, <code class="docutils literal"><span class="pre">SHARED_LOCK_FUNCTION</span></code>,
+<code class="docutils literal"><span class="pre">UNLOCK_FUNCTION</span></code></p>
+<p><code class="docutils literal"><span class="pre">ACQUIRE</span></code> 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. <code class="docutils literal"><span class="pre">ACQUIRE_SHARED</span></code> is similar.</p>
+<p><code class="docutils literal"><span class="pre">RELEASE</span></code> and <code class="docutils literal"><span class="pre">RELEASE_SHARED</span></code> 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></span><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 <code class="docutils literal"><span class="pre">ACQUIRE</span></code> or <code class="docutils literal"><span class="pre">RELEASE</span></code>, then the argument is
+assumed to be <code class="docutils literal"><span class="pre">this</span></code>, 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></span><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="k">private</span><span class="o">:</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="k">public</span><span class="o">:</span>
+ <span class="c1">// Hide mu from public interface.</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="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="n">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>: <code class="docutils literal"><span class="pre">LOCKS_EXCLUDED</span></code></p>
+<p><code class="docutils literal"><span class="pre">EXCLUDES</span></code> 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></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="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 <code class="docutils literal"><span class="pre">REQUIRES</span></code>, <code class="docutils literal"><span class="pre">EXCLUDES</span></code> 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"><span class="std std-ref">Negative Capabilities</span></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><code class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></code> 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"><span class="std std-ref">Known Limitations</span></a>, below.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><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="nf">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 <code class="docutils literal"><span class="pre">.cc</span></code> or <code class="docutils literal"><span class="pre">.cpp</span></code> 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>: <code class="docutils literal"><span class="pre">LOCK_RETURNED</span></code></p>
+<p><code class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></code> 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></span><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</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="k">public</span><span class="o">:</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">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="n">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><code class="docutils literal"><span class="pre">ACQUIRED_BEFORE</span></code> and <code class="docutils literal"><span class="pre">ACQUIRED_AFTER</span></code> 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></span><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>: <code class="docutils literal"><span class="pre">LOCKABLE</span></code></p>
+<p><code class="docutils literal"><span class="pre">CAPABILITY</span></code> 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. <code class="docutils literal"><span class="pre">"mutex"</span></code>. See the <code class="docutils literal"><span class="pre">Container</span></code> example
+given above, or the <code class="docutils literal"><span class="pre">Mutex</span></code> class in <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></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>: <code class="docutils literal"><span class="pre">SCOPED_LOCKABLE</span></code></p>
+<p><code class="docutils literal"><span class="pre">SCOPED_CAPABILITY</span></code> 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
+<code class="docutils literal"><span class="pre">MutexLocker</span></code> class in <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></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> <code class="docutils literal"><span class="pre">EXCLUSIVE_TRYLOCK_FUNCTION</span></code>, <code class="docutils literal"><span class="pre">SHARED_TRYLOCK_FUNCTION</span></code></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 <code class="docutils literal"><span class="pre">true</span></code> or <code class="docutils literal"><span class="pre">false</span></code>, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as <code class="docutils literal"><span class="pre">ACQUIRE</span></code>. See <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></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> <code class="docutils literal"><span class="pre">ASSERT_EXCLUSIVE_LOCK</span></code>, <code class="docutils literal"><span class="pre">ASSERT_SHARED_LOCK</span></code></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"><span class="std std-ref">mutex.h</span></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 class="simple">
+<li><code class="docutils literal"><span class="pre">-Wthread-safety</span></code>: Umbrella flag which turns on the following three:<ul>
+<li><code class="docutils literal"><span class="pre">-Wthread-safety-attributes</span></code>: Sanity checks on attribute syntax.</li>
+<li><code class="docutils literal"><span class="pre">-Wthread-safety-analysis</span></code>: The core analysis.</li>
+<li><dl class="first docutils">
+<dt><code class="docutils literal"><span class="pre">-Wthread-safety-precise</span></code>: Requires that mutex expressions match precisely.</dt>
+<dd>This warning can be disabled for code which has a lot of aliases.</dd>
+</dl>
+</li>
+<li><code class="docutils literal"><span class="pre">-Wthread-safety-reference</span></code>: Checks when guarded members are passed by reference.</li>
+</ul>
+</li>
+</ul>
+<p><a class="reference internal" href="#negative"><span class="std std-ref">Negative Capabilities</span></a> are an experimental feature, which are enabled with:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">-Wthread-safety-negative</span></code>: 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><code class="docutils literal"><span class="pre">-Wthread-safety-beta</span></code>: 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></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="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 <code class="docutils literal"><span class="pre">!</span></code> operator, to indicate that a capability
+should <em>not</em> be held.</p>
+<p>For example, using <code class="docutils literal"><span class="pre">REQUIRES(!mu)</span></code> instead of <code class="docutils literal"><span class="pre">EXCLUDES(mu)</span></code> will produce
+the appropriate warnings:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">-Wthread-safety-negative</span></code>.</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"><span class="std std-ref">No conditionally held locks.</span></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></span><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 <code class="docutils literal"><span class="pre">mu</span></code>
+is a private member of <code class="docutils literal"><span class="pre">c</span></code>, then it is an error to write <code class="docutils literal"><span class="pre">c.mu</span></code> in an
+attribute.</p>
+<p>One workaround is to (ab)use the <code class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></code> 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></span><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="k">public</span><span class="o">:</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="n">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="n">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, <code class="docutils literal"><span class="pre">doSomethingTwice()</span></code> is an external routine that
+requires <code class="docutils literal"><span class="pre">c.mu</span></code> to be locked, which cannot be declared directly because <code class="docutils literal"><span class="pre">mu</span></code>
+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 <code class="docutils literal"><span class="pre">getMu()</span></code>
+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></span><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 <code class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></code>.
+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></span><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="k">public</span><span class="o">:</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 <code class="docutils literal"><span class="pre">Autocleanup</span></code> calls <code class="docutils literal"><span class="pre">mu.Unlock()</span></code>, 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></span><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="k">public</span><span class="o">:</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"><span class="std std-ref">mutex.h</span></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 <code class="docutils literal"><span class="pre">mutex.h</span></code> 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></span><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 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="k">public</span><span class="o">:</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="n">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="n">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="n">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="n">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="n">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="n">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="n">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="k">private</span><span class="o">:</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">mut</span><span class="p">;</span>
+
+<span class="k">public</span><span class="o">:</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_var)</span>
+
+<span class="c1">// Deprecated.</span>
+<span class="cp">#define GUARDED_VAR \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(guarded_var)</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" role="navigation" aria-label="bottom navigation">
+
+ <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" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/ThreadSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/ThreadSanitizer.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/ThreadSanitizer.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/ThreadSanitizer.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,194 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="MemorySanitizer" href="MemorySanitizer.html" />
+ <link rel="prev" title="AddressSanitizer" href="AddressSanitizer.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>ThreadSanitizer</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <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 <code class="docutils literal"><span class="pre">-fsanitize=thread</span></code>. To get a
+reasonable performance add <code class="docutils literal"><span class="pre">-O1</span></code> or higher. Use <code class="docutils literal"><span class="pre">-g</span></code> to get file names
+and line numbers in the warning messages.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">%</span> cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c
+<span class="gp">#</span>include <pthread.h>
+<span class="go">int Global;</span>
+<span class="go">void *Thread1(void *x) {</span>
+<span class="go"> Global = 42;</span>
+<span class="go"> return x;</span>
+<span class="go">}</span>
+<span class="go">int main() {</span>
+<span class="go"> pthread_t t;</span>
+<span class="go"> pthread_create(&t, NULL, Thread1, NULL);</span>
+<span class="go"> Global = 43;</span>
+<span class="go"> pthread_join(t, NULL);</span>
+<span class="go"> return Global;</span>
+<span class="go">}</span>
+
+<span class="gp">$</span> clang -fsanitize<span class="o">=</span>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
+<code class="docutils literal"><span class="pre">addr2line</span></code> process (this will be fixed in future).</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>% ./a.out
+WARNING: ThreadSanitizer: data race <span class="o">(</span><span class="nv">pid</span><span class="o">=</span><span class="m">19219</span><span class="o">)</span>
+ Write of size <span class="m">4</span> at 0x7fcf47b21bc0 by thread T1:
+ <span class="c1">#0 Thread1 tiny_race.c:4 (exe+0x00000000a360)</span>
+
+ Previous write of size <span class="m">4</span> at 0x7fcf47b21bc0 by main thread:
+ <span class="c1">#0 main tiny_race.c:10 (exe+0x00000000a3b4)</span>
+
+ Thread T1 <span class="o">(</span>running<span class="o">)</span> created at:
+ <span class="c1">#0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)</span>
+ <span class="c1">#1 main tiny_race.c:9 (exe+0x00000000a3a4)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-feature-thread-sanitizer">
+<h2><code class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></code><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"><span class="std std-ref">__has_feature</span></a> can be used for
+this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><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><code class="docutils literal"><span class="pre">__attribute__((no_sanitize("thread")))</span></code><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 <code class="docutils literal"><span class="pre">no_sanitize("thread")</span></code> 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 <code class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></code>.</p>
+</div>
+<div class="section" id="blacklist">
+<h2>Blacklist<a class="headerlink" href="#blacklist" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer supports <code class="docutils literal"><span class="pre">src</span></code> and <code class="docutils literal"><span class="pre">fun</span></code> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><span class="doc">Sanitizer special case list</span></a>, that can be used to suppress data race reports
+in the specified source files or functions. Unlike functions marked with
+<code class="docutils literal"><span class="pre">no_sanitize("thread")</span></code> 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 <code class="docutils literal"><span class="pre">ulimit</span></code> 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
+<code class="docutils literal"><span class="pre">fsanitize=thread</span></code> flag will cause Clang to act as though the <code class="docutils literal"><span class="pre">-fPIE</span></code>
+flag had been supplied if compiling without <code class="docutils literal"><span class="pre">-fPIC</span></code>, and as though the
+<code class="docutils literal"><span class="pre">-pie</span></code> 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 <code class="docutils literal"><span class="pre">make</span> <span class="pre">check-tsan</span></code> 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="https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual">https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual</a></p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <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" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/Toolchain.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/Toolchain.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/Toolchain.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/Toolchain.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,387 @@
+<!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>Assembling a Complete Toolchain — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ <link rel="prev" title="Clang Compiler Userâs Manual" href="UsersManual.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Assembling a Complete Toolchain</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="UsersManual.html">Clang Compiler User’s Manual</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="assembling-a-complete-toolchain">
+<h1>Assembling a Complete Toolchain<a class="headerlink" href="#assembling-a-complete-toolchain" 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="id8">Introduction</a></li>
+<li><a class="reference internal" href="#tools" id="id9">Tools</a><ul>
+<li><a class="reference internal" href="#clang-frontend" id="id10">Clang frontend</a></li>
+<li><a class="reference internal" href="#language-frontends-for-other-languages" id="id11">Language frontends for other languages</a></li>
+<li><a class="reference internal" href="#assember" id="id12">Assember</a></li>
+<li><a class="reference internal" href="#linker" id="id13">Linker</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#runtime-libraries" id="id14">Runtime libraries</a><ul>
+<li><a class="reference internal" href="#compiler-runtime" id="id15">Compiler runtime</a></li>
+<li><a class="reference internal" href="#atomics-library" id="id16">Atomics library</a></li>
+<li><a class="reference internal" href="#unwind-library" id="id17">Unwind library</a></li>
+<li><a class="reference internal" href="#sanitizer-runtime" id="id18">Sanitizer runtime</a></li>
+<li><a class="reference internal" href="#c-standard-library" id="id19">C standard library</a></li>
+<li><a class="reference internal" href="#c-abi-library" id="id20">C++ ABI library</a></li>
+<li><a class="reference internal" href="#id6" id="id21">C++ standard library</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id8">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang is only one component in a complete tool chain for C family
+programming languages. In order to assemble a complete toolchain,
+additional tools and runtime libraries are required. Clang is designed
+to interoperate with existing tools and libraries for its target
+platforms, and the LLVM project provides alternatives for a number
+of these components.</p>
+<p>This document describes the required and optional components in a
+complete toolchain, where to find them, and the supported versions
+and limitations of each option.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document currently describes Clang configurations on POSIX-like
+operating systems with the GCC-compatible <code class="docutils literal"><span class="pre">clang</span></code> driver. When
+targeting Windows with the MSVC-compatible <code class="docutils literal"><span class="pre">clang-cl</span></code> driver, some
+of the details are different.</p>
+</div>
+</div>
+<div class="section" id="tools">
+<h2><a class="toc-backref" href="#id9">Tools</a><a class="headerlink" href="#tools" title="Permalink to this headline">¶</a></h2>
+<p>A complete compilation of C family programming languages typically
+involves the following pipeline of tools, some of which are omitted
+in some compilations:</p>
+<ul class="simple">
+<li><strong>Preprocessor</strong>: This performs the actions of the C preprocessor:
+expanding #includes and #defines.
+The <code class="docutils literal"><span class="pre">-E</span></code> flag instructs Clang to stop after this step.</li>
+<li><strong>Parsing</strong>: This parses and semantically analyzes the source language and
+builds a source-level intermediate representation (“AST”), producing a
+<a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><span class="std std-ref">precompiled header (PCH)</span></a>,
+preamble, or
+<a class="reference internal" href="Modules.html"><span class="doc">precompiled module file (PCM)</span></a>,
+depending on the input.
+The <code class="docutils literal"><span class="pre">-precompile</span></code> flag instructs Clang to stop after this step. This is
+the default when the input is a header file.</li>
+<li><strong>IR generation</strong>: This converts the source-level intermediate representation
+into an optimizer-specific intermediate representation (IR); for Clang, this
+is LLVM IR.
+The <code class="docutils literal"><span class="pre">-emit-llvm</span></code> flag instructs Clang to stop after this step. If combined
+with <code class="docutils literal"><span class="pre">-S</span></code>, Clang will produce textual LLVM IR; otherwise, it will produce
+LLVM IR bitcode.</li>
+<li><strong>Compiler backend</strong>: This converts the intermediate representation
+into target-specific assembly code.
+The <code class="docutils literal"><span class="pre">-S</span></code> flag instructs Clang to stop after this step.</li>
+<li><strong>Assembler</strong>: This converts target-specific assembly code into
+target-specific machine code object files.
+The <code class="docutils literal"><span class="pre">-c</span></code> flag instructs Clang to stop after this step.</li>
+<li><strong>Linker</strong>: This combines multiple object files into a single image
+(either a shared object or an executable).</li>
+</ul>
+<p>Clang provides all of these pieces other than the linker. When multiple
+steps are performed by the same tool, it is common for the steps to be
+fused together to avoid creating intermediate files.</p>
+<p>When given an output of one of the above steps as an input, earlier steps
+are skipped (for instance, a <code class="docutils literal"><span class="pre">.s</span></code> file input will be assembled and linked).</p>
+<p>The Clang driver can be invoked with the <code class="docutils literal"><span class="pre">-###</span></code> flag (this argument will need
+to be escaped under most shells) to see which commands it would run for the
+above steps, without running them. The <code class="docutils literal"><span class="pre">-v</span></code> (verbose) flag will print the
+commands in addition to running them.</p>
+<div class="section" id="clang-frontend">
+<h3><a class="toc-backref" href="#id10">Clang frontend</a><a class="headerlink" href="#clang-frontend" title="Permalink to this headline">¶</a></h3>
+<p>The Clang frontend (<code class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></code>) is used to compile C family languages. The
+command-line interface of the frontend is considered to be an implementation
+detail, intentionally has no external documentation, and is subject to change
+without notice.</p>
+</div>
+<div class="section" id="language-frontends-for-other-languages">
+<h3><a class="toc-backref" href="#id11">Language frontends for other languages</a><a class="headerlink" href="#language-frontends-for-other-languages" title="Permalink to this headline">¶</a></h3>
+<p>Clang can be provided with inputs written in non-C-family languages. In such
+cases, an external tool will be used to compile the input. The
+currently-supported languages are:</p>
+<ul class="simple">
+<li>Ada (<code class="docutils literal"><span class="pre">-x</span> <span class="pre">ada</span></code>, <code class="docutils literal"><span class="pre">.ad[bs]</span></code>)</li>
+<li>Fortran (<code class="docutils literal"><span class="pre">-x</span> <span class="pre">f95</span></code>, <code class="docutils literal"><span class="pre">.f</span></code>, <code class="docutils literal"><span class="pre">.f9[05]</span></code>, <code class="docutils literal"><span class="pre">.for</span></code>, <code class="docutils literal"><span class="pre">.fpp</span></code>, case-insensitive)</li>
+<li>Java (<code class="docutils literal"><span class="pre">-x</span> <span class="pre">java</span></code>)</li>
+</ul>
+<p>In each case, GCC will be invoked to compile the input.</p>
+</div>
+<div class="section" id="assember">
+<h3><a class="toc-backref" href="#id12">Assember</a><a class="headerlink" href="#assember" title="Permalink to this headline">¶</a></h3>
+<p>Clang can either use LLVM’s integrated assembler or an external system-specific
+tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from
+assembly.
+By default, Clang uses LLVM’s integrataed assembler on all targets where it is
+supported. If you wish to use the system assember instead, use the
+<code class="docutils literal"><span class="pre">-fno-integrated-as</span></code> option.</p>
+</div>
+<div class="section" id="linker">
+<h3><a class="toc-backref" href="#id13">Linker</a><a class="headerlink" href="#linker" title="Permalink to this headline">¶</a></h3>
+<p>Clang can be configured to use one of several different linkers:</p>
+<ul class="simple">
+<li>GNU ld</li>
+<li>GNU gold</li>
+<li>LLVM’s <a class="reference external" href="http://lld.llvm.org">lld</a></li>
+<li>MSVC’s link.exe</li>
+</ul>
+<p>Link-time optimization is natively supported by lld, and supported via
+a <a class="reference external" href="http://llvm.org/docs/GoldPlugin.html">linker plugin</a> when using gold.</p>
+<p>The default linker varies between targets, and can be overridden via the
+<code class="docutils literal"><span class="pre">-fuse-ld=<linker</span> <span class="pre">name></span></code> flag.</p>
+</div>
+</div>
+<div class="section" id="runtime-libraries">
+<h2><a class="toc-backref" href="#id14">Runtime libraries</a><a class="headerlink" href="#runtime-libraries" title="Permalink to this headline">¶</a></h2>
+<p>A number of different runtime libraries are required to provide different
+layers of support for C family programs. Clang will implicitly link an
+appropriate implementation of each runtime library, selected based on
+target defaults or explicitly selected by the <code class="docutils literal"><span class="pre">--rtlib=</span></code> and <code class="docutils literal"><span class="pre">--stdlib=</span></code>
+flags.</p>
+<p>The set of implicitly-linked libraries depend on the language mode. As a
+consequence, you should use <code class="docutils literal"><span class="pre">clang++</span></code> when linking C++ programs in order
+to ensure the C++ runtimes are provided.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">There may exist other implementations for these components not described
+below. Please let us know how well those other implementations work with
+Clang so they can be added to this list!</p>
+</div>
+<div class="section" id="compiler-runtime">
+<h3><a class="toc-backref" href="#id15">Compiler runtime</a><a class="headerlink" href="#compiler-runtime" title="Permalink to this headline">¶</a></h3>
+<p>The compiler runtime library provides definitions of functions implicitly
+invoked by the compiler to support operations not natively supported by
+the underlying hardware (for instance, 128-bit integer multiplications),
+and where inline expansion of the operation is deemed unsuitable.</p>
+<p>The default runtime library is target-specific. For targets where GCC is
+the dominant compiler, Clang currently defaults to using libgcc_s. On most
+other targets, compiler-rt is used by default.</p>
+<div class="section" id="compiler-rt-llvm">
+<h4>compiler-rt (LLVM)<a class="headerlink" href="#compiler-rt-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="http://compiler-rt.llvm.org/">LLVM’s compiler runtime library</a> provides a
+complete set of runtime library functions containing all functions that
+Clang will implicitly call, in <code class="docutils literal"><span class="pre">libclang_rt.builtins.<arch>.a</span></code>.</p>
+<p>You can instruct Clang to use compiler-rt with the <code class="docutils literal"><span class="pre">--rtlib=compiler-rt</span></code> flag.
+This is not supported on every platform.</p>
+<p>If using libc++ and/or libc++abi, you may need to configure them to use
+compiler-rt rather than libgcc_s by passing <code class="docutils literal"><span class="pre">-DLIBCXX_USE_COMPILER_RT=YES</span></code>
+and/or <code class="docutils literal"><span class="pre">-DLIBCXXABI_USE_COMPILER_RT=YES</span></code> to <code class="docutils literal"><span class="pre">cmake</span></code>. Otherwise, you
+may end up with both runtime libraries linked into your program (this is
+typically harmless, but wasteful).</p>
+</div>
+<div class="section" id="libgcc-s-gnu">
+<h4>libgcc_s (GNU)<a class="headerlink" href="#libgcc-s-gnu" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html">GCC’s runtime library</a>
+can be used in place of compiler-rt. However, it lacks several functions
+that LLVM may emit references to, particularly when using Clang’s
+<code class="docutils literal"><span class="pre">__builtin_*_overflow</span></code> family of intrinsics.</p>
+<p>You can instruct Clang to use libgcc_s with the <code class="docutils literal"><span class="pre">--rtlib=libgcc</span></code> flag.
+This is not supported on every platform.</p>
+</div>
+</div>
+<div class="section" id="atomics-library">
+<h3><a class="toc-backref" href="#id16">Atomics library</a><a class="headerlink" href="#atomics-library" title="Permalink to this headline">¶</a></h3>
+<p>If your program makes use of atomic operations and the compiler is not able
+to lower them all directly to machine instructions (because there either is
+no known suitable machine instruction or the operand is not known to be
+suitably aligned), a call to a runtime library <code class="docutils literal"><span class="pre">__atomic_*</span></code> function
+will be generated. A runtime library containing these atomics functions is
+necessary for such programs.</p>
+<div class="section" id="id1">
+<h4>compiler-rt (LLVM)<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>compiler-rt contains an implementation of an atomics library.</p>
+</div>
+<div class="section" id="libatomic-gnu">
+<h4>libatomic (GNU)<a class="headerlink" href="#libatomic-gnu" title="Permalink to this headline">¶</a></h4>
+<p>libgcc_s does not provide an implementation of an atomics library. Instead,
+<a class="reference external" href="https://gcc.gnu.org/wiki/Atomic/GCCMM">GCC’s libatomic library</a> can be
+used to supply these when using libgcc_s.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang does not currently automatically link against libatomic when using
+libgcc_s. You may need to manually add <code class="docutils literal"><span class="pre">-latomic</span></code> to support this
+configuration when using non-native atomic operations (if you see link errors
+referring to <code class="docutils literal"><span class="pre">__atomic_*</span></code> functions).</p>
+</div>
+</div>
+</div>
+<div class="section" id="unwind-library">
+<h3><a class="toc-backref" href="#id17">Unwind library</a><a class="headerlink" href="#unwind-library" title="Permalink to this headline">¶</a></h3>
+<p>The unwind library provides a family of <code class="docutils literal"><span class="pre">_Unwind_*</span></code> functions implementing
+the language-neutral stack unwinding portion of the Itanium C++ ABI
+(<a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#base-abi">Level I</a>).
+It is a dependency of the C++ ABI library, and sometimes is a dependency
+of other runtimes.</p>
+<div class="section" id="libunwind-llvm">
+<h4>libunwind (LLVM)<a class="headerlink" href="#libunwind-llvm" title="Permalink to this headline">¶</a></h4>
+<p>LLVM’s unwinder library can be obtained from subversion:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">llvm-src$ svn co http://llvm.org/svn/llvm-project/libunwind/trunk projects/libunwind</span>
+</pre></div>
+</div>
+<p>When checked out into projects/libunwind within an LLVM checkout,
+it should be automatically picked up by the LLVM build system.</p>
+<p>If using libc++abi, you may need to configure it to use libunwind
+rather than libgcc_s by passing <code class="docutils literal"><span class="pre">-DLIBCXXABI_USE_LLVM_UNWINDER=YES</span></code>
+to <code class="docutils literal"><span class="pre">cmake</span></code>. If libc++abi is configured to use some version of
+libunwind, that library will be implicitly linked into binaries that
+link to libc++abi.</p>
+</div>
+<div class="section" id="id2">
+<h4>libgcc_s (GNU)<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>libgcc_s has an integrated unwinder, and does not need an external unwind
+library to be provided.</p>
+</div>
+<div class="section" id="libunwind-nongnu-org">
+<h4>libunwind (nongnu.org)<a class="headerlink" href="#libunwind-nongnu-org" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the libunwind specification.
+See <a class="reference external" href="http://www.nongnu.org/libunwind">libunwind (nongnu.org)</a>.</p>
+</div>
+<div class="section" id="libunwind-pathscale">
+<h4>libunwind (PathScale)<a class="headerlink" href="#libunwind-pathscale" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the libunwind specification.
+See <a class="reference external" href="https://github.com/pathscale/libunwind">libunwind (pathscale)</a>.</p>
+</div>
+</div>
+<div class="section" id="sanitizer-runtime">
+<h3><a class="toc-backref" href="#id18">Sanitizer runtime</a><a class="headerlink" href="#sanitizer-runtime" title="Permalink to this headline">¶</a></h3>
+<p>The instrumentation added by Clang’s sanitizers (<code class="docutils literal"><span class="pre">-fsanitize=...</span></code>) implicitly
+makes calls to a runtime library, in order to maintain side state about the
+execution of the program and to issue diagnostic messages when a problem is
+detected.</p>
+<p>The only supported implementation of these runtimes is provided by LLVM’s
+compiler-rt, and the relevant portion of that library
+(<code class="docutils literal"><span class="pre">libclang_rt.<sanitizer>.<arch>.a</span></code>)
+will be implicitly linked when linking with a <code class="docutils literal"><span class="pre">-fsanitize=...</span></code> flag.</p>
+</div>
+<div class="section" id="c-standard-library">
+<h3><a class="toc-backref" href="#id19">C standard library</a><a class="headerlink" href="#c-standard-library" title="Permalink to this headline">¶</a></h3>
+<p>Clang supports a wide variety of
+<a class="reference external" href="http://en.cppreference.com/w/c">C standard library</a>
+implementations.</p>
+</div>
+<div class="section" id="c-abi-library">
+<h3><a class="toc-backref" href="#id20">C++ ABI library</a><a class="headerlink" href="#c-abi-library" title="Permalink to this headline">¶</a></h3>
+<p>The C++ ABI library provides an implementation of the library portion of
+the Itanium C++ ABI, covering both the
+<a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/abi.html">support functionality in the main Itanium C++ ABI document</a> and
+<a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-abi">Level II of the exception handling support</a>.
+References to the functions and objects in this library are implicitly
+generated by Clang when compiling C++ code.</p>
+<p>While it is possible to link C++ code using libstdc++ and code using libc++
+together into the same program (so long as you do not attempt to pass C++
+standard library objects across the boundary), it is not generally possible
+to have more than one C++ ABI library in a program.</p>
+<p>The version of the C++ ABI library used by Clang will be the one that the
+chosen C++ standard library was linked against. Several implementations are
+available:</p>
+<div class="section" id="libc-abi-llvm">
+<h4>libc++abi (LLVM)<a class="headerlink" href="#libc-abi-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="http://libcxxabi.llvm.org/">libc++abi</a> is LLVM’s implementation of this
+specification.</p>
+</div>
+<div class="section" id="libsupc-gnu">
+<h4>libsupc++ (GNU)<a class="headerlink" href="#libsupc-gnu" title="Permalink to this headline">¶</a></h4>
+<p>libsupc++ is GCC’s implementation of this specification. However, this
+library is only used when libstdc++ is linked statically. The dynamic
+library version of libstdc++ contains a copy of libsupc++.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang does not currently automatically link against libatomic when statically
+linking libstdc++. You may need to manually add <code class="docutils literal"><span class="pre">-lsupc++</span></code> to support this
+configuration when using <code class="docutils literal"><span class="pre">-static</span></code> or <code class="docutils literal"><span class="pre">-static-libstdc++</span></code>.</p>
+</div>
+</div>
+<div class="section" id="libcxxrt-pathscale">
+<h4>libcxxrt (PathScale)<a class="headerlink" href="#libcxxrt-pathscale" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the Itanium C++ ABI specification.
+See <a class="reference external" href="https://github.com/pathscale/libcxxrt">libcxxrt</a>.</p>
+</div>
+</div>
+<div class="section" id="id6">
+<h3><a class="toc-backref" href="#id21">C++ standard library</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
+<p>Clang supports use of either LLVM’s libc++ or GCC’s libstdc++ implementation
+of the <a class="reference external" href="http://en.cppreference.com/w/cpp">C++ standard library</a>.</p>
+<div class="section" id="libc-llvm">
+<h4>libc++ (LLVM)<a class="headerlink" href="#libc-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="http://libcxx.llvm.org/">libc++</a> is LLVM’s implementation of the C++
+standard library, aimed at being a complete implementation of the C++
+standards from C++11 onwards.</p>
+<p>You can instruct Clang to use libc++ with the <code class="docutils literal"><span class="pre">-stdlib=libc++</span></code> flag.</p>
+</div>
+<div class="section" id="libstdc-gnu">
+<h4>libstdc++ (GNU)<a class="headerlink" href="#libstdc-gnu" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://gcc.gnu.org/onlinedocs/libstdc++/">libstdc++</a> is GCC’s implementation
+of the C++ standard library. Clang supports a wide range of versions of
+libstdc++, from around version 4.2 onwards, and will implicitly work around
+some bugs in older versions of libstdc++.</p>
+<p>You can instruct Clang to use libstdc++ with the <code class="docutils literal"><span class="pre">-stdlib=libstdc++</span></code> flag.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="UsersManual.html">Clang Compiler User’s Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LanguageExtensions.html">Clang Language Extensions</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/Tooling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/Tooling.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/Tooling.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/Tooling.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,164 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="External Clang Examples" href="ExternalClangExamples.html" />
+ <link rel="prev" title="Frequently Asked Questions (FAQ)" href="FAQ.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Choosing the Right Interface for Your Application</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <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"><span class="doc">Clang Plugins</span></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"><span class="doc">LibTooling</span></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"><span class="doc">Clang tools</span></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" role="navigation" aria-label="bottom navigation">
+
+ <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" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,371 @@
+<!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>UndefinedBehaviorSanitizer — Clang 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="DataFlowSanitizer" href="DataFlowSanitizer.html" />
+ <link rel="prev" title="MemorySanitizer" href="MemorySanitizer.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>UndefinedBehaviorSanitizer</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="MemorySanitizer.html">MemorySanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DataFlowSanitizer.html">DataFlowSanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="undefinedbehaviorsanitizer">
+<h1>UndefinedBehaviorSanitizer<a class="headerlink" href="#undefinedbehaviorsanitizer" 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></li>
+<li><a class="reference internal" href="#available-checks" id="id4">Available checks</a><ul>
+<li><a class="reference internal" href="#volatile" id="id5">Volatile</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#minimal-runtime" id="id6">Minimal Runtime</a></li>
+<li><a class="reference internal" href="#stack-traces-and-report-symbolization" id="id7">Stack traces and report symbolization</a></li>
+<li><a class="reference internal" href="#issue-suppression" id="id8">Issue Suppression</a><ul>
+<li><a class="reference internal" href="#disabling-instrumentation-with-attribute-no-sanitize-undefined" id="id9">Disabling Instrumentation with <code class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></code></a></li>
+<li><a class="reference internal" href="#suppressing-errors-in-recompiled-code-blacklist" id="id10">Suppressing Errors in Recompiled Code (Blacklist)</a></li>
+<li><a class="reference internal" href="#runtime-suppressions" id="id11">Runtime suppressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-platforms" id="id12">Supported Platforms</a></li>
+<li><a class="reference internal" href="#current-status" id="id13">Current Status</a></li>
+<li><a class="reference internal" href="#additional-configuration" id="id14">Additional Configuration</a><ul>
+<li><a class="reference internal" href="#example" id="id15">Example</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#more-information" id="id16">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>UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector.
+UBSan modifies the program at compile-time to catch various kinds of undefined
+behavior during program execution, for example:</p>
+<ul class="simple">
+<li>Using misaligned or null pointer</li>
+<li>Signed integer overflow</li>
+<li>Conversion to, from, or between floating-point types which would
+overflow the destination</li>
+</ul>
+<p>See the full list of available <a class="reference internal" href="#ubsan-checks"><span class="std std-ref">checks</span></a> below.</p>
+<p>UBSan has an optional run-time library which provides better error reporting.
+The checks have small runtime cost and no impact on address space layout or ABI.</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>Use <code class="docutils literal"><span class="pre">clang++</span></code> to compile and link your program with <code class="docutils literal"><span class="pre">-fsanitize=undefined</span></code>
+flag. Make sure to use <code class="docutils literal"><span class="pre">clang++</span></code> (not <code class="docutils literal"><span class="pre">ld</span></code>) as a linker, so that your
+executable is linked with proper UBSan runtime libraries. You can use <code class="docutils literal"><span class="pre">clang</span></code>
+instead of <code class="docutils literal"><span class="pre">clang++</span></code> if you’re compiling/linking C code.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">%</span> cat test.cc
+<span class="go">int main(int argc, char **argv) {</span>
+<span class="go"> int k = 0x7fffffff;</span>
+<span class="go"> k += argc;</span>
+<span class="go"> return 0;</span>
+<span class="go">}</span>
+<span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>undefined test.cc
+<span class="gp">%</span> ./a.out
+<span class="go">test.cc:3:5: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'</span>
+</pre></div>
+</div>
+<p>You can enable only a subset of <a class="reference internal" href="#ubsan-checks"><span class="std std-ref">checks</span></a> offered by UBSan,
+and define the desired behavior for each kind of check:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">-fsanitize=...</span></code>: print a verbose error report and continue execution (default);</li>
+<li><code class="docutils literal"><span class="pre">-fno-sanitize-recover=...</span></code>: print a verbose error report and exit the program;</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize-trap=...</span></code>: execute a trap instruction (doesn’t require UBSan run-time support).</li>
+</ul>
+<p>For example if you compile/link your program as:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>signed-integer-overflow,null,alignment -fno-sanitize-recover<span class="o">=</span>null -fsanitize-trap<span class="o">=</span>alignment
+</pre></div>
+</div>
+<p>the program will continue execution after signed integer overflows, exit after
+the first invalid use of a null pointer, and trap after the first use of misaligned
+pointer.</p>
+</div>
+<div class="section" id="available-checks">
+<span id="ubsan-checks"></span><h2><a class="toc-backref" href="#id4">Available checks</a><a class="headerlink" href="#available-checks" title="Permalink to this headline">¶</a></h2>
+<p>Available checks are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal"><span class="pre">-fsanitize=alignment</span></code>: Use of a misaligned pointer or creation
+of a misaligned reference.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=bool</span></code>: Load of a <code class="docutils literal"><span class="pre">bool</span></code> value which is neither
+<code class="docutils literal"><span class="pre">true</span></code> nor <code class="docutils literal"><span class="pre">false</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=builtin</span></code>: Passing invalid values to compiler builtins.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=bounds</span></code>: Out of bounds array indexing, in cases
+where the array bound can be statically determined.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=enum</span></code>: Load of a value of an enumerated type which
+is not in the range of representable values for that enumerated
+type.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=float-cast-overflow</span></code>: Conversion to, from, or
+between floating-point types which would overflow the
+destination.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=float-divide-by-zero</span></code>: Floating point division by
+zero.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=function</span></code>: Indirect call of a function through a
+function pointer of the wrong type (Darwin/Linux, C++ and x86/x86_64
+only).</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=integer-divide-by-zero</span></code>: Integer division by zero.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=nonnull-attribute</span></code>: Passing null pointer as a function
+parameter which is declared to never be null.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=null</span></code>: Use of a null pointer or creation of a null
+reference.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=nullability-arg</span></code>: Passing null as a function parameter
+which is annotated with <code class="docutils literal"><span class="pre">_Nonnull</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=nullability-assign</span></code>: Assigning null to an lvalue which
+is annotated with <code class="docutils literal"><span class="pre">_Nonnull</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=nullability-return</span></code>: Returning null from a function with
+a return type annotated with <code class="docutils literal"><span class="pre">_Nonnull</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=object-size</span></code>: An attempt to potentially use bytes which
+the optimizer can determine are not part of the object being accessed.
+This will also detect some types of undefined behavior that may not
+directly access memory, but are provably incorrect given the size of
+the objects involved, such as invalid downcasts and calling methods on
+invalid pointers. These checks are made in terms of
+<code class="docutils literal"><span class="pre">__builtin_object_size</span></code>, and consequently may be able to detect more
+problems at higher optimization levels.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=pointer-overflow</span></code>: Performing pointer arithmetic which
+overflows.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=return</span></code>: In C++, reaching the end of a
+value-returning function without returning a value.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=returns-nonnull-attribute</span></code>: Returning null pointer
+from a function which is declared to never return null.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=shift</span></code>: 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 <code class="docutils literal"><span class="pre">-fsanitize=shift-base</span></code> or
+<code class="docutils literal"><span class="pre">-fsanitize=shift-exponent</span></code> to check only left-hand side or
+right-hand side of shift operation, respectively.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=signed-integer-overflow</span></code>: Signed integer overflow,
+including all the checks added by <code class="docutils literal"><span class="pre">-ftrapv</span></code>, and checking for
+overflow in signed division (<code class="docutils literal"><span class="pre">INT_MIN</span> <span class="pre">/</span> <span class="pre">-1</span></code>).</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=unreachable</span></code>: If control flow reaches an unreachable
+program point.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=unsigned-integer-overflow</span></code>: Unsigned integer
+overflows. Note that unlike signed integer overflow, unsigned integer
+is not undefined behavior. However, while it has well-defined semantics,
+it is often unintentional, so UBSan offers to catch it.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=vla-bound</span></code>: A variable-length array whose bound
+does not evaluate to a positive value.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=vptr</span></code>: 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 <code class="docutils literal"><span class="pre">-fno-rtti</span></code>. Link must be performed by <code class="docutils literal"><span class="pre">clang++</span></code>, not
+<code class="docutils literal"><span class="pre">clang</span></code>, to make sure C++-specific parts of the runtime library and C++
+standard libraries are present.</li>
+</ul>
+</div></blockquote>
+<dl class="docutils">
+<dt>You can also use the following check groups:</dt>
+<dd><ul class="first last simple">
+<li><code class="docutils literal"><span class="pre">-fsanitize=undefined</span></code>: All of the checks listed above other than
+<code class="docutils literal"><span class="pre">unsigned-integer-overflow</span></code> and the <code class="docutils literal"><span class="pre">nullability-*</span></code> checks.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=undefined-trap</span></code>: Deprecated alias of
+<code class="docutils literal"><span class="pre">-fsanitize=undefined</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=integer</span></code>: Checks for undefined or suspicious integer
+behavior (e.g. unsigned integer overflow).</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=nullability</span></code>: Enables <code class="docutils literal"><span class="pre">nullability-arg</span></code>,
+<code class="docutils literal"><span class="pre">nullability-assign</span></code>, and <code class="docutils literal"><span class="pre">nullability-return</span></code>. While violating
+nullability does not have undefined behavior, it is often unintentional,
+so UBSan offers to catch it.</li>
+</ul>
+</dd>
+</dl>
+<div class="section" id="volatile">
+<h3><a class="toc-backref" href="#id5">Volatile</a><a class="headerlink" href="#volatile" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal"><span class="pre">null</span></code>, <code class="docutils literal"><span class="pre">alignment</span></code>, <code class="docutils literal"><span class="pre">object-size</span></code>, and <code class="docutils literal"><span class="pre">vptr</span></code> checks do not apply
+to pointers to types with the <code class="docutils literal"><span class="pre">volatile</span></code> qualifier.</p>
+</div>
+</div>
+<div class="section" id="minimal-runtime">
+<h2><a class="toc-backref" href="#id6">Minimal Runtime</a><a class="headerlink" href="#minimal-runtime" title="Permalink to this headline">¶</a></h2>
+<p>There is a minimal UBSan runtime available suitable for use in production
+environments. This runtime has a small attack surface. It only provides very
+basic issue logging and deduplication, and does not support <code class="docutils literal"><span class="pre">-fsanitize=vptr</span></code>
+checking.</p>
+<p>To use the minimal runtime, add <code class="docutils literal"><span class="pre">-fsanitize-minimal-runtime</span></code> to the clang
+command line options. For example, if you’re used to compiling with
+<code class="docutils literal"><span class="pre">-fsanitize=undefined</span></code>, you could enable the minimal runtime with
+<code class="docutils literal"><span class="pre">-fsanitize=undefined</span> <span class="pre">-fsanitize-minimal-runtime</span></code>.</p>
+</div>
+<div class="section" id="stack-traces-and-report-symbolization">
+<h2><a class="toc-backref" href="#id7">Stack traces and report symbolization</a><a class="headerlink" href="#stack-traces-and-report-symbolization" title="Permalink to this headline">¶</a></h2>
+<p>If you want UBSan to print symbolized stack trace for each error report, you
+will need to:</p>
+<ol class="arabic simple">
+<li>Compile with <code class="docutils literal"><span class="pre">-g</span></code> and <code class="docutils literal"><span class="pre">-fno-omit-frame-pointer</span></code> to get proper debug
+information in your binary.</li>
+<li>Run your program with environment variable
+<code class="docutils literal"><span class="pre">UBSAN_OPTIONS=print_stacktrace=1</span></code>.</li>
+<li>Make sure <code class="docutils literal"><span class="pre">llvm-symbolizer</span></code> binary is in <code class="docutils literal"><span class="pre">PATH</span></code>.</li>
+</ol>
+</div>
+<div class="section" id="issue-suppression">
+<h2><a class="toc-backref" href="#id8">Issue Suppression</a><a class="headerlink" href="#issue-suppression" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is not expected to produce false positives.
+If you see one, look again; most likely it is a true positive!</p>
+<div class="section" id="disabling-instrumentation-with-attribute-no-sanitize-undefined">
+<h3><a class="toc-backref" href="#id9">Disabling Instrumentation with <code class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></code></a><a class="headerlink" href="#disabling-instrumentation-with-attribute-no-sanitize-undefined" title="Permalink to this headline">¶</a></h3>
+<p>You disable UBSan checks for particular functions with
+<code class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></code>. You can use all values of
+<code class="docutils literal"><span class="pre">-fsanitize=</span></code> flag in this attribute, e.g. if your function deliberately
+contains possible signed integer overflow, you can use
+<code class="docutils literal"><span class="pre">__attribute__((no_sanitize("signed-integer-overflow")))</span></code>.</p>
+<p>This attribute may not be
+supported by other compilers, so consider using it together with
+<code class="docutils literal"><span class="pre">#if</span> <span class="pre">defined(__clang__)</span></code>.</p>
+</div>
+<div class="section" id="suppressing-errors-in-recompiled-code-blacklist">
+<h3><a class="toc-backref" href="#id10">Suppressing Errors in Recompiled Code (Blacklist)</a><a class="headerlink" href="#suppressing-errors-in-recompiled-code-blacklist" title="Permalink to this headline">¶</a></h3>
+<p>UndefinedBehaviorSanitizer supports <code class="docutils literal"><span class="pre">src</span></code> and <code class="docutils literal"><span class="pre">fun</span></code> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><span class="doc">Sanitizer special case list</span></a>, that can be used to suppress error reports
+in the specified source files or functions.</p>
+</div>
+<div class="section" id="runtime-suppressions">
+<h3><a class="toc-backref" href="#id11">Runtime suppressions</a><a class="headerlink" href="#runtime-suppressions" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes you can suppress UBSan error reports for specific files, functions,
+or libraries without recompiling the code. You need to pass a path to
+suppression file in a <code class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></code> environment variable.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="nv">UBSAN_OPTIONS</span><span class="o">=</span><span class="nv">suppressions</span><span class="o">=</span>MyUBSan.supp
+</pre></div>
+</div>
+<p>You need to specify a <a class="reference internal" href="#ubsan-checks"><span class="std std-ref">check</span></a> you are suppressing and the
+bug location. For example:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>signed-integer-overflow:file-with-known-overflow.cpp
+alignment:function_doing_unaligned_access
+vptr:shared_object_with_vptr_failures.so
+</pre></div>
+</div>
+<p>There are several limitations:</p>
+<ul class="simple">
+<li>Sometimes your binary must have enough debug info and/or symbol table, so
+that the runtime could figure out source file or function name to match
+against the suppression.</li>
+<li>It is only possible to suppress recoverable checks. For the example above,
+you can additionally pass
+<code class="docutils literal"><span class="pre">-fsanitize-recover=signed-integer-overflow,alignment,vptr</span></code>, although
+most of UBSan checks are recoverable by default.</li>
+<li>Check groups (like <code class="docutils literal"><span class="pre">undefined</span></code>) can’t be used in suppressions file, only
+fine-grained checks are supported.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="supported-platforms">
+<h2><a class="toc-backref" href="#id12">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is supported on the following OS:</p>
+<ul class="simple">
+<li>Android</li>
+<li>Linux</li>
+<li>FreeBSD</li>
+<li>OS X 10.6 onwards</li>
+</ul>
+<p>and for the following architectures:</p>
+<ul class="simple">
+<li>i386/x86_64</li>
+<li>ARM</li>
+<li>AArch64</li>
+<li>PowerPC64</li>
+<li>MIPS/MIPS64</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id13">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is available on selected platforms starting from LLVM
+3.3. The test suite is integrated into the CMake build and can be run with
+<code class="docutils literal"><span class="pre">check-ubsan</span></code> command.</p>
+</div>
+<div class="section" id="additional-configuration">
+<h2><a class="toc-backref" href="#id14">Additional Configuration</a><a class="headerlink" href="#additional-configuration" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer adds static check data for each check unless it is
+in trap mode. This check data includes the full file name. The option
+<code class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=N</span></code> can be used to trim this
+information. If <code class="docutils literal"><span class="pre">N</span></code> is positive, file information emitted by
+UndefinedBehaviorSanitizer will drop the first <code class="docutils literal"><span class="pre">N</span></code> components from the file
+path. If <code class="docutils literal"><span class="pre">N</span></code> is negative, the last <code class="docutils literal"><span class="pre">N</span></code> components will be kept.</p>
+<div class="section" id="example">
+<h3><a class="toc-backref" href="#id15">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>For a file called <code class="docutils literal"><span class="pre">/code/library/file.cpp</span></code>, here is what would be emitted:
+* Default (No flag, or <code class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=0</span></code>): <code class="docutils literal"><span class="pre">/code/library/file.cpp</span></code>
+* <code class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=1</span></code>: <code class="docutils literal"><span class="pre">code/library/file.cpp</span></code>
+* <code class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=2</span></code>: <code class="docutils literal"><span class="pre">library/file.cpp</span></code>
+* <code class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=-1</span></code>: <code class="docutils literal"><span class="pre">file.cpp</span></code>
+* <code class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=-2</span></code>: <code class="docutils literal"><span class="pre">library/file.cpp</span></code></p>
+</div>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id16">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>From LLVM project blog:
+<a class="reference external" href="http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html">What Every C Programmer Should Know About Undefined Behavior</a></li>
+<li>From John Regehr’s <em>Embedded in Academia</em> blog:
+<a class="reference external" href="http://blog.regehr.org/archives/213">A Guide to Undefined Behavior in C and C++</a></li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="MemorySanitizer.html">MemorySanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DataFlowSanitizer.html">DataFlowSanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/UsersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/UsersManual.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/UsersManual.html (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/UsersManual.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,2904 @@
+<!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 6 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: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Assembling a Complete Toolchain" href="Toolchain.html" />
+ <link rel="prev" title="Clang 6.0.0 Release Notes" href="ReleaseNotes.html" />
+ </head>
+ <body role="document">
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 6 documentation</span></a></h1>
+ <h2 class="heading"><span>Clang Compiler Userâs Manual</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="ReleaseNotes.html">Clang 6.0.0 Release Notes</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Toolchain.html">Assembling a Complete Toolchain</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="id9">Introduction</a><ul>
+<li><a class="reference internal" href="#terminology" id="id10">Terminology</a></li>
+<li><a class="reference internal" href="#basic-usage" id="id11">Basic Usage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#command-line-options" id="id12">Command Line Options</a><ul>
+<li><a class="reference internal" href="#options-to-control-error-and-warning-messages" id="id13">Options to Control Error and Warning Messages</a><ul>
+<li><a class="reference internal" href="#formatting-of-diagnostics" id="id14">Formatting of Diagnostics</a></li>
+<li><a class="reference internal" href="#individual-warning-groups" id="id15">Individual Warning Groups</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#options-to-control-clang-crash-diagnostics" id="id16">Options to Control Clang Crash Diagnostics</a></li>
+<li><a class="reference internal" href="#options-to-emit-optimization-reports" id="id17">Options to Emit Optimization Reports</a><ul>
+<li><a class="reference internal" href="#current-limitations" id="id18">Current limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-options" id="id19">Other Options</a></li>
+<li><a class="reference internal" href="#configuration-files" id="id20">Configuration files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#language-and-target-independent-features" id="id21">Language and Target-Independent Features</a><ul>
+<li><a class="reference internal" href="#controlling-errors-and-warnings" id="id22">Controlling Errors and Warnings</a><ul>
+<li><a class="reference internal" href="#controlling-how-clang-displays-diagnostics" id="id23">Controlling How Clang Displays Diagnostics</a></li>
+<li><a class="reference internal" href="#diagnostic-mappings" id="id24">Diagnostic Mappings</a></li>
+<li><a class="reference internal" href="#diagnostic-categories" id="id25">Diagnostic Categories</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-command-line-flags" id="id26">Controlling Diagnostics via Command Line Flags</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-pragmas" id="id27">Controlling Diagnostics via Pragmas</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-in-system-headers" id="id28">Controlling Diagnostics in System Headers</a></li>
+<li><a class="reference internal" href="#enabling-all-diagnostics" id="id29">Enabling All Diagnostics</a></li>
+<li><a class="reference internal" href="#controlling-static-analyzer-diagnostics" id="id30">Controlling Static Analyzer Diagnostics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#precompiled-headers" id="id31">Precompiled Headers</a><ul>
+<li><a class="reference internal" href="#generating-a-pch-file" id="id32">Generating a PCH File</a></li>
+<li><a class="reference internal" href="#using-a-pch-file" id="id33">Using a PCH File</a></li>
+<li><a class="reference internal" href="#relocatable-pch-files" id="id34">Relocatable PCH Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-code-generation" id="id35">Controlling Code Generation</a></li>
+<li><a class="reference internal" href="#profile-guided-optimization" id="id36">Profile Guided Optimization</a><ul>
+<li><a class="reference internal" href="#differences-between-sampling-and-instrumentation" id="id37">Differences Between Sampling and Instrumentation</a></li>
+<li><a class="reference internal" href="#using-sampling-profilers" id="id38">Using Sampling Profilers</a><ul>
+<li><a class="reference internal" href="#sample-profile-formats" id="id39">Sample Profile Formats</a></li>
+<li><a class="reference internal" href="#sample-profile-text-format" id="id40">Sample Profile Text Format</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#profiling-with-instrumentation" id="id41">Profiling with Instrumentation</a></li>
+<li><a class="reference internal" href="#disabling-instrumentation" id="id42">Disabling Instrumentation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-debug-information" id="id43">Controlling Debug Information</a><ul>
+<li><a class="reference internal" href="#controlling-size-of-debug-information" id="id44">Controlling Size of Debug Information</a></li>
+<li><a class="reference internal" href="#controlling-macro-debug-info-generation" id="id45">Controlling Macro Debug Info Generation</a></li>
+<li><a class="reference internal" href="#controlling-debugger-tuning" id="id46">Controlling Debugger “Tuning”</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#comment-parsing-options" id="id47">Comment Parsing Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-language-features" id="id48">C Language Features</a><ul>
+<li><a class="reference internal" href="#extensions-supported-by-clang" id="id49">Extensions supported by clang</a></li>
+<li><a class="reference internal" href="#differences-between-various-standard-modes" id="id50">Differences between various standard modes</a></li>
+<li><a class="reference internal" href="#gcc-extensions-not-implemented-yet" id="id51">GCC extensions not implemented yet</a></li>
+<li><a class="reference internal" href="#intentionally-unsupported-gcc-extensions" id="id52">Intentionally unsupported GCC extensions</a></li>
+<li><a class="reference internal" href="#microsoft-extensions" id="id53">Microsoft extensions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#cxx" id="id54">C++ Language Features</a><ul>
+<li><a class="reference internal" href="#controlling-implementation-limits" id="id55">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-language-features" id="id56">Objective-C Language Features</a></li>
+<li><a class="reference internal" href="#objcxx" id="id57">Objective-C++ Language Features</a></li>
+<li><a class="reference internal" href="#openmp-features" id="id58">OpenMP Features</a><ul>
+<li><a class="reference internal" href="#id5" id="id59">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-features" id="id60">OpenCL Features</a><ul>
+<li><a class="reference internal" href="#opencl-specific-options" id="id61">OpenCL Specific Options</a></li>
+<li><a class="reference internal" href="#opencl-targets" id="id62">OpenCL Targets</a><ul>
+<li><a class="reference internal" href="#specific-targets" id="id63">Specific Targets</a></li>
+<li><a class="reference internal" href="#generic-targets" id="id64">Generic Targets</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-header" id="id65">OpenCL Header</a></li>
+<li><a class="reference internal" href="#opencl-extensions" id="id66">OpenCL Extensions</a></li>
+<li><a class="reference internal" href="#opencl-metadata" id="id67">OpenCL Metadata</a></li>
+<li><a class="reference internal" href="#opencl-specific-attributes" id="id68">OpenCL-Specific Attributes</a><ul>
+<li><a class="reference internal" href="#nosvm" id="id69">nosvm</a></li>
+<li><a class="reference internal" href="#opencl-unroll-hint" id="id70">opencl_unroll_hint</a></li>
+<li><a class="reference internal" href="#convergent" id="id71">convergent</a></li>
+<li><a class="reference internal" href="#noduplicate" id="id72">noduplicate</a></li>
+<li><a class="reference internal" href="#address-space" id="id73">address_space</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-builtins" id="id74">OpenCL builtins</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-specific-features-and-limitations" id="id75">Target-Specific Features and Limitations</a><ul>
+<li><a class="reference internal" href="#cpu-architectures-features-and-limitations" id="id76">CPU Architectures Features and Limitations</a><ul>
+<li><a class="reference internal" href="#x86" id="id77">X86</a></li>
+<li><a class="reference internal" href="#arm" id="id78">ARM</a></li>
+<li><a class="reference internal" href="#powerpc" id="id79">PowerPC</a></li>
+<li><a class="reference internal" href="#other-platforms" id="id80">Other platforms</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#operating-system-features-and-limitations" id="id81">Operating System Features and Limitations</a><ul>
+<li><a class="reference internal" href="#darwin-mac-os-x" id="id82">Darwin (Mac OS X)</a></li>
+<li><a class="reference internal" href="#windows" id="id83">Windows</a><ul>
+<li><a class="reference internal" href="#cygwin" id="id84">Cygwin</a></li>
+<li><a class="reference internal" href="#mingw32" id="id85">MinGW32</a></li>
+<li><a class="reference internal" href="#mingw-w64" id="id86">MinGW-w64</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-cl" id="id87">clang-cl</a><ul>
+<li><a class="reference internal" href="#id8" id="id88">Command-Line Options</a><ul>
+<li><a class="reference internal" href="#the-fallback-option" id="id89">The /fallback Option</a></li>
+</ul>
+</li>
+</ul>
+</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>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"><span class="doc">“Clang” CFE Internals Manual</span></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 one component in a complete toolchain for C family languages.
+A separate document describes the other pieces necessary to
+<a class="reference internal" href="Toolchain.html"><span class="doc">assemble a complete toolchain</span></a>.</p>
+<p>Clang is designed to support the C family of programming languages,
+which includes <a class="reference internal" href="#c"><span class="std std-ref">C</span></a>, <a class="reference internal" href="#objc"><span class="std std-ref">Objective-C</span></a>, <a class="reference internal" href="#cxx"><span class="std std-ref">C++</span></a>, and
+<a class="reference internal" href="#objcxx"><span class="std std-ref">Objective-C++</span></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"><span class="std std-ref">C Language</span></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"><span class="std std-ref">Objective-C Language</span></a>: ObjC 1, ObjC 2, ObjC 2.1, plus
+variants depending on base language.</li>
+<li><a class="reference internal" href="#cxx"><span class="std std-ref">C++ Language</span></a></li>
+<li><a class="reference internal" href="#objcxx"><span class="std std-ref">Objective C++ Language</span></a></li>
+<li><a class="reference internal" href="#opencl"><span class="std std-ref">OpenCL C Language</span></a>: v1.0, v1.1, v1.2, v2.0.</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"><span class="std std-ref">clang-cl</span></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"><span class="std std-ref">Target-Specific Features and
+Limitations</span></a> section for more details.</p>
+<p>The rest of the introduction introduces some basic <a class="reference internal" href="#terminology"><span class="std std-ref">compiler
+terminology</span></a> that is used throughout this manual and
+contains a basic <a class="reference internal" href="#basicusage"><span class="std std-ref">introduction to using Clang</span></a> as a
+command line compiler.</p>
+<div class="section" id="terminology">
+<span id="id1"></span><h3><a class="toc-backref" href="#id10">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="#id11">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="#id12">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"><code class="xref std std-option docutils literal"><span class="pre">-c</span></code></a>, <a class="reference internal" href="#cmdoption-g"><code class="xref std std-option docutils literal"><span class="pre">-g</span></code></a>, etc.</p>
+<div class="section" id="options-to-control-error-and-warning-messages">
+<h3><a class="toc-backref" href="#id13">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">
+<code class="descname">-Werror</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-werror" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warnings into errors.</p>
+</dd></dl>
+
+<p><code class="docutils literal"><span class="pre">-Werror=foo</span></code></p>
+<blockquote>
+<div>Turn warning “foo” into an error.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-wno-error">
+<code class="descname">-Wno-error</code><code class="descclassname">=foo</code><a class="headerlink" href="#cmdoption-wno-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warning “foo” into a warning even if <a class="reference internal" href="#cmdoption-werror"><code class="xref std std-option docutils literal"><span class="pre">-Werror</span></code></a> is specified.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wfoo">
+<code class="descname">-Wfoo</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wfoo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable warning “foo”.
+See the <a class="reference internal" href="DiagnosticsReference.html"><span class="doc">diagnostics reference</span></a> for a complete
+list of the warning flags that can be specified in this way.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wno-foo">
+<code class="descname">-Wno-foo</code><code class="descclassname"></code><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">
+<code class="descname">-w</code><code class="descclassname"></code><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">
+<code class="descname">-Weverything</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-weverything" title="Permalink to this definition">¶</a></dt>
+<dd><p><a class="reference internal" href="#diagnostics-enable-everything"><span class="std std-ref">Enable all diagnostics.</span></a></p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic">
+<code class="descname">-pedantic</code><code class="descclassname"></code><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">
+<code class="descname">-pedantic-errors</code><code class="descclassname"></code><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">
+<code class="descname">-Wsystem-headers</code><code class="descclassname"></code><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">
+<code class="descname">-ferror-limit</code><code class="descclassname">=123</code><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 <cite>-ferror-limit=0</cite>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-backtrace-limit">
+<code class="descname">-ftemplate-backtrace-limit</code><code class="descclassname">=123</code><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 <cite>-ftemplate-backtrace-limit=0</cite>.</p>
+</dd></dl>
+
+<div class="section" id="formatting-of-diagnostics">
+<span id="cl-diag-formatting"></span><h4><a class="toc-backref" href="#id14">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 not by a human,
+but by a program that wants consistent and easily parsable output. 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-default"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</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-default"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</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-default"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</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-default"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">2</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</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">
+<code class="descname">-fdiagnostics-format</code><code class="descclassname">=clang/msvc/vi</code><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-default"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>msvc</strong></dt>
+<dd><div class="first last highlight-default"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">11</span><span class="p">)</span> <span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>vi</strong></dt>
+<dd><div class="first last highlight-default"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">c</span> <span class="o">+</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span>
+</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 <code class="docutils literal"><span class="pre">[-Woption]</span></code> 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"><span class="std std-ref">warning group</span></a>
+option name when outputting a warning diagnostic. For example, in
+this output:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</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"><span class="std std-ref">-Wextra-tokens</span></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"><span class="std std-ref">#pragma GCC diagnostic</span></a>.</p>
+</dd>
+</dl>
+<span class="target" id="opt-fdiagnostics-show-category"></span><dl class="option">
+<dt id="cmdoption-fdiagnostics-show-category">
+<code class="descname">-fdiagnostics-show-category</code><code class="descclassname">=none/id/name</code><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-default"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span> <span class="p">[</span><span class="o">-</span><span class="n">Wformat</span><span class="p">]</span>
+<span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span> <span class="p">[</span><span class="o">-</span><span class="n">Wformat</span><span class="p">,</span><span class="mi">1</span><span class="p">]</span>
+<span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span> <span class="p">[</span><span class="o">-</span><span class="n">Wformat</span><span class="p">,</span><span class="n">Format</span> <span class="n">String</span><span class="p">]</span>
+</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-fsave-optimization-record">
+<dt><strong>-fsave-optimization-record</strong></dt>
+<dd><p class="first">Write optimization remarks to a YAML file.</p>
+<p class="last">This option, which defaults to off, controls whether Clang writes
+optimization reports to a YAML file. By recording diagnostics in a file,
+using a structured YAML format, users can parse or sort the remarks in a
+convenient way.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-foptimization-record-file">
+<dt><strong>-foptimization-record-file</strong></dt>
+<dd><p class="first">Control the file to which optimization reports are written.</p>
+<p>When optimization reports are being output (see
+<a class="reference internal" href="#opt-fsave-optimization-record"><span class="std std-ref">-fsave-optimization-record</span></a>), this
+option controls the file to which those reports are written.</p>
+<p class="last">If this option is not used, optimization records are output to a file named
+after the primary file being compiled. If that’s “foo.c”, for example,
+optimization records are output to “foo.opt.yaml”.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-show-hotness">
+<dt><strong>-f[no-]diagnostics-show-hotness</strong></dt>
+<dd><p class="first">Enable profile hotness information in diagnostic line.</p>
+<p>This option controls whether Clang prints the profile hotness associated
+with diagnostics in the presence of profile-guided optimization information.
+This is currently supported with optimization remarks (see
+<a class="reference internal" href="#rpass"><span class="std std-ref">Options to Emit Optimization Reports</span></a>). The hotness information
+allows users to focus on the hot optimization remarks that are likely to be
+more relevant for run-time performance.</p>
+<p>For example, in this output, the block containing the callsite of <cite>foo</cite> was
+executed 3000 times according to the profile data:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">s</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">7</span><span class="p">:</span><span class="mi">10</span><span class="p">:</span> <span class="n">remark</span><span class="p">:</span> <span class="n">foo</span> <span class="n">inlined</span> <span class="n">into</span> <span class="n">bar</span> <span class="p">(</span><span class="n">hotness</span><span class="p">:</span> <span class="mi">3000</span><span class="p">)</span> <span class="p">[</span><span class="o">-</span><span class="n">Rpass</span><span class="o">-</span><span class="n">analysis</span><span class="o">=</span><span class="n">inline</span><span class="p">]</span>
+ <span class="nb">sum</span> <span class="o">+=</span> <span class="n">foo</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">x</span> <span class="o">-</span> <span class="mi">2</span><span class="p">);</span>
+ <span class="o">^</span>
+</pre></div>
+</div>
+<p class="last">This option is implied when
+<a class="reference internal" href="#opt-fsave-optimization-record"><span class="std std-ref">-fsave-optimization-record</span></a> is used.
+Otherwise, it defaults to off.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-hotness-threshold">
+<dt><strong>-fdiagnostics-hotness-threshold</strong></dt>
+<dd><p class="first">Prevent optimization remarks from being output if they do not have at least
+this hotness value.</p>
+<p class="last">This option, which defaults to zero, controls the minimum hotness an
+optimization remark would need in order to be output by Clang. This is
+currently supported with optimization remarks (see <a class="reference internal" href="#rpass"><span class="std std-ref">Options to Emit
+Optimization Reports</span></a>) when profile hotness information in
+diagnostics is enabled (see
+<a class="reference internal" href="#opt-fdiagnostics-show-hotness"><span class="std std-ref">-fdiagnostics-show-hotness</span></a>).</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-default"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</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-default"><div class="highlight"><pre><span></span><span class="n">exprs</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">47</span><span class="p">:</span><span class="mi">15</span><span class="p">:{</span><span class="mi">47</span><span class="p">:</span><span class="mi">8</span><span class="o">-</span><span class="mi">47</span><span class="p">:</span><span class="mi">14</span><span class="p">}{</span><span class="mi">47</span><span class="p">:</span><span class="mi">17</span><span class="o">-</span><span class="mi">47</span><span class="p">:</span><span class="mi">24</span><span class="p">}:</span> <span class="n">error</span><span class="p">:</span> <span class="n">invalid</span> <span class="n">operands</span> <span class="n">to</span> <span class="n">binary</span> <span class="n">expression</span> <span class="p">(</span><span class="s1">'int *'</span> <span class="ow">and</span> <span class="s1">'_Complex float'</span><span class="p">)</span>
+ <span class="n">P</span> <span class="o">=</span> <span class="p">(</span><span class="n">P</span><span class="o">-</span><span class="mi">42</span><span class="p">)</span> <span class="o">+</span> <span class="n">Gamma</span><span class="o">*</span><span class="mi">4</span><span class="p">;</span>
+ <span class="o">~~~~~~</span> <span class="o">^</span> <span class="o">~~~~~~~</span>
+</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">
+<code class="descname">-fdiagnostics-parseable-fixits</code><code class="descclassname"></code><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-default"><div class="highlight"><pre><span></span><span class="n">fix</span><span class="o">-</span><span class="n">it</span><span class="p">:</span><span class="s2">"t.cpp"</span><span class="p">:{</span><span class="mi">7</span><span class="p">:</span><span class="mi">25</span><span class="o">-</span><span class="mi">7</span><span class="p">:</span><span class="mi">29</span><span class="p">}:</span><span class="s2">"Gamma"</span>
+</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">
+<code class="descname">-fno-elide-type</code><code class="descclassname"></code><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-default"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">cc</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">note</span><span class="p">:</span> <span class="n">candidate</span> <span class="n">function</span> <span class="ow">not</span> <span class="n">viable</span><span class="p">:</span> <span class="n">no</span> <span class="n">known</span> <span class="n">conversion</span> <span class="kn">from</span> <span class="s1">'vector<map<[...], map<float, [...]>>>'</span> <span class="n">to</span> <span class="s1">'vector<map<[...], map<double, [...]>>>'</span> <span class="k">for</span> <span class="mi">1</span><span class="n">st</span> <span class="n">argument</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>-fno-elide-type:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">cc</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">note</span><span class="p">:</span> <span class="n">candidate</span> <span class="n">function</span> <span class="ow">not</span> <span class="n">viable</span><span class="p">:</span> <span class="n">no</span> <span class="n">known</span> <span class="n">conversion</span> <span class="kn">from</span> <span class="s1">'vector<map<int, map<float, int>>>'</span> <span class="n">to</span> <span class="s1">'vector<map<int, map<double, int>>>'</span> <span class="k">for</span> <span class="mi">1</span><span class="n">st</span> <span class="n">argument</span><span class="p">;</span>
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-show-template-tree">
+<code class="descname">-fdiagnostics-show-template-tree</code><code class="descclassname"></code><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-default"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">cc</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">note</span><span class="p">:</span> <span class="n">candidate</span> <span class="n">function</span> <span class="ow">not</span> <span class="n">viable</span><span class="p">:</span> <span class="n">no</span> <span class="n">known</span> <span class="n">conversion</span> <span class="kn">from</span> <span class="s1">'vector<map<[...], map<float, [...]>>>'</span> <span class="n">to</span> <span class="s1">'vector<map<[...], map<double, [...]>>>'</span> <span class="k">for</span> <span class="mi">1</span><span class="n">st</span> <span class="n">argument</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>With <a class="reference internal" href="#cmdoption-fdiagnostics-show-template-tree"><code class="xref std std-option docutils literal"><span class="pre">-fdiagnostics-show-template-tree</span></code></a>:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">cc</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">note</span><span class="p">:</span> <span class="n">candidate</span> <span class="n">function</span> <span class="ow">not</span> <span class="n">viable</span><span class="p">:</span> <span class="n">no</span> <span class="n">known</span> <span class="n">conversion</span> <span class="k">for</span> <span class="mi">1</span><span class="n">st</span> <span class="n">argument</span><span class="p">;</span>
+ <span class="n">vector</span><span class="o"><</span>
+ <span class="nb">map</span><span class="o"><</span>
+ <span class="p">[</span><span class="o">...</span><span class="p">],</span>
+ <span class="nb">map</span><span class="o"><</span>
+ <span class="p">[</span><span class="nb">float</span> <span class="o">!=</span> <span class="n">double</span><span class="p">],</span>
+ <span class="p">[</span><span class="o">...</span><span class="p">]</span><span class="o">>>></span>
+</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="#id15">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">
+<code class="descname">-Wextra-tokens</code><code class="descclassname"></code><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-default"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+</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">
+<code class="descname">-Wambiguous-member-template</code><code class="descclassname"></code><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-default"><div class="highlight"><pre><span></span><span class="n">template</span><span class="o"><</span><span class="n">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">struct</span> <span class="nb">set</span><span class="p">{};</span>
+<span class="n">template</span><span class="o"><</span><span class="n">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">struct</span> <span class="n">trait</span> <span class="p">{</span> <span class="n">typedef</span> <span class="n">const</span> <span class="n">T</span><span class="o">&</span> <span class="nb">type</span><span class="p">;</span> <span class="p">};</span>
+<span class="n">struct</span> <span class="n">Value</span> <span class="p">{</span>
+ <span class="n">template</span><span class="o"><</span><span class="n">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">void</span> <span class="nb">set</span><span class="p">(</span><span class="n">typename</span> <span class="n">trait</span><span class="o"><</span><span class="n">T</span><span class="o">></span><span class="p">::</span><span class="nb">type</span> <span class="n">value</span><span class="p">)</span> <span class="p">{}</span>
+<span class="p">};</span>
+<span class="n">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">Value</span> <span class="n">v</span><span class="p">;</span>
+ <span class="n">v</span><span class="o">.</span><span class="n">set</span><span class="o"><</span><span class="n">double</span><span class="o">></span><span class="p">(</span><span class="mf">3.2</span><span class="p">);</span>
+<span class="p">}</span>
+</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">
+<code class="descname">-Wbind-to-temporary-copy</code><code class="descclassname"></code><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-default"><div class="highlight"><pre><span></span><span class="n">struct</span> <span class="n">NonCopyable</span> <span class="p">{</span>
+ <span class="n">NonCopyable</span><span class="p">();</span>
+<span class="n">private</span><span class="p">:</span>
+ <span class="n">NonCopyable</span><span class="p">(</span><span class="n">const</span> <span class="n">NonCopyable</span><span class="o">&</span><span class="p">);</span>
+<span class="p">};</span>
+<span class="n">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">const</span> <span class="n">NonCopyable</span><span class="o">&</span><span class="p">);</span>
+<span class="n">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">(</span><span class="n">NonCopyable</span><span class="p">());</span> <span class="o">//</span> <span class="n">Disallowed</span> <span class="ow">in</span> <span class="n">C</span><span class="o">++</span><span class="mi">98</span><span class="p">;</span> <span class="n">allowed</span> <span class="ow">in</span> <span class="n">C</span><span class="o">++</span><span class="mf">11.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">struct</span> <span class="n">NonCopyable2</span> <span class="p">{</span>
+ <span class="n">NonCopyable2</span><span class="p">();</span>
+ <span class="n">NonCopyable2</span><span class="p">(</span><span class="n">NonCopyable2</span><span class="o">&</span><span class="p">);</span>
+<span class="p">};</span>
+<span class="n">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">const</span> <span class="n">NonCopyable2</span><span class="o">&</span><span class="p">);</span>
+<span class="n">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">(</span><span class="n">NonCopyable2</span><span class="p">());</span> <span class="o">//</span> <span class="n">Disallowed</span> <span class="ow">in</span> <span class="n">C</span><span class="o">++</span><span class="mi">98</span><span class="p">;</span> <span class="n">allowed</span> <span class="ow">in</span> <span class="n">C</span><span class="o">++</span><span class="mf">11.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that if <code class="docutils literal"><span class="pre">NonCopyable2::NonCopyable2()</span></code> 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="#id16">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">
+<code class="descname">-fno-crash-diagnostics</code><code class="descclassname"></code><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>
+<p>Clang is also capable of generating preprocessed source file(s) and associated
+run script(s) even without a crash. This is specially useful when trying to
+generate a reproducer for warnings or errors while using modules.</p>
+<dl class="option">
+<dt id="cmdoption-gen-reproducer">
+<code class="descname">-gen-reproducer</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-gen-reproducer" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generates preprocessed source files, a reproducer script and if relevant, a
+cache containing: built module pcm’s and all headers needed to rebuilt the
+same modules.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="options-to-emit-optimization-reports">
+<span id="rpass"></span><h3><a class="toc-backref" href="#id17">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 <code class="docutils literal"><span class="pre">foo()</span></code> into <code class="docutils literal"><span class="pre">bar()</span></code>, 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 (<cite>-Rpass</cite>).</li>
+<li>When the pass fails to make a transformation (<cite>-Rpass-missed</cite>).</li>
+<li>When the pass determines whether or not to make a transformation
+(<cite>-Rpass-analysis</cite>).</li>
+</ol>
+<p>NOTE: Although the discussion below focuses on <cite>-Rpass</cite>, the exact
+same options apply to <cite>-Rpass-missed</cite> and <cite>-Rpass-analysis</cite>.</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></span><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
+<cite>-Rpass=.*</cite> (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>
+<p>Note that when using profile-guided optimization information, profile hotness
+information can be included in the remarks (see
+<a class="reference internal" href="#opt-fdiagnostics-show-hotness"><span class="std std-ref">-fdiagnostics-show-hotness</span></a>).</p>
+<div class="section" id="current-limitations">
+<h4><a class="toc-backref" href="#id18">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 <cite>-Rpass</cite> 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="#id19">Other Options</a><a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h3>
+<p>Clang options that don’t fit neatly into other categories.</p>
+<dl class="option">
+<dt id="cmdoption-mv">
+<code class="descname">-MV</code><code class="descclassname"></code><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 class="section" id="configuration-files">
+<h3><a class="toc-backref" href="#id20">Configuration files</a><a class="headerlink" href="#configuration-files" title="Permalink to this headline">¶</a></h3>
+<p>Configuration files group command-line options and allow all of them to be
+specified just by referencing the configuration file. They may be used, for
+example, to collect options required to tune compilation for particular
+target, such as -L, -I, -l, –sysroot, codegen options, etc.</p>
+<p>The command line option <cite>–config</cite> can be used to specify configuration
+file in a Clang invocation. For example:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">--</span><span class="n">config</span> <span class="o">/</span><span class="n">home</span><span class="o">/</span><span class="n">user</span><span class="o">/</span><span class="n">cfgs</span><span class="o">/</span><span class="n">testing</span><span class="o">.</span><span class="n">txt</span>
+<span class="n">clang</span> <span class="o">--</span><span class="n">config</span> <span class="n">debug</span><span class="o">.</span><span class="n">cfg</span>
+</pre></div>
+</div>
+<p>If the provided argument contains a directory separator, it is considered as
+a file path, and options are read from that file. Otherwise the argument is
+treated as a file name and is searched for sequentially in the directories:</p>
+<blockquote>
+<div><ul class="simple">
+<li>user directory,</li>
+<li>system directory,</li>
+<li>the directory where Clang executable resides.</li>
+</ul>
+</div></blockquote>
+<p>Both user and system directories for configuration files are specified during
+clang build using CMake parameters, CLANG_CONFIG_FILE_USER_DIR and
+CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first file found is used. It is
+an error if the required file cannot be found.</p>
+<p>Another way to specify a configuration file is to encode it in executable name.
+For example, if the Clang executable is named <cite>armv7l-clang</cite> (it may be a
+symbolic link to <cite>clang</cite>), then Clang will search for file <cite>armv7l.cfg</cite> in the
+directory where Clang resides.</p>
+<p>If a driver mode is specified in invocation, Clang tries to find a file specific
+for the specified mode. For example, if the executable file is named
+<cite>x86_64-clang-cl</cite>, Clang first looks for <cite>x86_64-cl.cfg</cite> and if it is not found,
+looks for <cite>x86_64.cfg</cite>.</p>
+<p>If the command line contains options that effectively change target architecture
+(these are -m32, -EL, and some others) and the configuration file starts with an
+architecture name, Clang tries to load the configuration file for the effective
+architecture. For example, invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">x86_64</span><span class="o">-</span><span class="n">clang</span> <span class="o">-</span><span class="n">m32</span> <span class="n">abc</span><span class="o">.</span><span class="n">c</span>
+</pre></div>
+</div>
+<p>causes Clang search for a file <cite>i368.cfg</cite> first, and if no such file is found,
+Clang looks for the file <cite>x86_64.cfg</cite>.</p>
+<p>The configuration file consists of command-line options specified on one or
+more lines. Lines composed of whitespace characters only are ignored as well as
+lines in which the first non-blank character is <cite>#</cite>. Long options may be split
+between several lines by a trailing backslash. Here is example of a
+configuration file:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Several options on line</span>
+<span class="o">-</span><span class="n">c</span> <span class="o">--</span><span class="n">target</span><span class="o">=</span><span class="n">x86_64</span><span class="o">-</span><span class="n">unknown</span><span class="o">-</span><span class="n">linux</span><span class="o">-</span><span class="n">gnu</span>
+
+<span class="c1"># Long option split between lines</span>
+<span class="o">-</span><span class="n">I</span><span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">gcc</span><span class="o">/</span><span class="n">x86_64</span><span class="o">-</span><span class="n">linux</span><span class="o">-</span><span class="n">gnu</span><span class="o">/</span><span class="mf">5.4</span><span class="o">.</span><span class="mi">0</span><span class="o">/../../../../</span>\
+<span class="n">include</span><span class="o">/</span><span class="n">c</span><span class="o">++/</span><span class="mf">5.4</span><span class="o">.</span><span class="mi">0</span>
+
+<span class="c1"># other config files may be included</span>
+<span class="nd">@linux</span><span class="o">.</span><span class="n">options</span>
+</pre></div>
+</div>
+<p>Files included by <cite>@file</cite> directives in configuration files are resolved
+relative to the including file. For example, if a configuration file
+<cite>~/.llvm/target.cfg</cite> contains the directive <cite>@os/linux.opts</cite>, the file
+<cite>linux.opts</cite> is searched for in the directory <cite>~/.llvm/os</cite>.</p>
+</div>
+</div>
+<div class="section" id="language-and-target-independent-features">
+<h2><a class="toc-backref" href="#id21">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="#id22">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="#id23">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"><span class="std std-ref">-fshow-column</span></a>,
+<a class="reference internal" href="#opt-fshow-source-location"><span class="std std-ref">-fshow-source-location</span></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"><span class="std std-ref">-fdiagnostics-show-option</span></a>].</li>
+<li>A <a class="reference internal" href="#diagnostics-categories"><span class="std std-ref">high-level category</span></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"><span class="std std-ref">-fdiagnostics-show-category</span></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"><span class="std std-ref">-fcaret-diagnostics</span></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"><span class="std std-ref">-fdiagnostics-fixit-info</span></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"><span class="std std-ref">-fdiagnostics-print-source-range-info</span></a>].</li>
+</ol>
+<p>For more information please see <a class="reference internal" href="#cl-diag-formatting"><span class="std std-ref">Formatting of
+Diagnostics</span></a>.</p>
+</div>
+<div class="section" id="diagnostic-mappings">
+<h4><a class="toc-backref" href="#id24">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="#id25">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"><span class="std std-ref">-fdiagnostics-show-category</span></a> option.
+When set to “<code class="docutils literal"><span class="pre">name</span></code>”, the category is printed textually in the
+diagnostic output. When it is set to “<code class="docutils literal"><span class="pre">id</span></code>”, a category number is
+printed. The mapping of category names to category id’s can be obtained
+by running ‘<code class="docutils literal"><span class="pre">clang</span> <span class="pre">--print-diagnostic-categories</span></code>‘.</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-command-line-flags">
+<h4><a class="toc-backref" href="#id26">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="#id27">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></span><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 <a class="reference internal" href="#cmdoption-wextra-tokens"><code class="xref std std-option docutils literal"><span class="pre">-Wextra-tokens</span></code></a> 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><span></span><span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// warning: extra tokens at end of #endif directive</span>
+
+<span class="cp">#pragma clang diagnostic push</span>
+<span class="cp">#pragma clang diagnostic ignored "-Wextra-tokens"</span>
+
+<span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// no warning</span>
+
+<span class="cp">#pragma clang diagnostic pop</span>
+</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></span><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 <code class="docutils literal"><span class="pre">#warning</span></code> and <code class="docutils literal"><span class="pre">#error</span></code> preprocessor
+directives, except that they may also be embedded into preprocessor macros via
+the C99 <code class="docutils literal"><span class="pre">_Pragma</span></code> operator, for example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><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="#id28">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 <code class="docutils literal"><span class="pre">-isystem</span></code>, but this can be overridden in
+several ways.</p>
+<p>The <code class="docutils literal"><span class="pre">system_header</span></code> 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><span></span><span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// warning: extra tokens at end of #endif directive</span>
+
+<span class="cp">#pragma clang system_header</span>
+
+<span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// no warning</span>
+</pre></div>
+</div>
+<p>The <cite>–system-header-prefix=</cite> and <cite>–no-system-header-prefix=</cite>
+command-line arguments can be used to override whether subsets of an include
+path are treated as system headers. When the name in a <code class="docutils literal"><span class="pre">#include</span></code> 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></span><span class="gp">$</span> clang -Ifoo -isystem bar --system-header-prefix<span class="o">=</span>x/ <span class="se">\</span>
+ --no-system-header-prefix<span class="o">=</span>x/y/
+</pre></div>
+</div>
+<p>Here, <code class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/a.h"</span></code> is treated as including a system header, even
+if the header is found in <code class="docutils literal"><span class="pre">foo</span></code>, and <code class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/y/b.h"</span></code> is treated
+as not including a system header, even if the header is found in
+<code class="docutils literal"><span class="pre">bar</span></code>.</p>
+<p>A <code class="docutils literal"><span class="pre">#include</span></code> 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="#id29">Enabling All Diagnostics</a><a class="headerlink" href="#enabling-all-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>In addition to the traditional <code class="docutils literal"><span class="pre">-W</span></code> flags, one can enable <strong>all</strong>
+diagnostics by passing <a class="reference internal" href="#cmdoption-weverything"><code class="xref std std-option docutils literal"><span class="pre">-Weverything</span></code></a>. This works as expected
+with
+<a class="reference internal" href="#cmdoption-werror"><code class="xref std std-option docutils literal"><span class="pre">-Werror</span></code></a>, and also includes the warnings from <a class="reference internal" href="#cmdoption-pedantic"><code class="xref std std-option docutils literal"><span class="pre">-pedantic</span></code></a>.</p>
+<p>Note that when combined with <a class="reference internal" href="#cmdoption-w"><code class="xref std std-option docutils literal"><span class="pre">-w</span></code></a> (which disables all warnings), that
+flag wins.</p>
+</div>
+<div class="section" id="controlling-static-analyzer-diagnostics">
+<h4><a class="toc-backref" href="#id30">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="#id31">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="#id32">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
+<cite>-x <language>-header</cite> option. This mirrors the interface in GCC
+for generating PCH files:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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="#id33">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"><code class="xref std std-option docutils literal"><span class="pre">-include</span></code></a>
+option is passed to <code class="docutils literal"><span class="pre">clang</span></code>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -include test.h test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal"><span class="pre">clang</span></code> driver will first check if a PCH file for <code class="docutils literal"><span class="pre">test.h</span></code> is
+available; if so, the contents of <code class="docutils literal"><span class="pre">test.h</span></code> (and the files it includes)
+will be processed from the PCH file. Otherwise, Clang falls back to
+directly processing the content of <code class="docutils literal"><span class="pre">test.h</span></code>. 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></span><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, <code class="docutils literal"><span class="pre">clang</span></code> will not automatically use the PCH file for
+<code class="docutils literal"><span class="pre">test.h</span></code> since <code class="docutils literal"><span class="pre">test.h</span></code> 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"><code class="xref std std-option docutils literal"><span class="pre">-include</span></code></a>.</p>
+</div>
+</div>
+<div class="section" id="relocatable-pch-files">
+<h4><a class="toc-backref" href="#id34">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 <code class="docutils literal"><span class="pre">mylib.h</span></code>
+that will be installed into <code class="docutils literal"><span class="pre">/usr/include</span></code>, create a subdirectory
+<code class="docutils literal"><span class="pre">build/usr/include</span></code> and place the header <code class="docutils literal"><span class="pre">mylib.h</span></code> into that
+subdirectory. If <code class="docutils literal"><span class="pre">mylib.h</span></code> depends on other headers, then they can be
+stored within <code class="docutils literal"><span class="pre">build/usr/include</span></code> in a way that mimics the installed
+location.</p>
+<p>Building a relocatable precompiled header requires two additional
+arguments. First, pass the <code class="docutils literal"><span class="pre">--relocatable-pch</span></code> flag to indicate that
+the resulting PCH file should be relocatable. Second, pass
+<cite>-isysroot /path/to/build</cite>, which makes all includes for your library
+relative to the build directory. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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, <code class="docutils literal"><span class="pre">mylib.h</span></code>
+can be found in <code class="docutils literal"><span class="pre">/usr/include/mylib.h</span></code>. If the headers are installed
+in some other system root, the <cite>-isysroot</cite> option can be used provide
+a different system root from which the headers will be based. For
+example, <cite>-isysroot /Developer/SDKs/MacOSX10.4u.sdk</cite> will look for
+<code class="docutils literal"><span class="pre">mylib.h</span></code> in <code class="docutils literal"><span class="pre">/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h</span></code>.</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="#id35">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"><code class="docutils literal"><span class="pre">-fsanitize=address</span></code>:
+<a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>, a memory error
+detector.</p>
+</li>
+<li><p id="opt-fsanitize-thread"><code class="docutils literal"><span class="pre">-fsanitize=thread</span></code>: <a class="reference internal" href="ThreadSanitizer.html"><span class="doc">ThreadSanitizer</span></a>, a data race detector.</p>
+</li>
+<li><p id="opt-fsanitize-memory"><code class="docutils literal"><span class="pre">-fsanitize=memory</span></code>: <a class="reference internal" href="MemorySanitizer.html"><span class="doc">MemorySanitizer</span></a>,
+a detector of uninitialized reads. Requires instrumentation of all
+program code.</p>
+</li>
+<li><p id="opt-fsanitize-undefined"><code class="docutils literal"><span class="pre">-fsanitize=undefined</span></code>: <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><span class="doc">UndefinedBehaviorSanitizer</span></a>,
+a fast and compatible undefined behavior checker.</p>
+</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=dataflow</span></code>: <a class="reference internal" href="DataFlowSanitizer.html"><span class="doc">DataFlowSanitizer</span></a>, a general data
+flow analysis.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=cfi</span></code>: <a class="reference internal" href="ControlFlowIntegrity.html"><span class="doc">control flow integrity</span></a>
+checks. Requires <code class="docutils literal"><span class="pre">-flto</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></code>: <a class="reference internal" href="SafeStack.html"><span class="doc">safe stack</span></a>
+protection against stack-based memory corruption errors.</li>
+</ul>
+<p>There are more fine-grained checks available: see
+the <a class="reference internal" href="UndefinedBehaviorSanitizer.html#ubsan-checks"><span class="std std-ref">list</span></a> of specific kinds of
+undefined behavior that can be detected and the <a class="reference internal" href="ControlFlowIntegrity.html#cfi-schemes"><span class="std std-ref">list</span></a>
+of control flow integrity schemes.</p>
+<p>The <code class="docutils literal"><span class="pre">-fsanitize=</span></code> argument must also be provided when linking, in
+order to link to the appropriate runtime library.</p>
+<p class="last">It is not possible to combine more than one of the <code class="docutils literal"><span class="pre">-fsanitize=address</span></code>,
+<code class="docutils literal"><span class="pre">-fsanitize=thread</span></code>, and <code class="docutils literal"><span class="pre">-fsanitize=memory</span></code> checkers in the same
+program.</p>
+</dd>
+</dl>
+<p><strong>-f[no-]sanitize-recover=check1,check2,...</strong></p>
+<p><strong>-f[no-]sanitize-recover=all</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by <code class="docutils literal"><span class="pre">-fsanitize=</span></code> 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
+<a class="reference internal" href="UndefinedBehaviorSanitizer.html"><span class="doc">UndefinedBehaviorSanitizer</span></a>,
+except for <code class="docutils literal"><span class="pre">-fsanitize=return</span></code> and <code class="docutils literal"><span class="pre">-fsanitize=unreachable</span></code>. Some
+sanitizers may not support recovery (or not support it by default
+e.g. <a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>), and always crash the program after the issue
+is detected.</p>
+<p>Note that the <code class="docutils literal"><span class="pre">-fsanitize-trap</span></code> 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
+<code class="docutils literal"><span class="pre">-fno-sanitize-trap</span></code>.</p>
+<p>For example, if a command line contains the flags <code class="docutils literal"><span class="pre">-fsanitize=undefined</span>
+<span class="pre">-fsanitize-trap=undefined</span></code>, the flag <code class="docutils literal"><span class="pre">-fsanitize-recover=alignment</span></code>
+will have no effect on its own; it will need to be accompanied by
+<code class="docutils literal"><span class="pre">-fno-sanitize-trap=alignment</span></code>.</p>
+</div></blockquote>
+<p><strong>-f[no-]sanitize-trap=check1,check2,...</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by the <code class="docutils literal"><span class="pre">-fsanitize=</span></code> 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 <a class="reference internal" href="ControlFlowIntegrity.html"><span class="doc">control flow integrity</span></a> schemes and <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><span class="doc">UndefinedBehaviorSanitizer</span></a>
+checks other than <code class="docutils literal"><span class="pre">vptr</span></code>. If this flag
+is supplied together with <code class="docutils literal"><span class="pre">-fsanitize=undefined</span></code>, the <code class="docutils literal"><span class="pre">vptr</span></code> sanitizer
+will be implicitly disabled.</p>
+<p>This flag is enabled by default for sanitizers in the <code class="docutils literal"><span class="pre">cfi</span></code> group.</p>
+</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-blacklist">
+<code class="descname">-fsanitize-blacklist</code><code class="descclassname">=/path/to/blacklist/file</code><a class="headerlink" href="#cmdoption-fsanitize-blacklist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable or modify sanitizer checks for objects (source files, functions,
+variables, types) listed in the file. See
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><span class="doc">Sanitizer special case list</span></a> for file format description.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-sanitize-blacklist">
+<code class="descname">-fno-sanitize-blacklist</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-sanitize-blacklist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t use blacklist file, if it was specified earlier in the command line.</p>
+</dd></dl>
+
+<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"><span class="doc">SanitizerCoverage</span></a> for more details.</div></blockquote>
+<p><strong>-f[no-]sanitize-stats</strong></p>
+<blockquote>
+<div>Enable simple statistics gathering for the enabled sanitizers.
+See <a class="reference internal" href="SanitizerStats.html"><span class="doc">SanitizerStats</span></a> for more details.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-undefined-trap-on-error">
+<code class="descname">-fsanitize-undefined-trap-on-error</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fsanitize-undefined-trap-on-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Deprecated alias for <code class="docutils literal"><span class="pre">-fsanitize-trap=undefined</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fsanitize-cfi-cross-dso">
+<code class="descname">-fsanitize-cfi-cross-dso</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fsanitize-cfi-cross-dso" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable cross-DSO control flow integrity checks. This flag modifies
+the behavior of sanitizers in the <code class="docutils literal"><span class="pre">cfi</span></code> group to allow checking
+of cross-DSO virtual and indirect calls.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fsanitize-cfi-icall-generalize-pointers">
+<code class="descname">-fsanitize-cfi-icall-generalize-pointers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fsanitize-cfi-icall-generalize-pointers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generalize pointers in return and argument types in function type signatures
+checked by Control Flow Integrity indirect call checking. See
+<a class="reference internal" href="ControlFlowIntegrity.html"><span class="doc">Control Flow Integrity</span></a> for more details.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstrict-vtable-pointers">
+<code class="descname">-fstrict-vtable-pointers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fstrict-vtable-pointers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable optimizations based on the strict rules for overwriting polymorphic
+C++ objects, i.e. the vptr is invariant during an object’s lifetime.
+This enables better devirtualization. Turned off by default, because it is
+still experimental.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ffast-math">
+<code class="descname">-ffast-math</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-ffast-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable fast-math mode. This defines the <code class="docutils literal"><span class="pre">__FAST_MATH__</span></code> preprocessor
+macro, and lets the compiler make aggressive, potentially-lossy assumptions
+about floating-point math. These include:</p>
+<ul class="simple">
+<li>Floating-point math obeys regular algebraic rules for real numbers (e.g.
+<code class="docutils literal"><span class="pre">+</span></code> and <code class="docutils literal"><span class="pre">*</span></code> are associative, <code class="docutils literal"><span class="pre">x/y</span> <span class="pre">==</span> <span class="pre">x</span> <span class="pre">*</span> <span class="pre">(1/y)</span></code>, and
+<code class="docutils literal"><span class="pre">(a</span> <span class="pre">+</span> <span class="pre">b)</span> <span class="pre">*</span> <span class="pre">c</span> <span class="pre">==</span> <span class="pre">a</span> <span class="pre">*</span> <span class="pre">c</span> <span class="pre">+</span> <span class="pre">b</span> <span class="pre">*</span> <span class="pre">c</span></code>),</li>
+<li>operands to floating-point operations are not equal to <code class="docutils literal"><span class="pre">NaN</span></code> and
+<code class="docutils literal"><span class="pre">Inf</span></code>, and</li>
+<li><code class="docutils literal"><span class="pre">+0</span></code> and <code class="docutils literal"><span class="pre">-0</span></code> are interchangeable.</li>
+</ul>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdenormal-fp-math">
+<code class="descname">-fdenormal-fp-math</code><code class="descclassname">=[values]</code><a class="headerlink" href="#cmdoption-fdenormal-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select which denormal numbers the code is permitted to require.</p>
+<p>Valid values are: <code class="docutils literal"><span class="pre">ieee</span></code>, <code class="docutils literal"><span class="pre">preserve-sign</span></code>, and <code class="docutils literal"><span class="pre">positive-zero</span></code>,
+which correspond to IEEE 754 denormal numbers, the sign of a
+flushed-to-zero number is preserved in the sign of 0, denormals are
+flushed to positive zero, respectively.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fwhole-program-vtables">
+<code class="descname">-fwhole-program-vtables</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fwhole-program-vtables" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable whole-program vtable optimizations, such as single-implementation
+devirtualization and virtual constant propagation, for classes with
+<a class="reference internal" href="LTOVisibility.html"><span class="doc">hidden LTO visibility</span></a>. Requires <code class="docutils literal"><span class="pre">-flto</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-assume-sane-operator-new">
+<code class="descname">-fno-assume-sane-operator-new</code><code class="descclassname"></code><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">
+<code class="descname">-ftrap-function</code><code class="descclassname">=[name]</code><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 <code class="docutils literal"><span class="pre">__builtin_trap()</span></code>.</p>
+<p>LLVM code generator translates <code class="docutils literal"><span class="pre">__builtin_trap()</span></code> to a trap
+instruction if it is supported by the target ISA. Otherwise, the
+builtin is translated into a call to <code class="docutils literal"><span class="pre">abort</span></code>. 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">
+<code class="descname">-ftls-model</code><code class="descclassname">=[model]</code><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: <code class="docutils literal"><span class="pre">global-dynamic</span></code>, <code class="docutils literal"><span class="pre">local-dynamic</span></code>,
+<code class="docutils literal"><span class="pre">initial-exec</span></code> and <code class="docutils literal"><span class="pre">local-exec</span></code>. The default value is
+<code class="docutils literal"><span class="pre">global-dynamic</span></code>. 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 <code class="docutils literal"><span class="pre">tls_model</span></code> attribute.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-femulated-tls">
+<code class="descname">-femulated-tls</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-femulated-tls" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select emulated TLS model, which overrides all -ftls-model choices.</p>
+<p>In emulated TLS mode, all access to TLS variables are converted to
+calls to __emutls_get_address in the runtime library.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mhwdiv">
+<code class="descname">-mhwdiv</code><code class="descclassname">=[values]</code><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: <code class="docutils literal"><span class="pre">arm</span></code>, <code class="docutils literal"><span class="pre">thumb</span></code> and <code class="docutils literal"><span class="pre">arm,thumb</span></code>.
+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">
+<code class="descname">-m</code><code class="descclassname">[no-]crc</code><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">
+<code class="descname">-mgeneral-regs-only</code><code class="descclassname"></code><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="option">
+<dt id="cmdoption-mcompact-branches">
+<code class="descname">-mcompact-branches</code><code class="descclassname">=[values]</code><a class="headerlink" href="#cmdoption-mcompact-branches" title="Permalink to this definition">¶</a></dt>
+<dd><p>Control the usage of compact branches for MIPSR6.</p>
+<p>Valid values are: <code class="docutils literal"><span class="pre">never</span></code>, <code class="docutils literal"><span class="pre">optimal</span></code> and <code class="docutils literal"><span class="pre">always</span></code>.
+The default value is <code class="docutils literal"><span class="pre">optimal</span></code> which generates compact branches
+when a delay slot cannot be filled. <code class="docutils literal"><span class="pre">never</span></code> disables the usage of
+compact branches and <code class="docutils literal"><span class="pre">always</span></code> generates compact branches whenever
+possible.</p>
+</dd></dl>
+
+<dl class="docutils">
+<dt><strong>-f[no-]max-type-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></span><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-type-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="#id36">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 <code class="docutils literal"><span class="pre">foo</span></code> is called more
+frequently than another function <code class="docutils literal"><span class="pre">bar</span></code> 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="#id37">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 <code class="docutils literal"><span class="pre">-fprofile-instr-generate</span></code> must be used with <code class="docutils literal"><span class="pre">-fprofile-instr-use</span></code>.
+Similarly, sampling profiles generated by external profilers must be
+converted and used with <code class="docutils literal"><span class="pre">-fprofile-sample-use</span></code>.</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="#id38">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 <code class="docutils literal"><span class="pre">-gline-tables-only</span></code> or <code class="docutils literal"><span class="pre">-g</span></code> 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></span><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></span><span class="gp">$</span> perf record -b ./code
+</pre></div>
+</div>
+<p>Note the use of the <code class="docutils literal"><span class="pre">-b</span></code> 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 <code class="docutils literal"><span class="pre">create_llvm_prof</span></code>.
+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 <code class="docutils literal"><span class="pre">perf.data</span></code> file to LLVM using
+the command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">perf.data</span></code> and the binary file <code class="docutils literal"><span class="pre">./code</span></code> and emit
+the profile data in <code class="docutils literal"><span class="pre">code.prof</span></code>. Note that if you ran <code class="docutils literal"><span class="pre">perf</span></code>
+without the <code class="docutils literal"><span class="pre">-b</span></code> flag, you need to use <code class="docutils literal"><span class="pre">--use_lbr=false</span></code> when
+calling <code class="docutils literal"><span class="pre">create_llvm_prof</span></code>.</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 <code class="docutils literal"><span class="pre">-gline-tables-only</span></code> and <code class="docutils literal"><span class="pre">-fprofile-sample-use</span></code>.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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="#id39">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. It can also be generated from
+the binary or gcov formats using the <code class="docutils literal"><span class="pre">llvm-profdata</span></code> tool.</li>
+<li>Binary encoding. This uses a more efficient encoding that yields smaller
+profile files. This is the format generated by the <code class="docutils literal"><span class="pre">create_llvm_prof</span></code> tool
+in <a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>.</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. This
+encoding is only generated by the <code class="docutils literal"><span class="pre">create_gcov</span></code> tool in
+<a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>. It can be read by LLVM and
+<code class="docutils literal"><span class="pre">llvm-profdata</span></code>, but it cannot be generated by either.</li>
+</ol>
+<p>If you are using Linux Perf to generate sampling profiles, you can use the
+conversion tool <code class="docutils literal"><span class="pre">create_llvm_prof</span></code> 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="#id40">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 <code class="docutils literal"><span class="pre">ProfileData</span></code> library in LLVM’s source tree
+(specifically, <code class="docutils literal"><span class="pre">include/llvm/ProfileData/SampleProfReader.h</span></code>).</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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>
+<span class="go"> offsetA[.discriminator]: fnA:num_of_total_samples</span>
+<span class="go"> offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]</span>
+<span class="go"> offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]</span>
+<span class="go"> offsetB[.discriminator]: fnB:num_of_total_samples</span>
+<span class="go"> offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]</span>
+</pre></div>
+</div>
+<p>This is a nested tree in which the indentation represents the nesting level
+of the inline stack. There are no blank lines in the file. And the spacing
+within a single line is fixed. Additional spaces will result in an error
+while reading the file.</p>
+<p>Any line starting with the ‘#’ character is completely ignored.</p>
+<p>Inlined calls are represented with indentation. The Inline stack is a
+stack of source locations in which the top of the stack represents the
+leaf function, and the bottom of the stack represents the actual
+symbol to which the instruction belongs.</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>There are two types of lines in the function body.</p>
+<ul class="simple">
+<li>Sampled line represents the profile information of a source location.
+<code class="docutils literal"><span class="pre">offsetN[.discriminator]:</span> <span class="pre">number_of_samples</span> <span class="pre">[fn5:num</span> <span class="pre">fn6:num</span> <span class="pre">...</span> <span class="pre">]</span></code></li>
+<li>Callsite line represents the profile information of an inlined callsite.
+<code class="docutils literal"><span class="pre">offsetA[.discriminator]:</span> <span class="pre">fnA:num_of_total_samples</span></code></li>
+</ul>
+<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 <code 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></code>.
+If the predicate <code class="docutils literal"><span class="pre">cond</span></code> is true 80% of the time, then the edge
+into function <code class="docutils literal"><span class="pre">foo</span></code> should be considered to be taken most of the
+time. But both calls to <code class="docutils literal"><span class="pre">foo</span></code> and <code class="docutils literal"><span class="pre">bar</span></code> 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
+<code class="docutils literal"><span class="pre">foo</span></code> and <code class="docutils literal"><span class="pre">bar</span></code> will be at the same line, but will have
+different discriminator values. This allows the compiler to correctly
+set edge weights into <code class="docutils literal"><span class="pre">foo</span></code> and <code class="docutils literal"><span class="pre">bar</span></code>.</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></span><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 <code class="docutils literal"><span class="pre">foo()</span></code>, <code class="docutils literal"><span class="pre">bar()</span></code> and <code class="docutils literal"><span class="pre">baz()</span></code>,
+with <code class="docutils literal"><span class="pre">baz()</span></code> being the relatively more frequently called target.</p>
+</li>
+</ol>
+<p>As an example, consider a program with the call chain <code class="docutils literal"><span class="pre">main</span> <span class="pre">-></span> <span class="pre">foo</span> <span class="pre">-></span> <span class="pre">bar</span></code>.
+When built with optimizations enabled, the compiler may inline the
+calls to <code class="docutils literal"><span class="pre">bar</span></code> and <code class="docutils literal"><span class="pre">foo</span></code> inside <code class="docutils literal"><span class="pre">main</span></code>. The generated profile
+could then be something like this:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">main:35504:0</span>
+<span class="go">1: _Z3foov:35504</span>
+<span class="go"> 2: _Z32bari:31977</span>
+<span class="go"> 1.1: 31977</span>
+<span class="go">2: 0</span>
+</pre></div>
+</div>
+<p>This profile indicates that there were a total of 35,504 samples
+collected in main. All of those were at line 1 (the call to <code class="docutils literal"><span class="pre">foo</span></code>).
+Of those, 31,977 were spent inside the body of <code class="docutils literal"><span class="pre">bar</span></code>. The last line
+of the profile (<code class="docutils literal"><span class="pre">2:</span> <span class="pre">0</span></code>) corresponds to line 2 inside <code class="docutils literal"><span class="pre">main</span></code>. No
+samples were collected there.</p>
+</div>
+</div>
+<div class="section" id="profiling-with-instrumentation">
+<h4><a class="toc-backref" href="#id41">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
+<code class="docutils literal"><span class="pre">-fprofile-instr-generate</span></code> option.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">default.profraw</span></code> file
+in the current directory. You can override that default by using option
+<code class="docutils literal"><span class="pre">-fprofile-instr-generate=</span></code> or by setting the <code class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></code>
+environment variable to specify an alternate file. If non-default file name
+is specified by both the environment variable and the command line option,
+the environment variable takes precedence. The file name pattern specified
+can include different modifiers: <code class="docutils literal"><span class="pre">%p</span></code>, <code class="docutils literal"><span class="pre">%h</span></code>, and <code class="docutils literal"><span class="pre">%m</span></code>.</p>
+<p>Any instance of <code class="docutils literal"><span class="pre">%p</span></code> 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></span><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>
+<p>The modifier <code class="docutils literal"><span class="pre">%h</span></code> can be used in scenarios where the same instrumented
+binary is run in multiple different host machines dumping profile data
+to a shared network based storage. The <code class="docutils literal"><span class="pre">%h</span></code> specifier will be substituted
+with the hostname so that profiles collected from different hosts do not
+clobber each other.</p>
+<p>While the use of <code class="docutils literal"><span class="pre">%p</span></code> specifier can reduce the likelihood for the profiles
+dumped from different processes to clobber each other, such clobbering can still
+happen because of the <code class="docutils literal"><span class="pre">pid</span></code> re-use by the OS. Another side-effect of using
+<code class="docutils literal"><span class="pre">%p</span></code> is that the storage requirement for raw profile data files is greatly
+increased. To avoid issues like this, the <code class="docutils literal"><span class="pre">%m</span></code> specifier can used in the profile
+name. When this specifier is used, the profiler runtime will substitute <code class="docutils literal"><span class="pre">%m</span></code>
+with a unique integer identifier associated with the instrumented binary. Additionally,
+multiple raw profiles dumped from different processes that share a file system (can be
+on different hosts) will be automatically merged by the profiler runtime during the
+dumping. If the program links in multiple instrumented shared libraries, each library
+will dump the profile data into its own profile data file (with its unique integer
+id embedded in the profile name). Note that the merging enabled by <code class="docutils literal"><span class="pre">%m</span></code> is for raw
+profile data generated by profiler runtime. The resulting merged “raw” profile data
+file still needs to be converted to a different format expected by the compiler (
+see step 3 below).</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"code-%m.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 <code class="docutils literal"><span class="pre">merge</span></code> command of the
+<code class="docutils literal"><span class="pre">llvm-profdata</span></code> tool to do this.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">-fprofile-instr-use</span></code> option to specify the
+collected profile data.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><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 using an alternative instrumentation method can be
+controlled by the GCC-compatible flags <code class="docutils literal"><span class="pre">-fprofile-generate</span></code> and
+<code class="docutils literal"><span class="pre">-fprofile-use</span></code>. 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">
+<code class="descname">-fprofile-generate</code><code class="descclassname">[=<dirname>]</code><a class="headerlink" href="#cmdoption-fprofile-generate" title="Permalink to this definition">¶</a></dt>
+<dd><blockquote>
+<div><p>The <code class="docutils literal"><span class="pre">-fprofile-generate</span></code> and <code class="docutils literal"><span class="pre">-fprofile-generate=</span></code> flags will use
+an alterantive instrumentation method for profile generation. When
+given a directory name, it generates the profile file
+<code class="docutils literal"><span class="pre">default_%m.profraw</span></code> in the directory named <code class="docutils literal"><span class="pre">dirname</span></code> if specified.
+If <code class="docutils literal"><span class="pre">dirname</span></code> does not exist, it will be created at runtime. <code class="docutils literal"><span class="pre">%m</span></code> specifier
+will be substibuted with a unique id documented in step 2 above. In other words,
+with <code class="docutils literal"><span class="pre">-fprofile-generate[=<dirname>]</span></code> option, the “raw” profile data automatic
+merging is turned on by default, so there will no longer any risk of profile
+clobbering from different running processes. For example,</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -fprofile-generate<span class="o">=</span>yyy/zzz code.cc -o code
+</pre></div>
+</div>
+<p>When <code class="docutils literal"><span class="pre">code</span></code> is executed, the profile will be written to the file
+<code class="docutils literal"><span class="pre">yyy/zzz/default_xxxx.profraw</span></code>.</p>
+<p>To generate the profile data file with the compiler readable format, the
+<code class="docutils literal"><span class="pre">llvm-profdata</span></code> tool can be used with the profile directory as the input:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>code.profdata yyy/zzz/
+</pre></div>
+</div>
+</div></blockquote>
+</div></blockquote>
+<p>If the user wants to turn off the auto-merging feature, or simply override the
+the profile dumping path specified at command line, the environment variable
+<code class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></code> can still be used to override
+the directory and filename for the profile file at runtime.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fprofile-use">
+<code class="descname">-fprofile-use</code><code class="descclassname">[=<pathname>]</code><a class="headerlink" href="#cmdoption-fprofile-use" title="Permalink to this definition">¶</a></dt>
+<dd><p>Without any other arguments, <code class="docutils literal"><span class="pre">-fprofile-use</span></code> behaves identically to
+<code class="docutils literal"><span class="pre">-fprofile-instr-use</span></code>. Otherwise, if <code class="docutils literal"><span class="pre">pathname</span></code> is the full path to a
+profile file, it reads from that file. If <code class="docutils literal"><span class="pre">pathname</span></code> is a directory name,
+it reads from <code class="docutils literal"><span class="pre">pathname/default.profdata</span></code>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="disabling-instrumentation">
+<h4><a class="toc-backref" href="#id42">Disabling Instrumentation</a><a class="headerlink" href="#disabling-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>In certain situations, it may be useful to disable profile generation or use
+for specific files in a build, without affecting the main compilation flags
+used for the other files in the project.</p>
+<p>In these cases, you can use the flag <code class="docutils literal"><span class="pre">-fno-profile-instr-generate</span></code> (or
+<code class="docutils literal"><span class="pre">-fno-profile-generate</span></code>) to disable profile generation, and
+<code class="docutils literal"><span class="pre">-fno-profile-instr-use</span></code> (or <code class="docutils literal"><span class="pre">-fno-profile-use</span></code>) to disable profile use.</p>
+<p>Note that these flags should appear after the corresponding profile
+flags to have an effect.</p>
+</div>
+</div>
+<div class="section" id="controlling-debug-information">
+<h3><a class="toc-backref" href="#id43">Controlling Debug Information</a><a class="headerlink" href="#controlling-debug-information" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="controlling-size-of-debug-information">
+<h4><a class="toc-backref" href="#id44">Controlling Size of Debug Information</a><a class="headerlink" href="#controlling-size-of-debug-information" title="Permalink to this headline">¶</a></h4>
+<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">
+<code class="descname">-g0</code><code class="descclassname"></code><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">
+<code class="descname">-gline-tables-only</code><code class="descclassname"></code><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 <code class="docutils literal"><span class="pre">gdb</span></code> or <code class="docutils literal"><span class="pre">addr2line</span></code>). 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">
+<code class="descname">-fstandalone-debug</code><code class="descclassname"></code><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">
+<code class="descname">-fno-standalone-debug</code><code class="descclassname"></code><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">
+<code class="descname">-g</code><code class="descclassname"></code><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="controlling-macro-debug-info-generation">
+<h4><a class="toc-backref" href="#id45">Controlling Macro Debug Info Generation</a><a class="headerlink" href="#controlling-macro-debug-info-generation" title="Permalink to this headline">¶</a></h4>
+<p>Debug info for C preprocessor macros increases the size of debug information in
+the binary. Macro debug info generated by Clang can be controlled by the flags
+listed below.</p>
+<dl class="option">
+<dt id="cmdoption-fdebug-macro">
+<code class="descname">-fdebug-macro</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fdebug-macro" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate debug info for preprocessor macros. This flag is discarded when
+<strong>-g0</strong> is enabled.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-debug-macro">
+<code class="descname">-fno-debug-macro</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-debug-macro" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not generate debug info for preprocessor macros (default).</p>
+</dd></dl>
+
+</div>
+<div class="section" id="controlling-debugger-tuning">
+<h4><a class="toc-backref" href="#id46">Controlling Debugger “Tuning”</a><a class="headerlink" href="#controlling-debugger-tuning" title="Permalink to this headline">¶</a></h4>
+<p>While Clang generally emits standard DWARF debug info (<a class="reference external" href="http://dwarfstd.org">http://dwarfstd.org</a>),
+different debuggers may know how to take advantage of different specific DWARF
+features. You can “tune” the debug info for one of several different debuggers.</p>
+<dl class="option">
+<dt id="cmdoption-ggdb">
+<code class="descname">-ggdb</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-glldb</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-gsce</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-ggdb" title="Permalink to this definition">¶</a></dt>
+<dd><p>Tune the debug info for the <code class="docutils literal"><span class="pre">gdb</span></code>, <code class="docutils literal"><span class="pre">lldb</span></code>, or Sony PlayStation®
+debugger, respectively. Each of these options implies <strong>-g</strong>. (Therefore, if
+you want both <strong>-gline-tables-only</strong> and debugger tuning, the tuning option
+must come first.)</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="comment-parsing-options">
+<h3><a class="toc-backref" href="#id47">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 <code class="docutils literal"><span class="pre">//</span></code> and
+<code class="docutils literal"><span class="pre">/*</span></code>.</p>
+<dl class="option">
+<dt id="cmdoption-wdocumentation">
+<code class="descname">-Wdocumentation</code><code class="descclassname"></code><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 <code class="docutils literal"><span class="pre">\param</span></code> commands name parameters that actually
+present in the function signature, checking that <code class="docutils literal"><span class="pre">\returns</span></code> is used only on
+functions that actually return a value etc.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wno-documentation-unknown-command">
+<code class="descname">-Wno-documentation-unknown-command</code><code class="descclassname"></code><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">
+<code class="descname">-fparse-all-comments</code><code class="descclassname"></code><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 <code class="docutils literal"><span class="pre">//</span></code> and <code class="docutils literal"><span class="pre">/*</span></code>).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fcomment-block-commands">
+<code class="descname">-fcomment-block-commands</code><code class="descclassname">=[commands]</code><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. <code class="docutils literal"><span class="pre">-fcomment-block-commands=foo,bar</span></code> defines
+custom commands <code class="docutils literal"><span class="pre">\foo</span></code> and <code class="docutils literal"><span class="pre">\bar</span></code>.</p>
+<p>It is also possible to use <code class="docutils literal"><span class="pre">-fcomment-block-commands</span></code> several times; e.g.
+<code class="docutils literal"><span class="pre">-fcomment-block-commands=foo</span> <span class="pre">-fcomment-block-commands=bar</span></code> 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="#id48">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="#id49">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"><span class="doc">Clang Language Extensions</span></a>.</p>
+</div>
+<div class="section" id="differences-between-various-standard-modes">
+<h3><a class="toc-backref" href="#id50">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
+<code class="docutils literal"><span class="pre">-pedantic-errors</span></code> to request an error if a feature from a later standard
+revision is used in an earlier mode.</p>
+<p>Differences between all <code class="docutils literal"><span class="pre">c*</span></code> and <code class="docutils literal"><span class="pre">gnu*</span></code> modes:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">c*</span></code> modes define “<code class="docutils literal"><span class="pre">__STRICT_ANSI__</span></code>”.</li>
+<li>Target-specific defines not prefixed by underscores, like “linux”,
+are defined in <code class="docutils literal"><span class="pre">gnu*</span></code> modes.</li>
+<li>Trigraphs default to being off in <code class="docutils literal"><span class="pre">gnu*</span></code> modes; they can be enabled by
+the -trigraphs option.</li>
+<li>The parser recognizes “asm” and “typeof” as keywords in <code class="docutils literal"><span class="pre">gnu*</span></code> modes;
+the variants “<code class="docutils literal"><span class="pre">__asm__</span></code>” and “<code class="docutils literal"><span class="pre">__typeof__</span></code>” are recognized in all
+modes.</li>
+<li>The Apple “blocks” extension is recognized by default in <code class="docutils literal"><span class="pre">gnu*</span></code> 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. <code class="docutils literal"><span class="pre">c*</span></code> modes are strictly compliant and treat these as VLAs.</li>
+</ul>
+<p>Differences between <code class="docutils literal"><span class="pre">*89</span></code> and <code class="docutils literal"><span class="pre">*99</span></code> modes:</p>
+<ul class="simple">
+<li>The <code class="docutils literal"><span class="pre">*99</span></code> modes default to implementing “inline” as specified in C99,
+while the <code class="docutils literal"><span class="pre">*89</span></code> modes implement the GNU version. This can be
+overridden for individual functions with the <code class="docutils literal"><span class="pre">__gnu_inline__</span></code>
+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: “<code 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></code>”.)</li>
+<li><code class="docutils literal"><span class="pre">__STDC_VERSION__</span></code> is not defined in <code class="docutils literal"><span class="pre">*89</span></code> modes.</li>
+<li>“inline” is not recognized as a keyword in c89 mode.</li>
+<li>“restrict” is not recognized as a keyword in <code class="docutils literal"><span class="pre">*89</span></code> modes.</li>
+<li>Commas are allowed in integer constant expressions in <code class="docutils literal"><span class="pre">*99</span></code> modes.</li>
+<li>Arrays which are not lvalues are not implicitly promoted to pointers
+in <code class="docutils literal"><span class="pre">*89</span></code> modes.</li>
+<li>Some warnings are different.</li>
+</ul>
+<p>Differences between <code class="docutils literal"><span class="pre">*99</span></code> and <code class="docutils literal"><span class="pre">*11</span></code> modes:</p>
+<ul class="simple">
+<li>Warnings for use of C11 features are disabled.</li>
+<li><code class="docutils literal"><span class="pre">__STDC_VERSION__</span></code> is defined to <code class="docutils literal"><span class="pre">201112L</span></code> rather than <code class="docutils literal"><span class="pre">199901L</span></code>.</li>
+</ul>
+<p>c94 mode is identical to c89 mode except that digraphs are enabled in
+c94 mode (FIXME: And <code class="docutils literal"><span class="pre">__STDC_VERSION__</span></code> should be defined!).</p>
+</div>
+<div class="section" id="gcc-extensions-not-implemented-yet">
+<h3><a class="toc-backref" href="#id51">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 decimal floating point types (<code class="docutils literal"><span class="pre">_Decimal32</span></code> and
+friends) or fixed-point types (<code class="docutils literal"><span class="pre">_Fract</span></code> 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></span><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 only supports global register variables when the register specified
+is non-allocatable (e.g. the stack pointer). Support for general global
+register variables 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
+<code class="docutils literal"><span class="pre">__builtin_va_arg_pack</span></code>/<code class="docutils literal"><span class="pre">__builtin_va_arg_pack_len</span></code>. 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"><span class="std std-ref">C++ Language Features</span></a>. Also, this
+list does not include bugs in mostly-implemented features; please see
+the <a class="reference external" href="https://bugs.llvm.org/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="#id52">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 <code class="docutils literal"><span class="pre">__builtin_apply</span></code> 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="#id53">Microsoft extensions</a><a class="headerlink" href="#microsoft-extensions" title="Permalink to this headline">¶</a></h3>
+<p>clang has support for many extensions from Microsoft Visual C++. To enable these
+extensions, use the <code class="docutils literal"><span class="pre">-fms-extensions</span></code> command-line option. This is the default
+for Windows targets. Clang does not implement every pragma or declspec provided
+by MSVC, but the popular ones, such as <code class="docutils literal"><span class="pre">__declspec(dllexport)</span></code> and <code class="docutils literal"><span class="pre">#pragma</span>
+<span class="pre">comment(lib)</span></code> are well supported.</p>
+<p>clang has a <code class="docutils literal"><span class="pre">-fms-compatibility</span></code> 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><code class="docutils literal"><span class="pre">-fdelayed-template-parsing</span></code> 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>
+<p>For compatibility with existing code that compiles with MSVC, clang defines the
+<code class="docutils literal"><span class="pre">_MSC_VER</span></code> and <code class="docutils literal"><span class="pre">_MSC_FULL_VER</span></code> macros. These default to the values of 1800
+and 180000000 respectively, making clang look like an early release of Visual
+C++ 2013. The <code class="docutils literal"><span class="pre">-fms-compatibility-version=</span></code> flag overrides these values. It
+accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC
+compatibility version makes clang behave more like that version of MSVC. For
+example, <code class="docutils literal"><span class="pre">-fms-compatibility-version=19</span></code> will enable C++14 features and define
+<code class="docutils literal"><span class="pre">char16_t</span></code> and <code class="docutils literal"><span class="pre">char32_t</span></code> as builtin types.</p>
+</div>
+</div>
+<div class="section" id="cxx">
+<span id="id3"></span><h2><a class="toc-backref" href="#id54">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="#id55">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">
+<code class="descname">-fbracket-depth</code><code class="descclassname">=N</code><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">
+<code class="descname">-fconstexpr-depth</code><code class="descclassname">=N</code><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">
+<code class="descname">-ftemplate-depth</code><code class="descclassname">=N</code><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">
+<code class="descname">-foperator-arrow-depth</code><code class="descclassname">=N</code><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="#id56">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="#id57">Objective-C++ Language Features</a><a class="headerlink" href="#objcxx" title="Permalink to this headline">¶</a></h2>
+</div>
+<div class="section" id="openmp-features">
+<span id="openmp"></span><h2><a class="toc-backref" href="#id58">OpenMP Features</a><a class="headerlink" href="#openmp-features" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports all OpenMP 3.1 directives and clauses. In addition, some
+features of OpenMP 4.0 are supported. For example, <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">simd</span></code>,
+<code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">for</span> <span class="pre">simd</span></code>, <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">parallel</span> <span class="pre">for</span> <span class="pre">simd</span></code> directives, extended
+set of atomic constructs, <code class="docutils literal"><span class="pre">proc_bind</span></code> clause for all parallel-based
+directives, <code class="docutils literal"><span class="pre">depend</span></code> clause for <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">task</span></code> directive (except for
+array sections), <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">cancel</span></code> and <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">cancellation</span> <span class="pre">point</span></code>
+directives, and <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">taskgroup</span></code> directive.</p>
+<p>Use <cite>-fopenmp</cite> to enable OpenMP. Support for OpenMP can be disabled with
+<cite>-fno-openmp</cite>.</p>
+<p>Use <cite>-fopenmp-simd</cite> to enable OpenMP simd features only, without linking
+the runtime library; for combined constructs
+(e.g. <code class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">parallel</span> <span class="pre">for</span> <span class="pre">simd</span></code>) the non-simd directives and clauses
+will be ignored. This can be disabled with <cite>-fno-openmp-simd</cite>.</p>
+<div class="section" id="id5">
+<h3><a class="toc-backref" href="#id59">Controlling implementation limits</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fopenmp-use-tls">
+<code class="descname">-fopenmp-use-tls</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fopenmp-use-tls" title="Permalink to this definition">¶</a></dt>
+<dd><p>Controls code generation for OpenMP threadprivate variables. In presence of
+this option all threadprivate variables are generated the same way as thread
+local variables, using TLS support. If <cite>-fno-openmp-use-tls</cite>
+is provided or target does not support TLS, code generation for threadprivate
+variables relies on OpenMP runtime library.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="opencl-features">
+<span id="opencl"></span><h2><a class="toc-backref" href="#id60">OpenCL Features</a><a class="headerlink" href="#opencl-features" title="Permalink to this headline">¶</a></h2>
+<p>Clang can be used to compile OpenCL kernels for execution on a device
+(e.g. GPU). It is possible to compile the kernel into a binary (e.g. for AMD or
+Nvidia targets) that can be uploaded to run directly on a device (e.g. using
+<a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111">clCreateProgramWithBinary</a>) or
+into generic bitcode files loadable into other toolchains.</p>
+<p>Compiling to a binary using the default target from the installation can be done
+as follows:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"kernel void k(){}"</span> > test.cl
+<span class="gp">$</span> clang test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Compiling for a specific target can be done by specifying the triple corresponding
+to the target, for example:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target nvptx64-unknown-unknown test.cl
+<span class="gp">$</span> clang -target amdgcn-amd-amdhsa-opencl test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Compiling to bitcode can be done as follows:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -c -emit-llvm test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>This will produce a generic test.bc file that can be used in vendor toolchains
+to perform machine code generation.</p>
+<p>Clang currently supports OpenCL C language standards up to v2.0.</p>
+<div class="section" id="opencl-specific-options">
+<h3><a class="toc-backref" href="#id61">OpenCL Specific Options</a><a class="headerlink" href="#opencl-specific-options" title="Permalink to this headline">¶</a></h3>
+<p>Most of the OpenCL build options from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200">the specification v2.0 section 5.8.4</a> are available.</p>
+<p>Examples:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -cl-std<span class="o">=</span>CL2.0 -cl-single-precision-constant test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Some extra options are available to support special OpenCL features.</p>
+<dl class="option">
+<dt id="cmdoption-finclude-default-header">
+<code class="descname">-finclude-default-header</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-finclude-default-header" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Loads standard includes during compilations. By default OpenCL headers are not
+loaded and therefore standard library includes are not available. To load them
+automatically a flag has been added to the frontend (see also <a class="reference internal" href="#opencl-header"><span class="std std-ref">the section
+on the OpenCL Header</span></a>):</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -Xclang -finclude-default-header test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Alternatively <code class="docutils literal"><span class="pre">-include</span></code> or <code class="docutils literal"><span class="pre">-I</span></code> followed by the path to the header location
+can be given manually.</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -I<path to clang>/lib/Headers/opencl-c.h test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>In this case the kernel code should contain <code class="docutils literal"><span class="pre">#include</span> <span class="pre"><opencl-c.h></span></code> just as a
+regular C include.</p>
+<span class="target" id="opencl-cl-ext"></span><dl class="option">
+<dt id="cmdoption-cl-ext">
+<code class="descname">-cl-ext</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-cl-ext" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Disables support of OpenCL extensions. All OpenCL targets provide a list
+of extensions that they support. Clang allows to amend this using the <code class="docutils literal"><span class="pre">-cl-ext</span></code>
+flag with a comma-separated list of extensions prefixed with <code class="docutils literal"><span class="pre">'+'</span></code> or <code class="docutils literal"><span class="pre">'-'</span></code>.
+The syntax: <code class="docutils literal"><span class="pre">-cl-ext=<(['-'|'+']<extension>[,])+></span></code>, where extensions
+can be either one of <a class="reference external" href="https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/EXTENSION.html">the OpenCL specification extensions</a>
+or any known vendor extension. Alternatively, <code class="docutils literal"><span class="pre">'all'</span></code> can be used to enable
+or disable all known extensions.
+Example disabling double support for the 64-bit SPIR target:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -cc1 -triple spir64-unknown-unknown -cl-ext<span class="o">=</span>-cl_khr_fp64 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Enabling all extensions except double support in R600 AMD GPU can be done using:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -cc1 -triple r600-unknown-unknown -cl-ext<span class="o">=</span>-all,+cl_khr_fp16 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<span class="target" id="opencl-fake-address-space-map"></span><dl class="option">
+<dt id="cmdoption-ffake-address-space-map">
+<code class="descname">-ffake-address-space-map</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-ffake-address-space-map" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Overrides the target address space map with a fake map.
+This allows adding explicit address space IDs to the bitcode for non-segmented
+memory architectures that don’t have separate IDs for each of the OpenCL
+logical address spaces by default. Passing <code class="docutils literal"><span class="pre">-ffake-address-space-map</span></code> will
+add/override address spaces of the target compiled for with the following values:
+<code class="docutils literal"><span class="pre">1-global</span></code>, <code class="docutils literal"><span class="pre">2-constant</span></code>, <code class="docutils literal"><span class="pre">3-local</span></code>, <code class="docutils literal"><span class="pre">4-generic</span></code>. The private address
+space is represented by the absence of an address space attribute in the IR (see
+also <a class="reference internal" href="#opencl-addrsp"><span class="std std-ref">the section on the address space attribute</span></a>).</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -ffake-address-space-map test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Some other flags used for the compilation for C can also be passed while
+compiling for OpenCL, examples: <code class="docutils literal"><span class="pre">-c</span></code>, <code class="docutils literal"><span class="pre">-O<1-4|s></span></code>, <code class="docutils literal"><span class="pre">-o</span></code>, <code class="docutils literal"><span class="pre">-emit-llvm</span></code>, etc.</p>
+</div>
+<div class="section" id="opencl-targets">
+<h3><a class="toc-backref" href="#id62">OpenCL Targets</a><a class="headerlink" href="#opencl-targets" title="Permalink to this headline">¶</a></h3>
+<p>OpenCL targets are derived from the regular Clang target classes. The OpenCL
+specific parts of the target representation provide address space mapping as
+well as a set of supported extensions.</p>
+<div class="section" id="specific-targets">
+<h4><a class="toc-backref" href="#id63">Specific Targets</a><a class="headerlink" href="#specific-targets" title="Permalink to this headline">¶</a></h4>
+<p>There is a set of concrete HW architectures that OpenCL can be compiled for.</p>
+<ul>
+<li><p class="first">For AMD target:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target amdgcn-amd-amdhsa-opencl test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+<li><p class="first">For Nvidia architectures:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target nvptx64-unknown-unknown test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="generic-targets">
+<h4><a class="toc-backref" href="#id64">Generic Targets</a><a class="headerlink" href="#generic-targets" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first">SPIR is available as a generic target to allow portable bitcode to be produced
+that can be used across GPU toolchains. The implementation follows <a class="reference external" href="https://www.khronos.org/spir">the SPIR
+specification</a>. There are two flavors
+available for 32 and 64 bits.</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target spir-unknown-unknown test.cl
+<span class="gp">$</span> clang -target spir64-unknown-unknown test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>All known OpenCL extensions are supported in the SPIR targets. Clang will
+generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and SPIR v2.0
+for OpenCL v2.0.</p>
+</li>
+<li><p class="first">x86 is used by some implementations that are x86 compatible and currently
+remains for backwards compatibility (with older implementations prior to
+SPIR target support). For “non-SPMD” targets which cannot spawn multiple
+work-items on the fly using hardware, which covers practically all non-GPU
+devices such as CPUs and DSPs, additional processing is needed for the kernels
+to support multiple work-item execution. For this, a 3rd party toolchain,
+such as for example <a class="reference external" href="http://portablecl.org/">POCL</a>, can be used.</p>
+<p>This target does not support multiple memory segments and, therefore, the fake
+address space map can be added using the <a class="reference internal" href="#opencl-fake-address-space-map"><span class="std std-ref">-ffake-address-space-map</span></a> flag.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="opencl-header">
+<span id="id6"></span><h3><a class="toc-backref" href="#id65">OpenCL Header</a><a class="headerlink" href="#opencl-header" title="Permalink to this headline">¶</a></h3>
+<p>By default Clang will not include standard headers and therefore OpenCL builtin
+functions and some types (i.e. vectors) are unknown. The default CL header is,
+however, provided in the Clang installation and can be enabled by passing the
+<code class="docutils literal"><span class="pre">-finclude-default-header</span></code> flag to the Clang frontend.</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}"</span> > test.cl
+<span class="gp">$</span> clang -Xclang -finclude-default-header -cl-std<span class="o">=</span>CL2.0 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Because the header is very large and long to parse, PCH (<a class="reference internal" href="PCHInternals.html"><span class="doc">Precompiled Header and Modules Internals</span></a>)
+and modules (<a class="reference internal" href="Modules.html"><span class="doc">Modules</span></a>) are used internally to improve the compilation
+speed.</p>
+<p>To enable modules for OpenCL:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path<span class="o">=</span><path to the generated module> test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="opencl-extensions">
+<h3><a class="toc-backref" href="#id66">OpenCL Extensions</a><a class="headerlink" href="#opencl-extensions" title="Permalink to this headline">¶</a></h3>
+<p>All of the <code class="docutils literal"><span class="pre">cl_khr_*</span></code> extensions from <a class="reference external" href="https://www.khronos.org/registry/OpenCL/sdk/2.0/docs/man/xhtml/EXTENSION.html">the official OpenCL specification</a>
+up to and including version 2.0 are available and set per target depending on the
+support available in the specific architecture.</p>
+<p>It is possible to alter the default extensions setting per target using
+<code class="docutils literal"><span class="pre">-cl-ext</span></code> flag. (See <a class="reference internal" href="#opencl-cl-ext"><span class="std std-ref">flags description</span></a> for more details).</p>
+<p>Vendor extensions can be added flexibly by declaring the list of types and
+functions associated with each extensions enclosed within the following
+compiler pragma directives:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span></span><span class="cp">#pragma OPENCL EXTENSION the_new_extension_name : begin</span>
+<span class="c1">// declare types and functions associated with the extension here</span>
+<span class="cp">#pragma OPENCL EXTENSION the_new_extension_name : end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>For example, parsing the following code adds <code class="docutils literal"><span class="pre">my_t</span></code> type and <code class="docutils literal"><span class="pre">my_func</span></code>
+function to the custom <code class="docutils literal"><span class="pre">my_ext</span></code> extension.</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span></span><span class="cp">#pragma OPENCL EXTENSION my_ext : begin</span>
+<span class="k">typedef</span> <span class="k">struct</span><span class="p">{</span>
+ <span class="kt">int</span> <span class="n">a</span><span class="p">;</span>
+<span class="p">}</span><span class="n">my_t</span><span class="p">;</span>
+<span class="kt">void</span> <span class="nf">my_func</span><span class="p">(</span><span class="n">my_t</span><span class="p">);</span>
+<span class="cp">#pragma OPENCL EXTENSION my_ext : end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Declaring the same types in different vendor extensions is disallowed.</p>
+</div>
+<div class="section" id="opencl-metadata">
+<h3><a class="toc-backref" href="#id67">OpenCL Metadata</a><a class="headerlink" href="#opencl-metadata" title="Permalink to this headline">¶</a></h3>
+<p>Clang uses metadata to provide additional OpenCL semantics in IR needed for
+backends and OpenCL runtime.</p>
+<p>Each kernel will have function metadata attached to it, specifying the arguments.
+Kernel argument metadata is used to provide source level information for querying
+at runtime, for example using the <a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167">clGetKernelArgInfo</a>
+call.</p>
+<p>Note that <code class="docutils literal"><span class="pre">-cl-kernel-arg-info</span></code> enables more information about the original CL
+code to be added e.g. kernel parameter names will appear in the OpenCL metadata
+along with other information.</p>
+<p>The IDs used to encode the OpenCL’s logical address spaces in the argument info
+metadata follows the SPIR address space mapping as defined in the SPIR
+specification <a class="reference external" href="https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18">section 2.2</a></p>
+</div>
+<div class="section" id="opencl-specific-attributes">
+<h3><a class="toc-backref" href="#id68">OpenCL-Specific Attributes</a><a class="headerlink" href="#opencl-specific-attributes" title="Permalink to this headline">¶</a></h3>
+<p>OpenCL support in Clang contains a set of attribute taken directly from the
+specification as well as additional attributes.</p>
+<p>See also <a class="reference internal" href="AttributeReference.html"><span class="doc">Attributes in Clang</span></a>.</p>
+<div class="section" id="nosvm">
+<h4><a class="toc-backref" href="#id69">nosvm</a><a class="headerlink" href="#nosvm" title="Permalink to this headline">¶</a></h4>
+<p>Clang supports this attribute to comply to OpenCL v2.0 conformance, but it
+does not have any effect on the IR. For more details reffer to the specification
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49">section 6.7.2</a></p>
+</div>
+<div class="section" id="opencl-unroll-hint">
+<h4><a class="toc-backref" href="#id70">opencl_unroll_hint</a><a class="headerlink" href="#opencl-unroll-hint" title="Permalink to this headline">¶</a></h4>
+<p>The implementation of this feature mirrors the unroll hint for C.
+More details on the syntax can be found in the specification
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61">section 6.11.5</a></p>
+</div>
+<div class="section" id="convergent">
+<h4><a class="toc-backref" href="#id71">convergent</a><a class="headerlink" href="#convergent" title="Permalink to this headline">¶</a></h4>
+<p>To make sure no invalid optimizations occur for single program multiple data
+(SPMD) / single instruction multiple thread (SIMT) Clang provides attributes that
+can be used for special functions that have cross work item semantics.
+An example is the subgroup operations such as <a class="reference external" href="https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt">intel_sub_group_shuffle</a></p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span></span><span class="c1">// Define custom my_sub_group_shuffle(data, c)</span>
+<span class="c1">// that makes use of intel_sub_group_shuffle</span>
+<span class="n">r1</span> <span class="o">=</span> <span class="p">...</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">r0</span><span class="p">)</span> <span class="n">r1</span> <span class="o">=</span> <span class="n">computeA</span><span class="p">();</span>
+<span class="c1">// Shuffle data from r1 into r3</span>
+<span class="c1">// of threads id r2.</span>
+<span class="n">r3</span> <span class="o">=</span> <span class="n">my_sub_group_shuffle</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">);</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">r0</span><span class="p">)</span> <span class="n">r3</span> <span class="o">=</span> <span class="n">computeB</span><span class="p">();</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>with non-SPMD semantics this is optimized to the following equivalent code:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">r1</span> <span class="o">=</span> <span class="p">...</span>
+<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">r0</span><span class="p">)</span>
+ <span class="c1">// Incorrect functionality! The data in r1</span>
+ <span class="c1">// have not been computed by all threads yet.</span>
+ <span class="n">r3</span> <span class="o">=</span> <span class="n">my_sub_group_shuffle</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">);</span>
+<span class="k">else</span> <span class="p">{</span>
+ <span class="n">r1</span> <span class="o">=</span> <span class="n">computeA</span><span class="p">();</span>
+ <span class="n">r3</span> <span class="o">=</span> <span class="n">my_sub_group_shuffle</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">);</span>
+ <span class="n">r3</span> <span class="o">=</span> <span class="n">computeB</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Declaring the function <code class="docutils literal"><span class="pre">my_sub_group_shuffle</span></code> with the convergent attribute
+would prevent this:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">my_sub_group_shuffle</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">convergent</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Using <code class="docutils literal"><span class="pre">convergent</span></code> guarantees correct execution by keeping CFG equivalence
+wrt operations marked as <code class="docutils literal"><span class="pre">convergent</span></code>. CFG <code class="docutils literal"><span class="pre">G´</span></code> is equivalent to <code class="docutils literal"><span class="pre">G</span></code> wrt
+node <code class="docutils literal"><span class="pre">Ni</span></code> : <code class="docutils literal"><span class="pre">iff</span> <span class="pre">â</span> <span class="pre">Nj</span> <span class="pre">(iâ j)</span></code> domination and post-domination relations with
+respect to <code class="docutils literal"><span class="pre">Ni</span></code> remain the same in both <code class="docutils literal"><span class="pre">G</span></code> and <code class="docutils literal"><span class="pre">G´</span></code>.</p>
+</div>
+<div class="section" id="noduplicate">
+<h4><a class="toc-backref" href="#id72">noduplicate</a><a class="headerlink" href="#noduplicate" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal"><span class="pre">noduplicate</span></code> is more restrictive with respect to optimizations than
+<code class="docutils literal"><span class="pre">convergent</span></code> because a convergent function only preserves CFG equivalence.
+This allows some optimizations to happen as long as the control flow remains
+unmodified.</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span></span><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="mi">4</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span>
+ <span class="n">my_sub_group_shuffle</span><span class="p">()</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>can be modified to:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>while using <code class="docutils literal"><span class="pre">noduplicate</span></code> would disallow this. Also <code class="docutils literal"><span class="pre">noduplicate</span></code> doesn’t
+have the same safe semantics of CFG as <code class="docutils literal"><span class="pre">convergent</span></code> and can cause changes in
+CFG that modify semantics of the original program.</p>
+<p><code class="docutils literal"><span class="pre">noduplicate</span></code> is kept for backwards compatibility only and it considered to be
+deprecated for future uses.</p>
+</div>
+<div class="section" id="address-space">
+<span id="opencl-addrsp"></span><h4><a class="toc-backref" href="#id73">address_space</a><a class="headerlink" href="#address-space" title="Permalink to this headline">¶</a></h4>
+<p>Clang has arbitrary address space support using the <code class="docutils literal"><span class="pre">address_space(N)</span></code>
+attribute, where <code class="docutils literal"><span class="pre">N</span></code> is an integer number in the range <code class="docutils literal"><span class="pre">0</span></code> to <code class="docutils literal"><span class="pre">16777215</span></code>
+(<code class="docutils literal"><span class="pre">0xffffffu</span></code>).</p>
+<p>An OpenCL implementation provides a list of standard address spaces using
+keywords: <code class="docutils literal"><span class="pre">private</span></code>, <code class="docutils literal"><span class="pre">local</span></code>, <code class="docutils literal"><span class="pre">global</span></code>, and <code class="docutils literal"><span class="pre">generic</span></code>. In the AST and
+in the IR local, global, or generic will be represented by the address space
+attribute with the corresponding unique number. Note that private does not have
+any corresponding attribute added and, therefore, is represented by the absence
+of an address space number. The specific IDs for an address space do not have to
+match between the AST and the IR. Typically in the AST address space numbers
+represent logical segments while in the IR they represent physical segments.
+Therefore, machines with flat memory segments can map all AST address space
+numbers to the same physical segment ID or skip address space attribute
+completely while generating the IR. However, if the address space information
+is needed by the IR passes e.g. to improve alias analysis, it is recommended
+to keep it and only lower to reflect physical memory segments in the late
+machine passes.</p>
+</div>
+</div>
+<div class="section" id="opencl-builtins">
+<h3><a class="toc-backref" href="#id74">OpenCL builtins</a><a class="headerlink" href="#opencl-builtins" title="Permalink to this headline">¶</a></h3>
+<p>There are some standard OpenCL functions that are implemented as Clang builtins:</p>
+<ul class="simple">
+<li>All pipe functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160">section 6.13.16.2/6.13.16.3</a> of
+the OpenCL v2.0 kernel language specification. `</li>
+<li>Address space qualifier conversion functions <code class="docutils literal"><span class="pre">to_global</span></code>/<code class="docutils literal"><span class="pre">to_local</span></code>/<code class="docutils literal"><span class="pre">to_private</span></code>
+from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101">section 6.13.9</a>.</li>
+<li>All the <code class="docutils literal"><span class="pre">enqueue_kernel</span></code> functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164">section 6.13.17.1</a> and
+enqueue query functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171">section 6.13.17.5</a>.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="target-specific-features-and-limitations">
+<span id="target-features"></span><h2><a class="toc-backref" href="#id75">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="#id76">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="#id77">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 <code class="docutils literal"><span class="pre">x86_64-mingw32</span></code>, passing i128(by value) is incompatible with the
+Microsoft x64 calling convention. You might need to tweak
+<code class="docutils literal"><span class="pre">WinX86_64ABIInfo::classify()</span></code> in lib/CodeGen/TargetInfo.cpp.</p>
+<p>For the X86 target, clang supports the <cite>-m16</cite> command line
+argument which enables 16-bit code output. This is broadly similar to
+using <code class="docutils literal"><span class="pre">asm(".code16gcc")</span></code> 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="#id78">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="#id79">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="#id80">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 <code class="docutils literal"><span class="pre">lib/Basic/Targets.cpp</span></code> 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 <code class="docutils literal"><span class="pre">lib/CodeGen/CGCall.cpp</span></code> 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="#id81">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="#id82">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="#id83">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"><span class="std std-ref">Microsoft Extensions</span></a>.</p>
+<div class="section" id="cygwin">
+<h5><a class="toc-backref" href="#id84">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="#id85">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><code class="docutils literal"><span class="pre">C:/mingw/include</span></code></li>
+<li><code class="docutils literal"><span class="pre">C:/mingw/lib</span></code></li>
+<li><code class="docutils literal"><span class="pre">C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++</span></code></li>
+</ul>
+<p>On MSYS, a few tests might fail.</p>
+</div>
+<div class="section" id="mingw-w64">
+<h5><a class="toc-backref" href="#id86">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><code 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></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/gcc.exe</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/clang.exe</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/clang++.exe</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/backward</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/../x86_64-w64-mingw32/include</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/../i686-w64-mingw32/include</span></code></li>
+<li><code class="docutils literal"><span class="pre">some_directory/bin/../include</span></code></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
+<code class="docutils literal"><span class="pre">i686-w64-mingw32</span></code> (or <code class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></code>) to be present on PATH.</p>
+<p><a class="reference external" href="https://bugs.llvm.org/show_bug.cgi?id=9072">Some tests might fail</a> on
+<code class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></code>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="clang-cl">
+<span id="id7"></span><h2><a class="toc-backref" href="#id87">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, 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="id8">
+<h3><a class="toc-backref" href="#id88">Command-Line Options</a><a class="headerlink" href="#id8" 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 <code class="docutils literal"><span class="pre">/</span></code> or <code class="docutils literal"><span class="pre">-</span></code>. It also supports
+some of Clang’s core options, such as the <code class="docutils literal"><span class="pre">-W</span></code> 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-default"><div class="highlight"><pre><span></span><span class="n">clang</span><span class="o">-</span><span class="n">cl</span><span class="o">.</span><span class="n">exe</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">argument</span> <span class="n">unused</span> <span class="n">during</span> <span class="n">compilation</span><span class="p">:</span> <span class="s1">'/AI'</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>To suppress warnings about unused arguments, use the <code class="docutils literal"><span class="pre">-Qunused-arguments</span></code> option.</p>
+<p>Options that are not known to clang-cl will be ignored by default. Use the
+<code class="docutils literal"><span class="pre">-Werror=unknown-argument</span></code> option in order to treat them as errors. If these
+options are spelled with a leading <code class="docutils literal"><span class="pre">/</span></code>, they will be mistaken for a filename:</p>
+<blockquote>
+<div><div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">clang</span><span class="o">-</span><span class="n">cl</span><span class="o">.</span><span class="n">exe</span><span class="p">:</span> <span class="n">error</span><span class="p">:</span> <span class="n">no</span> <span class="n">such</span> <span class="n">file</span> <span class="ow">or</span> <span class="n">directory</span><span class="p">:</span> <span class="s1">'/foobar'</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Please <a class="reference external" href="https://bugs.llvm.org/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 <code class="docutils literal"><span class="pre">clang-cl</span> <span class="pre">/?</span></code> to see a list of supported options:</p>
+<blockquote>
+<div><div class="highlight-default"><div class="highlight"><pre><span></span>CL.EXE COMPATIBILITY OPTIONS:
+ /? Display available options
+ /arch:<value> Set architecture for code generation
+ /Brepro- Emit an object file which cannot be reproduced over time
+ /Brepro Emit an object file which can be reproduced over time
+ /C Don't discard comments when preprocessing
+ /c Compile only
+ /d1reportAllClassLayout Dump record layout information
+ /diagnostics:caret Enable caret and column diagnostics (on by default)
+ /diagnostics:classic Disable column and caret diagnostics
+ /diagnostics:column Disable caret diagnostics but keep column info
+ /D <macro[=value]> Define macro
+ /EH<value> Exception handling model
+ /EP Disable linemarker output and preprocess to stdout
+ /execution-charset:<value>
+ Runtime encoding, supports only UTF-8
+ /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
+ /Fp<filename> Set pch filename (with /Yc and /Yu)
+ /GA Assume thread-local variables are defined in the executable
+ /Gd Set __cdecl as a default calling convention
+ /GF- Disable string pooling
+ /GR- Disable emission of RTTI data
+ /Gregcall Set __regcall as a default calling convention
+ /GR Enable emission of RTTI data
+ /Gr Set __fastcall as a default calling convention
+ /GS- Disable buffer security check
+ /GS Enable buffer security check
+ /Gs<value> Set stack probe size
+ /Gv Set __vectorcall as a default calling convention
+ /Gw- Don't put each data item in its own section
+ /Gw Put each data item in its own section
+ /GX- Enable exception handling
+ /GX Enable exception handling
+ /Gy- Don't put each function in its own section
+ /Gy Put each function in its own section
+ /Gz Set __stdcall as a default calling convention
+ /help Display available options
+ /imsvc <dir> Add directory to system include search path, as if part of %INCLUDE%
+ /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
+ /Od Disable optimization
+ /Oi- Disable use of builtin functions
+ /Oi Enable use of builtin functions
+ /Os Optimize for size
+ /Ot Optimize for speed
+ /O<value> 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
+ /source-charset:<value> Source encoding, supports only UTF-8
+ /std:<value> Language standard to compile for
+ /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
+ /utf-8 Set source and runtime encoding to UTF-8 (default)
+ /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 and -Wextra
+ /Wall Enable -Weverything
+ /WX- Do not treat warnings as errors
+ /WX Treat warnings as errors
+ /w Disable all warnings
+ /Y- Disable precompiled headers, overrides /Yc and /Yu
+ /Yc<filename> Generate a pch file for all code up to and including <filename>
+ /Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
+ /Z7 Enable CodeView debug information in object files
+ /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
+ /Zc:twoPhase- Disable two-phase name lookup in templates
+ /Zc:twoPhase Enable two-phase name lookup in templates
+ /Zd Emit debug line number tables only
+ /Zi Alias for /Z7. Does not produce PDBs.
+ /Zl Don't mention any default libraries in the object file
+ /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
+ -fdebug-macro Emit macro debug information
+ -fdelayed-template-parsing
+ Parse templated function definitions at the end of the translation unit
+ -fdiagnostics-absolute-paths
+ Print absolute paths in diagnostics
+ -fdiagnostics-parseable-fixits
+ Print fix-its in machine parseable form
+ -flto=<value> Set LTO mode to either 'full' or 'thin'
+ -flto Enable LTO in 'full' mode
+ -fms-compatibility-version=<value>
+ Dot-separated value representing the Microsoft compiler version
+ number to report in _MSC_VER (0 = don't define it (default))
+ -fms-compatibility Enable full Microsoft Visual C++ compatibility
+ -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
+ -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER
+ (0 = don't define it (default))
+ -fno-debug-macro Do not emit macro debug information
+ -fno-delayed-template-parsing
+ Disable delayed template parsing
+ -fno-sanitize-address-use-after-scope
+ Disable use-after-scope detection in AddressSanitizer
+ -fno-sanitize-blacklist Don't use blacklist file for sanitizers
+ -fno-sanitize-cfi-cross-dso
+ Disable control flow integrity (CFI) checks for cross-DSO calls.
+ -fno-sanitize-coverage=<value>
+ Disable specified features of coverage instrumentation for Sanitizers
+ -fno-sanitize-memory-track-origins
+ Disable origins tracking in MemorySanitizer
+ -fno-sanitize-memory-use-after-dtor
+ Disable use-after-destroy detection in MemorySanitizer
+ -fno-sanitize-recover=<value>
+ Disable recovery for specified sanitizers
+ -fno-sanitize-stats Disable sanitizer statistics gathering.
+ -fno-sanitize-thread-atomics
+ Disable atomic operations instrumentation in ThreadSanitizer
+ -fno-sanitize-thread-func-entry-exit
+ Disable function entry/exit instrumentation in ThreadSanitizer
+ -fno-sanitize-thread-memory-access
+ Disable memory access instrumentation in ThreadSanitizer
+ -fno-sanitize-trap=<value>
+ Disable trapping for specified sanitizers
+ -fno-standalone-debug Limit debug information produced to reduce size of debug binary
+ -fprofile-instr-generate=<file>
+ Generate instrumented code to collect execution counts into <file>
+ (overridden by LLVM_PROFILE_FILE env var)
+ -fprofile-instr-generate
+ Generate instrumented code to collect execution counts into default.profraw file
+ (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
+ -fprofile-instr-use=<value>
+ Use instrumentation data for profile-guided optimization
+ -fsanitize-address-field-padding=<value>
+ Level of field padding for AddressSanitizer
+ -fsanitize-address-globals-dead-stripping
+ Enable linker dead stripping of globals in AddressSanitizer
+ -fsanitize-address-use-after-scope
+ Enable use-after-scope detection in AddressSanitizer
+ -fsanitize-blacklist=<value>
+ Path to blacklist file for sanitizers
+ -fsanitize-cfi-cross-dso
+ Enable control flow integrity (CFI) checks for cross-DSO calls.
+ -fsanitize-cfi-icall-generalize-pointers
+ Generalize pointers in CFI indirect call type signature checks
+ -fsanitize-coverage=<value>
+ Specify the type of coverage instrumentation for Sanitizers
+ -fsanitize-memory-track-origins=<value>
+ Enable origins tracking in MemorySanitizer
+ -fsanitize-memory-track-origins
+ Enable origins tracking in MemorySanitizer
+ -fsanitize-memory-use-after-dtor
+ Enable use-after-destroy detection in MemorySanitizer
+ -fsanitize-recover=<value>
+ Enable recovery for specified sanitizers
+ -fsanitize-stats Enable sanitizer statistics gathering.
+ -fsanitize-thread-atomics
+ Enable atomic operations instrumentation in ThreadSanitizer (default)
+ -fsanitize-thread-func-entry-exit
+ Enable function entry/exit instrumentation in ThreadSanitizer (default)
+ -fsanitize-thread-memory-access
+ Enable memory access instrumentation in ThreadSanitizer (default)
+ -fsanitize-trap=<value> Enable trapping for specified sanitizers
+ -fsanitize-undefined-strip-path-components=<number>
+ Strip (or keep only, if negative) a given number of path components when emitting check metadata.
+ -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious
+ behavior. See user manual for available checks
+ -fstandalone-debug Emit full debug info for all types used by the program
+ -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
+ -gcodeview Generate CodeView debug information
+ -gline-tables-only Emit debug line number tables only
+ -miamcu Use Intel MCU ABI
+ -mllvm <value> Additional arguments to forward to LLVM's option processing
+ -nobuiltininc Disable builtin #include directories
+ -Qunused-arguments Don't emit warning for unused driver arguments
+ -R<remark> Enable the specified remark
+ --target=<value> Generate code for the given target
+ --version Print version information
+ -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="#id89">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 <code class="docutils literal"><span class="pre">/fallback</span></code> 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" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="ReleaseNotes.html">Clang 6.0.0 Release Notes</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Toolchain.html">Assembling a Complete Toolchain</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/tools/clang/docs/_images/DriverArchitecture.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/_images/DriverArchitecture.png?rev=326992&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/6.0.0/tools/clang/docs/_images/DriverArchitecture.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/6.0.0/tools/clang/docs/_images/PCHLayout.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/_images/PCHLayout.png?rev=326992&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/6.0.0/tools/clang/docs/_images/PCHLayout.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/6.0.0/tools/clang/docs/_sources/AddressSanitizer.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/_sources/AddressSanitizer.rst.txt?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/_sources/AddressSanitizer.rst.txt (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/_sources/AddressSanitizer.rst.txt Thu Mar 8 02:24:44 2018
@@ -0,0 +1,289 @@
+================
+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 (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`)
+* Use-after-scope (clang flag `-fsanitize-address-use-after-scope`)
+* 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,
+and can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on OS X;
+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 `no_sanitize_address` 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
+
+Suppressing memory leaks
+------------------------
+
+Memory leak reports produced by :doc:`LeakSanitizer` (if it is run as a part
+of AddressSanitizer) can be suppressed by a separate file passed as
+
+.. code-block:: bash
+
+ LSAN_OPTIONS=suppressions=MyLSan.supp
+
+which contains lines of the form `leak:<pattern>`. Memory leak will be
+suppressed if pattern matches any function name, source file name, or
+library name in the symbolized stack trace of the leak report. See
+`full documentation
+<https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#suppressions>`_
+for more details.
+
+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
+================
+
+`<https://github.com/google/sanitizers/wiki/AddressSanitizer>`_
Added: www-releases/trunk/6.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt (added)
+++ www-releases/trunk/6.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt Thu Mar 8 02:24:44 2018
@@ -0,0 +1,3567 @@
+..
+ -------------------------------------------------------------------
+ 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.
+
+Function Attributes
+===================
+
+
+#pragma omp declare simd
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","", "X", ""
+
+The `declare simd` construct can be applied to a function to enable the creation
+of one or more versions that can process multiple arguments using SIMD
+instructions from a single invocation in a SIMD loop. The `declare simd`
+directive is a declarative directive. There may be multiple `declare simd`
+directives for a function. The use of a `declare simd` construct on a function
+enables the creation of SIMD versions of the associated function that can be
+used to process multiple arguments from a single invocation from a SIMD loop
+concurrently.
+The syntax of the `declare simd` construct is as follows:
+
+ .. code-block:: none
+
+ #pragma omp declare simd [clause[[,] clause] ...] new-line
+ [#pragma omp declare simd [clause[[,] clause] ...] new-line]
+ [...]
+ function definition or declaration
+
+where clause is one of the following:
+
+ .. code-block:: none
+
+ simdlen(length)
+ linear(argument-list[:constant-linear-step])
+ aligned(argument-list[:alignment])
+ uniform(argument-list)
+ inbranch
+ notinbranch
+
+
+#pragma omp declare target
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","", "X", ""
+
+The `declare target` directive specifies that variables and functions are mapped
+to a device for OpenMP offload mechanism.
+
+The syntax of the declare target directive is as follows:
+
+ .. code-block:: c
+
+ #pragma omp declare target new-line
+ declarations-definition-seq
+ #pragma omp end declare target new-line
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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.
+
+
+abi_tag (gnu::abi_tag)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``abi_tag`` attribute can be applied to a function, variable, class or
+inline namespace declaration to modify the mangled name of the entity. It gives
+the ability to distinguish between different versions of the same entity but
+with different ABI versions supported. For example, a newer version of a class
+could have a different set of data members and thus have a different size. Using
+the ``abi_tag`` attribute, it is possible to have different mangled names for
+a global variable of the class type. Therefor, the old code could keep using
+the old manged name and the new code will use the new mangled name with tags.
+
+
+acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+Marks a function as acquiring a capability.
+
+
+alloc_align (gnu::alloc_align)
+------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+Use ``__attribute__((alloc_align(<alignment>))`` on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) is at least as aligned as the value of the indicated parameter. The
+parameter is given by its index in the list of formal parameters; the first
+parameter has index 1 unless the function is a C++ non-static member function,
+in which case the first parameter has index 2 to account for the implicit ``this``
+parameter.
+
+.. code-block:: c++
+
+ // The returned pointer has the alignment specified by the first parameter.
+ void *a(size_t align) __attribute__((alloc_align(1)));
+
+ // The returned pointer has the alignment specified by the second parameter.
+ void *b(void *v, size_t align) __attribute__((alloc_align(2)));
+
+ // The returned pointer has the alignment specified by the second visible
+ // parameter, however it must be adjusted for the implicit 'this' parameter.
+ void *Foo::b(void *v, size_t align) __attribute__((alloc_align(3)));
+
+Note that this attribute merely informs the compiler that a function always
+returns a sufficiently aligned pointer. It does not cause the compiler to
+emit code to enforce that alignment. The behavior is undefined if the returned
+poitner is not sufficiently aligned.
+
+
+alloc_size (gnu::alloc_size)
+----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``alloc_size`` attribute can be placed on functions that return pointers in
+order to hint to the compiler how many bytes of memory will be available at the
+returned poiner. ``alloc_size`` takes one or two arguments.
+
+- ``alloc_size(N)`` implies that argument number N equals the number of
+ available bytes at the returned pointer.
+- ``alloc_size(N, M)`` implies that the product of argument number N and
+ argument number M equals the number of available bytes at the returned
+ pointer.
+
+Argument numbers are 1-based.
+
+An example of how to use ``alloc_size``
+
+.. code-block:: c
+
+ void *my_malloc(int a) __attribute__((alloc_size(1)));
+ void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2)));
+
+ int main() {
+ void *const p = my_malloc(100);
+ assert(__builtin_object_size(p, 0) == 100);
+ void *const a = my_calloc(20, 5);
+ assert(__builtin_object_size(a, 0) == 100);
+ }
+
+.. Note:: This attribute works differently in clang than it does in GCC.
+ Specifically, clang will only trace ``const`` pointers (as above); we give up
+ on pointers that are not marked as ``const``. In the vast majority of cases,
+ this is unimportant, because LLVM has support for the ``alloc_size``
+ attribute. However, this may cause mildly unintuitive behavior when used with
+ other attributes, such as ``enable_if``.
+
+
+assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)
+-------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", "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(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+
+The availability attribute states that ``f`` was introduced in macOS 10.4,
+deprecated in macOS 10.6, and obsoleted in macOS 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 macOS 10.5, a call to ``f()``
+succeeds. If Clang is instructed to compile code for macOS 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 macOS 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.
+
+replacement=\ *string-literal*
+ Additional message text that Clang will use to provide Fix-It when emitting
+ a warning about use of a deprecated declaration. The Fix-It will replace
+ the deprecated declaration with the new declaration specified.
+
+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.
+
+``macos``
+ Apple's macOS operating system. The minimum deployment target is
+ specified by the ``-mmacosx-version-min=*version*`` command-line argument.
+ ``macosx`` is supported for backward-compatibility reasons, but it is
+ deprecated.
+
+``tvos``
+ Apple's tvOS operating system. The minimum deployment target is specified by
+ the ``-mtvos-version-min=*version*`` command-line argument.
+
+``watchos``
+ Apple's watchOS operating system. The minimum deployment target is specified by
+ the ``-mwatchos-version-min=*version*`` command-line argument.
+
+A declaration can typically 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.
+
+The flag ``strict`` disallows using API when deploying back to a
+platform version prior to when the declaration was introduced. An
+attempt to use such API before its introduction causes a hard error.
+Weakly-linking is almost always a better API choice, since it allows
+users to query availability at runtime.
+
+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(macos,introduced=10.4)));
+ void g(void) __attribute__((availability(macos,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 macos and ios availability from above.
+ void g(void) __attribute__((availability(macos,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(macos,introduced=10.4)));
+ - (id)method2 __attribute__((availability(macos,introduced=10.4)));
+ @end
+
+ @interface B : A
+ - (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later
+ - (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
+ @end
+
+Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from
+``<os/availability.h>`` can simplify the spelling:
+
+.. code-block:: objc
+
+ @interface A
+ - (id)method API_AVAILABLE(macos(10.11)));
+ - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
+ @end
+
+Also see the documentation for `@available
+<http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available>`_
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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.
+
+
+convergent (clang::convergent)
+------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``convergent`` attribute can be placed on a function declaration. It is
+translated into the LLVM ``convergent`` attribute, which indicates that the call
+instructions of a function with this attribute cannot be made control-dependent
+on any additional values.
+
+In languages designed for SPMD/SIMT programming model, e.g. OpenCL or CUDA,
+the call instructions of a function with this attribute must be executed by
+all work items or threads in a work group or sub group.
+
+This attribute is different from ``noduplicate`` because it allows duplicating
+function calls if it can be proved that the duplicated function calls are
+not made control-dependent on any additional values, e.g., unrolling a loop
+executed by all work items.
+
+Sample usage:
+.. code-block:: c
+
+ void convfunc(void) __attribute__((convergent));
+ // Setting it as a C++11 attribute is also valid in a C++ program.
+ // void convfunc(void) [[clang::convergent]];
+
+
+deprecated (gnu::deprecated)
+----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","X","X","", "", ""
+
+The ``deprecated`` attribute can be applied to a function, a variable, or a
+type. This is useful when identifying functions, variables, or types that are
+expected to be removed in a future version of a program.
+
+Consider the function declaration for a hypothetical function ``f``:
+
+.. code-block:: c++
+
+ void f(void) __attribute__((deprecated("message", "replacement")));
+
+When spelled as `__attribute__((deprecated))`, the deprecated attribute can have
+two optional string arguments. The first one is the message to display when
+emitting the warning; the second one enables the compiler to provide a Fix-It
+to replace the deprecated name with a new name. Otherwise, when spelled as
+`[[gnu::deprecated]] or [[deprecated]]`, the attribute can have one optional
+string argument which is the message to display when emitting the warning.
+
+
+diagnose_if
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", ""
+
+The ``diagnose_if`` attribute can be placed on function declarations to emit
+warnings or errors at compile-time if calls to the attributed function meet
+certain user-defined criteria. For example:
+
+.. code-block:: c
+
+ void abs(int a)
+ __attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning")));
+ void must_abs(int a)
+ __attribute__((diagnose_if(a >= 0, "Redundant abs call", "error")));
+
+ int val = abs(1); // warning: Redundant abs call
+ int val2 = must_abs(1); // error: Redundant abs call
+ int val3 = abs(val);
+ int val4 = must_abs(val); // Because run-time checks are not emitted for
+ // diagnose_if attributes, this executes without
+ // issue.
+
+
+``diagnose_if`` is closely related to ``enable_if``, with a few key differences:
+
+* Overload resolution is not aware of ``diagnose_if`` attributes: they're
+ considered only after we select the best candidate from a given candidate set.
+* Function declarations that differ only in their ``diagnose_if`` attributes are
+ considered to be redeclarations of the same function (not overloads).
+* If the condition provided to ``diagnose_if`` cannot be evaluated, no
+ diagnostic will be emitted.
+
+Otherwise, ``diagnose_if`` is essentially the logical negation of ``enable_if``.
+
+As a result of bullet number two, ``diagnose_if`` attributes will stack on the
+same function. For example:
+
+.. code-block:: c
+
+ int foo() __attribute__((diagnose_if(1, "diag1", "warning")));
+ int foo() __attribute__((diagnose_if(1, "diag2", "warning")));
+
+ int bar = foo(); // warning: diag1
+ // warning: diag2
+ int (*fooptr)(void) = foo; // warning: diag1
+ // warning: diag2
+
+ constexpr int supportsAPILevel(int N) { return N < 5; }
+ int baz(int a)
+ __attribute__((diagnose_if(!supportsAPILevel(10),
+ "Upgrade to API level 10 to use baz", "error")));
+ int baz(int a)
+ __attribute__((diagnose_if(!a, "0 is not recommended.", "warning")));
+
+ int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz
+ int v = baz(0); // error: Upgrade to API level 10 to use baz
+
+Query for this feature with ``__has_attribute(diagnose_if)``.
+
+
+disable_tail_calls (clang::disable_tail_calls)
+----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``disable_tail_calls`` attribute instructs the backend to not perform tail call optimization inside the marked function.
+
+For example:
+
+ .. code-block:: c
+
+ int callee(int);
+
+ int foo(int a) __attribute__((disable_tail_calls)) {
+ return callee(a); // This call is not tail-call optimized.
+ }
+
+Marking virtual functions as ``disable_tail_calls`` is legal.
+
+ .. code-block:: c++
+
+ int callee(int);
+
+ class Base {
+ public:
+ [[clang::disable_tail_calls]] virtual int foo1() {
+ return callee(); // This call is not tail-call optimized.
+ }
+ };
+
+ class Derived1 : public Base {
+ public:
+ int foo1() override {
+ return callee(); // This call is tail-call optimized.
+ }
+ };
+
+
+enable_if
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", "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)``.
+
+Note that functions with one or more ``enable_if`` attributes may not have
+their address taken, unless all of the conditions specified by said
+``enable_if`` are constants that evaluate to ``true``. For example:
+
+.. code-block:: c
+
+ const int TrueConstant = 1;
+ const int FalseConstant = 0;
+ int f(int a) __attribute__((enable_if(a > 0, "")));
+ int g(int a) __attribute__((enable_if(a == 0 || a != 0, "")));
+ int h(int a) __attribute__((enable_if(1, "")));
+ int i(int a) __attribute__((enable_if(TrueConstant, "")));
+ int j(int a) __attribute__((enable_if(FalseConstant, "")));
+
+ void fn() {
+ int (*ptr)(int);
+ ptr = &f; // error: 'a > 0' is not always true
+ ptr = &g; // error: 'a == 0 || a != 0' is not a truthy constant
+ ptr = &h; // OK: 1 is a truthy constant
+ ptr = &i; // OK: 'TrueConstant' is a truthy constant
+ ptr = &j; // error: 'FalseConstant' is a constant, but not truthy
+ }
+
+Because ``enable_if`` evaluation happens during overload resolution,
+``enable_if`` may give unintuitive results when used with templates, depending
+on when overloads are resolved. In the example below, clang will emit a
+diagnostic about no viable overloads for ``foo`` in ``bar``, but not in ``baz``:
+
+.. code-block:: c++
+
+ double foo(int i) __attribute__((enable_if(i > 0, "")));
+ void *foo(int i) __attribute__((enable_if(i <= 0, "")));
+ template <int I>
+ auto bar() { return foo(I); }
+
+ template <typename T>
+ auto baz() { return foo(T::number); }
+
+ struct WithNumber { constexpr static int number = 1; };
+ void callThem() {
+ bar<sizeof(WithNumber)>();
+ baz<WithNumber>();
+ }
+
+This is because, in ``bar``, ``foo`` is resolved prior to template
+instantiation, so the value for ``I`` isn't known (thus, both ``enable_if``
+conditions for ``foo`` fail). However, in ``baz``, ``foo`` is resolved during
+template instantiation, so the value for ``T::number`` is known.
+
+
+external_source_symbol (clang::external_source_symbol)
+------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``external_source_symbol`` attribute specifies that a declaration originates
+from an external source and describes the nature of that source.
+
+The fact that Clang is capable of recognizing declarations that were defined
+externally can be used to provide better tooling support for mixed-language
+projects or projects that rely on auto-generated code. For instance, an IDE that
+uses Clang and that supports mixed-language projects can use this attribute to
+provide a correct 'jump-to-definition' feature. For a concrete example,
+consider a protocol that's defined in a Swift file:
+
+.. code-block:: swift
+
+ @objc public protocol SwiftProtocol {
+ func method()
+ }
+
+This protocol can be used from Objective-C code by including a header file that
+was generated by the Swift compiler. The declarations in that header can use
+the ``external_source_symbol`` attribute to make Clang aware of the fact
+that ``SwiftProtocol`` actually originates from a Swift module:
+
+.. code-block:: objc
+
+ __attribute__((external_source_symbol(language="Swift",defined_in="module")))
+ @protocol SwiftProtocol
+ @required
+ - (void) method;
+ @end
+
+Consequently, when 'jump-to-definition' is performed at a location that
+references ``SwiftProtocol``, the IDE can jump to the original definition in
+the Swift source file rather than jumping to the Objective-C declaration in the
+auto-generated header file.
+
+The ``external_source_symbol`` attribute is a comma-separated list that includes
+clauses that describe the origin and the nature of the particular declaration.
+Those clauses can be:
+
+language=\ *string-literal*
+ The name of the source language in which this declaration was defined.
+
+defined_in=\ *string-literal*
+ The name of the source container in which the declaration was defined. The
+ exact definition of source container is language-specific, e.g. Swift's
+ source containers are modules, so ``defined_in`` should specify the Swift
+ module name.
+
+generated_declaration
+ This declaration was automatically generated by some tool.
+
+The clauses can be specified in any order. The clauses that are listed above are
+all optional, but the attribute has to have at least one clause.
+
+
+flatten (gnu::flatten)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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.
+
+
+force_align_arg_pointer (gnu::force_align_arg_pointer)
+------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+Use this attribute to force stack alignment.
+
+Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
+(like 'movaps') that work with the stack require operands to be 16-byte aligned.
+This attribute realigns the stack in the function prologue to make sure the
+stack can be used with SSE instructions.
+
+Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
+Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in
+rare cases where the caller does not align the stack properly (e.g. flow
+jumps from i386 arch code).
+
+ .. code-block:: c
+
+ __attribute__ ((force_align_arg_pointer))
+ void f () {
+ ...
+ }
+
+
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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.
+
+
+ifunc (gnu::ifunc)
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+``__attribute__((ifunc("resolver")))`` is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function.
+
+The symbol name of the resolver function is given in quotes. A function with this name (after mangling) must be defined in the current translation unit; it may be ``static``. The resolver function should take no arguments and return a pointer.
+
+The ``ifunc`` attribute may only be used on a function declaration. A function declaration with an ``ifunc`` attribute is considered to be a definition of the declared entity. The entity must not have weak linkage; for example, in C++, it cannot be applied to a declaration if a definition at that location would be considered inline.
+
+Not all targets support this attribute. ELF targets support this attribute when using binutils v2.20.1 or higher and glibc v2.11.1 or higher. Non-ELF targets currently do not support this attribute.
+
+
+internal_linkage (clang::internal_linkage)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``internal_linkage`` attribute changes the linkage type of the declaration to internal.
+This is similar to C-style ``static``, but can be used on classes and class methods. When applied to a class definition,
+this attribute affects all methods and static data members of that class.
+This can be used to contain the ABI of a C++ library by excluding unwanted class methods from the export tables.
+
+
+interrupt (ARM)
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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.
+
+
+interrupt (AVR)
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((interrupt))`` attribute on
+AVR 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.
+
+On the AVR, the hardware globally disables interrupts when an interrupt is executed.
+The first instruction of an interrupt handler declared with this attribute is a SEI
+instruction to re-enable interrupts. See also the signal attribute that
+does not insert a SEI instruction.
+
+
+interrupt (MIPS)
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((interrupt("ARGUMENT")))`` attribute on
+MIPS 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.
+
+By default, the compiler will produce a function prologue and epilogue suitable for
+an interrupt service routine that handles an External Interrupt Controller (eic)
+generated interrupt. This behaviour can be explicitly requested with the "eic"
+argument.
+
+Otherwise, for use with vectored interrupt mode, the argument passed should be
+of the form "vector=LEVEL" where LEVEL is one of the following values:
+"sw0", "sw1", "hw0", "hw1", "hw2", "hw3", "hw4", "hw5". The compiler will
+then set the interrupt mask to the corresponding level which will mask all
+interrupts up to and including the argument.
+
+The semantics are as follows:
+
+- The prologue is modified so that the Exception Program Counter (EPC) and
+ Status coprocessor registers are saved to the stack. The interrupt mask is
+ set so that the function can only be interrupted by a higher priority
+ interrupt. The epilogue will restore the previous values of EPC and Status.
+
+- The prologue and epilogue are modified to save and restore all non-kernel
+ registers as necessary.
+
+- The FPU is disabled in the prologue, as the floating pointer registers are not
+ spilled to the stack.
+
+- The function return sequence is changed to use an exception return instruction.
+
+- The parameter sets the interrupt mask for the function corresponding to the
+ interrupt level specified. If no mask is specified the interrupt mask
+ defaults to "eic".
+
+
+kernel
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", "X"
+
+``__attribute__((kernel))`` is used to mark a ``kernel`` function in
+RenderScript.
+
+In RenderScript, ``kernel`` functions are used to express data-parallel
+computations. The RenderScript runtime efficiently parallelizes ``kernel``
+functions to run on computational resources such as multi-core CPUs and GPUs.
+See the RenderScript_ documentation for more information.
+
+.. _RenderScript: https://developer.android.com/guide/topics/renderscript/compute.html
+
+
+long_call (gnu::long_call, gnu::far)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
+and ``__attribute__((near))`` attributes on MIPS targets. These attributes may
+only be added to function declarations and change the code generated
+by the compiler when directly calling the function. The ``near`` attribute
+allows calls to the function to be made using the ``jal`` instruction, which
+requires the function to be located in the same naturally aligned 256MB
+segment as the caller. The ``long_call`` and ``far`` attributes are synonyms
+and require the use of a different call sequence that works regardless
+of the distance between the functions.
+
+These attributes have no effect for position-independent code.
+
+These attributes take priority over command line switches such
+as ``-mlong-calls`` and ``-mno-long-calls``.
+
+
+micromips (gnu::micromips)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((micromips))`` and
+``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.
+
+These attributes override the `-mmicromips` and `-mno-micromips` options
+on the command line.
+
+
+no_caller_saved_registers (gnu::no_caller_saved_registers)
+----------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+Use this attribute to indicate that the specified function has no
+caller-saved registers. That is, all registers are callee-saved except for
+registers used for passing parameters to the function or returning parameters
+from the function.
+The compiler saves and restores any modified registers that were not used for
+passing or returning arguments to the function.
+
+The user can call functions specified with the 'no_caller_saved_registers'
+attribute from an interrupt handler without saving and restoring all
+call-clobbered registers.
+
+Note that 'no_caller_saved_registers' attribute is not a calling convention.
+In fact, it only overrides the decision of which registers should be saved by
+the caller, but not how the parameters are passed from the caller to the callee.
+
+For example:
+
+ .. code-block:: c
+
+ __attribute__ ((no_caller_saved_registers, fastcall))
+ void f (int arg1, int arg2) {
+ ...
+ }
+
+ In this case parameters 'arg1' and 'arg2' will be passed in registers.
+ In this case, on 32-bit x86 targets, the function 'f' will use ECX and EDX as
+ register parameters. However, it will not assume any scratch registers and
+ should save and restore any modified registers except for ECX and EDX.
+
+
+no_sanitize (clang::no_sanitize)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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_memory
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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_sanitize_thread
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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_split_stack (gnu::no_split_stack)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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.
+
+
+noalias
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","X","", "", ""
+
+The ``noalias`` attribute indicates that the only memory accesses inside
+function are loads and stores from objects pointed to by its pointer-typed
+arguments, with arbitrary offsets.
+
+
+nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result
+---------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","X","","", "", "X"
+
+Clang supports the ability to diagnose when the results of a function call
+expression are discarded under suspicious circumstances. A diagnostic is
+generated when a function or its return type is marked with ``[[nodiscard]]``
+(or ``__attribute__((warn_unused_result))``) and the function call appears as a
+potentially-evaluated discarded-value expression that is not explicitly cast to
+`void`.
+
+.. code-block: c++
+ struct [[nodiscard]] error_info { /*...*/ };
+ error_info enable_missile_safety_mode();
+
+ void launch_missiles();
+ void test_missiles() {
+ enable_missile_safety_mode(); // diagnoses
+ launch_missiles();
+ }
+ error_info &foo();
+ void f() { foo(); } // Does not diagnose, error_info is a reference.
+
+
+noduplicate (clang::noduplicate)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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.
+
+
+nomicromips (gnu::nomicromips)
+------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((micromips))`` and
+``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.
+
+These attributes override the `-mmicromips` and `-mno-micromips` options
+on the command line.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","X","","","", "", "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.
+
+
+not_tail_called (clang::not_tail_called)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``not_tail_called`` attribute prevents tail-call optimization on statically bound calls. It has no effect on indirect calls. Virtual functions, objective-c methods, and functions marked as ``always_inline`` cannot be marked as ``not_tail_called``.
+
+For example, it prevents tail-call optimization in the following case:
+
+ .. code-block:: c
+
+ int __attribute__((not_tail_called)) foo1(int);
+
+ int foo2(int a) {
+ return foo1(a); // No tail-call optimization on direct calls.
+ }
+
+However, it doesn't prevent tail-call optimization in this case:
+
+ .. code-block:: c
+
+ int __attribute__((not_tail_called)) foo1(int);
+
+ int foo2(int a) {
+ int (*fn)(int) = &foo1;
+
+ // not_tail_called has no effect on an indirect call even if the call can be
+ // resolved at compile time.
+ return (*fn)(a);
+ }
+
+Marking virtual functions as ``not_tail_called`` is an error:
+
+ .. code-block:: c++
+
+ class Base {
+ public:
+ // not_tail_called on a virtual function is an error.
+ [[clang::not_tail_called]] virtual int foo1();
+
+ virtual int foo2();
+
+ // Non-virtual functions can be marked ``not_tail_called``.
+ [[clang::not_tail_called]] int foo3();
+ };
+
+ class Derived1 : public Base {
+ public:
+ int foo1() override;
+
+ // not_tail_called on a virtual function is an error.
+ [[clang::not_tail_called]] int foo2() override;
+ };
+
+
+nothrow (gnu::nothrow)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","X","", "", "X"
+
+Clang supports the GNU style ``__attribute__((nothrow))`` and Microsoft style
+``__declspec(nothrow)`` attribute as an equivilent of `noexcept` on function
+declarations. This attribute informs the compiler that the annotated function
+does not throw an exception. This prevents exception-unwinding. This attribute
+is particularly useful on functions in the C Standard Library that are
+guaranteed to not throw an exception.
+
+
+objc_boxable (clang::objc_boxable)
+----------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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 (clang::objc_method_family)
+----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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 (clang::objc_requires_super)
+------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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 (clang::objc_runtime_name)
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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
+
+
+objc_runtime_visible (clang::objc_runtime_visible)
+--------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+This attribute specifies that the Objective-C class to which it applies is visible to the Objective-C runtime but not to the linker. Classes annotated with this attribute cannot be subclassed and cannot have categories defined for them.
+
+
+optnone (clang::optnone)
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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 (clang::overloadable)
+----------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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.
+
+* If no viable candidates are otherwise available, we allow a conversion from a
+ pointer of type ``T*`` to a pointer of type ``U*``, where ``T`` and ``U`` are
+ incompatible. This conversion is ranked below all other types of conversions.
+ Please note: ``U`` lacking qualifiers that are present on ``T`` is sufficient
+ for ``T`` and ``U`` to be incompatible.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions. If a function is marked with the ``overloadable``
+attribute, then all declarations and definitions of functions with that name,
+except for at most one (see the note below about unmarked overloads), must have
+the ``overloadable`` attribute. In addition, redeclarations of a function with
+the ``overloadable`` attribute must have the ``overloadable`` attribute, and
+redeclarations of a function without the ``overloadable`` attribute must *not*
+have 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 f(int); // error: redeclaration 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
+
+ int h(int);
+ int h(int) __attribute__((overloadable)); // error: declaration of "h" must not
+ // 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.
+
+For the purpose of backwards compatibility, at most one function with the same
+name as other ``overloadable`` functions may omit the ``overloadable``
+attribute. In this case, the function without the ``overloadable`` attribute
+will not have its name mangled.
+
+For example:
+
+.. code-block:: c
+
+ // Notes with mangled names assume Itanium mangling.
+ int f(int);
+ int f(double) __attribute__((overloadable));
+ void foo() {
+ f(5); // Emits a call to f (not _Z1fi, as it would with an overload that
+ // was marked with overloadable).
+ f(1.0); // Emits a call to _Z1fd.
+ }
+
+Support for unmarked overloads is not present in some versions of clang. You may
+query for it using ``__has_extension(overloadable_unmarked)``.
+
+Query for this attribute with ``__has_attribute(overloadable)``.
+
+
+release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+Marks a function as releasing a capability.
+
+
+short_call (gnu::short_call, gnu::near)
+---------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
+``__attribute__((short__call))``, and ``__attribute__((near))`` attributes
+on MIPS targets. These attributes may only be added to function declarations
+and change the code generated by the compiler when directly calling
+the function. The ``short_call`` and ``near`` attributes are synonyms and
+allow calls to the function to be made using the ``jal`` instruction, which
+requires the function to be located in the same naturally aligned 256MB segment
+as the caller. The ``long_call`` and ``far`` attributes are synonyms and
+require the use of a different call sequence that works regardless
+of the distance between the functions.
+
+These attributes have no effect for position-independent code.
+
+These attributes take priority over command line switches such
+as ``-mlong-calls`` and ``-mno-long-calls``.
+
+
+signal (gnu::signal)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((signal))`` attribute on
+AVR 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.
+
+Interrupt handler functions defined with the signal attribute do not re-enable interrupts.
+
+
+target (gnu::target)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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).
+
+
+xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument), xray_log_args (clang::xray_log_args)
+--------------------------------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+``__attribute__((xray_always_instrument))`` or ``[[clang::xray_always_instrument]]`` is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching.
+
+Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points.
+
+If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.
+
+``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is used to preserve N function arguments for the logging function. Currently, only N==1 is supported.
+
+
+xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument), xray_log_args (clang::xray_log_args)
+--------------------------------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+``__attribute__((xray_always_instrument))`` or ``[[clang::xray_always_instrument]]`` is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching.
+
+Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points.
+
+If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.
+
+``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is used to preserve N function arguments for the logging function. Currently, only N==1 is supported.
+
+
+Variable Attributes
+===================
+
+
+dllexport (gnu::dllexport)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","X","", "", "X"
+
+The ``__declspec(dllexport)`` attribute declares a variable, function, or
+Objective-C interface to be exported from the module. It is available under the
+``-fdeclspec`` flag for compatibility with various compilers. The primary use
+is for COFF object files which explicitly specify what interfaces are available
+for external use. See the dllexport_ documentation on MSDN for more
+information.
+
+.. _dllexport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
+
+
+dllimport (gnu::dllimport)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","X","", "", "X"
+
+The ``__declspec(dllimport)`` attribute declares a variable, function, or
+Objective-C interface to be imported from an external module. It is available
+under the ``-fdeclspec`` flag for compatibility with various compilers. The
+primary use is for COFF object files which explicitly specify what interfaces
+are imported from external modules. See the dllimport_ documentation on MSDN
+for more information.
+
+.. _dllimport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
+
+
+init_seg
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","", "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
+
+
+maybe_unused, unused, gnu::unused
+---------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","X","","", "", ""
+
+When passing the ``-Wunused`` flag to Clang, entities that are unused by the
+program may be diagnosed. The ``[[maybe_unused]]`` (or
+``__attribute__((unused))``) attribute can be used to silence such diagnostics
+when the entity cannot be removed. For instance, a local variable may exist
+solely for use in an ``assert()`` statement, which makes the local variable
+unused when ``NDEBUG`` is defined.
+
+The attribute may be applied to the declaration of a class, a typedef, a
+variable, a function or method, a function parameter, an enumeration, an
+enumerator, a non-static data member, or a label.
+
+.. code-block: c++
+ #include <cassert>
+
+ [[maybe_unused]] void f([[maybe_unused]] bool thing1,
+ [[maybe_unused]] bool thing2) {
+ [[maybe_unused]] bool b = thing1 && thing2;
+ assert(b);
+ }
+
+
+nodebug (gnu::nodebug)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``nodebug`` attribute allows you to suppress debugging information for a
+function or method, or for a variable that is not a parameter or a non-static
+data member.
+
+
+noescape (clang::noescape)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+``noescape`` placed on a function parameter of a pointer type is used to inform
+the compiler that the pointer cannot escape: that is, no reference to the object
+the pointer points to that is derived from the parameter value will survive
+after the function returns. Users are responsible for making sure parameters
+annotated with ``noescape`` do not actuallly escape.
+
+For example:
+
+.. code-block:: c
+
+ int *gp;
+
+ void nonescapingFunc(__attribute__((noescape)) int *p) {
+ *p += 100; // OK.
+ }
+
+ void escapingFunc(__attribute__((noescape)) int *p) {
+ gp = p; // Not OK.
+ }
+
+Additionally, when the parameter is a `block pointer
+<https://clang.llvm.org/docs/BlockLanguageSpec.html>`, the same restriction
+applies to copies of the block. For example:
+
+.. code-block:: c
+
+ typedef void (^BlockTy)();
+ BlockTy g0, g1;
+
+ void nonescapingFunc(__attribute__((noescape)) BlockTy block) {
+ block(); // OK.
+ }
+
+ void escapingFunc(__attribute__((noescape)) BlockTy block) {
+ g0 = block; // Not OK.
+ g1 = Block_copy(block); // Not OK either.
+ }
+
+
+nosvm
+-----
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", "X"
+
+OpenCL 2.0 supports the optional ``__attribute__((nosvm))`` qualifier for
+pointer variable. It informs the compiler that the pointer does not refer
+to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details.
+
+Since it is not widely used and has been removed from OpenCL 2.1, it is ignored
+by Clang.
+
+
+pass_object_size (clang::pass_object_size)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+.. Note:: The mangling of functions with parameters that are annotated with
+ ``pass_object_size`` is subject to change. You can get around this by
+ using ``__asm__("foo")`` to explicitly name your functions, thus preserving
+ your ABI; also, non-overloadable C functions with ``pass_object_size`` are
+ not mangled.
+
+The ``pass_object_size(Type)`` attribute can be placed on function parameters to
+instruct clang to call ``__builtin_object_size(param, Type)`` at each callsite
+of said function, and implicitly pass the result of this call in as an invisible
+argument of type ``size_t`` directly after the parameter annotated with
+``pass_object_size``. Clang will also replace any calls to
+``__builtin_object_size(param, Type)`` in the function by said implicit
+parameter.
+
+Example usage:
+
+.. code-block:: c
+
+ int bzero1(char *const p __attribute__((pass_object_size(0))))
+ __attribute__((noinline)) {
+ int i = 0;
+ for (/**/; i < (int)__builtin_object_size(p, 0); ++i) {
+ p[i] = 0;
+ }
+ return i;
+ }
+
+ int main() {
+ char chars[100];
+ int n = bzero1(&chars[0]);
+ assert(n == sizeof(chars));
+ return 0;
+ }
+
+If successfully evaluating ``__builtin_object_size(param, Type)`` at the
+callsite is not possible, then the "failed" value is passed in. So, using the
+definition of ``bzero1`` from above, the following code would exit cleanly:
+
+.. code-block:: c
+
+ int main2(int argc, char *argv[]) {
+ int n = bzero1(argv);
+ assert(n == -1);
+ return 0;
+ }
+
+``pass_object_size`` plays a part in overload resolution. If two overload
+candidates are otherwise equally good, then the overload with one or more
+parameters with ``pass_object_size`` is preferred. This implies that the choice
+between two identical overloads both with ``pass_object_size`` on one or more
+parameters will always be ambiguous; for this reason, having two such overloads
+is illegal. For example:
+
+.. code-block:: c++
+
+ #define PS(N) __attribute__((pass_object_size(N)))
+ // OK
+ void Foo(char *a, char *b); // Overload A
+ // OK -- overload A has no parameters with pass_object_size.
+ void Foo(char *a PS(0), char *b PS(0)); // Overload B
+ // Error -- Same signature (sans pass_object_size) as overload B, and both
+ // overloads have one or more parameters with the pass_object_size attribute.
+ void Foo(void *a PS(0), void *b);
+
+ // OK
+ void Bar(void *a PS(0)); // Overload C
+ // OK
+ void Bar(char *c PS(1)); // Overload D
+
+ void main() {
+ char known[10], *unknown;
+ Foo(unknown, unknown); // Calls overload B
+ Foo(known, unknown); // Calls overload B
+ Foo(unknown, known); // Calls overload B
+ Foo(known, known); // Calls overload B
+
+ Bar(known); // Calls overload D
+ Bar(unknown); // Calls overload D
+ }
+
+Currently, ``pass_object_size`` is a bit restricted in terms of its usage:
+
+* Only one use of ``pass_object_size`` is allowed per parameter.
+
+* It is an error to take the address of a function with ``pass_object_size`` on
+ any of its parameters. If you wish to do this, you can create an overload
+ without ``pass_object_size`` on any parameters.
+
+* It is an error to apply the ``pass_object_size`` attribute to parameters that
+ are not pointers. Additionally, any parameter that ``pass_object_size`` is
+ applied to must be marked ``const`` at its function's definition.
+
+
+require_constant_initialization (clang::require_constant_initialization)
+------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+This attribute specifies that the variable to which it is attached is intended
+to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_
+according to the rules of [basic.start.static]. The variable is required to
+have static or thread storage duration. If the initialization of the variable
+is not a constant initializer an error will be produced. This attribute may
+only be used in C++.
+
+Note that in C++03 strict constant expression checking is not done. Instead
+the attribute reports if Clang can emit the variable as a constant, even if it's
+not technically a 'constant initializer'. This behavior is non-portable.
+
+Static storage duration variables with constant initializers avoid hard-to-find
+bugs caused by the indeterminate order of dynamic initialization. They can also
+be safely used during dynamic initialization across translation units.
+
+This attribute acts as a compile time assertion that the requirements
+for constant initialization have been met. Since these requirements change
+between dialects and have subtle pitfalls it's important to fail fast instead
+of silently falling back on dynamic initialization.
+
+.. code-block:: c++
+
+ // -std=c++14
+ #define SAFE_STATIC [[clang::require_constant_initialization]]
+ struct T {
+ constexpr T(int) {}
+ ~T(); // non-trivial
+ };
+ SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor.
+ SAFE_STATIC T y = 42; // error: variable does not have a constant initializer
+ // copy initialization is not a constant expression on a non-literal type.
+
+
+section (gnu::section, __declspec(allocate))
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","X","", "", "X"
+
+The ``section`` attribute allows you to specify a specific section a
+global variable or function should be in after translation.
+
+
+swift_context (clang::swift_context)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``swift_context`` attribute marks a parameter of a ``swiftcall``
+function as having the special context-parameter ABI treatment.
+
+This treatment generally passes the context value in a special register
+which is normally callee-preserved.
+
+A ``swift_context`` parameter must either be the last parameter or must be
+followed by a ``swift_error_result`` parameter (which itself must always be
+the last parameter).
+
+A context parameter must have pointer or reference type.
+
+
+swift_error_result (clang::swift_error_result)
+----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``swift_error_result`` attribute marks a parameter of a ``swiftcall``
+function as having the special error-result ABI treatment.
+
+This treatment generally passes the underlying error value in and out of
+the function through a special register which is normally callee-preserved.
+This is modeled in C by pretending that the register is addressable memory:
+
+- The caller appears to pass the address of a variable of pointer type.
+ The current value of this variable is copied into the register before
+ the call; if the call returns normally, the value is copied back into the
+ variable.
+
+- The callee appears to receive the address of a variable. This address
+ is actually a hidden location in its own stack, initialized with the
+ value of the register upon entry. When the function returns normally,
+ the value in that hidden location is written back to the register.
+
+A ``swift_error_result`` parameter must be the last parameter, and it must be
+preceded by a ``swift_context`` parameter.
+
+A ``swift_error_result`` parameter must have type ``T**`` or ``T*&`` for some
+type T. Note that no qualifiers are permitted on the intermediate level.
+
+It is undefined behavior if the caller does not pass a pointer or
+reference to a valid object.
+
+The standard convention is that the error value itself (that is, the
+value stored in the apparent argument) will be null upon function entry,
+but this is not enforced by the ABI.
+
+
+swift_indirect_result (clang::swift_indirect_result)
+----------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
+function as having the special indirect-result ABI treatment.
+
+This treatment gives the parameter the target's normal indirect-result
+ABI treatment, which may involve passing it differently from an ordinary
+parameter. However, only the first indirect result will receive this
+treatment. Furthermore, low-level lowering may decide that a direct result
+must be returned indirectly; if so, this will take priority over the
+``swift_indirect_result`` parameters.
+
+A ``swift_indirect_result`` parameter must either be the first parameter or
+follow another ``swift_indirect_result`` parameter.
+
+A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for
+some object type ``T``. If ``T`` is a complete type at the point of
+definition of a function, it is undefined behavior if the argument
+value does not point to storage of adequate size and alignment for a
+value of type ``T``.
+
+Making indirect results explicit in the signature allows C functions to
+directly construct objects into them without relying on language
+optimizations like C++'s named return value optimization (NRVO).
+
+
+swiftcall (clang::swiftcall)
+----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+The ``swiftcall`` attribute indicates that a function should be called
+using the Swift calling convention for a function or function pointer.
+
+The lowering for the Swift calling convention, as described by the Swift
+ABI documentation, occurs in multiple phases. The first, "high-level"
+phase breaks down the formal parameters and results into innately direct
+and indirect components, adds implicit paraameters for the generic
+signature, and assigns the context and error ABI treatments to parameters
+where applicable. The second phase breaks down the direct parameters
+and results from the first phase and assigns them to registers or the
+stack. The ``swiftcall`` convention only handles this second phase of
+lowering; the C function type must accurately reflect the results
+of the first phase, as follows:
+
+- Results classified as indirect by high-level lowering should be
+ represented as parameters with the ``swift_indirect_result`` attribute.
+
+- Results classified as direct by high-level lowering should be represented
+ as follows:
+
+ - First, remove any empty direct results.
+
+ - If there are no direct results, the C result type should be ``void``.
+
+ - If there is one direct result, the C result type should be a type with
+ the exact layout of that result type.
+
+ - If there are a multiple direct results, the C result type should be
+ a struct type with the exact layout of a tuple of those results.
+
+- Parameters classified as indirect by high-level lowering should be
+ represented as parameters of pointer type.
+
+- Parameters classified as direct by high-level lowering should be
+ omitted if they are empty types; otherwise, they should be represented
+ as a parameter type with a layout exactly matching the layout of the
+ Swift parameter type.
+
+- The context parameter, if present, should be represented as a trailing
+ parameter with the ``swift_context`` attribute.
+
+- The error result parameter, if present, should be represented as a
+ trailing parameter (always following a context parameter) with the
+ ``swift_error_result`` attribute.
+
+``swiftcall`` does not support variadic arguments or unprototyped functions.
+
+The parameter ABI treatment attributes are aspects of the function type.
+A function type which which applies an ABI treatment attribute to a
+parameter is a different type from an otherwise-identical function type
+that does not. A single parameter may not have multiple ABI treatment
+attributes.
+
+Support for this feature is target-dependent, although it should be
+supported on every target that Swift supports. Query for this support
+with ``__has_attribute(swiftcall)``. This implies support for the
+``swift_context``, ``swift_error_result``, and ``swift_indirect_result``
+attributes.
+
+
+thread
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","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.
+
+
+tls_model (gnu::tls_model)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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.
+
+
+Type Attributes
+===============
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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 {};
+
+
+align_value
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", "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.
+
+
+empty_bases
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","X","", "", ""
+
+The empty_bases attribute permits the compiler to utilize the
+empty-base-optimization more frequently.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.
+
+
+enum_extensibility (clang::enum_extensibility)
+----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Attribute ``enum_extensibility`` is used to distinguish between enum definitions
+that are extensible and those that are not. The attribute can take either
+``closed`` or ``open`` as an argument. ``closed`` indicates a variable of the
+enum type takes a value that corresponds to one of the enumerators listed in the
+enum definition or, when the enum is annotated with ``flag_enum``, a value that
+can be constructed using values corresponding to the enumerators. ``open``
+indicates a variable of the enum type can take any values allowed by the
+standard and instructs clang to be more lenient when issuing warnings.
+
+.. code-block:: c
+
+ enum __attribute__((enum_extensibility(closed))) ClosedEnum {
+ A0, A1
+ };
+
+ enum __attribute__((enum_extensibility(open))) OpenEnum {
+ B0, B1
+ };
+
+ enum __attribute__((enum_extensibility(closed),flag_enum)) ClosedFlagEnum {
+ C0 = 1 << 0, C1 = 1 << 1
+ };
+
+ enum __attribute__((enum_extensibility(open),flag_enum)) OpenFlagEnum {
+ D0 = 1 << 0, D1 = 1 << 1
+ };
+
+ void foo1() {
+ enum ClosedEnum ce;
+ enum OpenEnum oe;
+ enum ClosedFlagEnum cfe;
+ enum OpenFlagEnum ofe;
+
+ ce = A1; // no warnings
+ ce = 100; // warning issued
+ oe = B1; // no warnings
+ oe = 100; // no warnings
+ cfe = C0 | C1; // no warnings
+ cfe = C0 | C1 | 4; // warning issued
+ ofe = D0 | D1; // no warnings
+ ofe = D0 | D1 | 4; // no warnings
+ }
+
+
+flag_enum (clang::flag_enum)
+----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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.
+
+
+layout_version
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","X","", "", ""
+
+The layout_version attribute requests that the compiler utilize the class
+layout rules of a particular compiler version.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.
+
+
+lto_visibility_public (clang::lto_visibility_public)
+----------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+See :doc:`LTOVisibility`.
+
+
+novtable
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","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. It is only supported when using the Microsoft C++ ABI.
+
+
+objc_subclassing_restricted (clang::objc_subclassing_restricted)
+----------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+This attribute can be added to an Objective-C ``@interface`` declaration to
+ensure that this class cannot be subclassed.
+
+
+selectany (gnu::selectany)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","X","", "", ""
+
+This attribute appertains to a global symbol, causing it to have a weak
+definition (
+`linkonce <https://llvm.org/docs/LangRef.html#linkage-types>`_
+), allowing the linker to select any definition.
+
+For more information see
+`gcc documentation <https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html>`_
+or `msvc documentation <https://docs.microsoft.com/pl-pl/cpp/cpp/selectany>`_.
+
+
+transparent_union (gnu::transparent_union)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+This attribute can be applied to a union to change the behaviour of calls to
+functions that have an argument with a transparent union type. The compiler
+behaviour is changed in the following manner:
+
+- A value whose type is any member of the transparent union can be passed as an
+ argument without the need to cast that value.
+
+- The argument is passed to the function using the calling convention of the
+ first member of the transparent union. Consequently, all the members of the
+ transparent union should have the same calling convention as its first member.
+
+Transparent unions are not supported in C++.
+
+
+Statement Attributes
+====================
+
+
+#pragma clang loop
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","", "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","", "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 and
+attempt to partially unroll the loop if the trip count is not 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.
+
+
+__attribute__((intel_reqd_sub_group_size))
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", "X"
+
+The optional attribute intel_reqd_sub_group_size can be used to indicate that
+the kernel must be compiled and executed with the specified subgroup size. When
+this attribute is present, get_max_sub_group_size() is guaranteed to return the
+specified integer value. This is important for the correctness of many subgroup
+algorithms, and in some cases may be used by the compiler to generate more optimal
+code. See `cl_intel_required_subgroup_size
+<https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt>`
+for details.
+
+
+__attribute__((opencl_unroll_hint))
+-----------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", ""
+
+The opencl_unroll_hint attribute qualifier can be used to specify that a loop
+(for, while and do loops) can be unrolled. This attribute qualifier can be
+used to specify full unrolling or partial unrolling by a specified amount.
+This is a compiler hint and the compiler may ignore this directive. See
+`OpenCL v2.0 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`_
+s6.11.5 for details.
+
+
+__read_only, __write_only, __read_write (read_only, write_only, read_write)
+---------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","X", "", ""
+
+The access qualifiers must be used with image object arguments or pipe arguments
+to declare if they are being read or written by a kernel or function.
+
+The read_only/__read_only, write_only/__write_only and read_write/__read_write
+names are reserved for use as access qualifiers and shall not be used otherwise.
+
+.. code-block:: c
+
+ kernel void
+ foo (read_only image2d_t imageA,
+ write_only image2d_t imageB) {
+ ...
+ }
+
+In the above example imageA is a read-only 2D image object, and imageB is a
+write-only 2D image object.
+
+The read_write (or __read_write) qualifier can not be used with pipe.
+
+More details can be found in the OpenCL C language Spec v2.0, Section 6.6.
+
+
+fallthrough, clang::fallthrough
+-------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","X","X","","", "", ""
+
+The ``fallthrough`` (or ``clang::fallthrough``) attribute is used
+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.
+
+By default, Clang does not warn on unannotated fallthrough from one ``switch``
+case to another. Diagnostics on fallthrough without a corresponding annotation
+can be enabled with the ``-Wimplicit-fallthrough`` argument.
+
+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();
+ }
+
+
+suppress (gsl::suppress)
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","X","","","", "", ""
+
+The ``[[gsl::suppress]]`` attribute suppresses specific
+clang-tidy diagnostics for rules of the `C++ Core Guidelines`_ in a portable
+way. The attribute can be attached to declarations, statements, and at
+namespace scope.
+
+.. code-block:: c++
+
+ [[gsl::suppress("Rh-public")]]
+ void f_() {
+ int *p;
+ [[gsl::suppress("type")]] {
+ p = reinterpret_cast<int*>(7);
+ }
+ }
+ namespace N {
+ [[clang::suppress("type", "bounds")]];
+ ...
+ }
+
+.. _`C++ Core Guidelines`: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement
+
+
+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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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".
+
+
+preserve_all (clang::preserve_all)
+----------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The ``preserve_all`` calling convention attempts to make the code
+in the caller even less intrusive than the ``preserve_most`` calling convention.
+This calling convention also behaves identical to the ``C`` calling convention
+on how arguments and return values are passed, but it uses a different set of
+caller/callee-saved registers. This removes the burden of saving and
+recovering a large register set before and after the call in the caller. If
+the arguments are passed in callee-saved registers, then they will be
+preserved by the callee across the call. This doesn't apply for values
+returned in callee-saved registers.
+
+- On X86-64 the callee preserves all general purpose registers, except for
+ R11. R11 can be used as a scratch register. Furthermore it also preserves
+ all floating-point registers (XMMs/YMMs).
+
+The idea behind this convention is to support calls to runtime functions
+that don't need to call out to any other functions.
+
+This calling convention, like the ``preserve_most`` calling convention, will be
+used by a future version of the Objective-C runtime and should be considered
+experimental at this time.
+
+
+preserve_most (clang::preserve_most)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", ""
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The ``preserve_most`` calling convention attempts to make the code
+in the caller as unintrusive as possible. This convention behaves identically
+to the ``C`` calling convention on how arguments and return values are passed,
+but it uses a different set of caller/callee-saved registers. This alleviates
+the burden of saving and recovering a large register set before and after the
+call in the caller. If the arguments are passed in callee-saved registers,
+then they will be preserved by the callee across the call. This doesn't
+apply for values returned in callee-saved registers.
+
+- On X86-64 the callee preserves all general purpose registers, except for
+ R11. R11 can be used as a scratch register. Floating-point registers
+ (XMMs/YMMs) are not preserved and need to be saved by the caller.
+
+The idea behind this convention is to support calls to runtime functions
+that have a hot path and a cold path. The hot path is usually a small piece
+of code that doesn't use many registers. The cold path might need to call out to
+another function and therefore only needs to preserve the caller-saved
+registers, which haven't already been saved by the caller. The
+`preserve_most` calling convention is very similar to the ``cold`` calling
+convention in terms of caller/callee-saved registers, but they are used for
+different types of function calls. ``coldcc`` is for function calls that are
+rarely executed, whereas `preserve_most` function calls are intended to be
+on the hot path and definitely executed a lot. Furthermore ``preserve_most``
+doesn't prevent the inliner from inlining the function call.
+
+This calling convention will be used by a future version of the Objective-C
+runtime and should therefore still be considered experimental at this time.
+Although this convention was created to optimize certain runtime calls to
+the Objective-C runtime, it is not limited to this runtime and might be used
+by other runtimes in the future too. The current implementation only
+supports X86-64 and AArch64, but the intention is to support more architectures
+in the future.
+
+
+regcall (gnu::regcall, __regcall)
+---------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","X", "", ""
+
+On x86 targets, this attribute changes the calling convention to
+`__regcall`_ convention. This convention aims to pass as many arguments
+as possible in registers. It also tries to utilize registers for the
+return value whenever it is possible.
+
+.. _`__regcall`: https://software.intel.com/en-us/node/693069
+
+
+regparm (gnu::regparm)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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 (clang::vectorcall, __vectorcall, _vectorcall)
+---------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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. Homogeneous 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
+
+
+AMD GPU Attributes
+==================
+
+
+amdgpu_flat_work_group_size (clang::amdgpu_flat_work_group_size)
+----------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+The flat work-group size is the number of work-items in the work-group size
+specified when the kernel is dispatched. It is the product of the sizes of the
+x, y, and z dimension of the work-group.
+
+Clang supports the
+``__attribute__((amdgpu_flat_work_group_size(<min>, <max>)))`` attribute for the
+AMDGPU target. This attribute may be attached to a kernel function definition
+and is an optimization hint.
+
+``<min>`` parameter specifies the minimum flat work-group size, and ``<max>``
+parameter specifies the maximum flat work-group size (must be greater than
+``<min>``) to which all dispatches of the kernel will conform. Passing ``0, 0``
+as ``<min>, <max>`` implies the default behavior (``128, 256``).
+
+If specified, the AMDGPU target backend might be able to produce better machine
+code for barriers and perform scratch promotion by estimating available group
+segment size.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes.
+
+
+amdgpu_num_sgpr (clang::amdgpu_num_sgpr)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
+``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing ``0`` as
+``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+amdgpu_num_vgpr (clang::amdgpu_num_vgpr)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
+``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing ``0`` as
+``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+amdgpu_waves_per_eu (clang::amdgpu_waves_per_eu)
+------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "X"
+
+A compute unit (CU) is responsible for executing the wavefronts of a work-group.
+It is composed of one or more execution units (EU), which are responsible for
+executing the wavefronts. An EU can have enough resources to maintain the state
+of more than one executing wavefront. This allows an EU to hide latency by
+switching between wavefronts in a similar way to symmetric multithreading on a
+CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
+resources used by a single wavefront have to be limited. For example, the number
+of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
+but can result in having to spill some register state to memory.
+
+Clang supports the ``__attribute__((amdgpu_waves_per_eu(<min>[, <max>])))``
+attribute for the AMDGPU target. This attribute may be attached to a kernel
+function definition and is an optimization hint.
+
+``<min>`` parameter specifies the requested minimum number of waves per EU, and
+*optional* ``<max>`` parameter specifies the requested maximum number of waves
+per EU (must be greater than ``<min>`` if specified). If ``<max>`` is omitted,
+then there is no restriction on the maximum number of waves per EU other than
+the one dictated by the hardware for which the kernel is compiled. Passing
+``0, 0`` as ``<min>, <max>`` implies the default behavior (no limits).
+
+If specified, this attribute allows an advanced developer to tune the number of
+wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
+target backend can use this information to limit resources, such as number of
+SGPRs, number of VGPRs, size of available group and private memory segments, in
+such a way that guarantees that at least ``<min>`` wavefronts and at most
+``<max>`` wavefronts are able to fit within the resources of an EU. Requesting
+more wavefronts can hide memory latency but limits available registers which
+can result in spilling. Requesting fewer wavefronts can help reduce cache
+thrashing, but can reduce memory latency hiding.
+
+This attribute controls the machine code generated by the AMDGPU target backend
+to ensure it is capable of meeting the requested values. However, when the
+kernel is executed, there may be other reasons that prevent meeting the request,
+for example, there may be wavefronts from other kernels executing on the EU.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+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 (clang::callable_when)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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 (clang::consumable)
+------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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 (clang::param_typestate)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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 (clang::return_typestate)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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 (clang::set_typestate)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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 (clang::test_typestate)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","","", "", "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. To see warnings produced by these
+checks, ensure that -Wtype-safety is enabled. 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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most non-variadic cases).
+
+In the attribute prototype above:
+ * ``arg_kind`` is an identifier that should be used when annotating all
+ applicable type tags.
+ * ``arg_idx`` provides the position of a function argument. The expected type of
+ this function argument will be determined by the function argument specified
+ by ``type_tag_idx``. In the code example below, "3" means that the type of the
+ function's third argument will be determined by ``type_tag_idx``.
+ * ``type_tag_idx`` provides the position of a function argument. This function
+ argument will be a type tag. The type tag will determine the expected type of
+ the argument specified by ``arg_idx``. In the code example below, "2" means
+ that the type tag associated with the function's second argument should agree
+ with the type of the argument specified by ``arg_idx``.
+
+For example:
+
+.. code-block:: c++
+
+ int fcntl(int fd, int cmd, ...)
+ __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+ // The function's second argument will be a type tag; this type tag will
+ // determine the expected type of the function's third argument.
+
+
+pointer_with_type_tag
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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.
+
+In the attribute prototype above:
+ * ``ptr_kind`` is an identifier that should be used when annotating all
+ applicable type tags.
+ * ``ptr_idx`` provides the position of a function argument; this function
+ argument will have a pointer type. The expected pointee type of this pointer
+ type will be determined by the function argument specified by
+ ``type_tag_idx``. In the code example below, "1" means that the pointee type
+ of the function's first argument will be determined by ``type_tag_idx``.
+ * ``type_tag_idx`` provides the position of a function argument; this function
+ argument will be a type tag. The type tag will determine the expected pointee
+ type of the pointer argument specified by ``ptr_idx``. In the code example
+ below, "3" means that the type tag associated with the function's third
+ argument should agree with the pointee type of the pointer argument specified
+ by ``ptr_idx``.
+
+For example:
+
+.. code-block:: c++
+
+ typedef int MPI_Datatype;
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+ // The function's 3rd argument will be a type tag; this type tag will
+ // determine the expected pointee type of the function's 1st argument.
+
+
+type_tag_for_datatype
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","","", "", ""
+
+When declaring a variable, use
+``__attribute__((type_tag_for_datatype(kind, type)))`` to create a type tag that
+is tied to the ``type`` argument given to the attribute.
+
+In the attribute prototype above:
+ * ``kind`` is an identifier that should be used when annotating all applicable
+ type tags.
+ * ``type`` indicates the name of the type.
+
+Clang supports annotating type tags of two forms.
+
+ * **Type tag that is a reference to a declared identifier.**
+ Use ``__attribute__((type_tag_for_datatype(kind, type)))`` when declaring that
+ identifier:
+
+ .. code-block:: c++
+
+ typedef int MPI_Datatype;
+ extern struct mpi_datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) ));
+ #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+ // &mpi_datatype_int is a type tag. It is tied to type "int".
+
+ * **Type tag that is an integral literal.**
+ Declare a ``static const`` variable with an initializer value and attach
+ ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration:
+
+ .. code-block:: c++
+
+ typedef int MPI_Datatype;
+ static const MPI_Datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) )) = 42;
+ #define MPI_INT ((MPI_Datatype) 42)
+ // The number 42 is a type tag. It is tied to type "int".
+
+
+The ``type_tag_for_datatype`` attribute also accepts an optional third argument
+that determines how the type of the function argument specified by either
+``arg_idx`` or ``ptr_idx`` is compared against the type associated with the type
+tag. (Recall that for the ``argument_with_type_tag`` attribute, the type of the
+function argument specified by ``arg_idx`` is compared against the type
+associated with the type tag. Also recall that for the ``pointer_with_type_tag``
+attribute, the pointee type of the function argument specified by ``ptr_idx`` is
+compared against the type associated with the type tag.) There are two supported
+values for this optional third argument:
+
+ * ``layout_compatible`` will cause types to be compared according to
+ layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
+ layout-compatibility rules for two standard-layout struct types and for two
+ standard-layout union types). This is useful when creating a type tag
+ associated with a struct or union type. For example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ typedef int MPI_Datatype;
+ 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)
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning because the
+ // layout of my_pair is
+ // compatible with that of
+ // internal_mpi_double_int
+
+ struct my_int_pair { int a; int b; }
+ struct my_int_pair *buffer2;
+ MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning because the
+ // layout of my_int_pair
+ // does not match that of
+ // internal_mpi_double_int
+
+ * ``must_be_null`` specifies that the function argument specified by either
+ ``arg_idx`` (for the ``argument_with_type_tag`` attribute) or ``ptr_idx`` (for
+ the ``pointer_with_type_tag`` attribute) should be a null pointer constant.
+ The second argument to the ``type_tag_for_datatype`` attribute is ignored. For
+ example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ typedef int MPI_Datatype;
+ 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)
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ 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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","","","","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.
+
+
+nonnull (gnu::nonnull)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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 (gnu::returns_nonnull)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","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
+
+
More information about the llvm-commits
mailing list