[www-releases] r331981 - Add 5.0.2 docs and update download.html
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Thu May 10 06:54:19 PDT 2018
Added: www-releases/trunk/5.0.2/tools/clang/docs/ObjectiveCLiterals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/ObjectiveCLiterals.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/ObjectiveCLiterals.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/ObjectiveCLiterals.html Thu May 10 06:54:16 2018
@@ -0,0 +1,590 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ <link rel="next" title="Language Specification for Blocks" href="BlockLanguageSpec.html" />
+ <link rel="prev" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Objective-C Literals</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="LanguageExtensions.html">Clang Language Extensions</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="BlockLanguageSpec.html">Language Specification for Blocks</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="objective-c-literals">
+<h1>Objective-C Literals<a class="headerlink" href="#objective-c-literals" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Three new features were introduced into clang at the same time:
+<em>NSNumber Literals</em> provide a syntax for creating <tt class="docutils literal"><span class="pre">NSNumber</span></tt> from
+scalar literal expressions; <em>Collection Literals</em> provide a short-hand
+for creating arrays and dictionaries; <em>Object Subscripting</em> provides a
+way to use subscripting with Objective-C objects. Users of Apple
+compiler releases can use these features starting with the Apple LLVM
+Compiler 4.0. Users of open-source LLVM.org compiler releases can use
+these features starting with clang v3.1.</p>
+<p>These language additions simplify common Objective-C programming
+patterns, make programs more concise, and improve the safety of
+container creation.</p>
+<p>This document describes how the features are implemented in clang, and
+how to use them in your own programs.</p>
+</div>
+<div class="section" id="nsnumber-literals">
+<h2>NSNumber Literals<a class="headerlink" href="#nsnumber-literals" title="Permalink to this headline">¶</a></h2>
+<p>The framework class <tt class="docutils literal"><span class="pre">NSNumber</span></tt> is used to wrap scalar values inside
+objects: signed and unsigned integers (<tt class="docutils literal"><span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>,
+<tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>), floating point numbers (<tt class="docutils literal"><span class="pre">float</span></tt>,
+<tt class="docutils literal"><span class="pre">double</span></tt>), and boolean values (<tt class="docutils literal"><span class="pre">BOOL</span></tt>, C++ <tt class="docutils literal"><span class="pre">bool</span></tt>). Scalar values
+wrapped in objects are also known as <em>boxed</em> values.</p>
+<p>In Objective-C, any character, numeric or boolean literal prefixed with
+the <tt class="docutils literal"><span class="pre">'@'</span></tt> character will evaluate to a pointer to an <tt class="docutils literal"><span class="pre">NSNumber</span></tt>
+object initialized with that value. C’s type suffixes may be used to
+control the size of numeric literals.</p>
+<div class="section" id="examples">
+<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
+<p>The following program illustrates the rules for <tt class="docutils literal"><span class="pre">NSNumber</span></tt> literals:</p>
+<div class="highlight-objc"><pre>void main(int argc, const char *argv[]) {
+ // character literals.
+ NSNumber *theLetterZ = @'Z'; // equivalent to [NSNumber numberWithChar:'Z']
+
+ // integral literals.
+ NSNumber *fortyTwo = @42; // equivalent to [NSNumber numberWithInt:42]
+ NSNumber *fortyTwoUnsigned = @42U; // equivalent to [NSNumber numberWithUnsignedInt:42U]
+ NSNumber *fortyTwoLong = @42L; // equivalent to [NSNumber numberWithLong:42L]
+ NSNumber *fortyTwoLongLong = @42LL; // equivalent to [NSNumber numberWithLongLong:42LL]
+
+ // floating point literals.
+ NSNumber *piFloat = @3.141592654F; // equivalent to [NSNumber numberWithFloat:3.141592654F]
+ NSNumber *piDouble = @3.1415926535; // equivalent to [NSNumber numberWithDouble:3.1415926535]
+
+ // BOOL literals.
+ NSNumber *yesNumber = @YES; // equivalent to [NSNumber numberWithBool:YES]
+ NSNumber *noNumber = @NO; // equivalent to [NSNumber numberWithBool:NO]
+
+#ifdef __cplusplus
+ NSNumber *trueNumber = @true; // equivalent to [NSNumber numberWithBool:(BOOL)true]
+ NSNumber *falseNumber = @false; // equivalent to [NSNumber numberWithBool:(BOOL)false]
+#endif
+}</pre>
+</div>
+</div>
+<div class="section" id="discussion">
+<h3>Discussion<a class="headerlink" href="#discussion" title="Permalink to this headline">¶</a></h3>
+<p>NSNumber literals only support literal scalar values after the <tt class="docutils literal"><span class="pre">'@'</span></tt>.
+Consequently, <tt class="docutils literal"><span class="pre">@INT_MAX</span></tt> works, but <tt class="docutils literal"><span class="pre">@INT_MIN</span></tt> does not, because
+they are defined like this:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="cp">#define INT_MAX 2147483647 </span><span class="cm">/* max value for an int */</span><span class="cp"></span>
+<span class="cp">#define INT_MIN (-2147483647-1) </span><span class="cm">/* min value for an int */</span><span class="cp"></span>
+</pre></div>
+</div>
+<p>The definition of <tt class="docutils literal"><span class="pre">INT_MIN</span></tt> is not a simple literal, but a
+parenthesized expression. Parenthesized expressions are supported using
+the <a class="reference external" href="#objc_boxed_expressions">boxed expression</a> syntax, which is
+described in the next section.</p>
+<p>Because <tt class="docutils literal"><span class="pre">NSNumber</span></tt> does not currently support wrapping <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt>
+values, the use of a <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span> <span class="pre">NSNumber</span></tt> literal (e.g.
+<tt class="docutils literal"><span class="pre">@123.23L</span></tt>) will be rejected by the compiler.</p>
+<p>Previously, the <tt class="docutils literal"><span class="pre">BOOL</span></tt> type was simply a typedef for <tt class="docutils literal"><span class="pre">signed</span> <span class="pre">char</span></tt>,
+and <tt class="docutils literal"><span class="pre">YES</span></tt> and <tt class="docutils literal"><span class="pre">NO</span></tt> were macros that expand to <tt class="docutils literal"><span class="pre">(BOOL)1</span></tt> and
+<tt class="docutils literal"><span class="pre">(BOOL)0</span></tt> respectively. To support <tt class="docutils literal"><span class="pre">@YES</span></tt> and <tt class="docutils literal"><span class="pre">@NO</span></tt> expressions,
+these macros are now defined using new language keywords in
+<tt class="docutils literal"><span class="pre"><objc/objc.h></span></tt>:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="cp">#if __has_feature(objc_bool)</span>
+<span class="cp">#define YES __objc_yes</span>
+<span class="cp">#define NO __objc_no</span>
+<span class="cp">#else</span>
+<span class="cp">#define YES ((BOOL)1)</span>
+<span class="cp">#define NO ((BOOL)0)</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>The compiler implicitly converts <tt class="docutils literal"><span class="pre">__objc_yes</span></tt> and <tt class="docutils literal"><span class="pre">__objc_no</span></tt> to
+<tt class="docutils literal"><span class="pre">(BOOL)1</span></tt> and <tt class="docutils literal"><span class="pre">(BOOL)0</span></tt>. The keywords are used to disambiguate
+<tt class="docutils literal"><span class="pre">BOOL</span></tt> and integer literals.</p>
+<p>Objective-C++ also supports <tt class="docutils literal"><span class="pre">@true</span></tt> and <tt class="docutils literal"><span class="pre">@false</span></tt> expressions, which
+are equivalent to <tt class="docutils literal"><span class="pre">@YES</span></tt> and <tt class="docutils literal"><span class="pre">@NO</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="boxed-expressions">
+<h2>Boxed Expressions<a class="headerlink" href="#boxed-expressions" title="Permalink to this headline">¶</a></h2>
+<p>Objective-C provides a new syntax for boxing C expressions:</p>
+<div class="highlight-objc"><pre>@( <expression> )</pre>
+</div>
+<p>Expressions of scalar (numeric, enumerated, BOOL), C string pointer
+and some C structures (via NSValue) are supported:</p>
+<div class="highlight-objc"><pre>// numbers.
+NSNumber *smallestInt = @(-INT_MAX - 1); // [NSNumber numberWithInt:(-INT_MAX - 1)]
+NSNumber *piOverTwo = @(M_PI / 2); // [NSNumber numberWithDouble:(M_PI / 2)]
+
+// enumerated types.
+typedef enum { Red, Green, Blue } Color;
+NSNumber *favoriteColor = @(Green); // [NSNumber numberWithInt:((int)Green)]
+
+// strings.
+NSString *path = @(getenv("PATH")); // [NSString stringWithUTF8String:(getenv("PATH"))]
+NSArray *pathComponents = [path componentsSeparatedByString:@":"];
+
+// structs.
+NSValue *center = @(view.center); // Point p = view.center;
+ // [NSValue valueWithBytes:&p objCType:@encode(Point)];
+NSValue *frame = @(view.frame); // Rect r = view.frame;
+ // [NSValue valueWithBytes:&r objCType:@encode(Rect)];</pre>
+</div>
+<div class="section" id="boxed-enums">
+<h3>Boxed Enums<a class="headerlink" href="#boxed-enums" title="Permalink to this headline">¶</a></h3>
+<p>Cocoa frameworks frequently define constant values using <em>enums.</em>
+Although enum values are integral, they may not be used directly as
+boxed literals (this avoids conflicts with future <tt class="docutils literal"><span class="pre">'@'</span></tt>-prefixed
+Objective-C keywords). Instead, an enum value must be placed inside a
+boxed expression. The following example demonstrates configuring an
+<tt class="docutils literal"><span class="pre">AVAudioRecorder</span></tt> using a dictionary that contains a boxed enumeration
+value:</p>
+<div class="highlight-objc"><pre>enum {
+ AVAudioQualityMin = 0,
+ AVAudioQualityLow = 0x20,
+ AVAudioQualityMedium = 0x40,
+ AVAudioQualityHigh = 0x60,
+ AVAudioQualityMax = 0x7F
+};
+
+- (AVAudioRecorder *)recordToFile:(NSURL *)fileURL {
+ NSDictionary *settings = @{ AVEncoderAudioQualityKey : @(AVAudioQualityMax) };
+ return [[AVAudioRecorder alloc] initWithURL:fileURL settings:settings error:NULL];
+}</pre>
+</div>
+<p>The expression <tt class="docutils literal"><span class="pre">@(AVAudioQualityMax)</span></tt> converts <tt class="docutils literal"><span class="pre">AVAudioQualityMax</span></tt>
+to an integer type, and boxes the value accordingly. If the enum has a
+<a class="reference internal" href="LanguageExtensions.html#objc-fixed-enum"><em>fixed underlying type</em></a> as in:</p>
+<div class="highlight-objc"><pre>typedef enum : unsigned char { Red, Green, Blue } Color;
+NSNumber *red = @(Red), *green = @(Green), *blue = @(Blue); // => [NSNumber numberWithUnsignedChar:]</pre>
+</div>
+<p>then the fixed underlying type will be used to select the correct
+<tt class="docutils literal"><span class="pre">NSNumber</span></tt> creation method.</p>
+<p>Boxing a value of enum type will result in a <tt class="docutils literal"><span class="pre">NSNumber</span></tt> pointer with a
+creation method according to the underlying type of the enum, which can
+be a <a class="reference internal" href="LanguageExtensions.html#objc-fixed-enum"><em>fixed underlying type</em></a>
+or a compiler-defined integer type capable of representing the values of
+all the members of the enumeration:</p>
+<div class="highlight-objc"><pre>typedef enum : unsigned char { Red, Green, Blue } Color;
+Color col = Red;
+NSNumber *nsCol = @(col); // => [NSNumber numberWithUnsignedChar:]</pre>
+</div>
+</div>
+<div class="section" id="boxed-c-strings">
+<h3>Boxed C Strings<a class="headerlink" href="#boxed-c-strings" title="Permalink to this headline">¶</a></h3>
+<p>A C string literal prefixed by the <tt class="docutils literal"><span class="pre">'@'</span></tt> token denotes an <tt class="docutils literal"><span class="pre">NSString</span></tt>
+literal in the same way a numeric literal prefixed by the <tt class="docutils literal"><span class="pre">'@'</span></tt> token
+denotes an <tt class="docutils literal"><span class="pre">NSNumber</span></tt> literal. When the type of the parenthesized
+expression is <tt class="docutils literal"><span class="pre">(char</span> <span class="pre">*)</span></tt> or <tt class="docutils literal"><span class="pre">(const</span> <span class="pre">char</span> <span class="pre">*)</span></tt>, the result of the
+boxed expression is a pointer to an <tt class="docutils literal"><span class="pre">NSString</span></tt> object containing
+equivalent character data, which is assumed to be ‘\0’-terminated and
+UTF-8 encoded. The following example converts C-style command line
+arguments into <tt class="docutils literal"><span class="pre">NSString</span></tt> objects.</p>
+<div class="highlight-objc"><pre>// Partition command line arguments into positional and option arguments.
+NSMutableArray *args = [NSMutableArray new];
+NSMutableDictionary *options = [NSMutableDictionary new];
+while (--argc) {
+ const char *arg = *++argv;
+ if (strncmp(arg, "--", 2) == 0) {
+ options[@(arg + 2)] = @(*++argv); // --key value
+ } else {
+ [args addObject:@(arg)]; // positional argument
+ }
+}</pre>
+</div>
+<p>As with all C pointers, character pointer expressions can involve
+arbitrary pointer arithmetic, therefore programmers must ensure that the
+character data is valid. Passing <tt class="docutils literal"><span class="pre">NULL</span></tt> as the character pointer will
+raise an exception at runtime. When possible, the compiler will reject
+<tt class="docutils literal"><span class="pre">NULL</span></tt> character pointers used in boxed expressions.</p>
+</div>
+<div class="section" id="boxed-c-structures">
+<h3>Boxed C Structures<a class="headerlink" href="#boxed-c-structures" title="Permalink to this headline">¶</a></h3>
+<p>Boxed expressions support construction of NSValue objects.
+It said that C structures can be used, the only requirement is:
+structure should be marked with <tt class="docutils literal"><span class="pre">objc_boxable</span></tt> attribute.
+To support older version of frameworks and/or third-party libraries
+you may need to add the attribute via <tt class="docutils literal"><span class="pre">typedef</span></tt>.</p>
+<div class="highlight-objc"><pre>struct __attribute__((objc_boxable)) Point {
+ // ...
+};
+
+typedef struct __attribute__((objc_boxable)) _Size {
+ // ...
+} Size;
+
+typedef struct _Rect {
+ // ...
+} Rect;
+
+struct Point p;
+NSValue *point = @(p); // ok
+Size s;
+NSValue *size = @(s); // ok
+
+Rect r;
+NSValue *bad_rect = @(r); // error
+
+typedef struct __attribute__((objc_boxable)) _Rect Rect;
+
+NSValue *good_rect = @(r); // ok</pre>
+</div>
+</div>
+</div>
+<div 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"><pre>NSArray *array = @[ @"Hello", NSApp, [NSNumber numberWithInt:42] ];</pre>
+</div>
+<p>This creates an <tt class="docutils literal"><span class="pre">NSArray</span></tt> with 3 elements. The comma-separated
+sub-expressions of an array literal can be any Objective-C object
+pointer typed expression.</p>
+<p>Immutable dictionary expression:</p>
+<div class="highlight-objc"><pre>NSDictionary *dictionary = @{
+ @"name" : NSUserName(),
+ @"date" : [NSDate date],
+ @"processInfo" : [NSProcessInfo processInfo]
+};</pre>
+</div>
+<p>This creates an <tt class="docutils literal"><span class="pre">NSDictionary</span></tt> with 3 key/value pairs. Value
+sub-expressions of a dictionary literal must be Objective-C object
+pointer typed, as in array literals. Key sub-expressions must be of an
+Objective-C object pointer type that implements the
+<tt class="docutils literal"><span class="pre"><NSCopying></span></tt> protocol.</p>
+</div>
+<div class="section" id="id2">
+<h3>Discussion<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<p>Neither keys nor values can have the value <tt class="docutils literal"><span class="pre">nil</span></tt> in containers. If the
+compiler can prove that a key or value is <tt class="docutils literal"><span class="pre">nil</span></tt> at compile time, then
+a warning will be emitted. Otherwise, a runtime error will occur.</p>
+<p>Using array and dictionary literals is safer than the variadic creation
+forms commonly in use today. Array literal expressions expand to calls
+to <tt class="docutils literal"><span class="pre">+[NSArray</span> <span class="pre">arrayWithObjects:count:]</span></tt>, which validates that all
+objects are non-<tt class="docutils literal"><span class="pre">nil</span></tt>. The variadic form,
+<tt class="docutils literal"><span class="pre">+[NSArray</span> <span class="pre">arrayWithObjects:]</span></tt> uses <tt class="docutils literal"><span class="pre">nil</span></tt> as an argument list
+terminator, which can lead to malformed array objects. Dictionary
+literals are similarly created with
+<tt class="docutils literal"><span class="pre">+[NSDictionary</span> <span class="pre">dictionaryWithObjects:forKeys:count:]</span></tt> which validates
+all objects and keys, unlike
+<tt class="docutils literal"><span class="pre">+[NSDictionary</span> <span class="pre">dictionaryWithObjectsAndKeys:]</span></tt> which also uses a
+<tt class="docutils literal"><span class="pre">nil</span></tt> parameter as an argument list terminator.</p>
+</div>
+</div>
+<div class="section" id="object-subscripting">
+<h2>Object Subscripting<a class="headerlink" href="#object-subscripting" title="Permalink to this headline">¶</a></h2>
+<p>Objective-C object pointer values can now be used with C’s subscripting
+operator.</p>
+<div class="section" id="id3">
+<h3>Examples<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
+<p>The following code demonstrates the use of object subscripting syntax
+with <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt> and <tt class="docutils literal"><span class="pre">NSMutableDictionary</span></tt> objects:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">NSMutableArray</span> <span class="o">*</span><span class="n">array</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">NSUInteger</span> <span class="n">idx</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">id</span> <span class="n">newObject</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">id</span> <span class="n">oldObject</span> <span class="o">=</span> <span class="n">array</span><span class="p">[</span><span class="n">idx</span><span class="p">];</span>
+<span class="n">array</span><span class="p">[</span><span class="n">idx</span><span class="p">]</span> <span class="o">=</span> <span class="n">newObject</span><span class="p">;</span> <span class="c1">// replace oldObject with newObject</span>
+
+<span class="n">NSMutableDictionary</span> <span class="o">*</span><span class="n">dictionary</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">key</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">oldObject</span> <span class="o">=</span> <span class="n">dictionary</span><span class="p">[</span><span class="n">key</span><span class="p">];</span>
+<span class="n">dictionary</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">newObject</span><span class="p">;</span> <span class="c1">// replace oldObject with newObject</span>
+</pre></div>
+</div>
+<p>The next section explains how subscripting expressions map to accessor
+methods.</p>
+</div>
+<div class="section" id="subscripting-methods">
+<h3>Subscripting Methods<a class="headerlink" href="#subscripting-methods" title="Permalink to this headline">¶</a></h3>
+<p>Objective-C supports two kinds of subscript expressions: <em>array-style</em>
+subscript expressions use integer typed subscripts; <em>dictionary-style</em>
+subscript expressions use Objective-C object pointer typed subscripts.
+Each type of subscript expression is mapped to a message send using a
+predefined selector. The advantage of this design is flexibility: class
+designers are free to introduce subscripting by declaring methods or by
+adopting protocols. Moreover, because the method names are selected by
+the type of the subscript, an object can be subscripted using both array
+and dictionary styles.</p>
+<div class="section" id="array-style-subscripting">
+<h4>Array-Style Subscripting<a class="headerlink" href="#array-style-subscripting" title="Permalink to this headline">¶</a></h4>
+<p>When the subscript operand has an integral type, the expression is
+rewritten to use one of two different selectors, depending on whether
+the element is being read or written. When an expression reads an
+element using an integral index, as in the following example:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">NSUInteger</span> <span class="n">idx</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">id</span> <span class="n">value</span> <span class="o">=</span> <span class="n">object</span><span class="p">[</span><span class="n">idx</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>it is translated into a call to <tt class="docutils literal"><span class="pre">objectAtIndexedSubscript:</span></tt></p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">object</span> <span class="nl">objectAtIndexedSubscript:</span><span class="n">idx</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>When an expression writes an element using an integral index:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">object</span><span class="p">[</span><span class="n">idx</span><span class="p">]</span> <span class="o">=</span> <span class="n">newValue</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>it is translated to a call to <tt class="docutils literal"><span class="pre">setObject:atIndexedSubscript:</span></tt></p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">object</span> <span class="nl">setObject:</span><span class="n">newValue</span> <span class="nl">atIndexedSubscript:</span><span class="n">idx</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>These message sends are then type-checked and performed just like
+explicit message sends. The method used for objectAtIndexedSubscript:
+must be declared with an argument of integral type and a return value of
+some Objective-C object pointer type. The method used for
+setObject:atIndexedSubscript: must be declared with its first argument
+having some Objective-C pointer type and its second argument having
+integral type.</p>
+<p>The meaning of indexes is left up to the declaring class. The compiler
+will coerce the index to the appropriate argument type of the method it
+uses for type-checking. For an instance of <tt class="docutils literal"><span class="pre">NSArray</span></tt>, reading an
+element using an index outside the range <tt class="docutils literal"><span class="pre">[0,</span> <span class="pre">array.count)</span></tt> will raise
+an exception. For an instance of <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt>, assigning to an
+element using an index within this range will replace that element, but
+assigning to an element using an index outside this range will raise an
+exception; no syntax is provided for inserting, appending, or removing
+elements for mutable arrays.</p>
+<p>A class need not declare both methods in order to take advantage of this
+language feature. For example, the class <tt class="docutils literal"><span class="pre">NSArray</span></tt> declares only
+<tt class="docutils literal"><span class="pre">objectAtIndexedSubscript:</span></tt>, so that assignments to elements will fail
+to type-check; moreover, its subclass <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt> declares
+<tt class="docutils literal"><span class="pre">setObject:atIndexedSubscript:</span></tt>.</p>
+</div>
+<div class="section" id="dictionary-style-subscripting">
+<h4>Dictionary-Style Subscripting<a class="headerlink" href="#dictionary-style-subscripting" title="Permalink to this headline">¶</a></h4>
+<p>When the subscript operand has an Objective-C object pointer type, the
+expression is rewritten to use one of two different selectors, depending
+on whether the element is being read from or written to. When an
+expression reads an element using an Objective-C object pointer
+subscript operand, as in the following example:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">key</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">id</span> <span class="n">value</span> <span class="o">=</span> <span class="n">object</span><span class="p">[</span><span class="n">key</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>it is translated into a call to the <tt class="docutils literal"><span class="pre">objectForKeyedSubscript:</span></tt> method:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">object</span> <span class="nl">objectForKeyedSubscript:</span><span class="n">key</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>When an expression writes an element using an Objective-C object pointer
+subscript:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">object</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">newValue</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>it is translated to a call to <tt class="docutils literal"><span class="pre">setObject:forKeyedSubscript:</span></tt></p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">object</span> <span class="nl">setObject:</span><span class="n">newValue</span> <span class="nl">forKeyedSubscript:</span><span class="n">key</span><span class="p">];</span>
+</pre></div>
+</div>
+<p>The behavior of <tt class="docutils literal"><span class="pre">setObject:forKeyedSubscript:</span></tt> is class-specific; but
+in general it should replace an existing value if one is already
+associated with a key, otherwise it should add a new value for the key.
+No syntax is provided for removing elements from mutable dictionaries.</p>
+</div>
+</div>
+<div class="section" id="id4">
+<h3>Discussion<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
+<p>An Objective-C subscript expression occurs when the base operand of the
+C subscript operator has an Objective-C object pointer type. Since this
+potentially collides with pointer arithmetic on the value, these
+expressions are only supported under the modern Objective-C runtime,
+which categorically forbids such arithmetic.</p>
+<p>Currently, only subscripts of integral or Objective-C object pointer
+type are supported. In C++, a class type can be used if it has a single
+conversion function to an integral or Objective-C pointer type, in which
+case that conversion is applied and analysis continues as appropriate.
+Otherwise, the expression is ill-formed.</p>
+<p>An Objective-C object subscript expression is always an l-value. If the
+expression appears on the left-hand side of a simple assignment operator
+(=), the element is written as described below. If the expression
+appears on the left-hand side of a compound assignment operator (e.g.
++=), the program is ill-formed, because the result of reading an element
+is always an Objective-C object pointer and no binary operators are
+legal on such pointers. If the expression appears in any other position,
+the element is read as described below. It is an error to take the
+address of a subscript expression, or (in C++) to bind a reference to
+it.</p>
+<p>Programs can use object subscripting with Objective-C object pointers of
+type <tt class="docutils literal"><span class="pre">id</span></tt>. Normal dynamic message send rules apply; the compiler must
+see <em>some</em> declaration of the subscripting methods, and will pick the
+declaration seen first.</p>
+</div>
+</div>
+<div class="section" id="caveats">
+<h2>Caveats<a class="headerlink" href="#caveats" title="Permalink to this headline">¶</a></h2>
+<p>Objects created using the literal or boxed expression syntax are not
+guaranteed to be uniqued by the runtime, but nor are they guaranteed to
+be newly-allocated. As such, the result of performing direct comparisons
+against the location of an object literal (using <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">!=</span></tt>, <tt class="docutils literal"><span class="pre"><</span></tt>,
+<tt class="docutils literal"><span class="pre"><=</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, or <tt class="docutils literal"><span class="pre">>=</span></tt>) is not well-defined. This is usually a simple
+mistake in code that intended to call the <tt class="docutils literal"><span class="pre">isEqual:</span></tt> method (or the
+<tt class="docutils literal"><span class="pre">compare:</span></tt> method).</p>
+<p>This caveat applies to compile-time string literals as well.
+Historically, string literals (using the <tt class="docutils literal"><span class="pre">@"..."</span></tt> syntax) have been
+uniqued across translation units during linking. This is an
+implementation detail of the compiler and should not be relied upon. If
+you are using such code, please use global string constants instead
+(<tt class="docutils literal"><span class="pre">NSString</span> <span class="pre">*</span> <span class="pre">const</span> <span class="pre">MyConst</span> <span class="pre">=</span> <span class="pre">@"..."</span></tt>) or use <tt class="docutils literal"><span class="pre">isEqual:</span></tt>.</p>
+</div>
+<div class="section" id="grammar-additions">
+<h2>Grammar Additions<a class="headerlink" href="#grammar-additions" title="Permalink to this headline">¶</a></h2>
+<p>To support the new syntax described above, the Objective-C
+<tt class="docutils literal"><span class="pre">@</span></tt>-expression grammar has the following new productions:</p>
+<div class="highlight-python"><pre>objc-at-expression : '@' (string-literal | encode-literal | selector-literal | protocol-literal | object-literal)
+ ;
+
+object-literal : ('+' | '-')? numeric-constant
+ | character-constant
+ | boolean-constant
+ | array-literal
+ | dictionary-literal
+ ;
+
+boolean-constant : '__objc_yes' | '__objc_no' | 'true' | 'false' /* boolean keywords. */
+ ;
+
+array-literal : '[' assignment-expression-list ']'
+ ;
+
+assignment-expression-list : assignment-expression (',' assignment-expression-list)?
+ | /* empty */
+ ;
+
+dictionary-literal : '{' key-value-list '}'
+ ;
+
+key-value-list : key-value-pair (',' key-value-list)?
+ | /* empty */
+ ;
+
+key-value-pair : assignment-expression ':' assignment-expression
+ ;</pre>
+</div>
+<p>Note: <tt class="docutils literal"><span class="pre">@true</span></tt> and <tt class="docutils literal"><span class="pre">@false</span></tt> are only supported in Objective-C++.</p>
+</div>
+<div class="section" id="availability-checks">
+<h2>Availability Checks<a class="headerlink" href="#availability-checks" title="Permalink to this headline">¶</a></h2>
+<p>Programs test for the new features by using clang’s __has_feature
+checks. Here are examples of their use:</p>
+<div class="highlight-objc"><pre>#if __has_feature(objc_array_literals)
+ // new way.
+ NSArray *elements = @[ @"H", @"He", @"O", @"C" ];
+#else
+ // old way (equivalent).
+ id objects[] = { @"H", @"He", @"O", @"C" };
+ NSArray *elements = [NSArray arrayWithObjects:objects count:4];
+#endif
+
+#if __has_feature(objc_dictionary_literals)
+ // new way.
+ NSDictionary *masses = @{ @"H" : @1.0078, @"He" : @4.0026, @"O" : @15.9990, @"C" : @12.0096 };
+#else
+ // old way (equivalent).
+ id keys[] = { @"H", @"He", @"O", @"C" };
+ id values[] = { [NSNumber numberWithDouble:1.0078], [NSNumber numberWithDouble:4.0026],
+ [NSNumber numberWithDouble:15.9990], [NSNumber numberWithDouble:12.0096] };
+ NSDictionary *masses = [NSDictionary dictionaryWithObjects:objects forKeys:keys count:4];
+#endif
+
+#if __has_feature(objc_subscripting)
+ NSUInteger i, count = elements.count;
+ for (i = 0; i < count; ++i) {
+ NSString *element = elements[i];
+ NSNumber *mass = masses[element];
+ NSLog(@"the mass of %@ is %@", element, mass);
+ }
+#else
+ NSUInteger i, count = [elements count];
+ for (i = 0; i < count; ++i) {
+ NSString *element = [elements objectAtIndex:i];
+ NSNumber *mass = [masses objectForKey:element];
+ NSLog(@"the mass of %@ is %@", element, mass);
+ }
+#endif
+
+#if __has_attribute(objc_boxable)
+ typedef struct __attribute__((objc_boxable)) _Rect Rect;
+#endif
+
+#if __has_feature(objc_boxed_nsvalue_expressions)
+ CABasicAnimation animation = [CABasicAnimation animationWithKeyPath:@"position"];
+ animation.fromValue = @(layer.position);
+ animation.toValue = @(newPosition);
+ [layer addAnimation:animation forKey:@"move"];
+#else
+ CABasicAnimation animation = [CABasicAnimation animationWithKeyPath:@"position"];
+ animation.fromValue = [NSValue valueWithCGPoint:layer.position];
+ animation.toValue = [NSValue valueWithCGPoint:newPosition];
+ [layer addAnimation:animation forKey:@"move"];
+#endif</pre>
+</div>
+<p>Code can use also <tt class="docutils literal"><span class="pre">__has_feature(objc_bool)</span></tt> to check for the
+availability of numeric literals support. This checks for the new
+<tt class="docutils literal"><span class="pre">__objc_yes</span> <span class="pre">/</span> <span class="pre">__objc_no</span></tt> keywords, which enable the use of
+<tt class="docutils literal"><span class="pre">@YES</span> <span class="pre">/</span> <span class="pre">@NO</span></tt> literals.</p>
+<p>To check whether boxed expressions are supported, use
+<tt class="docutils literal"><span class="pre">__has_feature(objc_boxed_expressions)</span></tt> feature macro.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="LanguageExtensions.html">Clang Language Extensions</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="BlockLanguageSpec.html">Language Specification for Blocks</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/PCHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/PCHInternals.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/PCHInternals.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/PCHInternals.html Thu May 10 06:54:16 2018
@@ -0,0 +1,594 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="ABI tags" href="ItaniumMangleAbiTags.html" />
+ <link rel="prev" title="Pretokenized Headers (PTH)" href="PTHInternals.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Precompiled Header and Modules Internals</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <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 <tt class="docutils literal"><span class="pre">clang</span></tt></a></li>
+<li><a class="reference internal" href="#design-philosophy" id="id2">Design Philosophy</a></li>
+<li><a class="reference internal" href="#ast-file-contents" id="id3">AST File Contents</a><ul>
+<li><a class="reference internal" href="#metadata-block" id="id4">Metadata Block</a></li>
+<li><a class="reference internal" href="#source-manager-block" id="id5">Source Manager Block</a></li>
+<li><a class="reference internal" href="#preprocessor-block" id="id6">Preprocessor Block</a></li>
+<li><a class="reference internal" href="#types-block" id="id7">Types Block</a></li>
+<li><a class="reference internal" href="#declarations-block" id="id8">Declarations Block</a></li>
+<li><a class="reference internal" href="#statements-and-expressions" id="id9">Statements and Expressions</a></li>
+<li><a class="reference internal" href="#pchinternals-ident-table" id="id10">Identifier Table Block</a></li>
+<li><a class="reference internal" href="#method-pool-block" id="id11">Method Pool Block</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ast-reader-integration-points" id="id12">AST Reader Integration Points</a></li>
+<li><a class="reference internal" href="#chained-precompiled-headers" id="id13">Chained precompiled headers</a></li>
+<li><a class="reference internal" href="#modules" id="id14">Modules</a></li>
+</ul>
+</div>
+<p>This document describes the design and implementation of Clang’s precompiled
+headers (PCH) and modules. If you are interested in the end-user view, please
+see the <a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>User’s Manual</em></a>.</p>
+<div class="section" id="using-precompiled-headers-with-clang">
+<h2><a class="toc-backref" href="#id1">Using Precompiled Headers with <tt class="docutils literal"><span class="pre">clang</span></tt></a><a class="headerlink" href="#using-precompiled-headers-with-clang" title="Permalink to this headline">¶</a></h2>
+<p>The Clang compiler frontend, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, supports two command line options
+for generating and using PCH files.</p>
+<p>To generate PCH files using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, use the option <cite>-emit-pch</cite>:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>clang -cc1 test.h -emit-pch -o test.h.pch
+</pre></div>
+</div>
+<p>This option is transparently used by <tt class="docutils literal"><span class="pre">clang</span></tt> when generating PCH files. The
+resulting PCH file contains the serialized form of the compiler’s internal
+representation after it has completed parsing and semantic analysis. The PCH
+file can then be used as a prefix header with the <cite>-include-pch</cite>
+option:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>clang -cc1 -include-pch test.h.pch test.c -o test.s
+</pre></div>
+</div>
+</div>
+<div class="section" id="design-philosophy">
+<h2><a class="toc-backref" href="#id2">Design Philosophy</a><a class="headerlink" href="#design-philosophy" title="Permalink to this headline">¶</a></h2>
+<p>Precompiled headers are meant to improve overall compile times for projects, so
+the design of precompiled headers is entirely driven by performance concerns.
+The use case for precompiled headers is relatively simple: when there is a
+common set of headers that is included in nearly every source file in the
+project, we <em>precompile</em> that bundle of headers into a single precompiled
+header (PCH file). Then, when compiling the source files in the project, we
+load the PCH file first (as a prefix header), which acts as a stand-in for that
+bundle of headers.</p>
+<p>A precompiled header implementation improves performance when:</p>
+<ul class="simple">
+<li>Loading the PCH file is significantly faster than re-parsing the bundle of
+headers stored within the PCH file. Thus, a precompiled header design
+attempts to minimize the cost of reading the PCH file. Ideally, this cost
+should not vary with the size of the precompiled header file.</li>
+<li>The cost of generating the PCH file initially is not so large that it
+counters the per-source-file performance improvement due to eliminating the
+need to parse the bundled headers in the first place. This is particularly
+important on multi-core systems, because PCH file generation serializes the
+build when all compilations require the PCH file to be up-to-date.</li>
+</ul>
+<p>Modules, as implemented in Clang, use the same mechanisms as precompiled
+headers to save a serialized AST file (one per module) and use those AST
+modules. From an implementation standpoint, modules are a generalization of
+precompiled headers, lifting a number of restrictions placed on precompiled
+headers. In particular, there can only be one precompiled header and it must
+be included at the beginning of the translation unit. The extensions to the
+AST file format required for modules are discussed in the section on
+<a class="reference internal" href="#pchinternals-modules"><em>modules</em></a>.</p>
+<p>Clang’s AST files are designed with a compact on-disk representation, which
+minimizes both creation time and the time required to initially load the AST
+file. The AST file itself contains a serialized representation of Clang’s
+abstract syntax trees and supporting data structures, stored using the same
+compressed bitstream as <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM’s bitcode file format</a>.</p>
+<p>Clang’s AST files are loaded “lazily” from disk. When an AST file is initially
+loaded, Clang reads only a small amount of data from the AST file to establish
+where certain important data structures are stored. The amount of data read in
+this initial load is independent of the size of the AST file, such that a
+larger AST file does not lead to longer AST load times. The actual header data
+in the AST file — macros, functions, variables, types, etc. — is loaded
+only when it is referenced from the user’s code, at which point only that
+entity (and those entities it depends on) are deserialized from the AST file.
+With this approach, the cost of using an AST file for a translation unit is
+proportional to the amount of code actually used from the AST file, rather than
+being proportional to the size of the AST file itself.</p>
+<p>When given the <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 <tt class="docutils literal"><span class="pre">Cocoa.h</span></tt> header
+(which is built as a precompiled header), this option illustrates how little of
+the actual precompiled header is required:</p>
+<div class="highlight-none"><div class="highlight"><pre>*** AST File Statistics:
+ 895/39981 source location entries read (2.238563%)
+ 19/15315 types read (0.124061%)
+ 20/82685 declarations read (0.024188%)
+ 154/58070 identifiers read (0.265197%)
+ 0/7260 selectors read (0.000000%)
+ 0/30842 statements read (0.000000%)
+ 4/8400 macros read (0.047619%)
+ 1/4995 lexical declcontexts read (0.020020%)
+ 0/4413 visible declcontexts read (0.000000%)
+ 0/7230 method pool entries read (0.000000%)
+ 0 method pool misses
+</pre></div>
+</div>
+<p>For this small program, only a tiny fraction of the source locations, types,
+declarations, identifiers, and macros were actually deserialized from the
+precompiled header. These statistics can be useful to determine whether the
+AST file implementation can be improved by making more of the implementation
+lazy.</p>
+<p>Precompiled headers can be chained. When you create a PCH while including an
+existing PCH, Clang can create the new PCH by referencing the original file and
+only writing the new data to the new file. For example, you could create a PCH
+out of all the headers that are very commonly used throughout your project, and
+then create a PCH for every single source file in the project that includes the
+code that is specific to that file, so that recompiling the file itself is very
+fast, without duplicating the data from the common headers for every file. The
+mechanisms behind chained precompiled headers are discussed in a <a class="reference internal" href="#pchinternals-chained"><em>later
+section</em></a>.</p>
+</div>
+<div class="section" id="ast-file-contents">
+<h2><a class="toc-backref" href="#id3">AST File Contents</a><a class="headerlink" href="#ast-file-contents" title="Permalink to this headline">¶</a></h2>
+<p>An AST file produced by clang is an object file container with a <tt class="docutils literal"><span class="pre">clangast</span></tt>
+(COFF) or <tt class="docutils literal"><span class="pre">__clangast</span></tt> (ELF and Mach-O) section containing the serialized AST.
+Other target-specific sections in the object file container are used to hold
+debug information for the data types defined in the AST. Tools built on top of
+libclang that do not need debug information may also produce raw AST files that
+only contain the serialized AST.</p>
+<p>The <tt class="docutils literal"><span class="pre">clangast</span></tt> section is organized into several different blocks, each of
+which contains the serialized representation of a part of Clang’s internal
+representation. Each of the blocks corresponds to either a block or a record
+within <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM’s bitstream format</a>.
+The contents of each of these logical blocks are described below.</p>
+<img alt="_images/PCHLayout.png" src="_images/PCHLayout.png" />
+<p>The <tt class="docutils literal"><span class="pre">llvm-objdump</span></tt> utility provides a <tt class="docutils literal"><span class="pre">-raw-clang-ast</span></tt> option to extract the
+binary contents of the AST section from an object file container.</p>
+<p>The <a class="reference external" href="http://llvm.org/docs/CommandGuide/llvm-bcanalyzer.html">llvm-bcanalyzer</a>
+utility can be used to examine the actual structure of the bitstream for the AST
+section. This information can be used both to help understand the structure of
+the AST section and to isolate areas where the AST representation can still be
+optimized, e.g., through the introduction of abbreviations.</p>
+<div class="section" id="metadata-block">
+<h3><a class="toc-backref" href="#id4">Metadata Block</a><a class="headerlink" href="#metadata-block" title="Permalink to this headline">¶</a></h3>
+<p>The metadata block contains several records that provide information about how
+the AST file was built. This metadata is primarily used to validate the use of
+an AST file. For example, a precompiled header built for a 32-bit x86 target
+cannot be used when compiling for a 64-bit x86 target. The metadata block
+contains information about:</p>
+<dl class="docutils">
+<dt>Language options</dt>
+<dd>Describes the particular language dialect used to compile the AST file,
+including major options (e.g., Objective-C support) and more minor options
+(e.g., support for “<tt class="docutils literal"><span class="pre">//</span></tt>” comments). The contents of this record correspond to
+the <tt class="docutils literal"><span class="pre">LangOptions</span></tt> class.</dd>
+<dt>Target architecture</dt>
+<dd>The target triple that describes the architecture, platform, and ABI for
+which the AST file was generated, e.g., <tt class="docutils literal"><span class="pre">i386-apple-darwin9</span></tt>.</dd>
+<dt>AST version</dt>
+<dd>The major and minor version numbers of the AST file format. Changes in the
+minor version number should not affect backward compatibility, while changes
+in the major version number imply that a newer compiler cannot read an older
+precompiled header (and vice-versa).</dd>
+<dt>Original file name</dt>
+<dd>The full path of the header that was used to generate the AST file.</dd>
+<dt>Predefines buffer</dt>
+<dd>Although not explicitly stored as part of the metadata, the predefines buffer
+is used in the validation of the AST file. The predefines buffer itself
+contains code generated by the compiler to initialize the preprocessor state
+according to the current target, platform, and command-line options. For
+example, the predefines buffer will contain “<tt class="docutils literal"><span class="pre">#define</span> <span class="pre">__STDC__</span> <span class="pre">1</span></tt>” when we
+are compiling C without Microsoft extensions. The predefines buffer itself
+is stored within the <a class="reference internal" href="#pchinternals-sourcemgr"><em>Source Manager Block</em></a>, but its contents are
+verified along with the rest of the metadata.</dd>
+</dl>
+<p>A chained PCH file (that is, one that references another PCH) and a module
+(which may import other modules) have additional metadata containing the list
+of all AST files that this AST file depends on. Each of those files will be
+loaded along with this AST file.</p>
+<p>For chained precompiled headers, the language options, target architecture and
+predefines buffer data is taken from the end of the chain, since they have to
+match anyway.</p>
+</div>
+<div class="section" id="source-manager-block">
+<span id="pchinternals-sourcemgr"></span><h3><a class="toc-backref" href="#id5">Source Manager Block</a><a class="headerlink" href="#source-manager-block" title="Permalink to this headline">¶</a></h3>
+<p>The source manager block contains the serialized representation of Clang’s
+<a class="reference internal" href="InternalsManual.html#sourcemanager"><em>SourceManager</em></a> class, which handles the mapping from
+source locations (as represented in Clang’s abstract syntax tree) into actual
+column/line positions within a source file or macro instantiation. The AST
+file’s representation of the source manager also includes information about all
+of the headers that were (transitively) included when building the AST file.</p>
+<p>The bulk of the source manager block is dedicated to information about the
+various files, buffers, and macro instantiations into which a source location
+can refer. Each of these is referenced by a numeric “file ID”, which is a
+unique number (allocated starting at 1) stored in the source location. Clang
+serializes the information for each kind of file ID, along with an index that
+maps file IDs to the position within the AST file where the information about
+that file ID is stored. The data associated with a file ID is loaded only when
+required by the front end, e.g., to emit a diagnostic that includes a macro
+instantiation history inside the header itself.</p>
+<p>The source manager block also contains information about all of the headers
+that were included when building the AST file. This includes information about
+the controlling macro for the header (e.g., when the preprocessor identified
+that the contents of the header dependent on a macro like
+<tt class="docutils literal"><span class="pre">LLVM_CLANG_SOURCEMANAGER_H</span></tt>).</p>
+</div>
+<div class="section" id="preprocessor-block">
+<span id="pchinternals-preprocessor"></span><h3><a class="toc-backref" href="#id6">Preprocessor Block</a><a class="headerlink" href="#preprocessor-block" title="Permalink to this headline">¶</a></h3>
+<p>The preprocessor block contains the serialized representation of the
+preprocessor. Specifically, it contains all of the macros that have been
+defined by the end of the header used to build the AST file, along with the
+token sequences that comprise each macro. The macro definitions are only read
+from the AST file when the name of the macro first occurs in the program. This
+lazy loading of macro definitions is triggered by lookups into the
+<a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>.</p>
+</div>
+<div class="section" id="types-block">
+<span id="pchinternals-types"></span><h3><a class="toc-backref" href="#id7">Types Block</a><a class="headerlink" href="#types-block" title="Permalink to this headline">¶</a></h3>
+<p>The types block contains the serialized representation of all of the types
+referenced in the translation unit. Each Clang type node (<tt class="docutils literal"><span class="pre">PointerType</span></tt>,
+<tt class="docutils literal"><span class="pre">FunctionProtoType</span></tt>, etc.) has a corresponding record type in the AST file.
+When types are deserialized from the AST file, the data within the record is
+used to reconstruct the appropriate type node using the AST context.</p>
+<p>Each type has a unique type ID, which is an integer that uniquely identifies
+that type. Type ID 0 represents the NULL type, type IDs less than
+<tt class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></tt> represent predefined types (<tt class="docutils literal"><span class="pre">void</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, etc.),
+while other “user-defined” type IDs are assigned consecutively from
+<tt class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></tt> upward as the types are encountered. The AST file has
+an associated mapping from the user-defined types block to the location within
+the types block where the serialized representation of that type resides,
+enabling lazy deserialization of types. When a type is referenced from within
+the AST file, that reference is encoded using the type ID shifted left by 3
+bits. The lower three bits are used to represent the <tt class="docutils literal"><span class="pre">const</span></tt>, <tt class="docutils literal"><span class="pre">volatile</span></tt>,
+and <tt class="docutils literal"><span class="pre">restrict</span></tt> qualifiers, as in Clang’s <a class="reference internal" href="InternalsManual.html#qualtype"><em>QualType</em></a> class.</p>
+</div>
+<div class="section" id="declarations-block">
+<span id="pchinternals-decls"></span><h3><a class="toc-backref" href="#id8">Declarations Block</a><a class="headerlink" href="#declarations-block" title="Permalink to this headline">¶</a></h3>
+<p>The declarations block contains the serialized representation of all of the
+declarations referenced in the translation unit. Each Clang declaration node
+(<tt class="docutils literal"><span class="pre">VarDecl</span></tt>, <tt class="docutils literal"><span class="pre">FunctionDecl</span></tt>, etc.) has a corresponding record type in the
+AST file. When declarations are deserialized from the AST file, the data
+within the record is used to build and populate a new instance of the
+corresponding <tt class="docutils literal"><span class="pre">Decl</span></tt> node. As with types, each declaration node has a
+numeric ID that is used to refer to that declaration within the AST file. In
+addition, a lookup table provides a mapping from that numeric ID to the offset
+within the precompiled header where that declaration is described.</p>
+<p>Declarations in Clang’s abstract syntax trees are stored hierarchically. At
+the top of the hierarchy is the translation unit (<tt class="docutils literal"><span class="pre">TranslationUnitDecl</span></tt>),
+which contains all of the declarations in the translation unit but is not
+actually written as a specific declaration node. Its child declarations (such
+as functions or struct types) may also contain other declarations inside them,
+and so on. Within Clang, each declaration is stored within a <a class="reference internal" href="InternalsManual.html#declcontext"><em>declaration
+context</em></a>, as represented by the <tt class="docutils literal"><span class="pre">DeclContext</span></tt> class.
+Declaration contexts provide the mechanism to perform name lookup within a
+given declaration (e.g., find the member named <tt class="docutils literal"><span class="pre">x</span></tt> in a structure) and
+iterate over the declarations stored within a context (e.g., iterate over all
+of the fields of a structure for structure layout).</p>
+<p>In Clang’s AST file format, deserializing a declaration that is a
+<tt class="docutils literal"><span class="pre">DeclContext</span></tt> is a separate operation from deserializing all of the
+declarations stored within that declaration context. Therefore, Clang will
+deserialize the translation unit declaration without deserializing the
+declarations within that translation unit. When required, the declarations
+stored within a declaration context will be deserialized. There are two
+representations of the declarations within a declaration context, which
+correspond to the name-lookup and iteration behavior described above:</p>
+<ul class="simple">
+<li>When the front end performs name lookup to find a name <tt class="docutils literal"><span class="pre">x</span></tt> within a given
+declaration context (for example, during semantic analysis of the expression
+<tt class="docutils literal"><span class="pre">p->x</span></tt>, where <tt class="docutils literal"><span class="pre">p</span></tt>‘s type is defined in the precompiled header), Clang
+refers to an on-disk hash table that maps from the names within that
+declaration context to the declaration IDs that represent each visible
+declaration with that name. The actual declarations will then be
+deserialized to provide the results of name lookup.</li>
+<li>When the front end performs iteration over all of the declarations within a
+declaration context, all of those declarations are immediately
+de-serialized. For large declaration contexts (e.g., the translation unit),
+this operation is expensive; however, large declaration contexts are not
+traversed in normal compilation, since such a traversal is unnecessary.
+However, it is common for the code generator and semantic analysis to
+traverse declaration contexts for structs, classes, unions, and
+enumerations, although those contexts contain relatively few declarations in
+the common case.</li>
+</ul>
+</div>
+<div class="section" id="statements-and-expressions">
+<h3><a class="toc-backref" href="#id9">Statements and Expressions</a><a class="headerlink" href="#statements-and-expressions" title="Permalink to this headline">¶</a></h3>
+<p>Statements and expressions are stored in the AST file in both the <a class="reference internal" href="#pchinternals-types"><em>types</em></a> and the <a class="reference internal" href="#pchinternals-decls"><em>declarations</em></a> blocks,
+because every statement or expression will be associated with either a type or
+declaration. The actual statement and expression records are stored
+immediately following the declaration or type that owns the statement or
+expression. For example, the statement representing the body of a function
+will be stored directly following the declaration of the function.</p>
+<p>As with types and declarations, each statement and expression kind in Clang’s
+abstract syntax tree (<tt class="docutils literal"><span class="pre">ForStmt</span></tt>, <tt class="docutils literal"><span class="pre">CallExpr</span></tt>, etc.) has a corresponding
+record type in the AST file, which contains the serialized representation of
+that statement or expression. Each substatement or subexpression within an
+expression is stored as a separate record (which keeps most records to a fixed
+size). Within the AST file, the subexpressions of an expression are stored, in
+reverse order, prior to the expression that owns those expression, using a form
+of <a class="reference external" href="http://en.wikipedia.org/wiki/Reverse_Polish_notation">Reverse Polish Notation</a>. For example, an
+expression <tt class="docutils literal"><span class="pre">3</span> <span class="pre">-</span> <span class="pre">4</span> <span class="pre">+</span> <span class="pre">5</span></tt> would be represented as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="100%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(5)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(4)</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(3)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(-)</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(+)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">STOP</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p>When reading this representation, Clang evaluates each expression record it
+encounters, builds the appropriate abstract syntax tree node, and then pushes
+that expression on to a stack. When a record contains <em>N</em> subexpressions —
+<tt class="docutils literal"><span class="pre">BinaryOperator</span></tt> has two of them — those expressions are popped from the
+top of the stack. The special STOP code indicates that we have reached the end
+of a serialized expression or statement; other expression or statement records
+may follow, but they are part of a different expression.</p>
+</div>
+<div class="section" id="pchinternals-ident-table">
+<span id="identifier-table-block"></span><h3><a class="toc-backref" href="#id10">Identifier Table Block</a><a class="headerlink" href="#pchinternals-ident-table" title="Permalink to this headline">¶</a></h3>
+<p>The identifier table block contains an on-disk hash table that maps each
+identifier mentioned within the AST file to the serialized representation of
+the identifier’s information (e.g, the <tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> structure). The
+serialized representation contains:</p>
+<ul class="simple">
+<li>The actual identifier string.</li>
+<li>Flags that describe whether this identifier is the name of a built-in, a
+poisoned identifier, an extension token, or a macro.</li>
+<li>If the identifier names a macro, the offset of the macro definition within
+the <a class="reference internal" href="#pchinternals-preprocessor"><em>Preprocessor Block</em></a>.</li>
+<li>If the identifier names one or more declarations visible from translation
+unit scope, the <a class="reference internal" href="#pchinternals-decls"><em>declaration IDs</em></a> of these
+declarations.</li>
+</ul>
+<p>When an AST file is loaded, the AST file reader mechanism introduces itself
+into the identifier table as an external lookup source. Thus, when the user
+program refers to an identifier that has not yet been seen, Clang will perform
+a lookup into the identifier table. If an identifier is found, its contents
+(macro definitions, flags, top-level declarations, etc.) will be deserialized,
+at which point the corresponding <tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> structure will have the
+same contents it would have after parsing the headers in the AST file.</p>
+<p>Within the AST file, the identifiers used to name declarations are represented
+with an integral value. A separate table provides a mapping from this integral
+value (the identifier ID) to the location within the on-disk hash table where
+that identifier is stored. This mapping is used when deserializing the name of
+a declaration, the identifier of a token, or any other construct in the AST
+file that refers to a name.</p>
+</div>
+<div class="section" id="method-pool-block">
+<span id="pchinternals-method-pool"></span><h3><a class="toc-backref" href="#id11">Method Pool Block</a><a class="headerlink" href="#method-pool-block" title="Permalink to this headline">¶</a></h3>
+<p>The method pool block is represented as an on-disk hash table that serves two
+purposes: it provides a mapping from the names of Objective-C selectors to the
+set of Objective-C instance and class methods that have that particular
+selector (which is required for semantic analysis in Objective-C) and also
+stores all of the selectors used by entities within the AST file. The design
+of the method pool is similar to that of the <a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>: the first time a particular selector is formed
+during the compilation of the program, Clang will search in the on-disk hash
+table of selectors; if found, Clang will read the Objective-C methods
+associated with that selector into the appropriate front-end data structure
+(<tt class="docutils literal"><span class="pre">Sema::InstanceMethodPool</span></tt> and <tt class="docutils literal"><span class="pre">Sema::FactoryMethodPool</span></tt> for instance and
+class methods, respectively).</p>
+<p>As with identifiers, selectors are represented by numeric values within the AST
+file. A separate index maps these numeric selector values to the offset of the
+selector within the on-disk hash table, and will be used when de-serializing an
+Objective-C method declaration (or other Objective-C construct) that refers to
+the selector.</p>
+</div>
+</div>
+<div class="section" id="ast-reader-integration-points">
+<h2><a class="toc-backref" href="#id12">AST Reader Integration Points</a><a class="headerlink" href="#ast-reader-integration-points" title="Permalink to this headline">¶</a></h2>
+<p>The “lazy” deserialization behavior of AST files requires their integration
+into several completely different submodules of Clang. For example, lazily
+deserializing the declarations during name lookup requires that the name-lookup
+routines be able to query the AST file to find entities stored there.</p>
+<p>For each Clang data structure that requires direct interaction with the AST
+reader logic, there is an abstract class that provides the interface between
+the two modules. The <tt class="docutils literal"><span class="pre">ASTReader</span></tt> class, which handles the loading of an AST
+file, inherits from all of these abstract classes to provide lazy
+deserialization of Clang’s data structures. <tt class="docutils literal"><span class="pre">ASTReader</span></tt> implements the
+following abstract classes:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">ExternalSLocEntrySource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">SourceManager</span></tt> class, and
+is used whenever the <a class="reference internal" href="#pchinternals-sourcemgr"><em>source manager</em></a> needs to
+load the details of a file, buffer, or macro instantiation.</dd>
+<dt><tt class="docutils literal"><span class="pre">IdentifierInfoLookup</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">IdentifierTable</span></tt> class, and
+is used whenever the program source refers to an identifier that has not yet
+been seen. In this case, the AST reader searches for this identifier within
+its <a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a> to load any top-level
+declarations or macros associated with that identifier.</dd>
+<dt><tt class="docutils literal"><span class="pre">ExternalASTSource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">ASTContext</span></tt> class, and is
+used whenever the abstract syntax tree nodes need to loaded from the AST
+file. It provides the ability to de-serialize declarations and types
+identified by their numeric values, read the bodies of functions when
+required, and read the declarations stored within a declaration context
+(either for iteration or for name lookup).</dd>
+<dt><tt class="docutils literal"><span class="pre">ExternalSemaSource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">Sema</span></tt> class, and is used
+whenever semantic analysis needs to read information from the <a class="reference internal" href="#pchinternals-method-pool"><em>global
+method pool</em></a>.</dd>
+</dl>
+</div>
+<div class="section" id="chained-precompiled-headers">
+<span id="pchinternals-chained"></span><h2><a class="toc-backref" href="#id13">Chained precompiled headers</a><a class="headerlink" href="#chained-precompiled-headers" title="Permalink to this headline">¶</a></h2>
+<p>Chained precompiled headers were initially intended to improve the performance
+of IDE-centric operations such as syntax highlighting and code completion while
+a particular source file is being edited by the user. To minimize the amount
+of reparsing required after a change to the file, a form of precompiled header
+— called a precompiled <em>preamble</em> — is automatically generated by parsing
+all of the headers in the source file, up to and including the last
+<tt class="docutils literal"><span class="pre">#include</span></tt>. When only the source file changes (and none of the headers it
+depends on), reparsing of that source file can use the precompiled preamble and
+start parsing after the <tt class="docutils literal"><span class="pre">#include</span></tt>s, so parsing time is proportional to the
+size of the source file (rather than all of its includes). However, the
+compilation of that translation unit may already use a precompiled header: in
+this case, Clang will create the precompiled preamble as a chained precompiled
+header that refers to the original precompiled header. This drastically
+reduces the time needed to serialize the precompiled preamble for use in
+reparsing.</p>
+<p>Chained precompiled headers get their name because each precompiled header can
+depend on one other precompiled header, forming a chain of dependencies. A
+translation unit will then include the precompiled header that starts the chain
+(i.e., nothing depends on it). This linearity of dependencies is important for
+the semantic model of chained precompiled headers, because the most-recent
+precompiled header can provide information that overrides the information
+provided by the precompiled headers it depends on, just like a header file
+<tt class="docutils literal"><span class="pre">B.h</span></tt> that includes another header <tt class="docutils literal"><span class="pre">A.h</span></tt> can modify the state produced by
+parsing <tt class="docutils literal"><span class="pre">A.h</span></tt>, e.g., by <tt class="docutils literal"><span class="pre">#undef</span></tt>‘ing a macro defined in <tt class="docutils literal"><span class="pre">A.h</span></tt>.</p>
+<p>There are several ways in which chained precompiled headers generalize the AST
+file model:</p>
+<dl class="docutils">
+<dt>Numbering of IDs</dt>
+<dd>Many different kinds of entities — identifiers, declarations, types, etc.
+— have ID numbers that start at 1 or some other predefined constant and
+grow upward. Each precompiled header records the maximum ID number it has
+assigned in each category. Then, when a new precompiled header is generated
+that depends on (chains to) another precompiled header, it will start
+counting at the next available ID number. This way, one can determine, given
+an ID number, which AST file actually contains the entity.</dd>
+<dt>Name lookup</dt>
+<dd>When writing a chained precompiled header, Clang attempts to write only
+information that has changed from the precompiled header on which it is
+based. This changes the lookup algorithm for the various tables, such as the
+<a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>: the search starts at the
+most-recent precompiled header. If no entry is found, lookup then proceeds
+to the identifier table in the precompiled header it depends on, and so one.
+Once a lookup succeeds, that result is considered definitive, overriding any
+results from earlier precompiled headers.</dd>
+<dt>Update records</dt>
+<dd>There are various ways in which a later precompiled header can modify the
+entities described in an earlier precompiled header. For example, later
+precompiled headers can add entries into the various name-lookup tables for
+the translation unit or namespaces, or add new categories to an Objective-C
+class. Each of these updates is captured in an “update record” that is
+stored in the chained precompiled header file and will be loaded along with
+the original entity.</dd>
+</dl>
+</div>
+<div class="section" id="modules">
+<span id="pchinternals-modules"></span><h2><a class="toc-backref" href="#id14">Modules</a><a class="headerlink" href="#modules" title="Permalink to this headline">¶</a></h2>
+<p>Modules generalize the chained precompiled header model yet further, from a
+linear chain of precompiled headers to an arbitrary directed acyclic graph
+(DAG) of AST files. All of the same techniques used to make chained
+precompiled headers work — ID number, name lookup, update records — are
+shared with modules. However, the DAG nature of modules introduce a number of
+additional complications to the model:</p>
+<dl class="docutils">
+<dt>Numbering of IDs</dt>
+<dd>The simple, linear numbering scheme used in chained precompiled headers falls
+apart with the module DAG, because different modules may end up with
+different numbering schemes for entities they imported from common shared
+modules. To account for this, each module file provides information about
+which modules it depends on and which ID numbers it assigned to the entities
+in those modules, as well as which ID numbers it took for its own new
+entities. The AST reader then maps these “local” ID numbers into a “global”
+ID number space for the current translation unit, providing a 1-1 mapping
+between entities (in whatever AST file they inhabit) and global ID numbers.
+If that translation unit is then serialized into an AST file, this mapping
+will be stored for use when the AST file is imported.</dd>
+<dt>Declaration merging</dt>
+<dd>It is possible for a given entity (from the language’s perspective) to be
+declared multiple times in different places. For example, two different
+headers can have the declaration of <tt class="docutils literal"><span class="pre">printf</span></tt> or could forward-declare
+<tt class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></tt>. If each of those headers is included in a module, and some
+third party imports both of those modules, there is a potentially serious
+problem: name lookup for <tt class="docutils literal"><span class="pre">printf</span></tt> or <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></tt> will find both
+declarations, but the AST nodes are unrelated. This would result in a
+compilation error, due to an ambiguity in name lookup. Therefore, the AST
+reader performs declaration merging according to the appropriate language
+semantics, ensuring that the two disjoint declarations are merged into a
+single redeclaration chain (with a common canonical declaration), so that it
+is as if one of the headers had been included before the other.</dd>
+<dt>Name Visibility</dt>
+<dd>Modules allow certain names that occur during module creation to be “hidden”,
+so that they are not part of the public interface of the module and are not
+visible to its clients. The AST reader maintains a “visible” bit on various
+AST nodes (declarations, macros, etc.) to indicate whether that particular
+AST node is currently visible; the various name lookup mechanisms in Clang
+inspect the visible bit to determine whether that entity, which is still in
+the AST (because other, visible AST nodes may depend on it), can actually be
+found by name lookup. When a new (sub)module is imported, it may make
+existing, non-visible, already-deserialized AST nodes visible; it is the
+responsibility of the AST reader to find and update these AST nodes when it
+is notified of the import.</dd>
+</dl>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ItaniumMangleAbiTags.html">ABI tags</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/PTHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/PTHInternals.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/PTHInternals.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/PTHInternals.html Thu May 10 06:54:16 2018
@@ -0,0 +1,218 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Precompiled Header and Modules Internals" href="PCHInternals.html" />
+ <link rel="prev" title="Driver Design & Internals" href="DriverInternals.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Pretokenized Headers (PTH)</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="DriverInternals.html">Driver Design & Internals</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="PCHInternals.html">Precompiled Header and Modules Internals</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="pretokenized-headers-pth">
+<h1>Pretokenized Headers (PTH)<a class="headerlink" href="#pretokenized-headers-pth" title="Permalink to this headline">¶</a></h1>
+<p>This document first describes the low-level interface for using PTH and
+then briefly elaborates on its design and implementation. If you are
+interested in the end-user view, please see the <a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>User’s Manual</em></a>.</p>
+<div class="section" id="using-pretokenized-headers-with-clang-low-level-interface">
+<h2>Using Pretokenized Headers with <tt class="docutils literal"><span class="pre">clang</span></tt> (Low-level Interface)<a class="headerlink" href="#using-pretokenized-headers-with-clang-low-level-interface" title="Permalink to this headline">¶</a></h2>
+<p>The Clang compiler frontend, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, supports three command line
+options for generating and using PTH files.</p>
+<p>To generate PTH files using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, use the option <tt class="docutils literal"><span class="pre">-emit-pth</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 test.h -emit-pth -o test.h.pth
+</pre></div>
+</div>
+<p>This option is transparently used by <tt class="docutils literal"><span class="pre">clang</span></tt> when generating PTH
+files. Similarly, PTH files can be used as prefix headers using the
+<tt class="docutils literal"><span class="pre">-include-pth</span></tt> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 -include-pth test.h.pth test.c -o test.s
+</pre></div>
+</div>
+<p>Alternatively, Clang’s PTH files can be used as a raw “token-cache” (or
+“content” cache) of the source included by the original header file.
+This means that the contents of the PTH file are searched as substitutes
+for <em>any</em> source files that are used by <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> to process a
+source file. This is done by specifying the <tt class="docutils literal"><span class="pre">-token-cache</span></tt> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat test.h
+<span class="gp">#</span>include <stdio.h>
+<span class="gp">$</span> clang -cc1 -emit-pth test.h -o test.h.pth
+<span class="gp">$</span> cat test.c
+<span class="gp">#</span>include <span class="s2">"test.h"</span>
+<span class="gp">$</span> clang -cc1 test.c -o <span class="nb">test</span> -token-cache test.h.pth
+</pre></div>
+</div>
+<p>In this example the contents of <tt class="docutils literal"><span class="pre">stdio.h</span></tt> (and the files it includes)
+will be retrieved from <tt class="docutils literal"><span class="pre">test.h.pth</span></tt>, as the PTH file is being used in
+this case as a raw cache of the contents of <tt class="docutils literal"><span class="pre">test.h</span></tt>. This is a
+low-level interface used to both implement the high-level PTH interface
+as well as to provide alternative means to use PTH-style caching.</p>
+</div>
+<div class="section" id="pth-design-and-implementation">
+<h2>PTH Design and Implementation<a class="headerlink" href="#pth-design-and-implementation" title="Permalink to this headline">¶</a></h2>
+<p>Unlike GCC’s precompiled headers, which cache the full ASTs and
+preprocessor state of a header file, Clang’s pretokenized header files
+mainly cache the raw lexer <em>tokens</em> that are needed to segment the
+stream of characters in a source file into keywords, identifiers, and
+operators. Consequently, PTH serves to mainly directly speed up the
+lexing and preprocessing of a source file, while parsing and
+type-checking must be completely redone every time a PTH file is used.</p>
+<div class="section" id="basic-design-tradeoffs">
+<h3>Basic Design Tradeoffs<a class="headerlink" href="#basic-design-tradeoffs" title="Permalink to this headline">¶</a></h3>
+<p>In the long term there are plans to provide an alternate PCH
+implementation for Clang that also caches the work for parsing and type
+checking the contents of header files. The current implementation of PCH
+in Clang as pretokenized header files was motivated by the following
+factors:</p>
+<dl class="docutils">
+<dt><strong>Language independence</strong></dt>
+<dd>PTH files work with any language that
+Clang’s lexer can handle, including C, Objective-C, and (in the early
+stages) C++. This means development on language features at the
+parsing level or above (which is basically almost all interesting
+pieces) does not require PTH to be modified.</dd>
+<dt><strong>Simple design</strong></dt>
+<dd>Relatively speaking, PTH has a simple design and
+implementation, making it easy to test. Further, because the
+machinery for PTH resides at the lower-levels of the Clang library
+stack it is fairly straightforward to profile and optimize.</dd>
+</dl>
+<p>Further, compared to GCC’s PCH implementation (which is the dominate
+precompiled header file implementation that Clang can be directly
+compared against) the PTH design in Clang yields several attractive
+features:</p>
+<dl class="docutils">
+<dt><strong>Architecture independence</strong></dt>
+<dd><p class="first">In contrast to GCC’s PCH files (and
+those of several other compilers), Clang’s PTH files are architecture
+independent, requiring only a single PTH file when building a
+program for multiple architectures.</p>
+<p class="last">For example, on Mac OS X one may wish to compile a “universal binary”
+that runs on PowerPC, 32-bit Intel (i386), and 64-bit Intel
+architectures. In contrast, GCC requires a PCH file for each
+architecture, as the definitions of types in the AST are
+architecture-specific. Since a Clang PTH file essentially represents
+a lexical cache of header files, a single PTH file can be safely used
+when compiling for multiple architectures. This can also reduce
+compile times because only a single PTH file needs to be generated
+during a build instead of several.</p>
+</dd>
+<dt><strong>Reduced memory pressure</strong></dt>
+<dd>Similar to GCC, Clang reads PTH files
+via the use of memory mapping (i.e., <tt class="docutils literal"><span class="pre">mmap</span></tt>). Clang, however,
+memory maps PTH files as read-only, meaning that multiple invocations
+of <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> can share the same pages in memory from a
+memory-mapped PTH file. In comparison, GCC also memory maps its PCH
+files but also modifies those pages in memory, incurring the
+copy-on-write costs. The read-only nature of PTH can greatly reduce
+memory pressure for builds involving multiple cores, thus improving
+overall scalability.</dd>
+<dt><strong>Fast generation</strong></dt>
+<dd>PTH files can be generated in a small fraction
+of the time needed to generate GCC’s PCH files. Since PTH/PCH
+generation is a serial operation that typically blocks progress
+during a build, faster generation time leads to improved processor
+utilization with parallel builds on multicore machines.</dd>
+</dl>
+<p>Despite these strengths, PTH’s simple design suffers some algorithmic
+handicaps compared to other PCH strategies such as those used by GCC.
+While PTH can greatly speed up the processing time of a header file, the
+amount of work required to process a header file is still roughly linear
+in the size of the header file. In contrast, the amount of work done by
+GCC to process a precompiled header is (theoretically) constant (the
+ASTs for the header are literally memory mapped into the compiler). This
+means that only the pieces of the header file that are referenced by the
+source file including the header are the only ones the compiler needs to
+process during actual compilation. While GCC’s particular implementation
+of PCH mitigates some of these algorithmic strengths via the use of
+copy-on-write pages, the approach itself can fundamentally dominate at
+an algorithmic level, especially when one considers header files of
+arbitrary size.</p>
+<p>There is also a PCH implementation for Clang based on the lazy
+deserialization of ASTs. This approach theoretically has the same
+constant-time algorithmic advantages just mentioned but also retains some
+of the strengths of PTH such as reduced memory pressure (ideal for
+multi-core builds).</p>
+</div>
+<div class="section" id="internal-pth-optimizations">
+<h3>Internal PTH Optimizations<a class="headerlink" href="#internal-pth-optimizations" title="Permalink to this headline">¶</a></h3>
+<p>While the main optimization employed by PTH is to reduce lexing time of
+header files by caching pre-lexed tokens, PTH also employs several other
+optimizations to speed up the processing of header files:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">stat</span></tt> caching: PTH files cache information obtained via calls to
+<tt class="docutils literal"><span class="pre">stat</span></tt> that <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> uses to resolve which files are included
+by <tt class="docutils literal"><span class="pre">#include</span></tt> directives. This greatly reduces the overhead
+involved in context-switching to the kernel to resolve included
+files.</li>
+<li>Fast skipping of <tt class="docutils literal"><span class="pre">#ifdef</span></tt> ... <tt class="docutils literal"><span class="pre">#endif</span></tt> chains: PTH files
+record the basic structure of nested preprocessor blocks. When the
+condition of the preprocessor block is false, all of its tokens are
+immediately skipped instead of requiring them to be handled by
+Clang’s preprocessor.</li>
+</ul>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="DriverInternals.html">Driver Design & Internals</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="PCHInternals.html">Precompiled Header and Modules Internals</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/RAVFrontendAction.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/RAVFrontendAction.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/RAVFrontendAction.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/RAVFrontendAction.html Thu May 10 06:54:16 2018
@@ -0,0 +1,261 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Tutorial for building tools using LibTooling and LibASTMatchers" href="LibASTMatchersTutorial.html" />
+ <link rel="prev" title="Clang Plugins" href="ClangPlugins.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>How to write RecursiveASTVisitor based ASTFrontendActions.</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ClangPlugins.html">Clang Plugins</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="how-to-write-recursiveastvisitor-based-astfrontendactions">
+<h1>How to write RecursiveASTVisitor based ASTFrontendActions.<a class="headerlink" href="#how-to-write-recursiveastvisitor-based-astfrontendactions" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>In this tutorial you will learn how to create a FrontendAction that uses
+a RecursiveASTVisitor to find CXXRecordDecl AST nodes with a specified
+name.</p>
+</div>
+<div class="section" id="creating-a-frontendaction">
+<h2>Creating a FrontendAction<a class="headerlink" href="#creating-a-frontendaction" title="Permalink to this headline">¶</a></h2>
+<p>When writing a clang based tool like a Clang Plugin or a standalone tool
+based on LibTooling, the common entry point is the FrontendAction.
+FrontendAction is an interface that allows execution of user specific
+actions as part of the compilation. To run tools over the AST clang
+provides the convenience interface ASTFrontendAction, which takes care
+of executing the action. The only part left is to implement the
+CreateASTConsumer method that returns an ASTConsumer per translation
+unit.</p>
+<div class="highlight-python"><pre>class FindNamedClassAction : public clang::ASTFrontendAction {
+public:
+ virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return std::unique_ptr<clang::ASTConsumer>(
+ new FindNamedClassConsumer);
+ }
+};</pre>
+</div>
+</div>
+<div class="section" id="creating-an-astconsumer">
+<h2>Creating an ASTConsumer<a class="headerlink" href="#creating-an-astconsumer" title="Permalink to this headline">¶</a></h2>
+<p>ASTConsumer is an interface used to write generic actions on an AST,
+regardless of how the AST was produced. ASTConsumer provides many
+different entry points, but for our use case the only one needed is
+HandleTranslationUnit, which is called with the ASTContext for the
+translation unit.</p>
+<div class="highlight-python"><pre>class FindNamedClassConsumer : public clang::ASTConsumer {
+public:
+ virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+ // Traversing the translation unit decl via a RecursiveASTVisitor
+ // will visit all nodes in the AST.
+ Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+ }
+private:
+ // A RecursiveASTVisitor implementation.
+ FindNamedClassVisitor Visitor;
+};</pre>
+</div>
+</div>
+<div class="section" id="using-the-recursiveastvisitor">
+<h2>Using the RecursiveASTVisitor<a class="headerlink" href="#using-the-recursiveastvisitor" title="Permalink to this headline">¶</a></h2>
+<p>Now that everything is hooked up, the next step is to implement a
+RecursiveASTVisitor to extract the relevant information from the AST.</p>
+<p>The RecursiveASTVisitor provides hooks of the form bool
+VisitNodeType(NodeType *) for most AST nodes; the exception are TypeLoc
+nodes, which are passed by-value. We only need to implement the methods
+for the relevant node types.</p>
+<p>Let’s start by writing a RecursiveASTVisitor that visits all
+CXXRecordDecl’s.</p>
+<div class="highlight-python"><pre>class FindNamedClassVisitor
+ : public RecursiveASTVisitor<FindNamedClassVisitor> {
+public:
+ bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ // For debugging, dumping the AST nodes will show which nodes are already
+ // being visited.
+ Declaration->dump();
+
+ // The return value indicates whether we want the visitation to proceed.
+ // Return false to stop the traversal of the AST.
+ return true;
+ }
+};</pre>
+</div>
+<p>In the methods of our RecursiveASTVisitor we can now use the full power
+of the Clang AST to drill through to the parts that are interesting for
+us. For example, to find all class declaration with a certain name, we
+can check for a specific qualified name:</p>
+<div class="highlight-python"><pre>bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C")
+ Declaration->dump();
+ return true;
+}</pre>
+</div>
+</div>
+<div class="section" id="accessing-the-sourcemanager-and-astcontext">
+<h2>Accessing the SourceManager and ASTContext<a class="headerlink" href="#accessing-the-sourcemanager-and-astcontext" title="Permalink to this headline">¶</a></h2>
+<p>Some of the information about the AST, like source locations and global
+identifier information, are not stored in the AST nodes themselves, but
+in the ASTContext and its associated source manager. To retrieve them we
+need to hand the ASTContext into our RecursiveASTVisitor implementation.</p>
+<p>The ASTContext is available from the CompilerInstance during the call to
+CreateASTConsumer. We can thus extract it there and hand it into our
+freshly created FindNamedClassConsumer:</p>
+<div class="highlight-python"><pre>virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return std::unique_ptr<clang::ASTConsumer>(
+ new FindNamedClassConsumer(&Compiler.getASTContext()));
+}</pre>
+</div>
+<p>Now that the ASTContext is available in the RecursiveASTVisitor, we can
+do more interesting things with AST nodes, like looking up their source
+locations:</p>
+<div class="highlight-python"><pre>bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+ // getFullLoc uses the ASTContext's SourceManager to resolve the source
+ // location and break it up into its line and column parts.
+ FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+ if (FullLocation.isValid())
+ llvm::outs() << "Found declaration at "
+ << FullLocation.getSpellingLineNumber() << ":"
+ << FullLocation.getSpellingColumnNumber() << "\n";
+ }
+ return true;
+}</pre>
+</div>
+</div>
+<div class="section" id="putting-it-all-together">
+<h2>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Permalink to this headline">¶</a></h2>
+<p>Now we can combine all of the above into a small example program:</p>
+<div class="highlight-python"><pre>#include "clang/AST/ASTConsumer.h"
+#include "clang/AST/RecursiveASTVisitor.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Frontend/FrontendAction.h"
+#include "clang/Tooling/Tooling.h"
+
+using namespace clang;
+
+class FindNamedClassVisitor
+ : public RecursiveASTVisitor<FindNamedClassVisitor> {
+public:
+ explicit FindNamedClassVisitor(ASTContext *Context)
+ : Context(Context) {}
+
+ bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+ FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+ if (FullLocation.isValid())
+ llvm::outs() << "Found declaration at "
+ << FullLocation.getSpellingLineNumber() << ":"
+ << FullLocation.getSpellingColumnNumber() << "\n";
+ }
+ return true;
+ }
+
+private:
+ ASTContext *Context;
+};
+
+class FindNamedClassConsumer : public clang::ASTConsumer {
+public:
+ explicit FindNamedClassConsumer(ASTContext *Context)
+ : Visitor(Context) {}
+
+ virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+ Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+ }
+private:
+ FindNamedClassVisitor Visitor;
+};
+
+class FindNamedClassAction : public clang::ASTFrontendAction {
+public:
+ virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return std::unique_ptr<clang::ASTConsumer>(
+ new FindNamedClassConsumer(&Compiler.getASTContext()));
+ }
+};
+
+int main(int argc, char **argv) {
+ if (argc > 1) {
+ clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]);
+ }
+}</pre>
+</div>
+<p>We store this into a file called FindClassDecls.cpp and create the
+following CMakeLists.txt to link it:</p>
+<div class="highlight-python"><pre>add_clang_executable(find-class-decls FindClassDecls.cpp)
+
+target_link_libraries(find-class-decls clangTooling)</pre>
+</div>
+<p>When running this tool over a small code snippet it will output all
+declarations of a class n::m::C it found:</p>
+<div class="highlight-python"><pre>$ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }"
+Found declaration at 1:29</pre>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ClangPlugins.html">Clang Plugins</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/ReleaseNotes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/ReleaseNotes.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/ReleaseNotes.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/ReleaseNotes.html Thu May 10 06:54:16 2018
@@ -0,0 +1,478 @@
+
+
+<!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 5.0.0 Release Notes — Clang 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Clang Compiler Userâs Manual" href="UsersManual.html" />
+ <link rel="prev" title="Using Clang as a Compiler" href="index.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Clang 5.0.0 Release Notes</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="index.html">Using Clang as a Compiler</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="UsersManual.html">Clang Compiler User’s Manual</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="clang-5-0-0-release-notes">
+<h1>Clang 5.0.0 Release Notes<a class="headerlink" href="#clang-5-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="id3">Introduction</a></li>
+<li><a class="reference internal" href="#what-s-new-in-clang-5-0-0" id="id4">What’s New in Clang 5.0.0?</a><ul>
+<li><a class="reference internal" href="#major-new-features" id="id5">Major New Features</a></li>
+<li><a class="reference internal" href="#new-compiler-flags" id="id6">New Compiler Flags</a></li>
+<li><a class="reference internal" href="#deprecated-compiler-flags" id="id7">Deprecated Compiler Flags</a></li>
+<li><a class="reference internal" href="#new-pragmas-in-clang" id="id8">New Pragmas in Clang</a></li>
+<li><a class="reference internal" href="#attribute-changes-in-clang" id="id9">Attribute Changes in Clang</a></li>
+<li><a class="reference internal" href="#c-language-changes-in-clang" id="id10">C Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#id1" id="id11">C++ Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#objective-c-language-changes-in-clang" id="id12">Objective-C Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#opencl-c-language-changes-in-clang" id="id13">OpenCL C Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#clang-format" id="id14">clang-format</a></li>
+<li><a class="reference internal" href="#libclang" id="id15">libclang</a></li>
+<li><a class="reference internal" href="#static-analyzer" id="id16">Static Analyzer</a></li>
+<li><a class="reference internal" href="#undefined-behavior-sanitizer-ubsan" id="id17">Undefined Behavior Sanitizer (UBSan)</a></li>
+<li><a class="reference internal" href="#python-binding-changes" id="id18">Python Binding Changes</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-information" id="id19">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="#id3">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 5.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-5-0-0">
+<h2><a class="toc-backref" href="#id4">What’s New in Clang 5.0.0?</a><a class="headerlink" href="#what-s-new-in-clang-5-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="major-new-features">
+<h3><a class="toc-backref" href="#id5">Major New Features</a><a class="headerlink" href="#major-new-features" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="c-coroutines">
+<h4>C++ coroutines<a class="headerlink" href="#c-coroutines" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="http://open-std.org/jtc1/sc22/wg21/docs/papers/2017/n4680.pdf">C++ coroutines TS</a>
+implementation has landed. Use <tt class="docutils literal"><span class="pre">-fcoroutines-ts</span> <span class="pre">-stdlib=libc++</span></tt> to enable
+coroutine support. Here is <a class="reference external" href="https://wandbox.org/permlink/Dth1IO5q8Oe31ew2">an example</a> to get you started.</p>
+</div>
+<div class="section" id="improvements-to-clang-s-diagnostics">
+<h4>Improvements to Clang’s diagnostics<a class="headerlink" href="#improvements-to-clang-s-diagnostics" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wcast-qual</span></tt> was implemented for C++. C-style casts are now properly
+diagnosed.</li>
+<li><tt class="docutils literal"><span class="pre">-Wunused-lambda-capture</span></tt> warns when a variable explicitly captured
+by a lambda is not used in the body of the lambda.</li>
+<li><tt class="docutils literal"><span class="pre">-Wstrict-prototypes</span></tt> is a new warning that warns about non-prototype
+function and block declarations and types in C and Objective-C.</li>
+<li><tt class="docutils literal"><span class="pre">-Wunguarded-availability</span></tt> is a new warning that warns about uses of new
+APIs that were introduced in a system whose version is newer than the
+deployment target version. A new Objective-C expression <tt class="docutils literal"><span class="pre">@available</span></tt> has
+been introduced to perform system version checking at runtime. This warning
+is off by default to prevent unexpected warnings in existing projects.
+However, its less strict sibling <tt class="docutils literal"><span class="pre">-Wunguarded-availability-new</span></tt> is on by
+default. It warns about unguarded uses of APIs only when they were introduced
+in or after macOS 10.13, iOS 11, tvOS 11 or watchOS 4.</li>
+<li>The <tt class="docutils literal"><span class="pre">-Wdocumentation</span></tt> warning now allows the use of <tt class="docutils literal"><span class="pre">\param</span></tt> and
+<tt class="docutils literal"><span class="pre">\returns</span></tt> documentation directives in the documentation comments for
+declarations with a function or a block pointer type.</li>
+<li>The compiler no longer warns about unreachable <tt class="docutils literal"><span class="pre">__builtin_unreachable</span></tt>
+statements.</li>
+</ul>
+</div>
+</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><tt class="docutils literal"><span class="pre">--autocomplete</span></tt> was implemented to obtain a list of flags and its arguments.
+This is used for shell autocompletion.</li>
+</ul>
+</div>
+<div class="section" id="deprecated-compiler-flags">
+<h3><a class="toc-backref" href="#id7">Deprecated Compiler Flags</a><a class="headerlink" href="#deprecated-compiler-flags" title="Permalink to this headline">¶</a></h3>
+<p>The following options are deprecated and ignored. They will be removed in
+future versions of Clang.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fslp-vectorize-aggressive</span></tt> used to enable the BB vectorizing pass. They have been superseeded
+by the normal SLP vectorizer.</li>
+<li><tt class="docutils literal"><span class="pre">-fno-slp-vectorize-aggressive</span></tt> used to be the default behavior of clang.</li>
+</ul>
+</div>
+<div class="section" id="new-pragmas-in-clang">
+<h3><a class="toc-backref" href="#id8">New Pragmas in Clang</a><a class="headerlink" href="#new-pragmas-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Clang now supports the <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">attribute</span></tt> pragma that allows users to apply
+an attribute to multiple declarations.</li>
+<li><tt class="docutils literal"><span class="pre">pragma</span> <span class="pre">pack</span></tt> directives that are included in a precompiled header are now
+applied correctly to the declarations in the compilation unit that includes
+that precompiled header.</li>
+</ul>
+</div>
+<div class="section" id="attribute-changes-in-clang">
+<h3><a class="toc-backref" href="#id9">Attribute Changes in Clang</a><a class="headerlink" href="#attribute-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>The <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute now allows at most one function with a given
+name to lack the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute. This unmarked function will not
+have its name mangled.</li>
+<li>The <tt class="docutils literal"><span class="pre">ms_abi</span></tt> attribute and the <tt class="docutils literal"><span class="pre">__builtin_ms_va_list</span></tt> types and builtins
+are now supported on AArch64.</li>
+</ul>
+</div>
+<div class="section" id="c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id10">C Language Changes in Clang</a><a class="headerlink" href="#c-language-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Added near complete support for implicit scalar to vector conversion, a GNU
+C/C++ language extension. With this extension, the following code is
+considered valid:</li>
+</ul>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">unsigned</span> <span class="n">v4i32</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">vector_size</span><span class="p">(</span><span class="mi">16</span><span class="p">)));</span>
+
+<span class="n">v4i32</span> <span class="nf">foo</span><span class="p">(</span><span class="n">v4i32</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Here 5 is implicitly casted to an unsigned value and replicated into a</span>
+ <span class="c1">// vector with as many elements as 'a'.</span>
+ <span class="k">return</span> <span class="n">a</span> <span class="o">+</span> <span class="mi">5</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The implicit conversion of a scalar value to a vector value–in the context of
+a vector expression–occurs when:</p>
+<ul class="simple">
+<li>The type of the vector is that of a <tt class="docutils literal"><span class="pre">__attribute__((vector_size(size)))</span></tt>
+vector, not an OpenCL <tt class="docutils literal"><span class="pre">__attribute__((ext_vector_type(size)))</span></tt> vector type.</li>
+<li>The scalar value can be casted to that of the vector element’s type without
+the loss of precision based on the type of the scalar and the type of the
+vector’s elements.</li>
+<li>For compile time constant values, the above rule is weakened to consider the
+value of the scalar constant rather than the constant’s type. However,
+for compatibility with GCC, floating point constants with precise integral
+representations are not implicitly converted to integer values.</li>
+</ul>
+<p>Currently the basic integer and floating point types with the following
+operators are supported: <tt class="docutils literal"><span class="pre">+</span></tt>, <tt class="docutils literal"><span class="pre">/</span></tt>, <tt class="docutils literal"><span class="pre">-</span></tt>, <tt class="docutils literal"><span class="pre">*</span></tt>, <tt class="docutils literal"><span class="pre">%</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, <tt class="docutils literal"><span class="pre"><</span></tt>,
+<tt class="docutils literal"><span class="pre">>=</span></tt>, <tt class="docutils literal"><span class="pre"><=</span></tt>, <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">!=</span></tt>, <tt class="docutils literal"><span class="pre">&</span></tt>, <tt class="docutils literal"><span class="pre">|</span></tt>, <tt class="docutils literal"><span class="pre">^</span></tt> and the corresponding
+assignment operators where applicable.</p>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id11">C++ Language Changes in Clang</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>We expect this to be the last Clang release that defaults to <tt class="docutils literal"><span class="pre">-std=gnu++98</span></tt>
+when using the GCC-compatible <tt class="docutils literal"><span class="pre">clang++</span></tt> driver. From Clang 6 onwards we
+expect to use <tt class="docutils literal"><span class="pre">-std=gnu++14</span></tt> or a later standard by default, to match the
+behavior of recent GCC releases. Users are encouraged to change their build
+files to explicitly specify their desired C++ standard.</li>
+<li>Support for the C++17 standard has been completed. This mode can be enabled
+using <tt class="docutils literal"><span class="pre">-std=c++17</span></tt> (the old flag <tt class="docutils literal"><span class="pre">-std=c++1z</span></tt> is still supported for
+compatibility).</li>
+<li>When targeting a platform that uses the Itanium C++ ABI, Clang implements a
+<a class="reference external" href="https://github.com/itanium-cxx-abi/cxx-abi/commit/7099637aba11fed6bdad7ee65bf4fd3f97fbf076">recent change to the ABI</a> that passes objects of class type indirectly if they
+have a non-trivial move constructor. Previous versions of Clang only
+considered the copy constructor, resulting in an ABI change in rare cases,
+but GCC has already implemented this change for several releases.
+This affects all targets other than Windows and PS4. You can opt out of this
+ABI change with <tt class="docutils literal"><span class="pre">-fclang-abi-compat=4.0</span></tt>.</li>
+<li>As mentioned in <a class="reference internal" href="#c-language-changes-in-clang">C Language Changes in Clang</a>, Clang’s support for
+implicit scalar to vector conversions also applies to C++. Additionally
+the following operators are also supported: <tt class="docutils literal"><span class="pre">&&</span></tt> and <tt class="docutils literal"><span class="pre">||</span></tt>.</li>
+</ul>
+</div>
+<div class="section" id="objective-c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id12">Objective-C Language Changes in Clang</a><a class="headerlink" href="#objective-c-language-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Clang now guarantees that a <tt class="docutils literal"><span class="pre">readwrite</span></tt> property is synthesized when an
+ambiguous property (i.e. a property that’s declared in multiple protocols)
+is synthesized. The <tt class="docutils literal"><span class="pre">-Wprotocol-property-synthesis-ambiguity</span></tt> warning that
+warns about incompatible property types is now promoted to an error when
+there’s an ambiguity between <tt class="docutils literal"><span class="pre">readwrite</span></tt> and <tt class="docutils literal"><span class="pre">readonly</span></tt> properties.</li>
+<li>Clang now prohibits synthesis of ambiguous properties with incompatible
+explicit property attributes. The following property attributes are
+checked for differences: <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">retain</span></tt>/<tt class="docutils literal"><span class="pre">strong</span></tt>, <tt class="docutils literal"><span class="pre">atomic</span></tt>,
+<tt class="docutils literal"><span class="pre">getter</span></tt> and <tt class="docutils literal"><span class="pre">setter</span></tt>.</li>
+</ul>
+</div>
+<div class="section" id="opencl-c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id13">OpenCL C Language Changes in Clang</a><a class="headerlink" href="#opencl-c-language-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<p>Various bug fixes and improvements:</p>
+<ul class="simple">
+<li>Extended OpenCL-related Clang tests.</li>
+<li>Improved diagnostics across several areas: scoped address space
+qualified variables, function pointers, atomics, type rank for overloading,
+block captures, <tt class="docutils literal"><span class="pre">reserve_id_t</span></tt>.</li>
+<li>Several address space related fixes for constant address space function scope variables,
+IR generation, mangling of <tt class="docutils literal"><span class="pre">generic</span></tt> and alloca (post-fix from general Clang
+refactoring of address spaces).</li>
+<li>Several improvements in extensions: fixed OpenCL version for <tt class="docutils literal"><span class="pre">cl_khr_mipmap_image</span></tt>,
+added missing <tt class="docutils literal"><span class="pre">cl_khr_3d_image_writes</span></tt>.</li>
+<li>Improvements in <tt class="docutils literal"><span class="pre">enqueue_kernel</span></tt>, especially the implementation of <tt class="docutils literal"><span class="pre">ndrange_t</span></tt> and blocks.</li>
+<li>OpenCL type related fixes: global samplers, the <tt class="docutils literal"><span class="pre">pipe_t</span></tt> size, internal type redefinition,
+and type compatibility checking in ternary and other operations.</li>
+<li>The OpenCL header has been extended with missing extension guards, and direct mapping of <tt class="docutils literal"><span class="pre">as_type</span></tt>
+to <tt class="docutils literal"><span class="pre">__builtin_astype</span></tt>.</li>
+<li>Fixed <tt class="docutils literal"><span class="pre">kernel_arg_type_qual</span></tt> and OpenCL/SPIR version in metadata.</li>
+<li>Added proper use of the kernel calling convention to various targets.</li>
+</ul>
+<p>The following new functionalities have been added:</p>
+<ul class="simple">
+<li>Added documentation on OpenCL to Clang user manual.</li>
+<li>Extended Clang builtins with required <tt class="docutils literal"><span class="pre">cl_khr_subgroups</span></tt> support.</li>
+<li>Add <tt class="docutils literal"><span class="pre">intel_reqd_sub_group_size</span></tt> attribute support.</li>
+<li>Added OpenCL types to <tt class="docutils literal"><span class="pre">CIndex</span></tt>.</li>
+</ul>
+</div>
+<div class="section" id="clang-format">
+<h3><a class="toc-backref" href="#id14">clang-format</a><a class="headerlink" href="#clang-format" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first">Option <strong>BreakBeforeInheritanceComma</strong> added to break before <tt class="docutils literal"><span class="pre">:</span></tt> and <tt class="docutils literal"><span class="pre">,</span></tt> in case of
+multiple inheritance in a class declaration. Enabled by default in the Mozilla coding style.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="34%" />
+<col width="66%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">true</th>
+<th class="head">false</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="first last highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span>
+ <span class="o">:</span> <span class="k">public</span> <span class="n">X</span>
+ <span class="p">,</span> <span class="k">public</span> <span class="n">Y</span> <span class="p">{</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</td>
+<td><div class="first last highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="o">:</span> <span class="k">public</span> <span class="n">X</span><span class="p">,</span> <span class="k">public</span> <span class="n">Y</span> <span class="p">{</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</td>
+</tr>
+</tbody>
+</table>
+</li>
+<li><p class="first">Align block comment decorations.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="51%" />
+<col width="49%" />
+</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 class="cm">/* line 1</span>
+<span class="cm"> * line 2</span>
+<span class="cm"> */</span>
+</pre></div>
+</div>
+</td>
+<td><div class="first last highlight-c++"><div class="highlight"><pre><span class="cm">/* line 1</span>
+<span class="cm"> * line 2</span>
+<span class="cm"> */</span>
+</pre></div>
+</div>
+</td>
+</tr>
+</tbody>
+</table>
+</li>
+<li><p class="first">The <a class="reference internal" href="ClangFormatStyleOptions.html"><em>Clang-Format Style Options</em></a> documentation provides detailed examples for most options.</p>
+</li>
+<li><p class="first">Namespace end comments are now added or updated automatically.</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 class="k">namespace</span> <span class="n">A</span> <span class="p">{</span>
+<span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">j</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</td>
+<td><div class="first last highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">A</span> <span class="p">{</span>
+<span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">j</span><span class="p">;</span>
+<span class="p">}</span> <span class="c1">// namespace A</span>
+</pre></div>
+</div>
+</td>
+</tr>
+</tbody>
+</table>
+</li>
+<li><p class="first">Comment reflow support added. Overly long comment lines will now be reflown with the rest of
+the paragraph instead of just broken. Option <strong>ReflowComments</strong> added and enabled by default.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="libclang">
+<h3><a class="toc-backref" href="#id15">libclang</a><a class="headerlink" href="#libclang" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first">Libclang now provides code-completion results for more C++ constructs
+and keywords. The following keywords/identifiers are now included in the
+code-completion results: <tt class="docutils literal"><span class="pre">static_assert</span></tt>, <tt class="docutils literal"><span class="pre">alignas</span></tt>, <tt class="docutils literal"><span class="pre">constexpr</span></tt>,
+<tt class="docutils literal"><span class="pre">final</span></tt>, <tt class="docutils literal"><span class="pre">noexcept</span></tt>, <tt class="docutils literal"><span class="pre">override</span></tt> and <tt class="docutils literal"><span class="pre">thread_local</span></tt>.</p>
+</li>
+<li><p class="first">Libclang now provides code-completion results for members from dependent
+classes. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+<span class="kt">void</span> <span class="n">appendValue</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="o">&</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="n">T</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">dest</span><span class="p">.</span> <span class="c1">// Relevant completion results are now shown after '.'</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that code-completion results are still not provided when the member
+expression includes a dependent base expression. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+<span class="kt">void</span> <span class="n">appendValue</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">T</span><span class="o">>></span> <span class="o">&</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="n">T</span> <span class="o">&</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">dest</span><span class="p">.</span><span class="n">at</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span> <span class="c1">// Libclang fails to provide completion results after '.'</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="static-analyzer">
+<h3><a class="toc-backref" href="#id16">Static Analyzer</a><a class="headerlink" href="#static-analyzer" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>The static analyzer now supports using the
+<a class="reference external" href="https://github.com/z3prover/z3">z3 theorem prover</a> from Microsoft Research
+as an external constraint solver. This allows reasoning over more complex
+queries, but performance is ~15x slower than the default range-based
+constraint solver. To enable the z3 solver backend, clang must be built with
+the <tt class="docutils literal"><span class="pre">CLANG_ANALYZER_BUILD_Z3=ON</span></tt> option, and the
+<tt class="docutils literal"><span class="pre">-Xanalyzer</span> <span class="pre">-analyzer-constraints=z3</span></tt> arguments passed at runtime.</li>
+</ul>
+</div>
+<div class="section" id="undefined-behavior-sanitizer-ubsan">
+<h3><a class="toc-backref" href="#id17">Undefined Behavior Sanitizer (UBSan)</a><a class="headerlink" href="#undefined-behavior-sanitizer-ubsan" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first">The Undefined Behavior Sanitizer has a new check for pointer overflow. This
+check is on by default. The flag to control this functionality is
+<tt class="docutils literal"><span class="pre">-fsanitize=pointer-overflow</span></tt>.</p>
+<p>Pointer overflow is an indicator of undefined behavior: when a pointer
+indexing expression wraps around the address space, or produces other
+unexpected results, its result may not point to a valid object.</p>
+</li>
+<li><p class="first">UBSan has several new checks which detect violations of nullability
+annotations. These checks are off by default. The flag to control this group
+of checks is <tt class="docutils literal"><span class="pre">-fsanitize=nullability</span></tt>. The checks can be individially enabled
+by <tt class="docutils literal"><span class="pre">-fsanitize=nullability-arg</span></tt> (which checks calls),
+<tt class="docutils literal"><span class="pre">-fsanitize=nullability-assign</span></tt> (which checks assignments), and
+<tt class="docutils literal"><span class="pre">-fsanitize=nullability-return</span></tt> (which checks return statements).</p>
+</li>
+<li><p class="first">UBSan can now detect invalid loads from bitfields and from ObjC BOOLs.</p>
+</li>
+<li><p class="first">UBSan can now avoid emitting unnecessary type checks in C++ class methods and
+in several other cases where the result is known at compile-time. UBSan can
+also avoid emitting unnecessary overflow checks in arithmetic expressions
+with promoted integer operands.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="python-binding-changes">
+<h3><a class="toc-backref" href="#id18">Python Binding Changes</a><a class="headerlink" href="#python-binding-changes" title="Permalink to this headline">¶</a></h3>
+<p>Python bindings now support both Python 2 and Python 3.</p>
+<p>The following methods have been added:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">is_scoped_enum</span></tt> has been added to <tt class="docutils literal"><span class="pre">Cursor</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">exception_specification_kind</span></tt> has been added to <tt class="docutils literal"><span class="pre">Cursor</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">get_address_space</span></tt> has been added to <tt class="docutils literal"><span class="pre">Type</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">get_typedef_name</span></tt> has been added to <tt class="docutils literal"><span class="pre">Type</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">get_exception_specification_kind</span></tt> has been added to <tt class="docutils literal"><span class="pre">Type</span></tt>.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="additional-information">
+<h2><a class="toc-backref" href="#id19">Additional Information</a><a class="headerlink" href="#additional-information" title="Permalink to this headline">¶</a></h2>
+<p>A wide variety of additional information is available on the <a class="reference external" href="http://clang.llvm.org/">Clang web
+page</a>. The web page contains versions of the
+API documentation which are up-to-date with the Subversion version of
+the source code. You can access versions of these documents specific to
+this release by going into the “<tt class="docutils literal"><span class="pre">clang/docs/</span></tt>” directory in the Clang
+tree.</p>
+<p>If you have any questions or comments about Clang, please feel free to
+contact us via the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-dev">mailing
+list</a>.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="index.html">Using Clang as a Compiler</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="UsersManual.html">Clang Compiler User’s Manual</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/SafeStack.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/SafeStack.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/SafeStack.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/SafeStack.html Thu May 10 06:54:16 2018
@@ -0,0 +1,272 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Source-based Code Coverage" href="SourceBasedCodeCoverage.html" />
+ <link rel="prev" title="LTO Visibility" href="LTOVisibility.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>SafeStack</span></h2>
+ </div>
+ <div class="topnav">
+
+ <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"><tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt></a></li>
+<li><a class="reference internal" href="#attribute-no-sanitize-safe-stack" id="id11"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-ptr" id="id12"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></tt></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-start" id="id13"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#design" id="id14">Design</a><ul>
+<li><a class="reference internal" href="#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 <tt class="docutils literal"><span class="pre">sigaltstack()</span></tt> must not use the unsafe stack (see
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt> below).</p>
+<p>Programs that use APIs from <tt class="docutils literal"><span class="pre">ucontext.h</span></tt> are not supported yet.</p>
+</div>
+</div>
+<div class="section" id="security">
+<h3><a class="toc-backref" href="#id5">Security</a><a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h3>
+<p>SafeStack protects return addresses, spilled registers and local variables that
+are always accessed in a safe way by separating them in a dedicated safe stack
+region. The safe stack is automatically protected against stack-based buffer
+overflows, since it is disjoint from the unsafe stack in memory, and it itself
+is always accessed in a safe way. In the current implementation, the safe stack
+is protected against arbitrary memory write vulnerabilities though
+randomization and information hiding: the safe stack is allocated at a random
+address and the instrumentation ensures that no pointers to the safe stack are
+ever stored outside of the safe stack itself (see limitations below).</p>
+<div class="section" id="known-security-limitations">
+<h4><a class="toc-backref" href="#id6">Known security limitations</a><a class="headerlink" href="#known-security-limitations" title="Permalink to this headline">¶</a></h4>
+<p>A complete protection against control-flow hijack attacks requires combining
+SafeStack with another mechanism that enforces the integrity of code pointers
+that are stored on the heap or the unsafe stack, such as <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">CPI</a>, or a forward-edge control flow integrity
+mechanism that enforces correct calling conventions at indirect call sites,
+such as <a class="reference external" href="http://research.google.com/pubs/archive/42808.pdf">IFCC</a> with arity
+checks. Clang has control-flow integrity protection scheme for <a class="reference internal" href="ControlFlowIntegrity.html"><em>C++ virtual
+calls</em></a>, but not non-virtual indirect calls. With
+SafeStack alone, an attacker can overwrite a function pointer on the heap or
+the unsafe stack and cause a program to call arbitrary location, which in turn
+might enable stack pivoting and return-oriented programming.</p>
+<p>In its current implementation, SafeStack provides precise protection against
+stack-based buffer overflows, but protection against arbitrary memory write
+vulnerabilities is probabilistic and relies on randomization and information
+hiding. The randomization is currently based on system-enforced ASLR and shares
+its known security limitations. The safe stack pointer hiding is not perfect
+yet either: system library functions such as <tt class="docutils literal"><span class="pre">swapcontext</span></tt>, exception
+handling mechanisms, intrinsics such as <tt class="docutils literal"><span class="pre">__builtin_frame_address</span></tt>, or
+low-level bugs in runtime support could leak the safe stack pointer. In the
+future, such leaks could be detected by static or dynamic analysis tools and
+prevented by adjusting such functions to either encrypt the stack pointer when
+storing it in the heap (as already done e.g., by <tt class="docutils literal"><span class="pre">setjmp</span></tt>/<tt class="docutils literal"><span class="pre">longjmp</span></tt>
+implementation in glibc), or store it in a safe region instead.</p>
+<p>The <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">CPI paper</a> describes two alternative,
+stronger safe stack protection mechanisms, that rely on software fault
+isolation, or hardware segmentation (as available on x86-32 and some x86-64
+CPUs).</p>
+<p>At the moment, SafeStack assumes that the compiler’s implementation is correct.
+This has not been verified except through manual code inspection, and could
+always regress in the future. It’s therefore desirable to have a separate
+static or dynamic binary verification tool that would check the correctness of
+the SafeStack instrumentation in final binaries.</p>
+</div>
+</div>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id7">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>To enable SafeStack, just pass <tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt> flag to both compile
+and link command lines.</p>
+<div class="section" id="supported-platforms">
+<h3><a class="toc-backref" href="#id8">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h3>
+<p>SafeStack was tested on Linux, FreeBSD and MacOSX.</p>
+</div>
+<div class="section" id="low-level-api">
+<h3><a class="toc-backref" href="#id9">Low-level API</a><a class="headerlink" href="#low-level-api" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="has-feature-safe-stack">
+<h4><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt></a><a class="headerlink" href="#has-feature-safe-stack" title="Permalink to this headline">¶</a></h4>
+<p>In some rare cases one may need to execute different code depending on
+whether SafeStack is enabled. The macro <tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt> can
+be used for this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if __has_feature(safe_stack)</span>
+<span class="cp">// code that builds only under SafeStack</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-safe-stack">
+<h4><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt></a><a class="headerlink" href="#attribute-no-sanitize-safe-stack" title="Permalink to this headline">¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt> on a function declaration
+to specify that the safe stack instrumentation should not be applied to that
+function, even if enabled globally (see <tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt> flag). This
+attribute may be required for functions that make assumptions about the
+exact layout of their stack frames.</p>
+<p>All local variables in functions with this attribute will be stored on the safe
+stack. The safe stack remains unprotected against memory errors when accessing
+these variables, so extra care must be taken to manually ensure that all such
+accesses are safe. Furthermore, the addresses of such local variables should
+never be stored on the heap, as it would leak the location of the SafeStack.</p>
+</div>
+<div class="section" id="builtin-get-unsafe-stack-ptr">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></tt></a><a class="headerlink" href="#builtin-get-unsafe-stack-ptr" title="Permalink to this headline">¶</a></h4>
+<p>This builtin function returns current unsafe stack pointer of the current
+thread.</p>
+</div>
+<div class="section" id="builtin-get-unsafe-stack-start">
+<h4><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></tt></a><a class="headerlink" href="#builtin-get-unsafe-stack-start" title="Permalink to this headline">¶</a></h4>
+<p>This builtin function returns a pointer to the start of the unsafe stack of the
+current thread.</p>
+</div>
+</div>
+</div>
+<div class="section" id="design">
+<h2><a class="toc-backref" href="#id14">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">¶</a></h2>
+<p>Please refer to the <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">Code-Pointer Integrity</a>
+project page for more information about the design of the SafeStack and its
+related technologies.</p>
+<div class="section" id="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 <tt class="docutils literal"><span class="pre">SafeStack::createStackRestorePoints</span></tt>.</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">
+
+ <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">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/SanitizerCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/SanitizerCoverage.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/SanitizerCoverage.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/SanitizerCoverage.html Thu May 10 06:54:16 2018
@@ -0,0 +1,381 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="SanitizerStats" href="SanitizerStats.html" />
+ <link rel="prev" title="LeakSanitizer" href="LeakSanitizer.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>SanitizerCoverage</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="LeakSanitizer.html">LeakSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="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="#tracing-pcs" id="id3">Tracing PCs</a></li>
+<li><a class="reference internal" href="#instrumentation-points" id="id4">Instrumentation points</a><ul>
+<li><a class="reference internal" href="#edge-coverage" id="id5">Edge coverage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tracing-data-flow" id="id6">Tracing data flow</a></li>
+<li><a class="reference internal" href="#default-implementation" id="id7">Default implementation</a><ul>
+<li><a class="reference internal" href="#sancov-data-format" id="id8">Sancov data format</a></li>
+<li><a class="reference internal" href="#sancov-tool" id="id9">Sancov Tool</a></li>
+<li><a class="reference internal" href="#coverage-reports" id="id10">Coverage Reports</a></li>
+<li><a class="reference internal" href="#output-directory" id="id11">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"><em>SourceBasedCodeCoverage</em></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 <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc-guard</span></tt> the compiler will insert the following code
+on every edge:</p>
+<div class="highlight-none"><div class="highlight"><pre>__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 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="n">uint32_t</span> <span class="o">*</span><span class="n">start</span><span class="p">,</span> <span class="n">uint32_t</span> <span class="o">*</span><span class="n">stop</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>With an additional <tt class="docutils literal"><span class="pre">...=trace-pc,indirect-calls</span></tt> flag
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc_indirect(void</span> <span class="pre">*callee)</span></tt> 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 class="cp">// trace-pc-guard-cb.cc</span>
+<span class="cp">#include <stdint.h></span>
+<span class="cp">#include <stdio.h></span>
+<span class="cp">#include <sanitizer/coverage_interface.h></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="n">uint32_t</span> <span class="o">*</span><span class="n">start</span><span class="p">,</span>
+ <span class="n">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="n">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="n">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="n">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 class="c1">// trace-pc-guard-example.cc</span>
+<span class="kt">void</span> <span class="n">foo</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="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 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 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 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 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="tracing-pcs">
+<h2><a class="toc-backref" href="#id3">Tracing PCs</a><a class="headerlink" href="#tracing-pcs" title="Permalink to this headline">¶</a></h2>
+<p>With <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc</span></tt> the compiler will insert
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc()</span></tt> on every edge.
+With an additional <tt class="docutils literal"><span class="pre">...=trace-pc,indirect-calls</span></tt> flag
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc_indirect(void</span> <span class="pre">*callee)</span></tt> 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="#id4">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><tt class="docutils literal"><span class="pre">edge</span></tt> (default): edges are instrumented (see below).</li>
+<li><tt class="docutils literal"><span class="pre">bb</span></tt>: basic blocks are instrumented.</li>
+<li><tt class="docutils literal"><span class="pre">func</span></tt>: only the entry block of every function will be instrumented.</li>
+</ul>
+<p>Use these flags together with <tt class="docutils literal"><span class="pre">trace-pc-guard</span></tt> or <tt class="docutils literal"><span class="pre">trace-pc</span></tt>,
+like this: <tt class="docutils literal"><span class="pre">-fsanitize-coverage=func,trace-pc-guard</span></tt>.</p>
+<p>When <tt class="docutils literal"><span class="pre">edge</span></tt> or <tt class="docutils literal"><span class="pre">bb</span></tt> is used, some of the edges/blocks may still be left
+uninstrumented (pruned) if such instrumentation is considered redundant.
+Use <tt class="docutils literal"><span class="pre">no-prune</span></tt> (e.g. <tt class="docutils literal"><span class="pre">-fsanitize-coverage=bb,no-prune,trace-pc-guard</span></tt>)
+to disable pruning. This could be useful for better coverage visualization.</p>
+<div class="section" id="edge-coverage">
+<h3><a class="toc-backref" href="#id5">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 class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">)</span>
+ <span class="o">*</span><span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It contains 3 basic blocks, let’s name them A, B, C:</p>
+<div class="highlight-none"><div class="highlight"><pre>A
+|\
+| \
+| B
+| /
+|/
+C
+</pre></div>
+</div>
+<p>If blocks A, B, and C are all covered we know for certain that the edges A=>B
+and B=>C were executed, but we still don’t know if the edge A=>C was executed.
+Such edges of control flow graph are called
+<a class="reference external" href="http://en.wikipedia.org/wiki/Control_flow_graph#Special_edges">critical</a>. The
+edge-level coverage simply splits all critical
+edges by introducing new dummy blocks and then instruments those blocks:</p>
+<div class="highlight-none"><div class="highlight"><pre>A
+|\
+| \
+D B
+| /
+|/
+C
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="tracing-data-flow">
+<h2><a class="toc-backref" href="#id6">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 <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-cmp</span></tt> the compiler will insert extra instrumentation
+around comparison instructions and switch statements.
+Similarly, with <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-div</span></tt> the compiler will instrument
+integer division instructions (to capture the right argument of division)
+and with <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-gep</span></tt> –
+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 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="n">__sanitizer_cov_trace_cmp1</span><span class="p">(</span><span class="n">uint8_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="n">uint8_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="n">__sanitizer_cov_trace_cmp2</span><span class="p">(</span><span class="n">uint16_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="n">uint16_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="n">__sanitizer_cov_trace_cmp4</span><span class="p">(</span><span class="n">uint32_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="n">uint32_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="n">__sanitizer_cov_trace_cmp8</span><span class="p">(</span><span class="n">uint64_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="n">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="n">__sanitizer_cov_trace_switch</span><span class="p">(</span><span class="n">uint64_t</span> <span class="n">Val</span><span class="p">,</span> <span class="n">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="n">__sanitizer_cov_trace_div4</span><span class="p">(</span><span class="n">uint32_t</span> <span class="n">Val</span><span class="p">);</span>
+<span class="kt">void</span> <span class="n">__sanitizer_cov_trace_div8</span><span class="p">(</span><span class="n">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="n">__sanitizer_cov_trace_gep</span><span class="p">(</span><span class="n">uintptr_t</span> <span class="n">Idx</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This interface is a subject to change.</p>
+</div>
+<div class="section" id="default-implementation">
+<h2><a class="toc-backref" href="#id7">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 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>1 ./a.out; 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>1 ./a.out foo ; 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 <tt class="docutils literal"><span class="pre">*.sancov</span></tt> file is created during the process shutdown.
+If the executable is dynamically linked against instrumented DSOs,
+one <tt class="docutils literal"><span class="pre">*.sancov</span></tt> file will be also created for every DSO.</p>
+<div class="section" id="sancov-data-format">
+<h3><a class="toc-backref" href="#id8">Sancov data format</a><a class="headerlink" href="#sancov-data-format" title="Permalink to this headline">¶</a></h3>
+<p>The format of <tt class="docutils literal"><span class="pre">*.sancov</span></tt> files is very simple: the first 8 bytes is the magic,
+one of <tt class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF64</span></tt> and <tt class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF32</span></tt>. The last byte of the
+magic defines the size of the following offsets. The rest of the data is the
+offsets in the corresponding binary/DSO that were executed during the run.</p>
+</div>
+<div class="section" id="sancov-tool">
+<h3><a class="toc-backref" href="#id9">Sancov Tool</a><a class="headerlink" href="#sancov-tool" title="Permalink to this headline">¶</a></h3>
+<p>An simple <tt class="docutils literal"><span class="pre">sancov</span></tt> 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
+<tt class="docutils literal"><span class="pre"><module_name>.<pid>.sancov</span></tt> 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 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="#id10">Coverage Reports</a><a class="headerlink" href="#coverage-reports" title="Permalink to this headline">¶</a></h3>
+<p><strong>Experimental</strong></p>
+<p><tt class="docutils literal"><span class="pre">.sancov</span></tt> 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 <tt class="docutils literal"><span class="pre">.sancov</span></tt> has to be symbolized
+to produce a <tt class="docutils literal"><span class="pre">.symcov</span></tt> file first:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">sancov -symbolize my_program.123.sancov my_program > my_program.123.symcov</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">.symcov</span></tt> file can be browsed overlayed over the source code by
+running <tt class="docutils literal"><span class="pre">tools/sancov/coverage-report-server.py</span></tt> script that will start
+an HTTP server.</p>
+</div>
+<div class="section" id="output-directory">
+<h3><a class="toc-backref" href="#id11">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 <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=coverage_dir=/path</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_dir=/tmp/cov"</span> ./a.out foo
+<span class="gp">%</span> ls -l /tmp/cov/*sancov
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="go">-rw-r----- 1 kcc eng 8 Nov 27 12:21 a.out.22679.sancov</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <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">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/SanitizerSpecialCaseList.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/SanitizerSpecialCaseList.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/SanitizerSpecialCaseList.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/SanitizerSpecialCaseList.html Thu May 10 06:54:16 2018
@@ -0,0 +1,153 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Control Flow Integrity" href="ControlFlowIntegrity.html" />
+ <link rel="prev" title="SanitizerStats" href="SanitizerStats.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Sanitizer special case list</span></h2>
+ </div>
+ <div class="topnav">
+
+ <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"><em>AddressSanitizer</em></a>, <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>
+or <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a> may want to disable or alter some checks for
+certain source-level entities to:</p>
+<ul class="simple">
+<li>speedup hot function, which is known to be correct;</li>
+<li>ignore a function that does some low-level magic (e.g. walks through the
+thread stack, bypassing the frame boundaries);</li>
+<li>ignore a known problem.</li>
+</ul>
+<p>To achieve this, user may create a file listing the entities they want to
+ignore, and pass it to clang at compile-time using
+<tt class="docutils literal"><span class="pre">-fsanitize-blacklist</span></tt> flag. See <a class="reference internal" href="UsersManual.html"><em>Clang Compiler User’s Manual</em></a> for details.</p>
+</div>
+<div class="section" id="example">
+<h2><a class="toc-backref" href="#id3">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>cat foo.c
+<span class="c">#include <stdlib.h></span>
+void bad_foo<span class="o">()</span> <span class="o">{</span>
+ int *a <span class="o">=</span> <span class="o">(</span>int*<span class="o">)</span>malloc<span class="o">(</span>40<span class="o">)</span>;
+ a<span class="o">[</span>10<span class="o">]</span> <span class="o">=</span> 1;
+<span class="o">}</span>
+int main<span class="o">()</span> <span class="o">{</span> bad_foo<span class="o">()</span>; <span class="o">}</span>
+<span class="nv">$ </span>cat blacklist.txt
+<span class="c"># Ignore reports from bad_foo function.</span>
+fun:bad_foo
+<span class="nv">$ </span>clang -fsanitize<span class="o">=</span>address foo.c ; ./a.out
+<span class="c"># AddressSanitizer prints an error report.</span>
+<span class="nv">$ </span>clang -fsanitize<span class="o">=</span>address -fsanitize-blacklist<span class="o">=</span>blacklist.txt foo.c ; ./a.out
+<span class="c"># No error report here.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="format">
+<h2><a class="toc-backref" href="#id4">Format</a><a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h2>
+<p>Each line contains an entity type, followed by a colon and a regular
+expression, specifying the names of the entities, optionally followed by
+an equals sign and a tool-specific category. Empty lines and lines starting
+with “#” are ignored. The meanining of <tt class="docutils literal"><span class="pre">*</span></tt> in regular expression for entity
+names is different - it is treated as in shell wildcarding. Two generic
+entity types are <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt>, which allow user to add, respectively,
+source files and functions to special case list. Some sanitizer tools may
+introduce custom entity types - refer to tool-specific docs.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Lines starting with # are ignored.</span>
+<span class="c"># Turn off checks for the source file (use absolute path or path relative</span>
+<span class="c"># to the current working directory):</span>
+src:/path/to/source/file.c
+<span class="c"># Turn off checks for a particular functions (use mangled names):</span>
+fun:MyFooBar
+fun:_Z8MyFooBarv
+<span class="c"># Extended regular expressions are supported:</span>
+fun:bad_<span class="o">(</span>foo|bar<span class="o">)</span>
+src:bad_source<span class="o">[</span>1-9<span class="o">]</span>.c
+<span class="c"># Shell like usage of * is supported (* is treated as .*):</span>
+src:bad/sources/*
+fun:*BadFunction*
+<span class="c"># Specific sanitizer tools may introduce categories.</span>
+src:/special/path/*<span class="o">=</span>special_sources
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="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">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/SanitizerStats.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/SanitizerStats.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/SanitizerStats.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/SanitizerStats.html Thu May 10 06:54:16 2018
@@ -0,0 +1,134 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Sanitizer special case list" href="SanitizerSpecialCaseList.html" />
+ <link rel="prev" title="SanitizerCoverage" href="SanitizerCoverage.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>SanitizerStats</span></h2>
+ </div>
+ <div class="topnav">
+
+ <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"><em>Control Flow Integrity</em></a>.
+In addition to <tt class="docutils literal"><span class="pre">-fsanitize=cfi*</span></tt>, pass the <tt class="docutils literal"><span class="pre">-fsanitize-stats</span></tt> 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 <tt class="docutils literal"><span class="pre">SANITIZER_STATS_PATH</span></tt> 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><tt class="docutils literal"><span class="pre">%b</span></tt> – The executable basename.</li>
+<li><tt class="docutils literal"><span class="pre">%p</span></tt> – The process ID.</li>
+</ul>
+</div></blockquote>
+<p>You can also send the <tt class="docutils literal"><span class="pre">SIGUSR2</span></tt> signal to a process to make it write
+sanitizer statistics immediately.</p>
+<p>The <tt class="docutils literal"><span class="pre">sanstats</span></tt> 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 <tt class="docutils literal"><span class="pre">-fsanitize-stats</span></tt>.</p>
+<p>The output of <tt class="docutils literal"><span class="pre">sanstats</span></tt> 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 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">
+
+ <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">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/SourceBasedCodeCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/SourceBasedCodeCoverage.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/SourceBasedCodeCoverage.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/SourceBasedCodeCoverage.html Thu May 10 06:54:16 2018
@@ -0,0 +1,346 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Modules" href="Modules.html" />
+ <link rel="prev" title="SafeStack" href="SafeStack.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Source-based Code Coverage</span></h2>
+ </div>
+ <div class="topnav">
+
+ <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"><em>SanitizerCoverage</em></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 <tt class="docutils literal"><span class="pre">-ftest-coverage</span></tt> or <tt class="docutils literal"><span class="pre">--coverage</span></tt>.</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 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 <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span>
+<span class="pre">-fcoverage-mapping</span></tt> to the compiler:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 1: 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 <tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt>
+environment variable. If that variable does not exist, the profile is written
+to <tt class="docutils literal"><span class="pre">default.profraw</span></tt> in the current directory of the program. If
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> 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 <tt class="docutils literal"><span class="pre">N</span> <span class="pre">=</span> <span class="pre">1</span></tt>. 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 class="gp">#</span> Step 2: 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 <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt>
+(which can combine multiple raw profiles and index them at the same time):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 3<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 class="gp">#</span> Step 3<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 <tt class="docutils literal"><span class="pre">foo<int>(...)</span></tt> and <tt class="docutils literal"><span class="pre">foo<float>(...)</span></tt>. If
+<tt class="docutils literal"><span class="pre">-show-line-counts-or-regions</span></tt> is enabled, <tt class="docutils literal"><span class="pre">llvm-cov</span></tt> displays sub-line
+region counts (even in macro expansions):</p>
+<div class="highlight-none"><div class="highlight"><pre> 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 class="gp">#</span> Step 3<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 <tt class="docutils literal"><span class="pre">llvm-cov</span></tt> 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 <tt class="docutils literal"><span class="pre">-sparse</span></tt> 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 <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> 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 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 <tt class="docutils literal"><span class="pre">llvm-cov</span> <span class="pre">export</span></tt>
+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 <tt class="docutils literal"><span class="pre">int</span> <span class="pre">__llvm_profile_runtime</span></tt> 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 <tt class="docutils literal"><span class="pre">void</span> <span class="pre">__llvm_profile_initialize_file(void)</span></tt> and call it
+once from each instrumented executable. This function parses
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt>, 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 <tt class="docutils literal"><span class="pre">void</span> <span class="pre">__llvm_profile_set_filename(char</span>
+<span class="pre">*)</span></tt>. These calls can be placed anywhere so long as they precede all calls
+to <tt class="docutils literal"><span class="pre">__llvm_profile_write_file</span></tt>.</li>
+<li>Forward-declare <tt class="docutils literal"><span class="pre">int</span> <span class="pre">__llvm_profile_write_file(void)</span></tt> 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 <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></tt>.</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
+<tt class="docutils literal"><span class="pre">-DLLVM_BUILD_INSTRUMENTED_COVERAGE=On</span></tt> to the cmake configuration. Raw
+profiles will be written to <tt class="docutils literal"><span class="pre">$BUILD_DIR/profiles/</span></tt>. To prepare an html
+report, run <tt class="docutils literal"><span class="pre">llvm/utils/prepare-code-coverage-artifact.py</span></tt>.</p>
+<p>To specify an alternate directory for raw profiles, use
+<tt class="docutils literal"><span class="pre">-DLLVM_PROFILE_DATA_DIR</span></tt>. To change the size of the profile merge pool, use
+<tt class="docutils literal"><span class="pre">-DLLVM_PROFILE_MERGE_POOL_SIZE</span></tt>.</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 <tt class="docutils literal"><span class="pre">-fcoverage-mapping</span></tt> in its <tt class="docutils literal"><span class="pre">--gc-sections</span></tt> mode. Possible
+workarounds include disabling <tt class="docutils literal"><span class="pre">--gc-sections</span></tt>, 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 class="kt">int</span> <span class="n">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 <tt class="docutils literal"><span class="pre">may_throw()</span></tt> propagates an exception into <tt class="docutils literal"><span class="pre">f</span></tt>, the code
+coverage tool may mark the <tt class="docutils literal"><span class="pre">return</span></tt> statement as executed even though it is
+not. A call to <tt class="docutils literal"><span class="pre">longjmp()</span></tt> can have similar effects.</p>
+</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <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">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/ThinLTO.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/ThinLTO.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/ThinLTO.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/ThinLTO.html Thu May 10 06:54:16 2018
@@ -0,0 +1,279 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Clang âmanâ pages" href="CommandGuide/index.html" />
+ <link rel="prev" title="MSVC compatibility" href="MSVCCompatibility.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>ThinLTO</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="MSVCCompatibility.html">MSVC compatibility</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 (ELF only).</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 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>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 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 <tt class="docutils literal"><span class="pre">-DLLVM_BINUTILS_INCDIR</span></tt> 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
+<tt class="docutils literal"><span class="pre">std::thread::hardware_concurrency</span></tt> 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 <tt class="docutils literal"><span class="pre">N</span></tt> via:</p>
+<ul class="simple">
+<li>gold:
+<tt class="docutils literal"><span class="pre">-Wl,-plugin-opt,jobs=N</span></tt></li>
+<li>ld64:
+<tt class="docutils literal"><span class="pre">-Wl,-mllvm,-threads=N</span></tt></li>
+<li>lld:
+<tt class="docutils literal"><span class="pre">-Wl,--thinlto-jobs=N</span></tt></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 r279883):
+<tt class="docutils literal"><span class="pre">-Wl,-plugin-opt,cache-dir=/path/to/cache</span></tt></li>
+<li>ld64 (support in clang 3.9 and Xcode 8):
+<tt class="docutils literal"><span class="pre">-Wl,-cache_path_lto,/path/to/cache</span></tt></li>
+<li>lld (as of LLVM r296702):
+<tt class="docutils literal"><span class="pre">-Wl,--thinlto-cache-dir=/path/to/cache</span></tt></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 ld64 and ELF lld, but currently only
+ELF lld allows you to control the policy with a policy string. The cache
+policy must be specified with a linker option.</p>
+<ul class="simple">
+<li>ELF lld (as of LLVM r298036):
+<tt class="docutils literal"><span class="pre">-Wl,--thinlto-cache-policy,POLICY</span></tt></li>
+</ul>
+<p>A policy string is a series of key-value pairs separated by <tt class="docutils literal"><span class="pre">:</span></tt> characters.
+Possible key-value pairs are:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">cache_size=X%</span></tt>: The maximum size for the cache directory is <tt class="docutils literal"><span class="pre">X</span></tt> 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"><tt class="docutils literal"><span class="pre">cache_size_bytes=X</span></tt>, <tt class="docutils literal"><span class="pre">cache_size_bytes=Xk</span></tt>, <tt class="docutils literal"><span class="pre">cache_size_bytes=Xm</span></tt>,
+<tt class="docutils literal"><span class="pre">cache_size_bytes=Xg</span></tt>:
+Sets the maximum size for the cache directory to <tt class="docutils literal"><span class="pre">X</span></tt> 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
+<tt class="docutils literal"><span class="pre">cache_size_bytes=1g</span></tt> on its own will cause both the 1GB and default 75%
+policies to be applied unless the default <tt class="docutils literal"><span class="pre">cache_size</span></tt> is overridden.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">prune_after=Xs</span></tt>, <tt class="docutils literal"><span class="pre">prune_after=Xm</span></tt>, <tt class="docutils literal"><span class="pre">prune_after=Xh</span></tt>: Sets the
+expiration time for cache files to <tt class="docutils literal"><span class="pre">X</span></tt> seconds (or minutes, hours
+respectively). When a file hasn’t been accessed for <tt class="docutils literal"><span class="pre">prune_after</span></tt> 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"><tt class="docutils literal"><span class="pre">prune_interval=Xs</span></tt>, <tt class="docutils literal"><span class="pre">prune_interval=Xm</span></tt>, <tt class="docutils literal"><span class="pre">prune_interval=Xh</span></tt>:
+Sets the pruning interval to <tt class="docutils literal"><span class="pre">X</span></tt> 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><tt class="docutils literal"><span class="pre">-DLLVM_ENABLE_LTO=Thin</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_PARALLEL_LINK_JOBS=1</span></tt>
+(since the ThinLTO link invokes parallel backend jobs)</li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_C_COMPILER=/path/to/host/clang</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_CXX_COMPILER=/path/to/host/clang++</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_RANLIB=/path/to/host/llvm-ranlib</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_AR=/path/to/host/llvm-ar</span></tt></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
+<tt class="docutils literal"><span class="pre">CMAKE_EXE_LINKER_FLAGS:STRING=</span></tt>. 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">
+
+ <p>
+ « <a href="MSVCCompatibility.html">MSVC compatibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="CommandGuide/index.html">Clang “man” pages</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/ThreadSafetyAnalysis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/ThreadSafetyAnalysis.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/ThreadSafetyAnalysis.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/ThreadSafetyAnalysis.html Thu May 10 06:54:16 2018
@@ -0,0 +1,916 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="AddressSanitizer" href="AddressSanitizer.html" />
+ <link rel="prev" title="Cross-compilation using Clang" href="CrossCompilation.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Thread Safety Analysis</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="CrossCompilation.html">Cross-compilation using Clang</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AddressSanitizer.html">AddressSanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="thread-safety-analysis">
+<h1>Thread Safety Analysis<a class="headerlink" href="#thread-safety-analysis" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang Thread Safety Analysis is a C++ language extension which warns about
+potential race conditions in code. The analysis is completely static (i.e.
+compile-time); there is no run-time overhead. The analysis is still
+under active development, but it is mature enough to be deployed in an
+industrial setting. It is being developed by Google, in collaboration with
+CERT/SEI, and is used extensively in Google’s internal code base.</p>
+<p>Thread safety analysis works very much like a type system for multi-threaded
+programs. In addition to declaring the <em>type</em> of data (e.g. <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment. For example, if <tt class="docutils literal"><span class="pre">foo</span></tt> is
+<em>guarded by</em> the mutex <tt class="docutils literal"><span class="pre">mu</span></tt>, then the analysis will issue a warning whenever
+a piece of code reads or writes to <tt class="docutils literal"><span class="pre">foo</span></tt> without first locking <tt class="docutils literal"><span class="pre">mu</span></tt>.
+Similarly, if there are particular routines that should only be called by
+the GUI thread, then the analysis will warn if other threads call those
+routines.</p>
+<div class="section" id="getting-started">
+<h3>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "mutex.h"</span>
+
+<span class="k">class</span> <span class="nc">BankAccount</span> <span class="p">{</span>
+<span class="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="n">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="n">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="n">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
+<tt class="docutils literal"><span class="pre">GUARDED_BY</span></tt> attribute declares that a thread must lock <tt class="docutils literal"><span class="pre">mu</span></tt> before it can
+read or write to <tt class="docutils literal"><span class="pre">balance</span></tt>, thus ensuring that the increment and decrement
+operations are atomic. Similarly, <tt class="docutils literal"><span class="pre">REQUIRES</span></tt> declares that
+the calling thread must lock <tt class="docutils literal"><span class="pre">mu</span></tt> before calling <tt class="docutils literal"><span class="pre">withdrawImpl</span></tt>.
+Because the caller is assumed to have locked <tt class="docutils literal"><span class="pre">mu</span></tt>, it is safe to modify
+<tt class="docutils literal"><span class="pre">balance</span></tt> within the body of the method.</p>
+<p>The <tt class="docutils literal"><span class="pre">depositImpl()</span></tt> method does not have <tt class="docutils literal"><span class="pre">REQUIRES</span></tt>, so the
+analysis issues a warning. Thread safety analysis is not inter-procedural, so
+caller requirements must be explicitly declared.
+There is also a warning in <tt class="docutils literal"><span class="pre">transferFrom()</span></tt>, because although the method
+locks <tt class="docutils literal"><span class="pre">this->mu</span></tt>, it does not lock <tt class="docutils literal"><span class="pre">b.mu</span></tt>. The analysis understands
+that these are two separate mutexes, in two different objects.</p>
+<p>Finally, there is a warning in the <tt class="docutils literal"><span class="pre">withdraw()</span></tt> method, because it fails to
+unlock <tt class="docutils literal"><span class="pre">mu</span></tt>. Every lock must have a corresponding unlock, and the analysis
+will detect both double locks, and double unlocks. A function is allowed to
+acquire a lock without releasing it, (or vice versa), but it must be annotated
+as such (using <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt>/<tt class="docutils literal"><span class="pre">RELEASE</span></tt>).</p>
+</div>
+<div class="section" id="running-the-analysis">
+<h3>Running The Analysis<a class="headerlink" href="#running-the-analysis" title="Permalink to this headline">¶</a></h3>
+<p>To run the analysis, simply compile with the <tt class="docutils literal"><span class="pre">-Wthread-safety</span></tt> flag, e.g.</p>
+<div class="highlight-bash"><div class="highlight"><pre>clang -c -Wthread-safety example.cpp
+</pre></div>
+</div>
+<p>Note that this example assumes the presence of a suitably annotated
+<a class="reference internal" href="#mutexheader"><em>mutex.h</em></a> that declares which methods perform locking,
+unlocking, and so on.</p>
+</div>
+</div>
+<div class="section" id="basic-concepts-capabilities">
+<h2>Basic Concepts: Capabilities<a class="headerlink" href="#basic-concepts-capabilities" title="Permalink to this headline">¶</a></h2>
+<p>Thread safety analysis provides a way of protecting <em>resources</em> with
+<em>capabilities</em>. A resource is either a data member, or a function/method
+that provides access to some underlying resource. The analysis ensures that
+the calling thread cannot access the <em>resource</em> (i.e. call the function, or
+read/write the data) unless it has the <em>capability</em> to do so.</p>
+<p>Capabilities are associated with named C++ objects which declare specific
+methods to acquire and release the capability. The name of the object serves
+to identify the capability. The most common example is a mutex. For example,
+if <tt class="docutils literal"><span class="pre">mu</span></tt> is a mutex, then calling <tt class="docutils literal"><span class="pre">mu.Lock()</span></tt> causes the calling thread
+to acquire the capability to access data that is protected by <tt class="docutils literal"><span class="pre">mu</span></tt>. Similarly,
+calling <tt class="docutils literal"><span class="pre">mu.Unlock()</span></tt> releases that capability.</p>
+<p>A thread may hold a capability either <em>exclusively</em> or <em>shared</em>. An exclusive
+capability can be held by only one thread at a time, while a shared capability
+can be held by many threads at the same time. This mechanism enforces a
+multiple-reader, single-writer pattern. Write operations to protected data
+require exclusive access, while read operations require only shared access.</p>
+<p>At any given moment during program execution, a thread holds a specific set of
+capabilities (e.g. the set of mutexes that it has locked.) These act like keys
+or tokens that allow the thread to access a given resource. Just like physical
+security keys, a thread cannot make copy of a capability, nor can it destroy
+one. A thread can only release a capability to another thread, or acquire one
+from another thread. The annotations are deliberately agnostic about the
+exact mechanism used to acquire and release capabilities; it assumes that the
+underlying implementation (e.g. the Mutex implementation) does the handoff in
+an appropriate manner.</p>
+<p>The set of capabilities that are actually held by a given thread at a given
+point in program execution is a run-time concept. The static analysis works
+by calculating an approximation of that set, called the <em>capability
+environment</em>. The capability environment is calculated for every program point,
+and describes the set of capabilities that are statically known to be held, or
+not held, at that particular point. This environment is a conservative
+approximation of the full set of capabilities that will actually held by a
+thread at run-time.</p>
+</div>
+<div class="section" id="reference-guide">
+<h2>Reference Guide<a class="headerlink" href="#reference-guide" title="Permalink to this headline">¶</a></h2>
+<p>The thread safety analysis uses attributes to declare threading constraints.
+Attributes must be attached to named declarations, such as classes, methods,
+and data members. Users are <em>strongly advised</em> to define macros for the various
+attributes; example definitions can be found in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below.
+The following documentation assumes the use of macros.</p>
+<p>For historical reasons, prior versions of thread safety used macro names that
+were very lock-centric. These macros have since been renamed to fit a more
+general capability model. The prior names are still in use, and will be
+mentioned under the tag <em>previously</em> where appropriate.</p>
+<div class="section" id="guarded-by-c-and-pt-guarded-by-c">
+<h3>GUARDED_BY(c) and PT_GUARDED_BY(c)<a class="headerlink" href="#guarded-by-c-and-pt-guarded-by-c" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">GUARDED_BY</span></tt> is an attribute on data members, which declares that the data
+member is protected by the given capability. Read operations on the data
+require shared access, while write operations require exclusive access.</p>
+<p><tt class="docutils literal"><span class="pre">PT_GUARDED_BY</span></tt> is similar, but is intended for use on pointers and smart
+pointers. There is no constraint on the data member itself, but the <em>data that
+it points to</em> is protected by the given capability.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">int</span> <span class="o">*</span><span class="n">p1</span> <span class="n">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="n">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="n">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">p1</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// Warning!</span>
+
+ <span class="o">*</span><span class="n">p2</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// Warning!</span>
+ <span class="n">p2</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">int</span><span class="p">;</span> <span class="c1">// OK.</span>
+
+ <span class="o">*</span><span class="n">p3</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// Warning!</span>
+ <span class="n">p3</span><span class="p">.</span><span class="n">reset</span><span class="p">(</span><span class="k">new</span> <span class="kt">int</span><span class="p">);</span> <span class="c1">// OK.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="requires-requires-shared">
+<h3>REQUIRES(...), REQUIRES_SHARED(...)<a class="headerlink" href="#requires-requires-shared" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">EXCLUSIVE_LOCKS_REQUIRED</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_LOCKS_REQUIRED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">REQUIRES</span></tt> is an attribute on functions or methods, which
+declares that the calling thread must have exclusive access to the given
+capabilities. More than one capability may be specified. The capabilities
+must be held on entry to the function, <em>and must still be held on exit</em>.</p>
+<p><tt class="docutils literal"><span class="pre">REQUIRES_SHARED</span></tt> is similar, but requires only shared access.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu1</span><span class="p">,</span> <span class="n">mu2</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">a</span> <span class="n">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="n">GUARDED_BY</span><span class="p">(</span><span class="n">mu2</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="n">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="n">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu1</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// Warning! Requires mu2.</span>
+ <span class="n">mu1</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="acquire-acquire-shared-release-release-shared">
+<h3>ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...)<a class="headerlink" href="#acquire-acquire-shared-release-release-shared" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">EXCLUSIVE_LOCK_FUNCTION</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_LOCK_FUNCTION</span></tt>,
+<tt class="docutils literal"><span class="pre">UNLOCK_FUNCTION</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">ACQUIRE</span></tt> is an attribute on functions or methods, which
+declares that the function acquires a capability, but does not release it. The
+caller must not hold the given capability on entry, and it will hold the
+capability on exit. <tt class="docutils literal"><span class="pre">ACQUIRE_SHARED</span></tt> is similar.</p>
+<p><tt class="docutils literal"><span class="pre">RELEASE</span></tt> and <tt class="docutils literal"><span class="pre">RELEASE_SHARED</span></tt> declare that the function releases the given
+capability. The caller must hold the capability on entry, and will no longer
+hold it on exit. It does not matter whether the given capability is shared or
+exclusive.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="n">MyClass</span> <span class="n">myObject</span> <span class="n">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="n">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="n">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="n">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">lockAndInit</span><span class="p">();</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+ <span class="n">cleanupAndUnlock</span><span class="p">();</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span> <span class="c1">// Warning, mu is not locked.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If no argument is passed to <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt> or <tt class="docutils literal"><span class="pre">RELEASE</span></tt>, then the argument is
+assumed to be <tt class="docutils literal"><span class="pre">this</span></tt>, and the analysis will not check the body of the
+function. This pattern is intended for use by classes which hide locking
+details behind an abstract interface. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">CAPABILITY</span><span class="p">(</span><span class="s">"mutex"</span><span class="p">)</span> <span class="n">Container</span> <span class="p">{</span>
+<span class="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="n">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">Container</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">c</span><span class="p">;</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">c</span><span class="p">.</span><span class="n">getElem</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="excludes">
+<h3>EXCLUDES(...)<a class="headerlink" href="#excludes" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCKS_EXCLUDED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">EXCLUDES</span></tt> is an attribute on functions or methods, which declares that
+the caller must <em>not</em> hold the given capabilities. This annotation is
+used to prevent deadlock. Many mutex implementations are not re-entrant, so
+deadlock can occur if the function acquires the mutex a second time.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">a</span> <span class="n">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="n">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="n">reset</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">clear</span><span class="p">();</span> <span class="c1">// Warning! Caller cannot hold 'mu'.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Unlike <tt class="docutils literal"><span class="pre">REQUIRES</span></tt>, <tt class="docutils literal"><span class="pre">EXCLUDES</span></tt> is optional. The analysis will not issue a
+warning if the attribute is missing, which can lead to false negatives in some
+cases. This issue is discussed further in <a class="reference internal" href="#negative"><em>Negative Capabilities</em></a>.</p>
+</div>
+<div class="section" id="no-thread-safety-analysis">
+<h3>NO_THREAD_SAFETY_ANALYSIS<a class="headerlink" href="#no-thread-safety-analysis" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></tt> is an attribute on functions or methods, which
+turns off thread safety checking for that method. It provides an escape hatch
+for functions which are either (1) deliberately thread-unsafe, or (2) are
+thread-safe, but too complicated for the analysis to understand. Reasons for
+(2) will be described in the <a class="reference internal" href="#limitations"><em>Known Limitations</em></a>, below.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Counter</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">a</span> <span class="n">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="n">unsafeIncrement</span><span class="p">()</span> <span class="n">NO_THREAD_SAFETY_ANALYSIS</span> <span class="p">{</span> <span class="n">a</span><span class="o">++</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Unlike the other attributes, NO_THREAD_SAFETY_ANALYSIS is not part of the
+interface of a function, and should thus be placed on the function definition
+(in the <tt class="docutils literal"><span class="pre">.cc</span></tt> or <tt class="docutils literal"><span class="pre">.cpp</span></tt> file) rather than on the function declaration
+(in the header).</p>
+</div>
+<div class="section" id="return-capability-c">
+<h3>RETURN_CAPABILITY(c)<a class="headerlink" href="#return-capability-c" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCK_RETURNED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></tt> is an attribute on functions or methods, which declares
+that the function returns a reference to the given capability. It is used to
+annotate getter methods that return mutexes.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="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="n">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><tt class="docutils literal"><span class="pre">ACQUIRED_BEFORE</span></tt> and <tt class="docutils literal"><span class="pre">ACQUIRED_AFTER</span></tt> are attributes on member
+declarations, specifically declarations of mutexes or other capabilities.
+These declarations enforce a particular order in which the mutexes must be
+acquired, in order to prevent deadlock.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">m1</span><span class="p">;</span>
+<span class="n">Mutex</span> <span class="n">m2</span> <span class="n">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="n">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">m2</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">m1</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span> <span class="c1">// Warning! m2 must be acquired after m1.</span>
+ <span class="n">m1</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="n">m2</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="capability-string">
+<h3>CAPABILITY(<string>)<a class="headerlink" href="#capability-string" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCKABLE</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">CAPABILITY</span></tt> is an attribute on classes, which specifies that objects of the
+class can be used as a capability. The string argument specifies the kind of
+capability in error messages, e.g. <tt class="docutils literal"><span class="pre">"mutex"</span></tt>. See the <tt class="docutils literal"><span class="pre">Container</span></tt> example
+given above, or the <tt class="docutils literal"><span class="pre">Mutex</span></tt> class in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>.</p>
+</div>
+<div class="section" id="scoped-capability">
+<h3>SCOPED_CAPABILITY<a class="headerlink" href="#scoped-capability" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">SCOPED_LOCKABLE</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">SCOPED_CAPABILITY</span></tt> is an attribute on classes that implement RAII-style
+locking, in which a capability is acquired in the constructor, and released in
+the destructor. Such classes require special handling because the constructor
+and destructor refer to the capability via different names; see the
+<tt class="docutils literal"><span class="pre">MutexLocker</span></tt> class in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below.</p>
+</div>
+<div class="section" id="try-acquire-bool-try-acquire-shared-bool">
+<h3>TRY_ACQUIRE(<bool>, ...), TRY_ACQUIRE_SHARED(<bool>, ...)<a class="headerlink" href="#try-acquire-bool-try-acquire-shared-bool" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously:</em> <tt class="docutils literal"><span class="pre">EXCLUSIVE_TRYLOCK_FUNCTION</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_TRYLOCK_FUNCTION</span></tt></p>
+<p>These are attributes on a function or method that tries to acquire the given
+capability, and returns a boolean value indicating success or failure.
+The first argument must be <tt class="docutils literal"><span class="pre">true</span></tt> or <tt class="docutils literal"><span class="pre">false</span></tt>, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt>. See <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below, for example uses.</p>
+</div>
+<div class="section" id="assert-capability-and-assert-shared-capability">
+<h3>ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...)<a class="headerlink" href="#assert-capability-and-assert-shared-capability" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously:</em> <tt class="docutils literal"><span class="pre">ASSERT_EXCLUSIVE_LOCK</span></tt>, <tt class="docutils literal"><span class="pre">ASSERT_SHARED_LOCK</span></tt></p>
+<p>These are attributes on a function or method that does a run-time test to see
+whether the calling thread holds the given capability. The function is assumed
+to fail (no return) if the capability is not held. See <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>,
+below, for example uses.</p>
+</div>
+<div class="section" id="guarded-var-and-pt-guarded-var">
+<h3>GUARDED_VAR and PT_GUARDED_VAR<a class="headerlink" href="#guarded-var-and-pt-guarded-var" title="Permalink to this headline">¶</a></h3>
+<p>Use of these attributes has been deprecated.</p>
+</div>
+<div class="section" id="warning-flags">
+<h3>Warning flags<a class="headerlink" href="#warning-flags" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety</span></tt>: Umbrella flag which turns on the following three:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-attributes</span></tt>: Sanity checks on attribute syntax.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-analysis</span></tt>: The core analysis.</p>
+</li>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal"><span class="pre">-Wthread-safety-precise</span></tt>: Requires that mutex expressions match precisely.</dt>
+<dd><p class="first last">This warning can be disabled for code which has a lot of aliases.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-reference</span></tt>: Checks when guarded members are passed by reference.</p>
+</li>
+</ul>
+</li>
+</ul>
+<p><a class="reference internal" href="#negative"><em>Negative Capabilities</em></a> are an experimental feature, which are enabled with:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wthread-safety-negative</span></tt>: Negative capabilities. Off by default.</li>
+</ul>
+<p>When new features and checks are added to the analysis, they can often introduce
+additional warnings. Those warnings are initially released as <em>beta</em> warnings
+for a period of time, after which they are migrated into the standard analysis.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wthread-safety-beta</span></tt>: New features. Off by default.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="negative-capabilities">
+<span id="negative"></span><h2>Negative Capabilities<a class="headerlink" href="#negative-capabilities" title="Permalink to this headline">¶</a></h2>
+<p>Thread Safety Analysis is designed to prevent both race conditions and
+deadlock. The GUARDED_BY and REQUIRES attributes prevent race conditions, by
+ensuring that a capability is held before reading or writing to guarded data,
+and the EXCLUDES attribute prevents deadlock, by making sure that a mutex is
+<em>not</em> held.</p>
+<p>However, EXCLUDES is an optional attribute, and does not provide the same
+safety guarantee as REQUIRES. In particular:</p>
+<blockquote>
+<div><ul class="simple">
+<li>A function which acquires a capability does not have to exclude it.</li>
+<li>A function which calls a function that excludes a capability does not
+have transitively exclude that capability.</li>
+</ul>
+</div></blockquote>
+<p>As a result, EXCLUDES can easily produce false negatives:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+ <span class="kt">void</span> <span class="n">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="n">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="n">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="n">bif</span><span class="p">()</span> <span class="n">EXCLUDES</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Negative requirements are an alternative EXCLUDES that provide
+a stronger safety guarantee. A negative requirement uses the REQUIRES
+attribute, in conjunction with the <tt class="docutils literal"><span class="pre">!</span></tt> operator, to indicate that a capability
+should <em>not</em> be held.</p>
+<p>For example, using <tt class="docutils literal"><span class="pre">REQUIRES(!mu)</span></tt> instead of <tt class="docutils literal"><span class="pre">EXCLUDES(mu)</span></tt> will produce
+the appropriate warnings:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">FooNeg</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+ <span class="kt">void</span> <span class="n">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="n">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="n">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="n">bif</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="o">!</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Negative requirements are an experimental feature which is off by default,
+because it will produce many warnings in existing code. It can be enabled
+by passing <tt class="docutils literal"><span class="pre">-Wthread-safety-negative</span></tt>.</p>
+</div>
+<div class="section" id="frequently-asked-questions">
+<span id="faq"></span><h2>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h2>
+<ol class="upperalpha simple" start="17">
+<li>Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?</li>
+</ol>
+<p>(A) Attributes are part of the formal interface of a function, and should
+always go in the header, where they are visible to anything that includes
+the header. Attributes in the .cpp file are not visible outside of the
+immediate translation unit, which leads to false negatives and false positives.</p>
+<ol class="upperalpha simple" start="17">
+<li>“<em>Mutex is not locked on every path through here?</em>” What does that mean?</li>
+</ol>
+<ol class="upperalpha simple">
+<li>See <a class="reference internal" href="#conditional-locks"><em>No conditionally held locks.</em></a>, below.</li>
+</ol>
+</div>
+<div class="section" id="known-limitations">
+<span id="limitations"></span><h2>Known Limitations<a class="headerlink" href="#known-limitations" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="lexical-scope">
+<h3>Lexical scope<a class="headerlink" href="#lexical-scope" title="Permalink to this headline">¶</a></h3>
+<p>Thread safety attributes contain ordinary C++ expressions, and thus follow
+ordinary C++ scoping rules. In particular, this means that mutexes and other
+capabilities must be declared before they can be used in an attribute.
+Use-before-declaration is okay within a single class, because attributes are
+parsed at the same time as method bodies. (C++ delays parsing of method bodies
+until the end of the class.) However, use-before-declaration is not allowed
+between classes, as illustrated below.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span><span class="p">;</span>
+
+<span class="k">class</span> <span class="nc">Bar</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">bar</span><span class="p">(</span><span class="n">Foo</span><span class="o">*</span> <span class="n">f</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">f</span><span class="o">-></span><span class="n">mu</span><span class="p">);</span> <span class="c1">// Error: mu undeclared.</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="private-mutexes">
+<h3>Private Mutexes<a class="headerlink" href="#private-mutexes" title="Permalink to this headline">¶</a></h3>
+<p>Good software engineering practice dictates that mutexes should be private
+members, because the locking mechanism used by a thread-safe class is part of
+its internal implementation. However, private mutexes can sometimes leak into
+the public interface of a class.
+Thread safety attributes follow normal C++ access restrictions, so if <tt class="docutils literal"><span class="pre">mu</span></tt>
+is a private member of <tt class="docutils literal"><span class="pre">c</span></tt>, then it is an error to write <tt class="docutils literal"><span class="pre">c.mu</span></tt> in an
+attribute.</p>
+<p>One workaround is to (ab)use the <tt class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></tt> attribute to provide a
+public <em>name</em> for a private mutex, without actually exposing the underlying
+mutex. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="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="n">doSomethingTwice</span><span class="p">(</span><span class="n">MyClass</span><span class="o">&</span> <span class="n">c</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">c</span><span class="p">.</span><span class="n">getMu</span><span class="p">())</span> <span class="p">{</span>
+ <span class="c1">// The analysis thinks that c.getMu() == c.mu</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In the above example, <tt class="docutils literal"><span class="pre">doSomethingTwice()</span></tt> is an external routine that
+requires <tt class="docutils literal"><span class="pre">c.mu</span></tt> to be locked, which cannot be declared directly because <tt class="docutils literal"><span class="pre">mu</span></tt>
+is private. This pattern is discouraged because it
+violates encapsulation, but it is sometimes necessary, especially when adding
+annotations to an existing code base. The workaround is to define <tt class="docutils literal"><span class="pre">getMu()</span></tt>
+as a fake getter method, which is provided only for the benefit of thread
+safety analysis.</p>
+</div>
+<div class="section" id="no-conditionally-held-locks">
+<span id="conditional-locks"></span><h3>No conditionally held locks.<a class="headerlink" href="#no-conditionally-held-locks" title="Permalink to this headline">¶</a></h3>
+<p>The analysis must be able to determine whether a lock is held, or not held, at
+every program point. Thus, sections of code where a lock <em>might be held</em> will
+generate spurious warnings (false positives). For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="kt">bool</span> <span class="n">b</span> <span class="o">=</span> <span class="n">needsToLock</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="p">...</span> <span class="c1">// Warning! Mutex 'mu' is not held on every path through here.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="no-checking-inside-constructors-and-destructors">
+<h3>No checking inside constructors and destructors.<a class="headerlink" href="#no-checking-inside-constructors-and-destructors" title="Permalink to this headline">¶</a></h3>
+<p>The analysis currently does not do any checking inside constructors or
+destructors. In other words, every constructor and destructor is treated as
+if it was annotated with <tt class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></tt>.
+The reason for this is that during initialization, only one thread typically
+has access to the object which is being initialized, and it is thus safe (and
+common practice) to initialize guarded members without acquiring any locks.
+The same is true of destructors.</p>
+<p>Ideally, the analysis would allow initialization of guarded members inside the
+object being initialized or destroyed, while still enforcing the usual access
+restrictions on everything else. However, this is difficult to enforce in
+practice, because in complex pointer-based data structures, it is hard to
+determine what data is owned by the enclosing object.</p>
+</div>
+<div class="section" id="no-inlining">
+<h3>No inlining.<a class="headerlink" href="#no-inlining" title="Permalink to this headline">¶</a></h3>
+<p>Thread safety analysis is strictly intra-procedural, just like ordinary type
+checking. It relies only on the declared attributes of a function, and will
+not attempt to inline any method calls. As a result, code such as the
+following will not work:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">AutoCleanup</span> <span class="p">{</span>
+ <span class="n">T</span><span class="o">*</span> <span class="n">object</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="n">T</span><span class="o">::*</span><span class="n">mp</span><span class="p">)();</span>
+
+<span class="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="n">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">AutoCleanup</span><span class="o"><</span><span class="n">Mutex</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">mu</span><span class="p">,</span> <span class="o">&</span><span class="n">Mutex</span><span class="o">::</span><span class="n">Unlock</span><span class="p">);</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span> <span class="c1">// Warning, mu is not unlocked.</span>
+</pre></div>
+</div>
+<p>In this case, the destructor of <tt class="docutils literal"><span class="pre">Autocleanup</span></tt> calls <tt class="docutils literal"><span class="pre">mu.Unlock()</span></tt>, so
+the warning is bogus. However,
+thread safety analysis cannot see the unlock, because it does not attempt to
+inline the destructor. Moreover, there is no way to annotate the destructor,
+because the destructor is calling a function that is not statically known.
+This pattern is simply not supported.</p>
+</div>
+<div class="section" id="no-alias-analysis">
+<h3>No alias analysis.<a class="headerlink" href="#no-alias-analysis" title="Permalink to this headline">¶</a></h3>
+<p>The analysis currently does not track pointer aliases. Thus, there can be
+false positives if two pointers both point to the same mutex.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MutexUnlocker</span> <span class="p">{</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="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="n">test</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mutex</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">{</span>
+ <span class="n">MutexUnlocker</span> <span class="n">munl</span><span class="p">(</span><span class="o">&</span><span class="n">mutex</span><span class="p">);</span> <span class="c1">// unlocks mutex</span>
+ <span class="n">doSomeIO</span><span class="p">();</span>
+ <span class="p">}</span> <span class="c1">// Warning: locks munl.mu</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The MutexUnlocker class is intended to be the dual of the MutexLocker class,
+defined in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>. However, it doesn’t work because the analysis
+doesn’t know that munl.mu == mutex. The SCOPED_CAPABILITY attribute handles
+aliasing for MutexLocker, but does so only for that particular pattern.</p>
+</div>
+<div class="section" id="acquired-before-and-acquired-after-are-currently-unimplemented">
+<h3>ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.<a class="headerlink" href="#acquired-before-and-acquired-after-are-currently-unimplemented" title="Permalink to this headline">¶</a></h3>
+<p>To be fixed in a future update.</p>
+</div>
+</div>
+<div class="section" id="mutex-h">
+<span id="mutexheader"></span><h2>mutex.h<a class="headerlink" href="#mutex-h" title="Permalink to this headline">¶</a></h2>
+<p>Thread safety analysis can be used with any threading library, but it does
+require that the threading API be wrapped in classes and methods which have the
+appropriate annotations. The following code provides <tt class="docutils literal"><span class="pre">mutex.h</span></tt> as an example;
+these methods should be filled in to call the appropriate underlying
+implementation.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+<span class="cp">#define THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+
+<span class="cp">// Enable thread safety attributes only with clang.</span>
+<span class="cp">// 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="nc">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="kc">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="kc">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="cp">// The original version of thread safety analysis the following attribute</span>
+<span class="cp">// definitions. These use a lock-based terminology. They are still in use</span>
+<span class="cp">// by existing thread safety code, and will continue to be supported.</span>
+
+<span class="cp">// Deprecated.</span>
+<span class="cp">#define PT_GUARDED_VAR \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_var)</span>
+
+<span class="cp">// Deprecated.</span>
+<span class="cp">#define GUARDED_VAR \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(guarded_var)</span>
+
+<span class="cp">// 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="cp">// 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="cp">// Replaced by CAPABILITY</span>
+<span class="cp">#define LOCKABLE \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(lockable)</span>
+
+<span class="cp">// Replaced by SCOPED_CAPABILITY</span>
+<span class="cp">#define SCOPED_LOCKABLE \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)</span>
+
+<span class="cp">// 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="cp">// 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="cp">// 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="cp">// 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="cp">// 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="cp">// 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="cp">// 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="cp">// 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="cp">// Replaced by RETURN_CAPABILITY</span>
+<span class="cp">#define LOCK_RETURNED(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))</span>
+
+<span class="cp">#endif </span><span class="c1">// USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES</span>
+
+<span class="cp">#endif </span><span class="c1">// THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="CrossCompilation.html">Cross-compilation using Clang</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AddressSanitizer.html">AddressSanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/ThreadSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/ThreadSanitizer.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/ThreadSanitizer.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/ThreadSanitizer.html Thu May 10 06:54:16 2018
@@ -0,0 +1,196 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="MemorySanitizer" href="MemorySanitizer.html" />
+ <link rel="prev" title="AddressSanitizer" href="AddressSanitizer.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>ThreadSanitizer</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="AddressSanitizer.html">AddressSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="MemorySanitizer.html">MemorySanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="threadsanitizer">
+<h1>ThreadSanitizer<a class="headerlink" href="#threadsanitizer" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer is a tool that detects data races. It consists of a compiler
+instrumentation module and a run-time library. Typical slowdown introduced by
+ThreadSanitizer is about <strong>5x-15x</strong>. Typical memory overhead introduced by
+ThreadSanitizer is about <strong>5x-10x</strong>.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2>How to build<a class="headerlink" href="#how-to-build" title="Permalink to this headline">¶</a></h2>
+<p>Build LLVM/Clang with <a class="reference external" href="http://llvm.org/docs/CMake.html">CMake</a>.</p>
+</div>
+<div class="section" id="supported-platforms">
+<h2>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
+Support for other 64-bit architectures is possible, contributions are welcome.
+Support for 32-bit platforms is problematic and is not planned.</p>
+</div>
+<div class="section" id="usage">
+<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>Simply compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>. To get a
+reasonable performance add <tt class="docutils literal"><span class="pre">-O1</span></tt> or higher. Use <tt class="docutils literal"><span class="pre">-g</span></tt> to get file names
+and line numbers in the warning messages.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><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
+<tt class="docutils literal"><span class="pre">addr2line</span></tt> process (this will be fixed in future).</p>
+<div class="highlight-bash"><div class="highlight"><pre>% ./a.out
+WARNING: ThreadSanitizer: data race <span class="o">(</span><span class="nv">pid</span><span class="o">=</span>19219<span class="o">)</span>
+ Write of size 4 at 0x7fcf47b21bc0 by thread T1:
+ <span class="c">#0 Thread1 tiny_race.c:4 (exe+0x00000000a360)</span>
+
+ Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
+ <span class="c">#0 main tiny_race.c:10 (exe+0x00000000a3b4)</span>
+
+ Thread T1 <span class="o">(</span>running<span class="o">)</span> created at:
+ <span class="c">#0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)</span>
+ <span class="c">#1 main tiny_race.c:9 (exe+0x00000000a3a4)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-feature-thread-sanitizer">
+<h2><tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt><a class="headerlink" href="#has-feature-thread-sanitizer" title="Permalink to this headline">¶</a></h2>
+<p>In some cases one may need to execute different code depending on whether
+ThreadSanitizer is enabled.
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>__has_feature</em></a> can be used for
+this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(__has_feature)</span>
+<span class="cp"># if __has_feature(thread_sanitizer)</span>
+<span class="cp">// code that builds only under ThreadSanitizer</span>
+<span class="cp"># endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-thread">
+<h2><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("thread")))</span></tt><a class="headerlink" href="#attribute-no-sanitize-thread" title="Permalink to this headline">¶</a></h2>
+<p>Some code should not be instrumented by ThreadSanitizer. One may use the
+function attribute <tt class="docutils literal"><span class="pre">no_sanitize("thread")</span></tt> to disable instrumentation of plain
+(non-atomic) loads/stores in a particular function. ThreadSanitizer still
+instruments such functions to avoid false positives and provide meaningful stack
+traces. This attribute may not be supported by other compilers, so we suggest
+to use it together with <tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt>.</p>
+</div>
+<div class="section" id="blacklist">
+<h2>Blacklist<a class="headerlink" href="#blacklist" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer supports <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to suppress data race reports
+in the specified source files or functions. Unlike functions marked with
+<tt class="docutils literal"><span class="pre">no_sanitize("thread")</span></tt> attribute, blacklisted functions are not instrumented
+at all. This can lead to false positives due to missed synchronization via
+atomic operations and missed stack frames in reports.</p>
+</div>
+<div class="section" id="limitations">
+<h2>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>ThreadSanitizer uses more real memory than a native run. At the default
+settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x
+(less accurate analysis) and 9x (more accurate analysis) overhead are also
+available.</li>
+<li>ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
+This means that tools like <tt class="docutils literal"><span class="pre">ulimit</span></tt> may not work as usually expected.</li>
+<li>Libc/libstdc++ static linking is not supported.</li>
+<li>Non-position-independent executables are not supported. Therefore, the
+<tt class="docutils literal"><span class="pre">fsanitize=thread</span></tt> flag will cause Clang to act as though the <tt class="docutils literal"><span class="pre">-fPIE</span></tt>
+flag had been supplied if compiling without <tt class="docutils literal"><span class="pre">-fPIC</span></tt>, and as though the
+<tt class="docutils literal"><span class="pre">-pie</span></tt> flag had been supplied if linking an executable.</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer is in beta stage. It is known to work on large C++ programs
+using pthreads, but we do not promise anything (yet). C++11 threading is
+supported with llvm libc++. The test suite is integrated into CMake build
+and can be run with <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-tsan</span></tt> command.</p>
+<p>We are actively working on enhancing the tool — stay tuned. Any help,
+especially in the form of minimized standalone tests is more than welcome.</p>
+</div>
+<div class="section" id="more-information">
+<h2>More Information<a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual">https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual</a></p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="AddressSanitizer.html">AddressSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="MemorySanitizer.html">MemorySanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/Toolchain.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/Toolchain.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/Toolchain.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/Toolchain.html Thu May 10 06:54:16 2018
@@ -0,0 +1,389 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.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>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Assembling a Complete Toolchain</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="UsersManual.html">Clang Compiler User’s Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="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 <tt class="docutils literal"><span class="pre">clang</span></tt> driver. When
+targeting Windows with the MSVC-compatible <tt class="docutils literal"><span class="pre">clang-cl</span></tt> 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 <tt class="docutils literal"><span class="pre">-E</span></tt> 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"><em>precompiled header (PCH)</em></a>,
+preamble, or
+<a class="reference internal" href="Modules.html"><em>precompiled module file (PCM)</em></a>,
+depending on the input.
+The <tt class="docutils literal"><span class="pre">-precompile</span></tt> 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 <tt class="docutils literal"><span class="pre">-emit-llvm</span></tt> flag instructs Clang to stop after this step. If combined
+with <tt class="docutils literal"><span class="pre">-S</span></tt>, 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 <tt class="docutils literal"><span class="pre">-S</span></tt> 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 <tt class="docutils literal"><span class="pre">-c</span></tt> 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 <tt class="docutils literal"><span class="pre">.s</span></tt> file input will be assembled and linked).</p>
+<p>The Clang driver can be invoked with the <tt class="docutils literal"><span class="pre">-###</span></tt> 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 <tt class="docutils literal"><span class="pre">-v</span></tt> (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 (<tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>) 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 (<tt class="docutils literal"><span class="pre">-x</span> <span class="pre">ada</span></tt>, <tt class="docutils literal"><span class="pre">.ad[bs]</span></tt>)</li>
+<li>Fortran (<tt class="docutils literal"><span class="pre">-x</span> <span class="pre">f95</span></tt>, <tt class="docutils literal"><span class="pre">.f</span></tt>, <tt class="docutils literal"><span class="pre">.f9[05]</span></tt>, <tt class="docutils literal"><span class="pre">.for</span></tt>, <tt class="docutils literal"><span class="pre">.fpp</span></tt>, case-insensitive)</li>
+<li>Java (<tt class="docutils literal"><span class="pre">-x</span> <span class="pre">java</span></tt>)</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
+<tt class="docutils literal"><span class="pre">-fno-integrated-as</span></tt> 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
+<tt class="docutils literal"><span class="pre">-fuse-ld=<linker</span> <span class="pre">name></span></tt> 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 <tt class="docutils literal"><span class="pre">--rtlib=</span></tt> and <tt class="docutils literal"><span class="pre">--stdlib=</span></tt>
+flags.</p>
+<p>The set of implicitly-linked libraries depend on the language mode. As a
+consequence, you should use <tt class="docutils literal"><span class="pre">clang++</span></tt> 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 <tt class="docutils literal"><span class="pre">libclang_rt.builtins.<arch>.a</span></tt>.</p>
+<p>You can instruct Clang to use compiler-rt with the <tt class="docutils literal"><span class="pre">--rtlib=compiler-rt</span></tt> 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 <tt class="docutils literal"><span class="pre">-DLIBCXX_USE_COMPILER_RT=YES</span></tt>
+and/or <tt class="docutils literal"><span class="pre">-DLIBCXXABI_USE_COMPILER_RT=YES</span></tt> to <tt class="docutils literal"><span class="pre">cmake</span></tt>. 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
+<tt class="docutils literal"><span class="pre">__builtin_*_overflow</span></tt> family of intrinsics.</p>
+<p>You can instruct Clang to use libgcc_s with the <tt class="docutils literal"><span class="pre">--rtlib=libgcc</span></tt> 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 <tt class="docutils literal"><span class="pre">__atomic_*</span></tt> 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 <tt class="docutils literal"><span class="pre">-latomic</span></tt> to support this
+configuration when using non-native atomic operations (if you see link errors
+referring to <tt class="docutils literal"><span class="pre">__atomic_*</span></tt> 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 <tt class="docutils literal"><span class="pre">_Unwind_*</span></tt> functions implementing
+the language-neutral stack unwinding portion of the Itanium C++ ABI
+(<a class="reference external" href="http://mentorembedded.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 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 <tt class="docutils literal"><span class="pre">-DLIBCXXABI_USE_LLVM_UNWINDER=YES</span></tt>
+to <tt class="docutils literal"><span class="pre">cmake</span></tt>. 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 (<tt class="docutils literal"><span class="pre">-fsanitize=...</span></tt>) 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
+(<tt class="docutils literal"><span class="pre">libclang_rt.<sanitizer>.<arch>.a</span></tt>)
+will be implicitly linked when linking with a <tt class="docutils literal"><span class="pre">-fsanitize=...</span></tt> 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://mentorembedded.github.io/cxx-abi/abi.html">support functionality in the main Itanium C++ ABI document</a> and
+<a class="reference external" href="http://mentorembedded.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 <tt class="docutils literal"><span class="pre">-lsupc++</span></tt> to support this
+configuration when using <tt class="docutils literal"><span class="pre">-static</span></tt> or <tt class="docutils literal"><span class="pre">-static-libstdc++</span></tt>.</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 <tt class="docutils literal"><span class="pre">-stdlib=libc++</span></tt> 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 <tt class="docutils literal"><span class="pre">-stdlib=libstdc++</span></tt> flag.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="UsersManual.html">Clang Compiler User’s Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LanguageExtensions.html">Clang Language Extensions</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/Tooling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/Tooling.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/Tooling.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/Tooling.html Thu May 10 06:54:16 2018
@@ -0,0 +1,166 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="External Clang Examples" href="ExternalClangExamples.html" />
+ <link rel="prev" title="Frequently Asked Questions (FAQ)" href="FAQ.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Choosing the Right Interface for Your Application</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="FAQ.html">Frequently Asked Questions (FAQ)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ExternalClangExamples.html">External Clang Examples</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="choosing-the-right-interface-for-your-application">
+<h1>Choosing the Right Interface for Your Application<a class="headerlink" href="#choosing-the-right-interface-for-your-application" title="Permalink to this headline">¶</a></h1>
+<p>Clang provides infrastructure to write tools that need syntactic and semantic
+information about a program. This document will give a short introduction of
+the different ways to write clang tools, and their pros and cons.</p>
+<div class="section" id="libclang">
+<h2>LibClang<a class="headerlink" href="#libclang" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="http://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a> is a stable high
+level C interface to clang. When in doubt LibClang is probably the interface
+you want to use. Consider the other interfaces only when you have a good
+reason not to use LibClang.</p>
+<p>Canonical examples of when to use LibClang:</p>
+<ul class="simple">
+<li>Xcode</li>
+<li>Clang Python Bindings</li>
+</ul>
+<p>Use LibClang when you...:</p>
+<ul class="simple">
+<li>want to interface with clang from other languages than C++</li>
+<li>need a stable interface that takes care to be backwards compatible</li>
+<li>want powerful high-level abstractions, like iterating through an AST with a
+cursor, and don’t want to learn all the nitty gritty details of Clang’s AST.</li>
+</ul>
+<p>Do not use LibClang when you...:</p>
+<ul class="simple">
+<li>want full control over the Clang AST</li>
+</ul>
+</div>
+<div class="section" id="clang-plugins">
+<h2>Clang Plugins<a class="headerlink" href="#clang-plugins" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="ClangPlugins.html"><em>Clang Plugins</em></a> allow you to run additional actions on the
+AST as part of a compilation. Plugins are dynamic libraries that are loaded at
+runtime by the compiler, and they’re easy to integrate into your build
+environment.</p>
+<p>Canonical examples of when to use Clang Plugins:</p>
+<ul class="simple">
+<li>special lint-style warnings or errors for your project</li>
+<li>creating additional build artifacts from a single compile step</li>
+</ul>
+<p>Use Clang Plugins when you...:</p>
+<ul class="simple">
+<li>need your tool to rerun if any of the dependencies change</li>
+<li>want your tool to make or break a build</li>
+<li>need full control over the Clang AST</li>
+</ul>
+<p>Do not use Clang Plugins when you...:</p>
+<ul class="simple">
+<li>want to run tools outside of your build environment</li>
+<li>want full control on how Clang is set up, including mapping of in-memory
+virtual files</li>
+<li>need to run over a specific subset of files in your project which is not
+necessarily related to any changes which would trigger rebuilds</li>
+</ul>
+</div>
+<div class="section" id="libtooling">
+<h2>LibTooling<a class="headerlink" href="#libtooling" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> is a C++ interface aimed at writing standalone
+tools, as well as integrating into services that run clang tools. Canonical
+examples of when to use LibTooling:</p>
+<ul class="simple">
+<li>a simple syntax checker</li>
+<li>refactoring tools</li>
+</ul>
+<p>Use LibTooling when you...:</p>
+<ul class="simple">
+<li>want to run tools over a single file, or a specific subset of files,
+independently of the build system</li>
+<li>want full control over the Clang AST</li>
+<li>want to share code with Clang Plugins</li>
+</ul>
+<p>Do not use LibTooling when you...:</p>
+<ul class="simple">
+<li>want to run as part of the build triggered by dependency changes</li>
+<li>want a stable interface so you don’t need to change your code when the AST API
+changes</li>
+<li>want high level abstractions like cursors and code completion out of the box</li>
+<li>do not want to write your tools in C++</li>
+</ul>
+<p><a class="reference internal" href="ClangTools.html"><em>Clang tools</em></a> are a collection of specific developer tools
+built on top of the LibTooling infrastructure as part of the Clang project.
+They are targeted at automating and improving core development activities of
+C/C++ developers.</p>
+<p>Examples of tools we are building or planning as part of the Clang project:</p>
+<ul class="simple">
+<li>Syntax checking (<strong class="program">clang-check</strong>)</li>
+<li>Automatic fixing of compile errors (<strong class="program">clang-fixit</strong>)</li>
+<li>Automatic code formatting (<strong class="program">clang-format</strong>)</li>
+<li>Migration tools for new features in new language standards</li>
+<li>Core refactoring tools</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="FAQ.html">Frequently Asked Questions (FAQ)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ExternalClangExamples.html">External Clang Examples</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/UndefinedBehaviorSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/UndefinedBehaviorSanitizer.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/UndefinedBehaviorSanitizer.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/UndefinedBehaviorSanitizer.html Thu May 10 06:54:16 2018
@@ -0,0 +1,359 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="DataFlowSanitizer" href="DataFlowSanitizer.html" />
+ <link rel="prev" title="MemorySanitizer" href="MemorySanitizer.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>UndefinedBehaviorSanitizer</span></h2>
+ </div>
+ <div class="topnav">
+
+ <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="#stack-traces-and-report-symbolization" id="id6">Stack traces and report symbolization</a></li>
+<li><a class="reference internal" href="#issue-suppression" id="id7">Issue Suppression</a><ul>
+<li><a class="reference internal" href="#disabling-instrumentation-with-attribute-no-sanitize-undefined" id="id8">Disabling Instrumentation with <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt></a></li>
+<li><a class="reference internal" href="#suppressing-errors-in-recompiled-code-blacklist" id="id9">Suppressing Errors in Recompiled Code (Blacklist)</a></li>
+<li><a class="reference internal" href="#runtime-suppressions" id="id10">Runtime suppressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-platforms" id="id11">Supported Platforms</a></li>
+<li><a class="reference internal" href="#current-status" id="id12">Current Status</a></li>
+<li><a class="reference internal" href="#additional-configuration" id="id13">Additional Configuration</a><ul>
+<li><a class="reference internal" href="#example" id="id14">Example</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#more-information" id="id15">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"><em>checks</em></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 <tt class="docutils literal"><span class="pre">clang++</span></tt> to compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>
+flag. Make sure to use <tt class="docutils literal"><span class="pre">clang++</span></tt> (not <tt class="docutils literal"><span class="pre">ld</span></tt>) as a linker, so that your
+executable is linked with proper UBSan runtime libraries. You can use <tt class="docutils literal"><span class="pre">clang</span></tt>
+instead of <tt class="docutils literal"><span class="pre">clang++</span></tt> if you’re compiling/linking C code.</p>
+<div class="highlight-console"><div class="highlight"><pre><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"><em>checks</em></a> offered by UBSan,
+and define the desired behavior for each kind of check:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize=...</span></tt>: print a verbose error report and continue execution (default);</li>
+<li><tt class="docutils literal"><span class="pre">-fno-sanitize-recover=...</span></tt>: print a verbose error report and exit the program;</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize-trap=...</span></tt>: 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 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><tt class="docutils literal"><span class="pre">-fsanitize=alignment</span></tt>: Use of a misaligned pointer or creation
+of a misaligned reference.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=bool</span></tt>: Load of a <tt class="docutils literal"><span class="pre">bool</span></tt> value which is neither
+<tt class="docutils literal"><span class="pre">true</span></tt> nor <tt class="docutils literal"><span class="pre">false</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=bounds</span></tt>: Out of bounds array indexing, in cases
+where the array bound can be statically determined.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=enum</span></tt>: Load of a value of an enumerated type which
+is not in the range of representable values for that enumerated
+type.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=float-cast-overflow</span></tt>: Conversion to, from, or
+between floating-point types which would overflow the
+destination.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=float-divide-by-zero</span></tt>: Floating point division by
+zero.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt>: Indirect call of a function through a
+function pointer of the wrong type (Linux, C++ and x86/x86_64 only).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=integer-divide-by-zero</span></tt>: Integer division by zero.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=nonnull-attribute</span></tt>: Passing null pointer as a function
+parameter which is declared to never be null.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=null</span></tt>: Use of a null pointer or creation of a null
+reference.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=nullability-arg</span></tt>: Passing null as a function parameter
+which is annotated with <tt class="docutils literal"><span class="pre">_Nonnull</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=nullability-assign</span></tt>: Assigning null to an lvalue which
+is annotated with <tt class="docutils literal"><span class="pre">_Nonnull</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=nullability-return</span></tt>: Returning null from a function with
+a return type annotated with <tt class="docutils literal"><span class="pre">_Nonnull</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=object-size</span></tt>: 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
+<tt class="docutils literal"><span class="pre">__builtin_object_size</span></tt>, and consequently may be able to detect more
+problems at higher optimization levels.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=pointer-overflow</span></tt>: Performing pointer arithmetic which
+overflows.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=return</span></tt>: In C++, reaching the end of a
+value-returning function without returning a value.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=returns-nonnull-attribute</span></tt>: Returning null pointer
+from a function which is declared to never return null.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=shift</span></tt>: Shift operators where the amount shifted is
+greater or equal to the promoted bit-width of the left hand side
+or less than zero, or where the left hand side is negative. For a
+signed left shift, also checks for signed overflow in C, and for
+unsigned overflow in C++. You can use <tt class="docutils literal"><span class="pre">-fsanitize=shift-base</span></tt> or
+<tt class="docutils literal"><span class="pre">-fsanitize=shift-exponent</span></tt> to check only left-hand side or
+right-hand side of shift operation, respectively.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=signed-integer-overflow</span></tt>: Signed integer overflow,
+including all the checks added by <tt class="docutils literal"><span class="pre">-ftrapv</span></tt>, and checking for
+overflow in signed division (<tt class="docutils literal"><span class="pre">INT_MIN</span> <span class="pre">/</span> <span class="pre">-1</span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=unreachable</span></tt>: If control flow reaches
+<tt class="docutils literal"><span class="pre">__builtin_unreachable</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=unsigned-integer-overflow</span></tt>: Unsigned integer
+overflows. 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><tt class="docutils literal"><span class="pre">-fsanitize=vla-bound</span></tt>: A variable-length array whose bound
+does not evaluate to a positive value.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=vptr</span></tt>: Use of an object whose vptr indicates that
+it is of the wrong dynamic type, or that its lifetime has not
+begun or has ended. Incompatible with <tt class="docutils literal"><span class="pre">-fno-rtti</span></tt>. Link must
+be performed by <tt class="docutils literal"><span class="pre">clang++</span></tt>, not <tt class="docutils literal"><span class="pre">clang</span></tt>, 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><tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>: All of the checks listed above other than
+<tt class="docutils literal"><span class="pre">unsigned-integer-overflow</span></tt> and the <tt class="docutils literal"><span class="pre">nullability-*</span></tt> checks.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=undefined-trap</span></tt>: Deprecated alias of
+<tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=integer</span></tt>: Checks for undefined or suspicious integer
+behavior (e.g. unsigned integer overflow).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=nullability</span></tt>: Enables <tt class="docutils literal"><span class="pre">nullability-arg</span></tt>,
+<tt class="docutils literal"><span class="pre">nullability-assign</span></tt>, and <tt class="docutils literal"><span class="pre">nullability-return</span></tt>. 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 <tt class="docutils literal"><span class="pre">null</span></tt>, <tt class="docutils literal"><span class="pre">alignment</span></tt>, <tt class="docutils literal"><span class="pre">object-size</span></tt>, and <tt class="docutils literal"><span class="pre">vptr</span></tt> checks do not apply
+to pointers to types with the <tt class="docutils literal"><span class="pre">volatile</span></tt> qualifier.</p>
+</div>
+</div>
+<div class="section" id="stack-traces-and-report-symbolization">
+<h2><a class="toc-backref" href="#id6">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 <tt class="docutils literal"><span class="pre">-g</span></tt> and <tt class="docutils literal"><span class="pre">-fno-omit-frame-pointer</span></tt> to get proper debug
+information in your binary.</li>
+<li>Run your program with environment variable
+<tt class="docutils literal"><span class="pre">UBSAN_OPTIONS=print_stacktrace=1</span></tt>.</li>
+<li>Make sure <tt class="docutils literal"><span class="pre">llvm-symbolizer</span></tt> binary is in <tt class="docutils literal"><span class="pre">PATH</span></tt>.</li>
+</ol>
+</div>
+<div class="section" id="issue-suppression">
+<h2><a class="toc-backref" href="#id7">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="#id8">Disabling Instrumentation with <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt></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
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt>. You can use all values of
+<tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag in this attribute, e.g. if your function deliberately
+contains possible signed integer overflow, you can use
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("signed-integer-overflow")))</span></tt>.</p>
+<p>This attribute may not be
+supported by other compilers, so consider using it together with
+<tt class="docutils literal"><span class="pre">#if</span> <span class="pre">defined(__clang__)</span></tt>.</p>
+</div>
+<div class="section" id="suppressing-errors-in-recompiled-code-blacklist">
+<h3><a class="toc-backref" href="#id9">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 <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to suppress error reports
+in the specified source files or functions.</p>
+</div>
+<div class="section" id="runtime-suppressions">
+<h3><a class="toc-backref" href="#id10">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 <tt class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></tt> environment variable.</p>
+<div class="highlight-bash"><div class="highlight"><pre><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"><em>check</em></a> you are suppressing and the
+bug location. For example:</p>
+<div class="highlight-bash"><div class="highlight"><pre>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
+<tt class="docutils literal"><span class="pre">-fsanitize-recover=signed-integer-overflow,alignment,vptr</span></tt>, although
+most of UBSan checks are recoverable by default.</li>
+<li>Check groups (like <tt class="docutils literal"><span class="pre">undefined</span></tt>) 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="#id11">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="#id12">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
+<tt class="docutils literal"><span class="pre">check-ubsan</span></tt> command.</p>
+</div>
+<div class="section" id="additional-configuration">
+<h2><a class="toc-backref" href="#id13">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
+<tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=N</span></tt> can be used to trim this
+information. If <tt class="docutils literal"><span class="pre">N</span></tt> is positive, file information emitted by
+UndefinedBehaviorSanitizer will drop the first <tt class="docutils literal"><span class="pre">N</span></tt> components from the file
+path. If <tt class="docutils literal"><span class="pre">N</span></tt> is negative, the last <tt class="docutils literal"><span class="pre">N</span></tt> components will be kept.</p>
+<div class="section" id="example">
+<h3><a class="toc-backref" href="#id14">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>For a file called <tt class="docutils literal"><span class="pre">/code/library/file.cpp</span></tt>, here is what would be emitted:
+* Default (No flag, or <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=0</span></tt>): <tt class="docutils literal"><span class="pre">/code/library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=1</span></tt>: <tt class="docutils literal"><span class="pre">code/library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=2</span></tt>: <tt class="docutils literal"><span class="pre">library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=-1</span></tt>: <tt class="docutils literal"><span class="pre">file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=-2</span></tt>: <tt class="docutils literal"><span class="pre">library/file.cpp</span></tt></p>
+</div>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id15">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">
+
+ <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">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/UsersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/UsersManual.html?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/UsersManual.html (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/UsersManual.html Thu May 10 06:54:16 2018
@@ -0,0 +1,2798 @@
+
+
+<!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 5 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <link rel="stylesheet" href="_static/print.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '5',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <script type="text/javascript" src="_static/theme_extras.js"></script>
+ <link rel="top" title="Clang 5 documentation" href="index.html" />
+ <link rel="next" title="Assembling a Complete Toolchain" href="Toolchain.html" />
+ <link rel="prev" title="Clang 5.0.0 Release Notes" href="ReleaseNotes.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 5 documentation</span></a></h1>
+ <h2 class="heading"><span>Clang Compiler Userâs Manual</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ReleaseNotes.html">Clang 5.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>
+</ul>
+</li>
+<li><a class="reference internal" href="#language-and-target-independent-features" id="id20">Language and Target-Independent Features</a><ul>
+<li><a class="reference internal" href="#controlling-errors-and-warnings" id="id21">Controlling Errors and Warnings</a><ul>
+<li><a class="reference internal" href="#controlling-how-clang-displays-diagnostics" id="id22">Controlling How Clang Displays Diagnostics</a></li>
+<li><a class="reference internal" href="#diagnostic-mappings" id="id23">Diagnostic Mappings</a></li>
+<li><a class="reference internal" href="#diagnostic-categories" id="id24">Diagnostic Categories</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-command-line-flags" id="id25">Controlling Diagnostics via Command Line Flags</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-pragmas" id="id26">Controlling Diagnostics via Pragmas</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-in-system-headers" id="id27">Controlling Diagnostics in System Headers</a></li>
+<li><a class="reference internal" href="#enabling-all-diagnostics" id="id28">Enabling All Diagnostics</a></li>
+<li><a class="reference internal" href="#controlling-static-analyzer-diagnostics" id="id29">Controlling Static Analyzer Diagnostics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#precompiled-headers" id="id30">Precompiled Headers</a><ul>
+<li><a class="reference internal" href="#generating-a-pch-file" id="id31">Generating a PCH File</a></li>
+<li><a class="reference internal" href="#using-a-pch-file" id="id32">Using a PCH File</a></li>
+<li><a class="reference internal" href="#relocatable-pch-files" id="id33">Relocatable PCH Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-code-generation" id="id34">Controlling Code Generation</a></li>
+<li><a class="reference internal" href="#profile-guided-optimization" id="id35">Profile Guided Optimization</a><ul>
+<li><a class="reference internal" href="#differences-between-sampling-and-instrumentation" id="id36">Differences Between Sampling and Instrumentation</a></li>
+<li><a class="reference internal" href="#using-sampling-profilers" id="id37">Using Sampling Profilers</a><ul>
+<li><a class="reference internal" href="#sample-profile-formats" id="id38">Sample Profile Formats</a></li>
+<li><a class="reference internal" href="#sample-profile-text-format" id="id39">Sample Profile Text Format</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#profiling-with-instrumentation" id="id40">Profiling with Instrumentation</a></li>
+<li><a class="reference internal" href="#disabling-instrumentation" id="id41">Disabling Instrumentation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-debug-information" id="id42">Controlling Debug Information</a><ul>
+<li><a class="reference internal" href="#controlling-size-of-debug-information" id="id43">Controlling Size of Debug Information</a></li>
+<li><a class="reference internal" href="#controlling-macro-debug-info-generation" id="id44">Controlling Macro Debug Info Generation</a></li>
+<li><a class="reference internal" href="#controlling-debugger-tuning" id="id45">Controlling Debugger “Tuning”</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#comment-parsing-options" id="id46">Comment Parsing Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-language-features" id="id47">C Language Features</a><ul>
+<li><a class="reference internal" href="#extensions-supported-by-clang" id="id48">Extensions supported by clang</a></li>
+<li><a class="reference internal" href="#differences-between-various-standard-modes" id="id49">Differences between various standard modes</a></li>
+<li><a class="reference internal" href="#gcc-extensions-not-implemented-yet" id="id50">GCC extensions not implemented yet</a></li>
+<li><a class="reference internal" href="#intentionally-unsupported-gcc-extensions" id="id51">Intentionally unsupported GCC extensions</a></li>
+<li><a class="reference internal" href="#microsoft-extensions" id="id52">Microsoft extensions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#cxx" id="id53">C++ Language Features</a><ul>
+<li><a class="reference internal" href="#controlling-implementation-limits" id="id54">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-language-features" id="id55">Objective-C Language Features</a></li>
+<li><a class="reference internal" href="#objcxx" id="id56">Objective-C++ Language Features</a></li>
+<li><a class="reference internal" href="#openmp-features" id="id57">OpenMP Features</a><ul>
+<li><a class="reference internal" href="#id5" id="id58">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-features" id="id59">OpenCL Features</a><ul>
+<li><a class="reference internal" href="#opencl-specific-options" id="id60">OpenCL Specific Options</a></li>
+<li><a class="reference internal" href="#opencl-targets" id="id61">OpenCL Targets</a><ul>
+<li><a class="reference internal" href="#specific-targets" id="id62">Specific Targets</a></li>
+<li><a class="reference internal" href="#generic-targets" id="id63">Generic Targets</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-header" id="id64">OpenCL Header</a></li>
+<li><a class="reference internal" href="#opencl-extensions" id="id65">OpenCL Extensions</a></li>
+<li><a class="reference internal" href="#opencl-metadata" id="id66">OpenCL Metadata</a></li>
+<li><a class="reference internal" href="#opencl-specific-attributes" id="id67">OpenCL-Specific Attributes</a><ul>
+<li><a class="reference internal" href="#nosvm" id="id68">nosvm</a></li>
+<li><a class="reference internal" href="#opencl-unroll-hint" id="id69">opencl_unroll_hint</a></li>
+<li><a class="reference internal" href="#convergent" id="id70">convergent</a></li>
+<li><a class="reference internal" href="#noduplicate" id="id71">noduplicate</a></li>
+<li><a class="reference internal" href="#address-space" id="id72">address_space</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-builtins" id="id73">OpenCL builtins</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-specific-features-and-limitations" id="id74">Target-Specific Features and Limitations</a><ul>
+<li><a class="reference internal" href="#cpu-architectures-features-and-limitations" id="id75">CPU Architectures Features and Limitations</a><ul>
+<li><a class="reference internal" href="#x86" id="id76">X86</a></li>
+<li><a class="reference internal" href="#arm" id="id77">ARM</a></li>
+<li><a class="reference internal" href="#powerpc" id="id78">PowerPC</a></li>
+<li><a class="reference internal" href="#other-platforms" id="id79">Other platforms</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#operating-system-features-and-limitations" id="id80">Operating System Features and Limitations</a><ul>
+<li><a class="reference internal" href="#darwin-mac-os-x" id="id81">Darwin (Mac OS X)</a></li>
+<li><a class="reference internal" href="#windows" id="id82">Windows</a><ul>
+<li><a class="reference internal" href="#cygwin" id="id83">Cygwin</a></li>
+<li><a class="reference internal" href="#mingw32" id="id84">MinGW32</a></li>
+<li><a class="reference internal" href="#mingw-w64" id="id85">MinGW-w64</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-cl" id="id86">clang-cl</a><ul>
+<li><a class="reference internal" href="#id8" id="id87">Command-Line Options</a><ul>
+<li><a class="reference internal" href="#the-fallback-option" id="id88">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"><em>“Clang” CFE Internals Manual</em></a>. If you are interested in the
+<a class="reference external" href="http://clang-analyzer.llvm.org">Clang Static Analyzer</a>, please see its web
+page.</p>
+<p>Clang is 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"><em>assemble a complete toolchain</em></a>.</p>
+<p>Clang is designed to support the C family of programming languages,
+which includes <a class="reference internal" href="#c"><em>C</em></a>, <a class="reference internal" href="#objc"><em>Objective-C</em></a>, <a class="reference internal" href="#cxx"><em>C++</em></a>, and
+<a class="reference internal" href="#objcxx"><em>Objective-C++</em></a> as well as many dialects of those. For
+language-specific information, please see the corresponding language
+specific section:</p>
+<ul class="simple">
+<li><a class="reference internal" href="#c"><em>C Language</em></a>: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
+C99 (+TC1, TC2, TC3).</li>
+<li><a class="reference internal" href="#objc"><em>Objective-C Language</em></a>: ObjC 1, ObjC 2, ObjC 2.1, plus
+variants depending on base language.</li>
+<li><a class="reference internal" href="#cxx"><em>C++ Language</em></a></li>
+<li><a class="reference internal" href="#objcxx"><em>Objective C++ Language</em></a></li>
+<li><a class="reference internal" href="#opencl"><em>OpenCL C Language</em></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"><em>clang-cl</em></a>, that is designed
+to be compatible with the Visual C++ compiler, cl.exe.</p>
+<p>In addition to language specific features, Clang has a variety of
+features that depend on what CPU architecture or operating system is
+being compiled for. Please see the <a class="reference internal" href="#target-features"><em>Target-Specific Features and
+Limitations</em></a> section for more details.</p>
+<p>The rest of the introduction introduces some basic <a class="reference internal" href="#terminology"><em>compiler
+terminology</em></a> that is used throughout this manual and
+contains a basic <a class="reference internal" href="#basicusage"><em>introduction to using Clang</em></a> as a
+command line compiler.</p>
+<div class="section" id="terminology">
+<span id="id1"></span><h3><a class="toc-backref" href="#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"><em class="xref std std-option">-c</em></a>, <a class="reference internal" href="#cmdoption-g"><em class="xref std std-option">-g</em></a>, etc.</p>
+<div class="section" id="options-to-control-error-and-warning-messages">
+<h3><a class="toc-backref" href="#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">
+<tt class="descname">-Werror</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Werror" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warnings into errors.</p>
+</dd></dl>
+
+<p><tt class="docutils literal"><span class="pre">-Werror=foo</span></tt></p>
+<blockquote>
+<div>Turn warning “foo” into an error.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-Wno-error">
+<tt class="descname">-Wno-error</tt><tt class="descclassname">=foo</tt><a class="headerlink" href="#cmdoption-Wno-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warning “foo” into an warning even if <a class="reference internal" href="#cmdoption-Werror"><em class="xref std std-option">-Werror</em></a> is specified.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wfoo">
+<tt class="descname">-Wfoo</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wfoo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable warning “foo”.
+See the <a class="reference internal" href="DiagnosticsReference.html"><em>diagnostics reference</em></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">
+<tt class="descname">-Wno-foo</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wno-foo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable warning “foo”.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-w">
+<tt class="descname">-w</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-w" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable all diagnostics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Weverything">
+<tt class="descname">-Weverything</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Weverything" title="Permalink to this definition">¶</a></dt>
+<dd><p><a class="reference internal" href="#diagnostics-enable-everything"><em>Enable all diagnostics.</em></a></p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic">
+<tt class="descname">-pedantic</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pedantic" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn on language extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic-errors">
+<tt class="descname">-pedantic-errors</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pedantic-errors" title="Permalink to this definition">¶</a></dt>
+<dd><p>Error on language extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wsystem-headers">
+<tt class="descname">-Wsystem-headers</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wsystem-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable warnings from system headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ferror-limit">
+<tt class="descname">-ferror-limit</tt><tt class="descclassname">=123</tt><a class="headerlink" href="#cmdoption-ferror-limit" title="Permalink to this definition">¶</a></dt>
+<dd><p>Stop emitting diagnostics after 123 errors have been produced. The default is
+20, and the error limit can be disabled with <cite>-ferror-limit=0</cite>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-backtrace-limit">
+<tt class="descname">-ftemplate-backtrace-limit</tt><tt class="descclassname">=123</tt><a class="headerlink" href="#cmdoption-ftemplate-backtrace-limit" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only emit up to 123 template instantiation notes within the template
+instantiation backtrace for a single warning or error. The default is 10, and
+the limit can be disabled with <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-python"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //</pre>
+</div>
+<p>When this is disabled, Clang will print “test.c:28: warning...” with
+no column number.</p>
+<p class="last">The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fshow-source-location">
+<dt><strong>-f[no-]show-source-location</strong></dt>
+<dd><p class="first">Print source file/line/column information in diagnostic.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the filename, line number and column number of a diagnostic.
+For example, when this is enabled, Clang will print something like:</p>
+<div class="highlight-python"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //</pre>
+</div>
+<p class="last">When this is disabled, Clang will not print the “test.c:28:8: ”
+part.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fcaret-diagnostics">
+<dt><strong>-f[no-]caret-diagnostics</strong></dt>
+<dd><p class="first">Print source line and ranges from source code in diagnostic.
+This option, which defaults to on, controls whether or not Clang
+prints the source line, source ranges, and caret when emitting a
+diagnostic. For example, when this is enabled, Clang will print
+something like:</p>
+<div class="last highlight-python"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //</pre>
+</div>
+</dd>
+<dt><strong>-f[no-]color-diagnostics</strong></dt>
+<dd><p class="first">This option, which defaults to on when a color-capable terminal is
+detected, controls whether or not Clang prints diagnostics in color.</p>
+<p>When this option is enabled, Clang will use colors to highlight
+specific parts of the diagnostic, e.g.,</p>
+<pre>
+ <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b>
+ #endif bad
+ <span style="color:green">^</span>
+ <span style="color:green">//</span>
+</pre><p>When this is disabled, Clang will just print:</p>
+<div class="last highlight-python"><pre>test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //</pre>
+</div>
+</dd>
+<dt><strong>-fansi-escape-codes</strong></dt>
+<dd>Controls whether ANSI escape codes are used instead of the Windows Console
+API to output colored diagnostics. This option is only used on Windows and
+defaults to off.</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-format">
+<tt class="descname">-fdiagnostics-format</tt><tt class="descclassname">=clang/msvc/vi</tt><a class="headerlink" href="#cmdoption-fdiagnostics-format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Changes diagnostic output format to better match IDEs and command line tools.</p>
+<p>This option controls the output format of the filename, line number,
+and column printed in diagnostic messages. The options, and their
+affect on formatting a simple conversion diagnostic, follow:</p>
+<dl class="docutils">
+<dt><strong>clang</strong> (default)</dt>
+<dd><div class="first last highlight-python"><pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'</pre>
+</div>
+</dd>
+<dt><strong>msvc</strong></dt>
+<dd><div class="first last highlight-python"><pre>t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'</pre>
+</div>
+</dd>
+<dt><strong>vi</strong></dt>
+<dd><div class="first last highlight-python"><pre>t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'</pre>
+</div>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="docutils" id="opt-fdiagnostics-show-option">
+<dt><strong>-f[no-]diagnostics-show-option</strong></dt>
+<dd><p class="first">Enable <tt class="docutils literal"><span class="pre">[-Woption]</span></tt> information in diagnostic line.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the associated <a class="reference internal" href="#cl-diag-warning-groups"><em>warning group</em></a>
+option name when outputting a warning diagnostic. For example, in
+this output:</p>
+<div class="highlight-python"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //</pre>
+</div>
+<p class="last">Passing <strong>-fno-diagnostics-show-option</strong> will prevent Clang from
+printing the [<a class="reference internal" href="#opt-wextra-tokens"><em>-Wextra-tokens</em></a>] information in
+the diagnostic. This information tells you the flag needed to enable
+or disable the diagnostic, either from the command line or through
+<a class="reference internal" href="#pragma-gcc-diagnostic"><em>#pragma GCC diagnostic</em></a>.</p>
+</dd>
+</dl>
+<span class="target" id="opt-fdiagnostics-show-category"></span><dl class="option">
+<dt id="cmdoption-fdiagnostics-show-category">
+<tt class="descname">-fdiagnostics-show-category</tt><tt class="descclassname">=none/id/name</tt><a class="headerlink" href="#cmdoption-fdiagnostics-show-category" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable printing category information in diagnostic line.</p>
+<p>This option, which defaults to “none”, controls whether or not Clang
+prints the category associated with a diagnostic when emitting it.
+Each diagnostic may or many not have an associated category, if it
+has one, it is listed in the diagnostic categorization field of the
+diagnostic line (in the []’s).</p>
+<p>For example, a format string warning will produce these three
+renditions based on the setting of this option:</p>
+<div class="highlight-python"><pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
+t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
+t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]</pre>
+</div>
+<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"><em>-fsave-optimization-record</em></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"><em>Options to Emit Optimization Reports</em></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-python"><pre>s.c:7:10: remark: foo inlined into bar (hotness: 3000) [-Rpass-analysis=inline]
+ sum += foo(x, x - 2);
+ ^</pre>
+</div>
+<p class="last">This option is implied when
+<a class="reference internal" href="#opt-fsave-optimization-record"><em>-fsave-optimization-record</em></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"><em>Options to Emit
+Optimization Reports</em></a>) when profile hotness information in
+diagnostics is enabled (see
+<a class="reference internal" href="#opt-fdiagnostics-show-hotness"><em>-fdiagnostics-show-hotness</em></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-python"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //</pre>
+</div>
+<p class="last">Passing <strong>-fno-diagnostics-fixit-info</strong> will prevent Clang from
+printing the “//” line at the end of the message. This information
+is useful for users who may not understand what is wrong, but can be
+confusing for machine parsing.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-print-source-range-info">
+<dt><strong>-fdiagnostics-print-source-range-info</strong></dt>
+<dd><p class="first">Print machine parsable information about source ranges.
+This option makes Clang print information about source ranges in a machine
+parsable format after the file/line/column number information. The
+information is a simple sequence of brace enclosed ranges, where each range
+lists the start and end line/column locations. For example, in this output:</p>
+<div class="highlight-python"><pre>exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
+ P = (P-42) + Gamma*4;
+ ~~~~~~ ^ ~~~~~~~</pre>
+</div>
+<p>The {}’s are generated by -fdiagnostics-print-source-range-info.</p>
+<p class="last">The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-parseable-fixits">
+<tt class="descname">-fdiagnostics-parseable-fixits</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fdiagnostics-parseable-fixits" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print Fix-Its in a machine parseable form.</p>
+<p>This option makes Clang print available Fix-Its in a machine
+parseable format at the end of diagnostics. The following example
+illustrates the format:</p>
+<div class="highlight-python"><pre>fix-it:"t.cpp":{7:25-7:29}:"Gamma"</pre>
+</div>
+<p>The range printed is a half-open range, so in this example the
+characters at column 25 up to but not including column 29 on line 7
+in t.cpp should be replaced with the string “Gamma”. Either the
+range or the replacement string may be empty (representing strict
+insertions and strict erasures, respectively). Both the file name
+and the insertion string escape backslash (as “\\”), tabs (as
+“\t”), newlines (as “\n”), double quotes(as “\””) and
+non-printable characters (as octal “\xxx”).</p>
+<p>The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-elide-type">
+<tt class="descname">-fno-elide-type</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-elide-type" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turns off elision in template type printing.</p>
+<p>The default for template type printing is to elide as many template
+arguments as possible, removing those which are the same in both
+template types, leaving only the differences. Adding this flag will
+print all the template arguments. If supported by the terminal,
+highlighting will still appear on differing arguments.</p>
+<p>Default:</p>
+<div class="highlight-python"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;</pre>
+</div>
+<p>-fno-elide-type:</p>
+<div class="highlight-python"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;</pre>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-show-template-tree">
+<tt class="descname">-fdiagnostics-show-template-tree</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fdiagnostics-show-template-tree" title="Permalink to this definition">¶</a></dt>
+<dd><p>Template type diffing prints a text tree.</p>
+<p>For diffing large templated types, this option will cause Clang to
+display the templates as an indented text tree, one argument per
+line, with differences marked inline. This is compatible with
+-fno-elide-type.</p>
+<p>Default:</p>
+<div class="highlight-python"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;</pre>
+</div>
+<p>With <a class="reference internal" href="#cmdoption-fdiagnostics-show-template-tree"><em class="xref std std-option">-fdiagnostics-show-template-tree</em></a>:</p>
+<div class="highlight-python"><pre>t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
+ vector<
+ map<
+ [...],
+ map<
+ [float != double],
+ [...]>>></pre>
+</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">
+<tt class="descname">-Wextra-tokens</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wextra-tokens" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about excess tokens at the end of a preprocessor directive.</p>
+<p>This option, which defaults to on, enables warnings about extra
+tokens at the end of preprocessor directives. For example:</p>
+<div class="highlight-python"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^</pre>
+</div>
+<p>These extra tokens are not strictly conforming, and are usually best
+handled by commenting them out.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wambiguous-member-template">
+<tt class="descname">-Wambiguous-member-template</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wambiguous-member-template" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about unqualified uses of a member template whose name resolves to
+another template at the location of the use.</p>
+<p>This option, which defaults to on, enables a warning in the
+following code:</p>
+<div class="highlight-python"><pre>template<typename T> struct set{};
+template<typename T> struct trait { typedef const T& type; };
+struct Value {
+ template<typename T> void set(typename trait<T>::type value) {}
+};
+void foo() {
+ Value v;
+ v.set<double>(3.2);
+}</pre>
+</div>
+<p>C++ [basic.lookup.classref] requires this to be an error, but,
+because it’s hard to work around, Clang downgrades it to a warning
+as an extension.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wbind-to-temporary-copy">
+<tt class="descname">-Wbind-to-temporary-copy</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wbind-to-temporary-copy" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about an unusable copy constructor when binding a reference to a
+temporary.</p>
+<p>This option enables warnings about binding a
+reference to a temporary when the temporary doesn’t have a usable
+copy constructor. For example:</p>
+<div class="highlight-python"><pre>struct NonCopyable {
+ NonCopyable();
+private:
+ NonCopyable(const NonCopyable&);
+};
+void foo(const NonCopyable&);
+void bar() {
+ foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
+}</pre>
+</div>
+<div class="highlight-python"><pre>struct NonCopyable2 {
+ NonCopyable2();
+ NonCopyable2(NonCopyable2&);
+};
+void foo(const NonCopyable2&);
+void bar() {
+ foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
+}</pre>
+</div>
+<p>Note that if <tt class="docutils literal"><span class="pre">NonCopyable2::NonCopyable2()</span></tt> has a default argument
+whose instantiation produces a compile error, that error will still
+be a hard error in C++98 mode even if this warning is turned off.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="options-to-control-clang-crash-diagnostics">
+<h3><a class="toc-backref" href="#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">
+<tt class="descname">-fno-crash-diagnostics</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-crash-diagnostics" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable auto-generation of preprocessed source files during a clang crash.</p>
+</dd></dl>
+
+<p>The -fno-crash-diagnostics flag can be helpful for speeding the process
+of generating a delta reduced test case.</p>
+<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">
+<tt class="descname">-gen-reproducer</tt><tt class="descclassname"></tt><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 <tt class="docutils literal"><span class="pre">foo()</span></tt> into <tt class="docutils literal"><span class="pre">bar()</span></tt>, or the loop unroller
+decides to unroll a loop N times, or the vectorizer decides to
+vectorize a loop body.</p>
+<p>Clang offers a family of flags which the optimizers can use to emit
+a diagnostic in three cases:</p>
+<ol class="arabic simple">
+<li>When the pass makes a transformation (<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 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"><em>-fdiagnostics-show-hotness</em></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 that don’t fit neatly into other categories.</p>
+<dl class="option">
+<dt id="cmdoption-MV">
+<tt class="descname">-MV</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-MV" title="Permalink to this definition">¶</a></dt>
+<dd><p>When emitting a dependency file, use formatting conventions appropriate
+for NMake or Jom. Ignored unless another option causes Clang to emit a
+dependency file.</p>
+</dd></dl>
+
+<p>When Clang emits a dependency file (e.g., you supplied the -M option)
+most filenames can be written to the file without any special formatting.
+Different Make tools will treat different sets of characters as “special”
+and use different conventions for telling the Make tool that the character
+is actually part of the filename. Normally Clang uses backslash to “escape”
+a special character, which is the convention used by GNU Make. The -MV
+option tells Clang to put double-quotes around the entire filename, which
+is the convention used by NMake and Jom.</p>
+</div>
+</div>
+<div class="section" id="language-and-target-independent-features">
+<h2><a class="toc-backref" href="#id20">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="#id21">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="#id22">Controlling How Clang Displays Diagnostics</a><a class="headerlink" href="#controlling-how-clang-displays-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>When Clang emits a diagnostic, it includes rich information in the
+output, and gives you fine-grain control over which information is
+printed. Clang has the ability to print this information, and these are
+the options that control it:</p>
+<ol class="arabic simple">
+<li>A file/line/column indicator that shows exactly where the diagnostic
+occurs in your code [<a class="reference internal" href="#opt-fshow-column"><em>-fshow-column</em></a>,
+<a class="reference internal" href="#opt-fshow-source-location"><em>-fshow-source-location</em></a>].</li>
+<li>A categorization of the diagnostic as a note, warning, error, or
+fatal error.</li>
+<li>A text string that describes what the problem is.</li>
+<li>An option that indicates how to control the diagnostic (for
+diagnostics that support it)
+[<a class="reference internal" href="#opt-fdiagnostics-show-option"><em>-fdiagnostics-show-option</em></a>].</li>
+<li>A <a class="reference internal" href="#diagnostics-categories"><em>high-level category</em></a> for the diagnostic
+for clients that want to group diagnostics by class (for diagnostics
+that support it)
+[<a class="reference internal" href="#opt-fdiagnostics-show-category"><em>-fdiagnostics-show-category</em></a>].</li>
+<li>The line of source code that the issue occurs on, along with a caret
+and ranges that indicate the important locations
+[<a class="reference internal" href="#opt-fcaret-diagnostics"><em>-fcaret-diagnostics</em></a>].</li>
+<li>“FixIt” information, which is a concise explanation of how to fix the
+problem (when Clang is certain it knows)
+[<a class="reference internal" href="#opt-fdiagnostics-fixit-info"><em>-fdiagnostics-fixit-info</em></a>].</li>
+<li>A machine-parsable representation of the ranges involved (off by
+default)
+[<a class="reference internal" href="#opt-fdiagnostics-print-source-range-info"><em>-fdiagnostics-print-source-range-info</em></a>].</li>
+</ol>
+<p>For more information please see <a class="reference internal" href="#cl-diag-formatting"><em>Formatting of
+Diagnostics</em></a>.</p>
+</div>
+<div class="section" id="diagnostic-mappings">
+<h4><a class="toc-backref" href="#id23">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="#id24">Diagnostic Categories</a><a class="headerlink" href="#diagnostic-categories" title="Permalink to this headline">¶</a></h4>
+<p>Though not shown by default, diagnostics may each be associated with a
+high-level category. This category is intended to make it possible to
+triage builds that produce a large number of errors or warnings in a
+grouped way.</p>
+<p>Categories are not shown by default, but they can be turned on with the
+<a class="reference internal" href="#opt-fdiagnostics-show-category"><em>-fdiagnostics-show-category</em></a> option.
+When set to “<tt class="docutils literal"><span class="pre">name</span></tt>”, the category is printed textually in the
+diagnostic output. When it is set to “<tt class="docutils literal"><span class="pre">id</span></tt>”, a category number is
+printed. The mapping of category names to category id’s can be obtained
+by running ‘<tt class="docutils literal"><span class="pre">clang</span> <span class="pre">--print-diagnostic-categories</span></tt>‘.</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-command-line-flags">
+<h4><a class="toc-backref" href="#id25">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="#id26">Controlling Diagnostics via Pragmas</a><a class="headerlink" href="#controlling-diagnostics-via-pragmas" title="Permalink to this headline">¶</a></h4>
+<p>Clang can also control what diagnostics are enabled through the use of
+pragmas in the source code. This is useful for turning off specific
+warnings in a section of source code. Clang supports GCC’s pragma for
+compatibility with existing source code, as well as several extensions.</p>
+<p>The pragma may control any warning that can be used from the command
+line. Warnings may be set to ignored, warning, error, or fatal. The
+following example code will tell Clang or GCC to ignore the -Wall
+warnings:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#pragma GCC diagnostic ignored "-Wall"</span>
+</pre></div>
+</div>
+<p>In addition to all of the functionality provided by GCC’s pragma, Clang
+also allows you to push and pop the current warning state. This is
+particularly useful when writing a header file that will be compiled by
+other people, because you don’t know what warning flags they build with.</p>
+<p>In the below example <a class="reference internal" href="#cmdoption-Wextra-tokens"><em class="xref std std-option">-Wextra-tokens</em></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 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 class="cp">// 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="cp">// The following will produce an error message</span>
+<span class="cp">#pragma GCC error "Not supported"</span>
+</pre></div>
+</div>
+<p>These pragmas operate similarly to the <tt class="docutils literal"><span class="pre">#warning</span></tt> and <tt class="docutils literal"><span class="pre">#error</span></tt> preprocessor
+directives, except that they may also be embedded into preprocessor macros via
+the C99 <tt class="docutils literal"><span class="pre">_Pragma</span></tt> operator, for example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define STR(X) #X</span>
+<span class="cp">#define DEFER(M,...) M(__VA_ARGS__)</span>
+<span class="cp">#define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))</span>
+
+<span class="n">CUSTOM_ERROR</span><span class="p">(</span><span class="s">"Feature not available"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="controlling-diagnostics-in-system-headers">
+<h4><a class="toc-backref" href="#id27">Controlling Diagnostics in System Headers</a><a class="headerlink" href="#controlling-diagnostics-in-system-headers" title="Permalink to this headline">¶</a></h4>
+<p>Warnings are suppressed when they occur in system headers. By default,
+an included file is treated as a system header if it is found in an
+include path specified by <tt class="docutils literal"><span class="pre">-isystem</span></tt>, but this can be overridden in
+several ways.</p>
+<p>The <tt class="docutils literal"><span class="pre">system_header</span></tt> pragma can be used to mark the current file as
+being a system header. No warnings will be produced from the location of
+the pragma onwards within the same file.</p>
+<div class="highlight-c"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">#include</span></tt> directive
+is found within a header search path and starts with a system prefix, the
+header is treated as a system header. The last prefix on the
+command-line which matches the specified header name takes precedence.
+For instance:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -Ifoo -isystem bar --system-header-prefix<span class="o">=</span>x/ <span class="se">\</span>
+<span class="go"> --no-system-header-prefix=x/y/</span>
+</pre></div>
+</div>
+<p>Here, <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/a.h"</span></tt> is treated as including a system header, even
+if the header is found in <tt class="docutils literal"><span class="pre">foo</span></tt>, and <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/y/b.h"</span></tt> is treated
+as not including a system header, even if the header is found in
+<tt class="docutils literal"><span class="pre">bar</span></tt>.</p>
+<p>A <tt class="docutils literal"><span class="pre">#include</span></tt> directive which finds a file relative to the current
+directory is treated as including a system header if the including file
+is treated as a system header.</p>
+</div>
+<div class="section" id="enabling-all-diagnostics">
+<span id="diagnostics-enable-everything"></span><h4><a class="toc-backref" href="#id28">Enabling All Diagnostics</a><a class="headerlink" href="#enabling-all-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>In addition to the traditional <tt class="docutils literal"><span class="pre">-W</span></tt> flags, one can enable <strong>all</strong>
+diagnostics by passing <a class="reference internal" href="#cmdoption-Weverything"><em class="xref std std-option">-Weverything</em></a>. This works as expected
+with
+<a class="reference internal" href="#cmdoption-Werror"><em class="xref std std-option">-Werror</em></a>, and also includes the warnings from <a class="reference internal" href="#cmdoption-pedantic"><em class="xref std std-option">-pedantic</em></a>.</p>
+<p>Note that when combined with <a class="reference internal" href="#cmdoption-w"><em class="xref std std-option">-w</em></a> (which disables all warnings), that
+flag wins.</p>
+</div>
+<div class="section" id="controlling-static-analyzer-diagnostics">
+<h4><a class="toc-backref" href="#id29">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="#id30">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="#id31">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 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="#id32">Using a PCH File</a><a class="headerlink" href="#using-a-pch-file" title="Permalink to this headline">¶</a></h4>
+<p>A PCH file can then be used as a prefix header when a <a class="reference internal" href="CommandGuide/clang.html#cmdoption-include"><em class="xref std std-option">-include</em></a>
+option is passed to <tt class="docutils literal"><span class="pre">clang</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -include test.h test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">clang</span></tt> driver will first check if a PCH file for <tt class="docutils literal"><span class="pre">test.h</span></tt> is
+available; if so, the contents of <tt class="docutils literal"><span class="pre">test.h</span></tt> (and the files it includes)
+will be processed from the PCH file. Otherwise, Clang falls back to
+directly processing the content of <tt class="docutils literal"><span class="pre">test.h</span></tt>. This mirrors the behavior
+of GCC.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>Clang does <em>not</em> automatically use PCH files for headers that are directly
+included within a source file. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -x c-header test.h -o test.h.pch
+<span class="gp">$</span> cat test.c
+<span class="gp">#</span>include <span class="s2">"test.h"</span>
+<span class="gp">$</span> clang test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p class="last">In this example, <tt class="docutils literal"><span class="pre">clang</span></tt> will not automatically use the PCH file for
+<tt class="docutils literal"><span class="pre">test.h</span></tt> since <tt class="docutils literal"><span class="pre">test.h</span></tt> was included directly in the source file and not
+specified on the command line using <a class="reference internal" href="CommandGuide/clang.html#cmdoption-include"><em class="xref std std-option">-include</em></a>.</p>
+</div>
+</div>
+<div class="section" id="relocatable-pch-files">
+<h4><a class="toc-backref" href="#id33">Relocatable PCH Files</a><a class="headerlink" href="#relocatable-pch-files" title="Permalink to this headline">¶</a></h4>
+<p>It is sometimes necessary to build a precompiled header from headers
+that are not yet in their final, installed locations. For example, one
+might build a precompiled header within the build tree that is then
+meant to be installed alongside the headers. Clang permits the creation
+of “relocatable” precompiled headers, which are built with a given path
+(into the build directory) and can later be used from an installed
+location.</p>
+<p>To build a relocatable precompiled header, place your headers into a
+subdirectory whose structure mimics the installed location. For example,
+if you want to build a precompiled header for the header <tt class="docutils literal"><span class="pre">mylib.h</span></tt>
+that will be installed into <tt class="docutils literal"><span class="pre">/usr/include</span></tt>, create a subdirectory
+<tt class="docutils literal"><span class="pre">build/usr/include</span></tt> and place the header <tt class="docutils literal"><span class="pre">mylib.h</span></tt> into that
+subdirectory. If <tt class="docutils literal"><span class="pre">mylib.h</span></tt> depends on other headers, then they can be
+stored within <tt class="docutils literal"><span class="pre">build/usr/include</span></tt> in a way that mimics the installed
+location.</p>
+<p>Building a relocatable precompiled header requires two additional
+arguments. First, pass the <tt class="docutils literal"><span class="pre">--relocatable-pch</span></tt> flag to indicate that
+the resulting PCH file should be relocatable. Second, pass
+<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 class="gp">#</span> clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+</pre></div>
+</div>
+<p>When loading the relocatable PCH file, the various headers used in the
+PCH file are found from the system header root. For example, <tt class="docutils literal"><span class="pre">mylib.h</span></tt>
+can be found in <tt class="docutils literal"><span class="pre">/usr/include/mylib.h</span></tt>. If the headers are installed
+in some other system root, the <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
+<tt class="docutils literal"><span class="pre">mylib.h</span></tt> in <tt class="docutils literal"><span class="pre">/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h</span></tt>.</p>
+<p>Relocatable precompiled headers are intended to be used in a limited
+number of cases where the compilation environment is tightly controlled
+and the precompiled header cannot be generated after headers have been
+installed.</p>
+</div>
+</div>
+<div class="section" id="controlling-code-generation">
+<span id="id2"></span><h3><a class="toc-backref" href="#id34">Controlling Code Generation</a><a class="headerlink" href="#controlling-code-generation" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides a number of ways to control code generation. The options
+are listed below.</p>
+<dl class="docutils">
+<dt><strong>-f[no-]sanitize=check1,check2,...</strong></dt>
+<dd><p class="first">Turn on runtime checks for various forms of undefined or suspicious
+behavior.</p>
+<p>This option controls whether Clang adds runtime checks for various
+forms of undefined or suspicious behavior, and is disabled by
+default. If a check fails, a diagnostic message is produced at
+runtime explaining the problem. The main checks are:</p>
+<ul class="simple">
+<li><p id="opt-fsanitize-address"><tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>:
+<a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>, a memory error
+detector.</p>
+</li>
+<li><p id="opt-fsanitize-thread"><tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>: <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>, a data race detector.</p>
+</li>
+<li><p id="opt-fsanitize-memory"><tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt>: <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a>,
+a detector of uninitialized reads. Requires instrumentation of all
+program code.</p>
+</li>
+<li><p id="opt-fsanitize-undefined"><tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>: <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><em>UndefinedBehaviorSanitizer</em></a>,
+a fast and compatible undefined behavior checker.</p>
+</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=dataflow</span></tt>: <a class="reference internal" href="DataFlowSanitizer.html"><em>DataFlowSanitizer</em></a>, a general data
+flow analysis.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi</span></tt>: <a class="reference internal" href="ControlFlowIntegrity.html"><em>control flow integrity</em></a>
+checks. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt>: <a class="reference internal" href="SafeStack.html"><em>safe stack</em></a>
+protection against stack-based memory corruption errors.</li>
+</ul>
+<p>There are more fine-grained checks available: see
+the <a class="reference internal" href="UndefinedBehaviorSanitizer.html#ubsan-checks"><em>list</em></a> of specific kinds of
+undefined behavior that can be detected and the <a class="reference internal" href="ControlFlowIntegrity.html#cfi-schemes"><em>list</em></a>
+of control flow integrity schemes.</p>
+<p>The <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> argument must also be provided when linking, in
+order to link to the appropriate runtime library.</p>
+<p class="last">It is not possible to combine more than one of the <tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>,
+<tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>, and <tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt> checkers in the same
+program.</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 <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag are non-fatal.
+If the check is fatal, program will halt after the first error
+of this kind is detected and error report is printed.</p>
+<p>By default, non-fatal checks are those enabled by
+<a class="reference internal" href="UndefinedBehaviorSanitizer.html"><em>UndefinedBehaviorSanitizer</em></a>,
+except for <tt class="docutils literal"><span class="pre">-fsanitize=return</span></tt> and <tt class="docutils literal"><span class="pre">-fsanitize=unreachable</span></tt>. Some
+sanitizers may not support recovery (or not support it by default
+e.g. <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>), and always crash the program after the issue
+is detected.</p>
+<p>Note that the <tt class="docutils literal"><span class="pre">-fsanitize-trap</span></tt> flag has precedence over this flag.
+This means that if a check has been configured to trap elsewhere on the
+command line, or if the check traps by default, this flag will not have
+any effect unless that sanitizer’s trapping behavior is disabled with
+<tt class="docutils literal"><span class="pre">-fno-sanitize-trap</span></tt>.</p>
+<p>For example, if a command line contains the flags <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span>
+<span class="pre">-fsanitize-trap=undefined</span></tt>, the flag <tt class="docutils literal"><span class="pre">-fsanitize-recover=alignment</span></tt>
+will have no effect on its own; it will need to be accompanied by
+<tt class="docutils literal"><span class="pre">-fno-sanitize-trap=alignment</span></tt>.</p>
+</div></blockquote>
+<p><strong>-f[no-]sanitize-trap=check1,check2,...</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by the <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag trap. This
+option is intended for use in cases where the sanitizer runtime cannot
+be used (for instance, when building libc or a kernel module), or where
+the binary size increase caused by the sanitizer runtime is a concern.</p>
+<p>This flag is only compatible with <a class="reference internal" href="ControlFlowIntegrity.html"><em>control flow integrity</em></a> schemes and <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><em>UndefinedBehaviorSanitizer</em></a>
+checks other than <tt class="docutils literal"><span class="pre">vptr</span></tt>. If this flag
+is supplied together with <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>, the <tt class="docutils literal"><span class="pre">vptr</span></tt> sanitizer
+will be implicitly disabled.</p>
+<p>This flag is enabled by default for sanitizers in the <tt class="docutils literal"><span class="pre">cfi</span></tt> group.</p>
+</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-blacklist">
+<tt class="descname">-fsanitize-blacklist</tt><tt class="descclassname">=/path/to/blacklist/file</tt><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"><em>Sanitizer special case list</em></a> for file format description.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-sanitize-blacklist">
+<tt class="descname">-fno-sanitize-blacklist</tt><tt class="descclassname"></tt><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"><em>SanitizerCoverage</em></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"><em>SanitizerStats</em></a> for more details.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-undefined-trap-on-error">
+<tt class="descname">-fsanitize-undefined-trap-on-error</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fsanitize-undefined-trap-on-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Deprecated alias for <tt class="docutils literal"><span class="pre">-fsanitize-trap=undefined</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fsanitize-cfi-cross-dso">
+<tt class="descname">-fsanitize-cfi-cross-dso</tt><tt class="descclassname"></tt><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 <tt class="docutils literal"><span class="pre">cfi</span></tt> group to allow checking
+of cross-DSO virtual and indirect calls.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstrict-vtable-pointers">
+<tt class="descname">-fstrict-vtable-pointers</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-ffast-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ffast-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable fast-math mode. This defines the <tt class="docutils literal"><span class="pre">__FAST_MATH__</span></tt> 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.
+<tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">*</span></tt> are associative, <tt 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></tt>, and
+<tt 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></tt>),</li>
+<li>operands to floating-point operations are not equal to <tt class="docutils literal"><span class="pre">NaN</span></tt> and
+<tt class="docutils literal"><span class="pre">Inf</span></tt>, and</li>
+<li><tt class="docutils literal"><span class="pre">+0</span></tt> and <tt class="docutils literal"><span class="pre">-0</span></tt> are interchangeable.</li>
+</ul>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdenormal-fp-math">
+<tt class="descname">-fdenormal-fp-math</tt><tt class="descclassname">=[values]</tt><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: <tt class="docutils literal"><span class="pre">ieee</span></tt>, <tt class="docutils literal"><span class="pre">preserve-sign</span></tt>, and <tt class="docutils literal"><span class="pre">positive-zero</span></tt>,
+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">
+<tt class="descname">-fwhole-program-vtables</tt><tt class="descclassname"></tt><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"><em>hidden LTO visibility</em></a>. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-assume-sane-operator-new">
+<tt class="descname">-fno-assume-sane-operator-new</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-assume-sane-operator-new" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t assume that the C++’s new operator is sane.</p>
+<p>This option tells the compiler to do not assume that C++’s global
+new operator will always return a pointer that does not alias any
+other pointer when the function returns.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftrap-function">
+<tt class="descname">-ftrap-function</tt><tt class="descclassname">=[name]</tt><a class="headerlink" href="#cmdoption-ftrap-function" title="Permalink to this definition">¶</a></dt>
+<dd><p>Instruct code generator to emit a function call to the specified
+function name for <tt class="docutils literal"><span class="pre">__builtin_trap()</span></tt>.</p>
+<p>LLVM code generator translates <tt class="docutils literal"><span class="pre">__builtin_trap()</span></tt> to a trap
+instruction if it is supported by the target ISA. Otherwise, the
+builtin is translated into a call to <tt class="docutils literal"><span class="pre">abort</span></tt>. If this option is
+set, then the code generator will always lower the builtin to a call
+to the specified function regardless of whether the target ISA has a
+trap instruction. This option is useful for environments (e.g.
+deeply embedded) where a trap cannot be properly handled, or when
+some custom behavior is desired.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftls-model">
+<tt class="descname">-ftls-model</tt><tt class="descclassname">=[model]</tt><a class="headerlink" href="#cmdoption-ftls-model" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select which TLS model to use.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">global-dynamic</span></tt>, <tt class="docutils literal"><span class="pre">local-dynamic</span></tt>,
+<tt class="docutils literal"><span class="pre">initial-exec</span></tt> and <tt class="docutils literal"><span class="pre">local-exec</span></tt>. The default value is
+<tt class="docutils literal"><span class="pre">global-dynamic</span></tt>. The compiler may use a different model if the
+selected model is not supported by the target, or if a more
+efficient model can be used. The TLS model can be overridden per
+variable using the <tt class="docutils literal"><span class="pre">tls_model</span></tt> attribute.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-femulated-tls">
+<tt class="descname">-femulated-tls</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-mhwdiv</tt><tt class="descclassname">=[values]</tt><a class="headerlink" href="#cmdoption-mhwdiv" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select the ARM modes (arm or thumb) that support hardware division
+instructions.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">arm</span></tt>, <tt class="docutils literal"><span class="pre">thumb</span></tt> and <tt class="docutils literal"><span class="pre">arm,thumb</span></tt>.
+This option is used to indicate which mode (arm or thumb) supports
+hardware division instructions. This only applies to the ARM
+architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-m">
+<tt class="descname">-m</tt><tt class="descclassname">[no-]crc</tt><a class="headerlink" href="#cmdoption-m" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable or disable CRC instructions.</p>
+<p>This option is used to indicate whether CRC instructions are to
+be generated. This only applies to the ARM architecture.</p>
+<p>CRC instructions are enabled by default on ARMv8.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mgeneral-regs-only">
+<tt class="descname">-mgeneral-regs-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-mgeneral-regs-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate code which only uses the general purpose registers.</p>
+<p>This option restricts the generated code to use general registers
+only. This only applies to the AArch64 architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mcompact-branches">
+<tt class="descname">-mcompact-branches</tt><tt class="descclassname">=[values]</tt><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: <tt class="docutils literal"><span class="pre">never</span></tt>, <tt class="docutils literal"><span class="pre">optimal</span></tt> and <tt class="docutils literal"><span class="pre">always</span></tt>.
+The default value is <tt class="docutils literal"><span class="pre">optimal</span></tt> which generates compact branches
+when a delay slot cannot be filled. <tt class="docutils literal"><span class="pre">never</span></tt> disables the usage of
+compact branches and <tt class="docutils literal"><span class="pre">always</span></tt> 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 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="#id35">Profile Guided Optimization</a><a class="headerlink" href="#profile-guided-optimization" title="Permalink to this headline">¶</a></h3>
+<p>Profile information enables better optimization. For example, knowing that a
+branch is taken very frequently helps the compiler make better decisions when
+ordering basic blocks. Knowing that a function <tt class="docutils literal"><span class="pre">foo</span></tt> is called more
+frequently than another function <tt class="docutils literal"><span class="pre">bar</span></tt> helps the inliner.</p>
+<p>Clang supports profile guided optimization with two different kinds of
+profiling. A sampling profiler can generate a profile with very low runtime
+overhead, or you can build an instrumented version of the code that collects
+more detailed profile information. Both kinds of profiles can provide execution
+counts for instructions in the code and information on branches taken and
+function invocation.</p>
+<p>Regardless of which kind of profiling you use, be careful to collect profiles
+by running your code with inputs that are representative of the typical
+behavior. Code that is not exercised in the profile will be optimized as if it
+is unimportant, and the compiler may make poor optimization choices for code
+that is disproportionately used while profiling.</p>
+<div class="section" id="differences-between-sampling-and-instrumentation">
+<h4><a class="toc-backref" href="#id36">Differences Between Sampling and Instrumentation</a><a class="headerlink" href="#differences-between-sampling-and-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>Although both techniques are used for similar purposes, there are important
+differences between the two:</p>
+<ol class="arabic simple">
+<li>Profile data generated with one cannot be used by the other, and there is no
+conversion tool that can convert one to the other. So, a profile generated
+via <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> must be used with <tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt>.
+Similarly, sampling profiles generated by external profilers must be
+converted and used with <tt class="docutils literal"><span class="pre">-fprofile-sample-use</span></tt>.</li>
+<li>Instrumentation profile data can be used for code coverage analysis and
+optimization.</li>
+<li>Sampling profiles can only be used for optimization. They cannot be used for
+code coverage analysis. Although it would be technically possible to use
+sampling profiles for code coverage, sample-based profiles are too
+coarse-grained for code coverage purposes; it would yield poor results.</li>
+<li>Sampling profiles must be generated by an external tool. The profile
+generated by that tool must then be converted into a format that can be read
+by LLVM. The section on sampling profilers describes one of the supported
+sampling profile formats.</li>
+</ol>
+</div>
+<div class="section" id="using-sampling-profilers">
+<h4><a class="toc-backref" href="#id37">Using Sampling Profilers</a><a class="headerlink" href="#using-sampling-profilers" title="Permalink to this headline">¶</a></h4>
+<p>Sampling profilers are used to collect runtime information, such as
+hardware counters, while your application executes. They are typically
+very efficient and do not incur a large runtime overhead. The
+sample data collected by the profiler can be used during compilation
+to determine what the most executed areas of the code are.</p>
+<p>Using the data from a sample profiler requires some changes in the way
+a program is built. Before the compiler can use profiling information,
+the code needs to execute under the profiler. The following is the
+usual build cycle when using sample profilers for optimization:</p>
+<ol class="arabic">
+<li><p class="first">Build the code with source line table information. You can use all the
+usual build flags that you always build your application with. The only
+requirement is that you add <tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> or <tt class="docutils literal"><span class="pre">-g</span></tt> to the
+command line. This is important for the profiler to be able to map
+instructions back to source line locations.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -gline-tables-only code.cc -o code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the executable under a sampling profiler. The specific profiler
+you use does not really matter, as long as its output can be converted
+into the format that the LLVM optimizer understands. Currently, there
+exists a conversion tool for the Linux Perf profiler
+(<a class="reference external" href="https://perf.wiki.kernel.org/">https://perf.wiki.kernel.org/</a>), so these examples assume that you
+are using Linux Perf to profile your code.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> perf record -b ./code
+</pre></div>
+</div>
+<p>Note the use of the <tt class="docutils literal"><span class="pre">-b</span></tt> flag. This tells Perf to use the Last Branch
+Record (LBR) to record call chains. While this is not strictly required,
+it provides better call information, which improves the accuracy of
+the profile data.</p>
+</li>
+<li><p class="first">Convert the collected profile data to LLVM’s sample profile format.
+This is currently supported via the AutoFDO converter <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt>.
+It is available at <a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>. Once built and
+installed, you can convert the <tt class="docutils literal"><span class="pre">perf.data</span></tt> file to LLVM using
+the command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> create_llvm_prof --binary<span class="o">=</span>./code --out<span class="o">=</span>code.prof
+</pre></div>
+</div>
+<p>This will read <tt class="docutils literal"><span class="pre">perf.data</span></tt> and the binary file <tt class="docutils literal"><span class="pre">./code</span></tt> and emit
+the profile data in <tt class="docutils literal"><span class="pre">code.prof</span></tt>. Note that if you ran <tt class="docutils literal"><span class="pre">perf</span></tt>
+without the <tt class="docutils literal"><span class="pre">-b</span></tt> flag, you need to use <tt class="docutils literal"><span class="pre">--use_lbr=false</span></tt> when
+calling <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt>.</p>
+</li>
+<li><p class="first">Build the code again using the collected profile. This step feeds
+the profile back to the optimizers. This should result in a binary
+that executes faster than the original one. Note that you are not
+required to build the code with the exact same arguments that you
+used in the first step. The only requirement is that you build the code
+with <tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> and <tt class="docutils literal"><span class="pre">-fprofile-sample-use</span></tt>.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -gline-tables-only -fprofile-sample-use<span class="o">=</span>code.prof code.cc -o code
+</pre></div>
+</div>
+</li>
+</ol>
+<div class="section" id="sample-profile-formats">
+<h5><a class="toc-backref" href="#id38">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 <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool.</li>
+<li>Binary encoding. This uses a more efficient encoding that yields smaller
+profile files. This is the format generated by the <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt> 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 <tt class="docutils literal"><span class="pre">create_gcov</span></tt> 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
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt>, 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 <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt> described in the previous section.
+Otherwise, you will need to write a conversion tool that converts your
+profiler’s native format into one of these three.</p>
+</div>
+<div class="section" id="sample-profile-text-format">
+<h5><a class="toc-backref" href="#id39">Sample Profile Text Format</a><a class="headerlink" href="#sample-profile-text-format" title="Permalink to this headline">¶</a></h5>
+<p>This section describes the ASCII text format for sampling profiles. It is,
+arguably, the easiest one to generate. If you are interested in generating any
+of the other two, consult the <tt class="docutils literal"><span class="pre">ProfileData</span></tt> library in in LLVM’s source tree
+(specifically, <tt class="docutils literal"><span class="pre">include/llvm/ProfileData/SampleProfReader.h</span></tt>).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">function1:total_samples:total_head_samples</span>
+<span class="go"> offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]</span>
+<span class="go"> offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]</span>
+<span class="go"> ...</span>
+<span class="go"> offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]</span>
+<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 identation 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.
+<tt 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></tt></li>
+<li>Callsite line represents the profile information of an inlined callsite.
+<tt class="docutils literal"><span class="pre">offsetA[.discriminator]:</span> <span class="pre">fnA:num_of_total_samples</span></tt></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 <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(cond)</span> <span class="pre">foo();</span> <span class="pre">else</span> <span class="pre">bar();</span></tt>.
+If the predicate <tt class="docutils literal"><span class="pre">cond</span></tt> is true 80% of the time, then the edge
+into function <tt class="docutils literal"><span class="pre">foo</span></tt> should be considered to be taken most of the
+time. But both calls to <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> are at the same source
+line, so a sample count at that line is not sufficient. The
+compiler needs to know which part of that line is taken more
+frequently.</p>
+<p>This is what discriminators provide. In this case, the calls to
+<tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> will be at the same line, but will have
+different discriminator values. This allows the compiler to correctly
+set edge weights into <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt>.</p>
+</li>
+<li><p class="first">Number of samples. This is an integer quantity representing the
+number of samples collected by the profiler at this source
+location.</p>
+</li>
+<li><p class="first">[OPTIONAL] Potential call targets and samples. If present, this
+line contains a call instruction. This models both direct and
+number of samples. For example,</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">130: 7 foo:3 bar:2 baz:7</span>
+</pre></div>
+</div>
+<p>The above means that at relative line offset 130 there is a call
+instruction that calls one of <tt class="docutils literal"><span class="pre">foo()</span></tt>, <tt class="docutils literal"><span class="pre">bar()</span></tt> and <tt class="docutils literal"><span class="pre">baz()</span></tt>,
+with <tt class="docutils literal"><span class="pre">baz()</span></tt> being the relatively more frequently called target.</p>
+</li>
+</ol>
+<p>As an example, consider a program with the call chain <tt 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></tt>.
+When built with optimizations enabled, the compiler may inline the
+calls to <tt class="docutils literal"><span class="pre">bar</span></tt> and <tt class="docutils literal"><span class="pre">foo</span></tt> inside <tt class="docutils literal"><span class="pre">main</span></tt>. The generated profile
+could then be something like this:</p>
+<div class="highlight-console"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">foo</span></tt>).
+Of those, 31,977 were spent inside the body of <tt class="docutils literal"><span class="pre">bar</span></tt>. The last line
+of the profile (<tt class="docutils literal"><span class="pre">2:</span> <span class="pre">0</span></tt>) corresponds to line 2 inside <tt class="docutils literal"><span class="pre">main</span></tt>. No
+samples were collected there.</p>
+</div>
+</div>
+<div class="section" id="profiling-with-instrumentation">
+<h4><a class="toc-backref" href="#id40">Profiling with Instrumentation</a><a class="headerlink" href="#profiling-with-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>Clang also supports profiling via instrumentation. This requires building a
+special instrumented version of the code and has some runtime
+overhead during the profiling, but it provides more detailed results than a
+sampling profiler. It also provides reproducible results, at least to the
+extent that the code behaves consistently across runs.</p>
+<p>Here are the steps for using profile guided optimization with
+instrumentation:</p>
+<ol class="arabic">
+<li><p class="first">Build an instrumented version of the code by compiling and linking with the
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> option.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-instr-generate code.cc -o code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the instrumented executable with inputs that reflect the typical usage.
+By default, the profile data will be written to a <tt class="docutils literal"><span class="pre">default.profraw</span></tt> file
+in the current directory. You can override that default by using option
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate=</span></tt> or by setting the <tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt>
+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: <tt class="docutils literal"><span class="pre">%p</span></tt>, <tt class="docutils literal"><span class="pre">%h</span></tt>, and <tt class="docutils literal"><span class="pre">%m</span></tt>.</p>
+<p>Any instance of <tt class="docutils literal"><span class="pre">%p</span></tt> in that file name will be replaced by the process
+ID, so that you can easily distinguish the profile output from multiple
+runs.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"code-%p.profraw"</span> ./code
+</pre></div>
+</div>
+<p>The modifier <tt class="docutils literal"><span class="pre">%h</span></tt> 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 <tt class="docutils literal"><span class="pre">%h</span></tt> 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 <tt class="docutils literal"><span class="pre">%p</span></tt> specifier can reduce the likelihood for the profiles
+dumped from different processes to clobber each other, such clobbering can still
+happen because of the <tt class="docutils literal"><span class="pre">pid</span></tt> re-use by the OS. Another side-effect of using
+<tt class="docutils literal"><span class="pre">%p</span></tt> is that the storage requirement for raw profile data files is greatly
+increased. To avoid issues like this, the <tt class="docutils literal"><span class="pre">%m</span></tt> specifier can used in the profile
+name. When this specifier is used, the profiler runtime will substitute <tt class="docutils literal"><span class="pre">%m</span></tt>
+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 <tt class="docutils literal"><span class="pre">%m</span></tt> 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 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 <tt class="docutils literal"><span class="pre">merge</span></tt> command of the
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool to do this.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>code.profdata code-*.profraw
+</pre></div>
+</div>
+<p>Note that this step is necessary even when there is only one “raw” profile,
+since the merge operation also changes the file format.</p>
+</li>
+<li><p class="first">Build the code again using the <tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt> option to specify the
+collected profile data.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-instr-use<span class="o">=</span>code.profdata code.cc -o code
+</pre></div>
+</div>
+<p>You can repeat step 4 as often as you like without regenerating the
+profile. As you make changes to your code, clang may no longer be able to
+use the profile data. It will warn you when this happens.</p>
+</li>
+</ol>
+<p>Profile generation using an alternative instrumentation method can be
+controlled by the GCC-compatible flags <tt class="docutils literal"><span class="pre">-fprofile-generate</span></tt> and
+<tt class="docutils literal"><span class="pre">-fprofile-use</span></tt>. Although these flags are semantically equivalent to
+their GCC counterparts, they <em>do not</em> handle GCC-compatible profiles.
+They are only meant to implement GCC’s semantics with respect to
+profile creation and use.</p>
+<dl class="option">
+<dt id="cmdoption-fprofile-generate">
+<tt class="descname">-fprofile-generate</tt><tt class="descclassname">[=<dirname>]</tt><a class="headerlink" href="#cmdoption-fprofile-generate" title="Permalink to this definition">¶</a></dt>
+<dd><blockquote>
+<div><p>The <tt class="docutils literal"><span class="pre">-fprofile-generate</span></tt> and <tt class="docutils literal"><span class="pre">-fprofile-generate=</span></tt> flags will use
+an alterantive instrumentation method for profile generation. When
+given a directory name, it generates the profile file
+<tt class="docutils literal"><span class="pre">default_%m.profraw</span></tt> in the directory named <tt class="docutils literal"><span class="pre">dirname</span></tt> if specified.
+If <tt class="docutils literal"><span class="pre">dirname</span></tt> does not exist, it will be created at runtime. <tt class="docutils literal"><span class="pre">%m</span></tt> specifier
+will be substibuted with a unique id documented in step 2 above. In other words,
+with <tt class="docutils literal"><span class="pre">-fprofile-generate[=<dirname>]</span></tt> 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 class="gp">$</span> clang++ -O2 -fprofile-generate<span class="o">=</span>yyy/zzz code.cc -o code
+</pre></div>
+</div>
+<p>When <tt class="docutils literal"><span class="pre">code</span></tt> is executed, the profile will be written to the file
+<tt class="docutils literal"><span class="pre">yyy/zzz/default_xxxx.profraw</span></tt>.</p>
+<p>To generate the profile data file with the compiler readable format, the
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool can be used with the profile directory as the input:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><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
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> 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">
+<tt class="descname">-fprofile-use</tt><tt class="descclassname">[=<pathname>]</tt><a class="headerlink" href="#cmdoption-fprofile-use" title="Permalink to this definition">¶</a></dt>
+<dd><p>Without any other arguments, <tt class="docutils literal"><span class="pre">-fprofile-use</span></tt> behaves identically to
+<tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt>. Otherwise, if <tt class="docutils literal"><span class="pre">pathname</span></tt> is the full path to a
+profile file, it reads from that file. If <tt class="docutils literal"><span class="pre">pathname</span></tt> is a directory name,
+it reads from <tt class="docutils literal"><span class="pre">pathname/default.profdata</span></tt>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="disabling-instrumentation">
+<h4><a class="toc-backref" href="#id41">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 <tt class="docutils literal"><span class="pre">-fno-profile-instr-generate</span></tt> (or
+<tt class="docutils literal"><span class="pre">-fno-profile-generate</span></tt>) to disable profile generation, and
+<tt class="docutils literal"><span class="pre">-fno-profile-instr-use</span></tt> (or <tt class="docutils literal"><span class="pre">-fno-profile-use</span></tt>) 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="#id42">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="#id43">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">
+<tt class="descname">-g0</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-g0" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t generate any debug info (default).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-gline-tables-only">
+<tt class="descname">-gline-tables-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-gline-tables-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate line number tables only.</p>
+<p>This kind of debug info allows to obtain stack traces with function names,
+file names and line numbers (by such tools as <tt class="docutils literal"><span class="pre">gdb</span></tt> or <tt class="docutils literal"><span class="pre">addr2line</span></tt>). It
+doesn’t contain any other data (e.g. description of local variables or
+function parameters).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstandalone-debug">
+<tt class="descname">-fstandalone-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fstandalone-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>Clang supports a number of optimizations to reduce the size of debug
+information in the binary. They work based on the assumption that
+the debug type information can be spread out over multiple
+compilation units. For instance, Clang will not emit type
+definitions for types that are not needed by a module and could be
+replaced with a forward declaration. Further, Clang will only emit
+type info for a dynamic C++ class in the module that contains the
+vtable for the class.</p>
+<p>The <strong>-fstandalone-debug</strong> option turns off these optimizations.
+This is useful when working with 3rd-party libraries that don’t come
+with debug information. Note that Clang will never emit type
+information for types that are not referenced at all by the program.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-standalone-debug">
+<tt class="descname">-fno-standalone-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-standalone-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>On Darwin <strong>-fstandalone-debug</strong> is enabled by default. The
+<strong>-fno-standalone-debug</strong> option can be used to get to turn on the
+vtable-based optimization described above.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-g">
+<tt class="descname">-g</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-g" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate complete debug info.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="controlling-macro-debug-info-generation">
+<h4><a class="toc-backref" href="#id44">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">
+<tt class="descname">-fdebug-macro</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-fno-debug-macro</tt><tt class="descclassname"></tt><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="#id45">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">
+<tt class="descname">-ggdb</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-glldb</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-gsce</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ggdb" title="Permalink to this definition">¶</a></dt>
+<dd><p>Tune the debug info for the <tt class="docutils literal"><span class="pre">gdb</span></tt>, <tt class="docutils literal"><span class="pre">lldb</span></tt>, 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="#id46">Comment Parsing Options</a><a class="headerlink" href="#comment-parsing-options" title="Permalink to this headline">¶</a></h3>
+<p>Clang parses Doxygen and non-Doxygen style documentation comments and attaches
+them to the appropriate declaration nodes. By default, it only parses
+Doxygen-style comments and ignores ordinary comments starting with <tt class="docutils literal"><span class="pre">//</span></tt> and
+<tt class="docutils literal"><span class="pre">/*</span></tt>.</p>
+<dl class="option">
+<dt id="cmdoption-Wdocumentation">
+<tt class="descname">-Wdocumentation</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wdocumentation" title="Permalink to this definition">¶</a></dt>
+<dd><p>Emit warnings about use of documentation comments. This warning group is off
+by default.</p>
+<p>This includes checking that <tt class="docutils literal"><span class="pre">\param</span></tt> commands name parameters that actually
+present in the function signature, checking that <tt class="docutils literal"><span class="pre">\returns</span></tt> is used only on
+functions that actually return a value etc.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wno-documentation-unknown-command">
+<tt class="descname">-Wno-documentation-unknown-command</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wno-documentation-unknown-command" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t warn when encountering an unknown Doxygen command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fparse-all-comments">
+<tt class="descname">-fparse-all-comments</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fparse-all-comments" title="Permalink to this definition">¶</a></dt>
+<dd><p>Parse all comments as documentation comments (including ordinary comments
+starting with <tt class="docutils literal"><span class="pre">//</span></tt> and <tt class="docutils literal"><span class="pre">/*</span></tt>).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fcomment-block-commands">
+<tt class="descname">-fcomment-block-commands</tt><tt class="descclassname">=[commands]</tt><a class="headerlink" href="#cmdoption-fcomment-block-commands" title="Permalink to this definition">¶</a></dt>
+<dd><p>Define custom documentation commands as block commands. This allows Clang to
+construct the correct AST for these custom commands, and silences warnings
+about unknown commands. Several commands must be separated by a comma
+<em>without trailing space</em>; e.g. <tt class="docutils literal"><span class="pre">-fcomment-block-commands=foo,bar</span></tt> defines
+custom commands <tt class="docutils literal"><span class="pre">\foo</span></tt> and <tt class="docutils literal"><span class="pre">\bar</span></tt>.</p>
+<p>It is also possible to use <tt class="docutils literal"><span class="pre">-fcomment-block-commands</span></tt> several times; e.g.
+<tt class="docutils literal"><span class="pre">-fcomment-block-commands=foo</span> <span class="pre">-fcomment-block-commands=bar</span></tt> does the same
+as above.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="c-language-features">
+<span id="c"></span><h2><a class="toc-backref" href="#id47">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="#id48">Extensions supported by clang</a><a class="headerlink" href="#extensions-supported-by-clang" title="Permalink to this headline">¶</a></h3>
+<p>See <a class="reference internal" href="LanguageExtensions.html"><em>Clang Language Extensions</em></a>.</p>
+</div>
+<div class="section" id="differences-between-various-standard-modes">
+<h3><a class="toc-backref" href="#id49">Differences between various standard modes</a><a class="headerlink" href="#differences-between-various-standard-modes" title="Permalink to this headline">¶</a></h3>
+<p>clang supports the -std option, which changes what language mode clang
+uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11,
+gnu11, and various aliases for those modes. If no -std option is
+specified, clang defaults to gnu11 mode. Many C99 and C11 features are
+supported in earlier modes as a conforming extension, with a warning. Use
+<tt class="docutils literal"><span class="pre">-pedantic-errors</span></tt> to request an error if a feature from a later standard
+revision is used in an earlier mode.</p>
+<p>Differences between all <tt class="docutils literal"><span class="pre">c*</span></tt> and <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">c*</span></tt> modes define “<tt class="docutils literal"><span class="pre">__STRICT_ANSI__</span></tt>”.</li>
+<li>Target-specific defines not prefixed by underscores, like “linux”,
+are defined in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes.</li>
+<li>Trigraphs default to being off in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes; they can be enabled by
+the -trigraphs option.</li>
+<li>The parser recognizes “asm” and “typeof” as keywords in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes;
+the variants “<tt class="docutils literal"><span class="pre">__asm__</span></tt>” and “<tt class="docutils literal"><span class="pre">__typeof__</span></tt>” are recognized in all
+modes.</li>
+<li>The Apple “blocks” extension is recognized by default in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes
+on some platforms; it can be enabled in any mode with the “-fblocks”
+option.</li>
+<li>Arrays that are VLA’s according to the standard, but which can be
+constant folded by the frontend are treated as fixed size arrays.
+This occurs for things like “int X[(1, 2)];”, which is technically a
+VLA. <tt class="docutils literal"><span class="pre">c*</span></tt> modes are strictly compliant and treat these as VLAs.</li>
+</ul>
+<p>Differences between <tt class="docutils literal"><span class="pre">*89</span></tt> and <tt class="docutils literal"><span class="pre">*99</span></tt> modes:</p>
+<ul class="simple">
+<li>The <tt class="docutils literal"><span class="pre">*99</span></tt> modes default to implementing “inline” as specified in C99,
+while the <tt class="docutils literal"><span class="pre">*89</span></tt> modes implement the GNU version. This can be
+overridden for individual functions with the <tt class="docutils literal"><span class="pre">__gnu_inline__</span></tt>
+attribute.</li>
+<li>Digraphs are not recognized in c89 mode.</li>
+<li>The scope of names defined inside a “for”, “if”, “switch”, “while”,
+or “do” statement is different. (example: “<tt class="docutils literal"><span class="pre">if</span> <span class="pre">((struct</span> <span class="pre">x</span> <span class="pre">{int</span>
+<span class="pre">x;}*)0)</span> <span class="pre">{}</span></tt>”.)</li>
+<li><tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> is not defined in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>“inline” is not recognized as a keyword in c89 mode.</li>
+<li>“restrict” is not recognized as a keyword in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>Commas are allowed in integer constant expressions in <tt class="docutils literal"><span class="pre">*99</span></tt> modes.</li>
+<li>Arrays which are not lvalues are not implicitly promoted to pointers
+in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>Some warnings are different.</li>
+</ul>
+<p>Differences between <tt class="docutils literal"><span class="pre">*99</span></tt> and <tt class="docutils literal"><span class="pre">*11</span></tt> modes:</p>
+<ul class="simple">
+<li>Warnings for use of C11 features are disabled.</li>
+<li><tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> is defined to <tt class="docutils literal"><span class="pre">201112L</span></tt> rather than <tt class="docutils literal"><span class="pre">199901L</span></tt>.</li>
+</ul>
+<p>c94 mode is identical to c89 mode except that digraphs are enabled in
+c94 mode (FIXME: And <tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> should be defined!).</p>
+</div>
+<div class="section" id="gcc-extensions-not-implemented-yet">
+<h3><a class="toc-backref" href="#id50">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 (<tt class="docutils literal"><span class="pre">_Decimal32</span></tt> and
+friends) or fixed-point types (<tt class="docutils literal"><span class="pre">_Fract</span></tt> and friends); nobody has
+expressed interest in these features yet, so it’s hard to say when
+they will be implemented.</p>
+</li>
+<li><p class="first">clang does not support nested functions; this is a complex feature
+which is infrequently used, so it is unlikely to be implemented
+anytime soon. In C++11 it can be emulated by assigning lambda
+functions to local variables, e.g:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span class="k">auto</span> <span class="k">const</span> <span class="n">local_function</span> <span class="o">=</span> <span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="kt">int</span> <span class="n">parameter</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Do something</span>
+<span class="p">};</span>
+<span class="p">...</span>
+<span class="n">local_function</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">clang 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
+<tt class="docutils literal"><span class="pre">__builtin_va_arg_pack</span></tt>/<tt class="docutils literal"><span class="pre">__builtin_va_arg_pack_len</span></tt>. This is
+used rarely, but in some potentially interesting places, like the
+glibc headers, so it may be implemented pending user demand. Note
+that because clang pretends to be like GCC 4.2, and this extension
+was introduced in 4.3, the glibc headers will not try to use this
+extension with clang at the moment.</p>
+</li>
+<li><p class="first">clang does not support the gcc extension for forward-declaring
+function parameters; this has not shown up in any real-world code
+yet, though, so it might never be implemented.</p>
+</li>
+</ul>
+<p>This is not a complete list; if you find an unsupported extension
+missing from this list, please send an e-mail to cfe-dev. This list
+currently excludes C++; see <a class="reference internal" href="#cxx"><em>C++ Language Features</em></a>. Also, this
+list does not include bugs in mostly-implemented features; please see
+the <a class="reference external" href="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="#id51">Intentionally unsupported GCC extensions</a><a class="headerlink" href="#intentionally-unsupported-gcc-extensions" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>clang does not support the gcc extension that allows variable-length
+arrays in structures. This is for a few reasons: one, it is tricky to
+implement, two, the extension is completely undocumented, and three,
+the extension appears to be rarely used. Note that clang <em>does</em>
+support flexible array members (arrays with a zero or unspecified
+size at the end of a structure).</li>
+<li>clang does not have an equivalent to gcc’s “fold”; this means that
+clang doesn’t accept some constructs gcc might accept in contexts
+where a constant expression is required, like “x-x” where x is a
+variable.</li>
+<li>clang does not support <tt class="docutils literal"><span class="pre">__builtin_apply</span></tt> and friends; this extension
+is extremely obscure and difficult to implement reliably.</li>
+</ul>
+</div>
+<div class="section" id="microsoft-extensions">
+<span id="c-ms"></span><h3><a class="toc-backref" href="#id52">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 <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> 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 <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> and <tt class="docutils literal"><span class="pre">#pragma</span>
+<span class="pre">comment(lib)</span></tt> are well supported.</p>
+<p>clang has a <tt class="docutils literal"><span class="pre">-fms-compatibility</span></tt> flag that makes clang accept enough
+invalid C++ to be able to parse most Microsoft headers. For example, it
+allows <a class="reference external" href="http://clang.llvm.org/compatibility.html#dep_lookup_bases">unqualified lookup of dependent base class members</a>, which is
+a common compatibility issue with clang. This flag is enabled by default
+for Windows targets.</p>
+<p><tt class="docutils literal"><span class="pre">-fdelayed-template-parsing</span></tt> lets clang delay parsing of function template
+definitions until the end of a translation unit. This flag is enabled by
+default for Windows targets.</p>
+<p>For compatibility with existing code that compiles with MSVC, clang defines the
+<tt class="docutils literal"><span class="pre">_MSC_VER</span></tt> and <tt class="docutils literal"><span class="pre">_MSC_FULL_VER</span></tt> macros. These default to the values of 1800
+and 180000000 respectively, making clang look like an early release of Visual
+C++ 2013. The <tt class="docutils literal"><span class="pre">-fms-compatibility-version=</span></tt> 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, <tt class="docutils literal"><span class="pre">-fms-compatibility-version=19</span></tt> will enable C++14 features and define
+<tt class="docutils literal"><span class="pre">char16_t</span></tt> and <tt class="docutils literal"><span class="pre">char32_t</span></tt> as builtin types.</p>
+</div>
+</div>
+<div class="section" id="cxx">
+<span id="id3"></span><h2><a class="toc-backref" href="#id53">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="#id54">Controlling implementation limits</a><a class="headerlink" href="#controlling-implementation-limits" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fbracket-depth">
+<tt class="descname">-fbracket-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-fbracket-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for nested parentheses, brackets, and braces to N. The
+default is 256.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fconstexpr-depth">
+<tt class="descname">-fconstexpr-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-fconstexpr-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for recursive constexpr function invocations to N. The
+default is 512.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-depth">
+<tt class="descname">-ftemplate-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-ftemplate-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for recursively nested template instantiations to N. The
+default is 256.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-foperator-arrow-depth">
+<tt class="descname">-foperator-arrow-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-foperator-arrow-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for iterative calls to ‘operator->’ functions to N. The
+default is 256.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="objective-c-language-features">
+<span id="objc"></span><h2><a class="toc-backref" href="#id55">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="#id56">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="#id57">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, <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">simd</span></tt>,
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">for</span> <span class="pre">simd</span></tt>, <tt 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></tt> directives, extended
+set of atomic constructs, <tt class="docutils literal"><span class="pre">proc_bind</span></tt> clause for all parallel-based
+directives, <tt class="docutils literal"><span class="pre">depend</span></tt> clause for <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">task</span></tt> directive (except for
+array sections), <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">cancel</span></tt> and <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">cancellation</span> <span class="pre">point</span></tt>
+directives, and <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">taskgroup</span></tt> directive.</p>
+<p>Use <cite>-fopenmp</cite> to enable OpenMP. Support for OpenMP can be disabled with
+<cite>-fno-openmp</cite>.</p>
+<div class="section" id="id5">
+<h3><a class="toc-backref" href="#id58">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">
+<tt class="descname">-fopenmp-use-tls</tt><tt class="descclassname"></tt><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="#id59">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 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 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 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="#id60">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 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">
+<tt class="descname">-finclude-default-header</tt><tt class="descclassname"></tt><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"><em>the section
+on the OpenCL Header</em></a>):</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -Xclang -finclude-default-header test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Alternatively <tt class="docutils literal"><span class="pre">-include</span></tt> or <tt class="docutils literal"><span class="pre">-I</span></tt> followed by the path to the header location
+can be given manually.</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><opencl-c.h></span></tt> just as a
+regular C include.</p>
+<span class="target" id="opencl-cl-ext"></span><dl class="option">
+<dt id="cmdoption-cl-ext">
+<tt class="descname">-cl-ext</tt><tt class="descclassname"></tt><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 <tt class="docutils literal"><span class="pre">-cl-ext</span></tt>
+flag with a comma-separated list of extensions prefixed with <tt class="docutils literal"><span class="pre">'+'</span></tt> or <tt class="docutils literal"><span class="pre">'-'</span></tt>.
+The syntax: <tt class="docutils literal"><span class="pre">-cl-ext=<(['-'|'+']<extension>[,])+></span></tt>, 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, <tt class="docutils literal"><span class="pre">'all'</span></tt> 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 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 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">
+<tt class="descname">-ffake-address-space-map</tt><tt class="descclassname"></tt><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 <tt class="docutils literal"><span class="pre">-ffake-address-space-map</span></tt> will
+add/override address spaces of the target compiled for with the following values:
+<tt class="docutils literal"><span class="pre">1-global</span></tt>, <tt class="docutils literal"><span class="pre">2-constant</span></tt>, <tt class="docutils literal"><span class="pre">3-local</span></tt>, <tt class="docutils literal"><span class="pre">4-generic</span></tt>. 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"><em>the section on the address space attribute</em></a>).</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><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: <tt class="docutils literal"><span class="pre">-c</span></tt>, <tt class="docutils literal"><span class="pre">-O<1-4|s></span></tt>, <tt class="docutils literal"><span class="pre">-o</span></tt>, <tt class="docutils literal"><span class="pre">-emit-llvm</span></tt>, etc.</p>
+</div>
+<div class="section" id="opencl-targets">
+<h3><a class="toc-backref" href="#id61">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="#id62">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 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 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="#id63">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 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"><em>-ffake-address-space-map</em></a> flag.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="opencl-header">
+<span id="id6"></span><h3><a class="toc-backref" href="#id64">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
+<tt class="docutils literal"><span class="pre">-finclude-default-header</span></tt> flag to the Clang frontend.</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><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"><em>Precompiled Header and Modules Internals</em></a>)
+and modules (<a class="reference internal" href="Modules.html"><em>Modules</em></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 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="#id65">OpenCL Extensions</a><a class="headerlink" href="#opencl-extensions" title="Permalink to this headline">¶</a></h3>
+<p>All of the <tt class="docutils literal"><span class="pre">cl_khr_*</span></tt> 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
+<tt class="docutils literal"><span class="pre">-cl-ext</span></tt> flag. (See <a class="reference internal" href="#opencl-cl-ext"><em>flags description</em></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 class="cp">#pragma OPENCL EXTENSION the_new_extension_name : begin</span>
+<span class="cp">// 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 <tt class="docutils literal"><span class="pre">my_t</span></tt> type and <tt class="docutils literal"><span class="pre">my_func</span></tt>
+function to the custom <tt class="docutils literal"><span class="pre">my_ext</span></tt> extension.</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><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="n">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="#id66">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 <tt class="docutils literal"><span class="pre">-cl-kernel-arg-info</span></tt> 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="#id67">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"><em>Attributes in Clang</em></a>.</p>
+<div class="section" id="nosvm">
+<h4><a class="toc-backref" href="#id68">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="#id69">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="#id70">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 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 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 <tt class="docutils literal"><span class="pre">my_sub_group_shuffle</span></tt> with the convergent attribute
+would prevent this:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">convergent</span></tt> guarantees correct execution by keeping CFG equivalence
+wrt operations marked as <tt class="docutils literal"><span class="pre">convergent</span></tt>. CFG <tt class="docutils literal"><span class="pre">G´</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">G</span></tt> wrt
+node <tt class="docutils literal"><span class="pre">Ni</span></tt> : <tt class="docutils literal"><span class="pre">iff</span> <span class="pre">â</span> <span class="pre">Nj</span> <span class="pre">(iâ j)</span></tt> domination and post-domination relations with
+respect to <tt class="docutils literal"><span class="pre">Ni</span></tt> remain the same in both <tt class="docutils literal"><span class="pre">G</span></tt> and <tt class="docutils literal"><span class="pre">G´</span></tt>.</p>
+</div>
+<div class="section" id="noduplicate">
+<h4><a class="toc-backref" href="#id71">noduplicate</a><a class="headerlink" href="#noduplicate" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">noduplicate</span></tt> is more restrictive with respect to optimizations than
+<tt class="docutils literal"><span class="pre">convergent</span></tt> 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 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 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 <tt class="docutils literal"><span class="pre">noduplicate</span></tt> would disallow this. Also <tt class="docutils literal"><span class="pre">noduplicate</span></tt> doesn’t
+have the same safe semantics of CFG as <tt class="docutils literal"><span class="pre">convergent</span></tt> and can cause changes in
+CFG that modify semantics of the original program.</p>
+<p><tt class="docutils literal"><span class="pre">noduplicate</span></tt> 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="#id72">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 <tt class="docutils literal"><span class="pre">address_space(N)</span></tt>
+attribute, where <tt class="docutils literal"><span class="pre">N</span></tt> is an integer number in the range <tt class="docutils literal"><span class="pre">0</span></tt> to <tt class="docutils literal"><span class="pre">16777215</span></tt>
+(<tt class="docutils literal"><span class="pre">0xffffffu</span></tt>).</p>
+<p>An OpenCL implementation provides a list of standard address spaces using
+keywords: <tt class="docutils literal"><span class="pre">private</span></tt>, <tt class="docutils literal"><span class="pre">local</span></tt>, <tt class="docutils literal"><span class="pre">global</span></tt>, and <tt class="docutils literal"><span class="pre">generic</span></tt>. 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="#id73">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 <tt class="docutils literal"><span class="pre">to_global</span></tt>/<tt class="docutils literal"><span class="pre">to_local</span></tt>/<tt class="docutils literal"><span class="pre">to_private</span></tt>
+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 <tt class="docutils literal"><span class="pre">enqueue_kernel</span></tt> 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="#id74">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="#id75">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="#id76">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h4>
+<p>The support for X86 (both 32-bit and 64-bit) is considered stable on
+Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
+to correctly compile many large C, C++, Objective-C, and Objective-C++
+codebases.</p>
+<p>On <tt class="docutils literal"><span class="pre">x86_64-mingw32</span></tt>, passing i128(by value) is incompatible with the
+Microsoft x64 calling convention. You might need to tweak
+<tt class="docutils literal"><span class="pre">WinX86_64ABIInfo::classify()</span></tt> in lib/CodeGen/TargetInfo.cpp.</p>
+<p>For the X86 target, clang supports the <cite>-m16</cite> command line
+argument which enables 16-bit code output. This is broadly similar to
+using <tt class="docutils literal"><span class="pre">asm(".code16gcc")</span></tt> with the GNU toolchain. The generated code
+and the ABI remains 32-bit but the assembler emits instructions
+appropriate for a CPU running in 16-bit mode, with address-size and
+operand-size prefixes to enable 32-bit addressing and operations.</p>
+</div>
+<div class="section" id="arm">
+<h4><a class="toc-backref" href="#id77">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="#id78">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="#id79">Other platforms</a><a class="headerlink" href="#other-platforms" title="Permalink to this headline">¶</a></h4>
+<p>clang currently contains some support for other architectures (e.g. Sparc);
+however, significant pieces of code generation are still missing, and they
+haven’t undergone significant testing.</p>
+<p>clang contains limited support for the MSP430 embedded processor, but
+both the clang support and the LLVM backend support are highly
+experimental.</p>
+<p>Other platforms are completely unsupported at the moment. Adding the
+minimal support needed for parsing and semantic analysis on a new
+platform is quite easy; see <tt class="docutils literal"><span class="pre">lib/Basic/Targets.cpp</span></tt> in the clang source
+tree. This level of support is also sufficient for conversion to LLVM IR
+for simple programs. Proper support for conversion to LLVM IR requires
+adding code to <tt class="docutils literal"><span class="pre">lib/CodeGen/CGCall.cpp</span></tt> at the moment; this is likely to
+change soon, though. Generating assembly requires a suitable LLVM
+backend.</p>
+</div>
+</div>
+<div class="section" id="operating-system-features-and-limitations">
+<h3><a class="toc-backref" href="#id80">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="#id81">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="#id82">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h4>
+<p>Clang has experimental support for targeting “Cygming” (Cygwin / MinGW)
+platforms.</p>
+<p>See also <a class="reference internal" href="#c-ms"><em>Microsoft Extensions</em></a>.</p>
+<div class="section" id="cygwin">
+<h5><a class="toc-backref" href="#id83">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="#id84">MinGW32</a><a class="headerlink" href="#mingw32" title="Permalink to this headline">¶</a></h5>
+<p>Clang works on some mingw32 distributions. Clang assumes directories as
+below;</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">C:/mingw/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">C:/mingw/lib</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++</span></tt></li>
+</ul>
+<p>On MSYS, a few tests might fail.</p>
+</div>
+<div class="section" id="mingw-w64">
+<h5><a class="toc-backref" href="#id85">MinGW-w64</a><a class="headerlink" href="#mingw-w64" title="Permalink to this headline">¶</a></h5>
+<p>For 32-bit (i686-w64-mingw32), and 64-bit (x86_64-w64-mingw32), Clang
+assumes as below;</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">GCC</span> <span class="pre">versions</span> <span class="pre">4.5.0</span> <span class="pre">to</span> <span class="pre">4.5.3,</span> <span class="pre">4.6.0</span> <span class="pre">to</span> <span class="pre">4.6.2,</span> <span class="pre">or</span> <span class="pre">4.7.0</span> <span class="pre">(for</span> <span class="pre">the</span> <span class="pre">C++</span> <span class="pre">header</span> <span class="pre">search</span> <span class="pre">path)</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/gcc.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/clang.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/clang++.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/backward</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../x86_64-w64-mingw32/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../i686-w64-mingw32/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include</span></tt></li>
+</ul>
+<p>This directory layout is standard for any toolchain you will find on the
+official <a class="reference external" href="http://mingw-w64.sourceforge.net">MinGW-w64 website</a>.</p>
+<p>Clang expects the GCC executable “gcc.exe” compiled for
+<tt class="docutils literal"><span class="pre">i686-w64-mingw32</span></tt> (or <tt class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></tt>) to be present on PATH.</p>
+<p><a class="reference external" href="https://bugs.llvm.org/show_bug.cgi?id=9072">Some tests might fail</a> on
+<tt class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></tt>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="clang-cl">
+<span id="id7"></span><h2><a class="toc-backref" href="#id86">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="#id87">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 <tt class="docutils literal"><span class="pre">/</span></tt> or <tt class="docutils literal"><span class="pre">-</span></tt>. It also supports
+some of Clang’s core options, such as the <tt class="docutils literal"><span class="pre">-W</span></tt> options.</p>
+<p>Options that are known to clang-cl, but not currently supported, are ignored
+with a warning. For example:</p>
+<blockquote>
+<div><div class="highlight-python"><pre>clang-cl.exe: warning: argument unused during compilation: '/AI'</pre>
+</div>
+</div></blockquote>
+<p>To suppress warnings about unused arguments, use the <tt class="docutils literal"><span class="pre">-Qunused-arguments</span></tt> option.</p>
+<p>Options that are not known to clang-cl will be ignored by default. Use the
+<tt class="docutils literal"><span class="pre">-Werror=unknown-argument</span></tt> option in order to treat them as errors. If these
+options are spelled with a leading <tt class="docutils literal"><span class="pre">/</span></tt>, they will be mistaken for a filename:</p>
+<blockquote>
+<div><div class="highlight-python"><pre>clang-cl.exe: error: no such file or directory: '/foobar'</pre>
+</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 <tt class="docutils literal"><span class="pre">clang-cl</span> <span class="pre">/?</span></tt> to see a list of supported options:</p>
+<blockquote>
+<div><div class="highlight-python"><pre>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
+ /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 -Wall and -Wextra
+ /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-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-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
+ -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
+ -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></blockquote>
+<div class="section" id="the-fallback-option">
+<h4><a class="toc-backref" href="#id88">The /fallback Option</a><a class="headerlink" href="#the-fallback-option" title="Permalink to this headline">¶</a></h4>
+<p>When clang-cl is run with the <tt class="docutils literal"><span class="pre">/fallback</span></tt> option, it will first try to
+compile files itself. For any file that it fails to compile, it will fall back
+and try to compile the file by invoking cl.exe.</p>
+<p>This option is intended to be used as a temporary means to build projects where
+clang-cl cannot successfully compile all the files. clang-cl may fail to compile
+a file either because it cannot generate code for some C++ feature, or because
+it cannot parse some Microsoft language extension.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ReleaseNotes.html">Clang 5.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">
+ © Copyright 2007-2018, The Clang Team.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/5.0.2/tools/clang/docs/_images/DriverArchitecture.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_images/DriverArchitecture.png?rev=331981&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/5.0.2/tools/clang/docs/_images/DriverArchitecture.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/5.0.2/tools/clang/docs/_images/PCHLayout.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_images/PCHLayout.png?rev=331981&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/5.0.2/tools/clang/docs/_images/PCHLayout.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: www-releases/trunk/5.0.2/tools/clang/docs/_sources/AddressSanitizer.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_sources/AddressSanitizer.txt?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/_sources/AddressSanitizer.txt (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/_sources/AddressSanitizer.txt Thu May 10 06:54:16 2018
@@ -0,0 +1,288 @@
+================
+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;
+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/5.0.2/tools/clang/docs/_sources/AttributeReference.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_sources/AttributeReference.txt?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/_sources/AttributeReference.txt (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/_sources/AttributeReference.txt Thu May 10 06:54:16 2018
@@ -0,0 +1,3471 @@
+..
+ -------------------------------------------------------------------
+ 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
+===================
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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.
+
+
+signal
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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.
+
+
+abi_tag (gnu::abi_tag)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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", "__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", "__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``.
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","", "", ""
+
+Clang supports the GNU style ``__attribute__((interrupt))`` attribute on
+x86/x86-64 targets.The compiler generates function entry and exit sequences
+suitable for use in an interrupt handler when this attribute is present.
+The 'IRET' instruction, instead of the 'RET' instruction, is used to return
+from interrupt or exception handlers. All registers, except for the EFLAGS
+register which is restored by the 'IRET' instruction, are preserved by the
+compiler.
+
+Any interruptible-without-stack-switch code must be compiled with
+-mno-red-zone since interrupt handlers can and will, because of the
+hardware design, touch the red zone.
+
+1. interrupt handler must be declared with a mandatory pointer argument:
+
+ .. code-block:: c
+
+ struct interrupt_frame
+ {
+ uword_t ip;
+ uword_t cs;
+ uword_t flags;
+ uword_t sp;
+ uword_t ss;
+ };
+
+ __attribute__ ((interrupt))
+ void f (struct interrupt_frame *frame) {
+ ...
+ }
+
+2. exception handler:
+
+ The exception handler is very similar to the interrupt handler with
+ a different mandatory function signature:
+
+ .. code-block:: c
+
+ __attribute__ ((interrupt))
+ void f (struct interrupt_frame *frame, uword_t error_code) {
+ ...
+ }
+
+ and compiler pops 'ERROR_CODE' off stack before the 'IRET' instruction.
+
+ The exception handler should only be used for exceptions which push an
+ error code and all other exceptions must use the interrupt handler.
+ The system will crash if the wrong handler is used.
+
+
+no_caller_saved_registers (gnu::no_caller_saved_registers)
+----------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)
+-------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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", "__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>`_
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "__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", "__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", "__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", "__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", "__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.
+
+
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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", "__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.
+
+
+micromips (gnu::micromips)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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".
+
+
+noalias
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+noduplicate (clang::noduplicate)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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_sanitize (clang::no_sanitize)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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_thread
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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_sanitize_memory
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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_split_stack (gnu::no_split_stack)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+not_tail_called (clang::not_tail_called)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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;
+ };
+
+
+#pragma omp declare simd
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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:: c
+
+ #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:: c
+
+ 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", "__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
+
+
+objc_boxable
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "__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
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","X","","", "", ""
+
+Marks a function as releasing a capability.
+
+
+kernel
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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
+
+
+target (gnu::target)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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).
+
+
+nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result
+---------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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.
+
+
+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", "__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", "__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", "__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", "__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", "__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
+
+
+nodebug (gnu::nodebug)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+nosvm
+-----
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "__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", "__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.
+
+
+swiftcall (gnu::swiftcall)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+swift_context (gnu::swift_context)
+----------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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 (gnu::swift_error_result)
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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 (gnu::swift_indirect_result)
+--------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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).
+
+
+tls_model (gnu::tls_model)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+thread
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+maybe_unused, unused, gnu::unused
+---------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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);
+ }
+
+
+Type Attributes
+===============
+
+
+align_value
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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", "__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
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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.
+
+
+lto_visibility_public (clang::lto_visibility_public)
+----------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","X","","", "", "X"
+
+See :doc:`LTOVisibility`.
+
+
+layout_version
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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 {};
+
+
+novtable
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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
+---------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","", "", "X"
+
+This attribute can be added to an Objective-C ``@interface`` declaration to
+ensure that this class cannot be subclassed.
+
+
+transparent_union (gnu::transparent_union)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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
+====================
+
+
+fallthrough, clang::fallthrough
+-------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "","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();
+ }
+
+
+#pragma clang loop
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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.
+
+
+__read_only, __write_only, __read_write (read_only, write_only, read_write)
+---------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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.
+
+
+__attribute__((intel_reqd_sub_group_size))
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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.
+
+
+suppress (gsl::suppress)
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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
+
+
+Consumed Annotation Checking
+============================
+Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although **the implementation
+for these annotations is currently in development and are subject to change.**
+
+callable_when
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "X","","","", "", "X"
+
+Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
+returns true if the object is in the specified state..
+
+
+AMD GPU Attributes
+==================
+
+
+amdgpu_flat_work_group_size
+---------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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.
+
+
+Calling Conventions
+===================
+Clang supports several different calling conventions, depending on the target
+platform and architecture. The calling convention used for a function determines
+how parameters are passed, how results are returned to the caller, and other
+low-level details of calling a function.
+
+fastcall (gnu::fastcall, __fastcall, _fastcall)
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "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", "__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", "__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
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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", "__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", "__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", "__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", "__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 (__vectorcall, _vectorcall)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+ "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
+
+
+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", "__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", "__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", "__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", "__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", "__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", "__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", "__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", "__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 (gnu::nonnull)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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
+
+
+_Nonnull
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__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", "__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", "__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.
+
+
Added: www-releases/trunk/5.0.2/tools/clang/docs/_sources/AutomaticReferenceCounting.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_sources/AutomaticReferenceCounting.txt?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/_sources/AutomaticReferenceCounting.txt (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/_sources/AutomaticReferenceCounting.txt Thu May 10 06:54:16 2018
@@ -0,0 +1,2288 @@
+.. FIXME: move to the stylesheet or Sphinx plugin
+
+.. raw:: html
+
+ <style>
+ .arc-term { font-style: italic; font-weight: bold; }
+ .revision { font-style: italic; }
+ .when-revised { font-weight: bold; font-style: normal; }
+
+ /*
+ * Automatic numbering is described in this article:
+ * http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
+ */
+ /*
+ * Automatic numbering for the TOC.
+ * This is wrong from the semantics point of view, since it is an ordered
+ * list, but uses "ul" tag.
+ */
+ div#contents.contents.local ul {
+ counter-reset: toc-section;
+ list-style-type: none;
+ }
+ div#contents.contents.local ul li {
+ counter-increment: toc-section;
+ background: none; // Remove bullets
+ }
+ div#contents.contents.local ul li a.reference:before {
+ content: counters(toc-section, ".") " ";
+ }
+
+ /* Automatic numbering for the body. */
+ body {
+ counter-reset: section subsection subsubsection;
+ }
+ .section h2 {
+ counter-reset: subsection subsubsection;
+ counter-increment: section;
+ }
+ .section h2 a.toc-backref:before {
+ content: counter(section) " ";
+ }
+ .section h3 {
+ counter-reset: subsubsection;
+ counter-increment: subsection;
+ }
+ .section h3 a.toc-backref:before {
+ content: counter(section) "." counter(subsection) " ";
+ }
+ .section h4 {
+ counter-increment: subsubsection;
+ }
+ .section h4 a.toc-backref:before {
+ content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
+ }
+ </style>
+
+.. role:: arc-term
+.. role:: revision
+.. role:: when-revised
+
+==============================================
+Objective-C Automatic Reference Counting (ARC)
+==============================================
+
+.. contents::
+ :local:
+
+.. _arc.meta:
+
+About this document
+===================
+
+.. _arc.meta.purpose:
+
+Purpose
+-------
+
+The first and primary purpose of this document is to serve as a complete
+technical specification of Automatic Reference Counting. Given a core
+Objective-C compiler and runtime, it should be possible to write a compiler and
+runtime which implements these new semantics.
+
+The secondary purpose is to act as a rationale for why ARC was designed in this
+way. This should remain tightly focused on the technical design and should not
+stray into marketing speculation.
+
+.. _arc.meta.background:
+
+Background
+----------
+
+This document assumes a basic familiarity with C.
+
+:arc-term:`Blocks` are a C language extension for creating anonymous functions.
+Users interact with and transfer block objects using :arc-term:`block
+pointers`, which are represented like a normal pointer. A block may capture
+values from local variables; when this occurs, memory must be dynamically
+allocated. The initial allocation is done on the stack, but the runtime
+provides a ``Block_copy`` function which, given a block pointer, either copies
+the underlying block object to the heap, setting its reference count to 1 and
+returning the new block pointer, or (if the block object is already on the
+heap) increases its reference count by 1. The paired function is
+``Block_release``, which decreases the reference count by 1 and destroys the
+object if the count reaches zero and is on the heap.
+
+Objective-C is a set of language extensions, significant enough to be
+considered a different language. It is a strict superset of C. The extensions
+can also be imposed on C++, producing a language called Objective-C++. The
+primary feature is a single-inheritance object system; we briefly describe the
+modern dialect.
+
+Objective-C defines a new type kind, collectively called the :arc-term:`object
+pointer types`. This kind has two notable builtin members, ``id`` and
+``Class``; ``id`` is the final supertype of all object pointers. The validity
+of conversions between object pointer types is not checked at runtime. Users
+may define :arc-term:`classes`; each class is a type, and the pointer to that
+type is an object pointer type. A class may have a superclass; its pointer
+type is a subtype of its superclass's pointer type. A class has a set of
+:arc-term:`ivars`, fields which appear on all instances of that class. For
+every class *T* there's an associated metaclass; it has no fields, its
+superclass is the metaclass of *T*'s superclass, and its metaclass is a global
+class. Every class has a global object whose class is the class's metaclass;
+metaclasses have no associated type, so pointers to this object have type
+``Class``.
+
+A class declaration (``@interface``) declares a set of :arc-term:`methods`. A
+method has a return type, a list of argument types, and a :arc-term:`selector`:
+a name like ``foo:bar:baz:``, where the number of colons corresponds to the
+number of formal arguments. A method may be an instance method, in which case
+it can be invoked on objects of the class, or a class method, in which case it
+can be invoked on objects of the metaclass. A method may be invoked by
+providing an object (called the :arc-term:`receiver`) and a list of formal
+arguments interspersed with the selector, like so:
+
+.. code-block:: objc
+
+ [receiver foo: fooArg bar: barArg baz: bazArg]
+
+This looks in the dynamic class of the receiver for a method with this name,
+then in that class's superclass, etc., until it finds something it can execute.
+The receiver "expression" may also be the name of a class, in which case the
+actual receiver is the class object for that class, or (within method
+definitions) it may be ``super``, in which case the lookup algorithm starts
+with the static superclass instead of the dynamic class. The actual methods
+dynamically found in a class are not those declared in the ``@interface``, but
+those defined in a separate ``@implementation`` declaration; however, when
+compiling a call, typechecking is done based on the methods declared in the
+``@interface``.
+
+Method declarations may also be grouped into :arc-term:`protocols`, which are not
+inherently associated with any class, but which classes may claim to follow.
+Object pointer types may be qualified with additional protocols that the object
+is known to support.
+
+:arc-term:`Class extensions` are collections of ivars and methods, designed to
+allow a class's ``@interface`` to be split across multiple files; however,
+there is still a primary implementation file which must see the
+``@interface``\ s of all class extensions. :arc-term:`Categories` allow
+methods (but not ivars) to be declared *post hoc* on an arbitrary class; the
+methods in the category's ``@implementation`` will be dynamically added to that
+class's method tables which the category is loaded at runtime, replacing those
+methods in case of a collision.
+
+In the standard environment, objects are allocated on the heap, and their
+lifetime is manually managed using a reference count. This is done using two
+instance methods which all classes are expected to implement: ``retain``
+increases the object's reference count by 1, whereas ``release`` decreases it
+by 1 and calls the instance method ``dealloc`` if the count reaches 0. To
+simplify certain operations, there is also an :arc-term:`autorelease pool`, a
+thread-local list of objects to call ``release`` on later; an object can be
+added to this pool by calling ``autorelease`` on it.
+
+Block pointers may be converted to type ``id``; block objects are laid out in a
+way that makes them compatible with Objective-C objects. There is a builtin
+class that all block objects are considered to be objects of; this class
+implements ``retain`` by adjusting the reference count, not by calling
+``Block_copy``.
+
+.. _arc.meta.evolution:
+
+Evolution
+---------
+
+ARC is under continual evolution, and this document must be updated as the
+language progresses.
+
+If a change increases the expressiveness of the language, for example by
+lifting a restriction or by adding new syntax, the change will be annotated
+with a revision marker, like so:
+
+ ARC applies to Objective-C pointer types, block pointer types, and
+ :when-revised:`[beginning Apple 8.0, LLVM 3.8]` :revision:`BPTRs declared
+ within` ``extern "BCPL"`` blocks.
+
+For now, it is sensible to version this document by the releases of its sole
+implementation (and its host project), clang. "LLVM X.Y" refers to an
+open-source release of clang from the LLVM project. "Apple X.Y" refers to an
+Apple-provided release of the Apple LLVM Compiler. Other organizations that
+prepare their own, separately-versioned clang releases and wish to maintain
+similar information in this document should send requests to cfe-dev.
+
+If a change decreases the expressiveness of the language, for example by
+imposing a new restriction, this should be taken as an oversight in the
+original specification and something to be avoided in all versions. Such
+changes are generally to be avoided.
+
+.. _arc.general:
+
+General
+=======
+
+Automatic Reference Counting implements automatic memory management for
+Objective-C objects and blocks, freeing the programmer from the need to
+explicitly insert retains and releases. It does not provide a cycle collector;
+users must explicitly manage the lifetime of their objects, breaking cycles
+manually or with weak or unsafe references.
+
+ARC may be explicitly enabled with the compiler flag ``-fobjc-arc``. It may
+also be explicitly disabled with the compiler flag ``-fno-objc-arc``. The last
+of these two flags appearing on the compile line "wins".
+
+If ARC is enabled, ``__has_feature(objc_arc)`` will expand to 1 in the
+preprocessor. For more information about ``__has_feature``, see the
+:ref:`language extensions <langext-__has_feature-__has_extension>` document.
+
+.. _arc.objects:
+
+Retainable object pointers
+==========================
+
+This section describes retainable object pointers, their basic operations, and
+the restrictions imposed on their use under ARC. Note in particular that it
+covers the rules for pointer *values* (patterns of bits indicating the location
+of a pointed-to object), not pointer *objects* (locations in memory which store
+pointer values). The rules for objects are covered in the next section.
+
+A :arc-term:`retainable object pointer` (or "retainable pointer") is a value of
+a :arc-term:`retainable object pointer type` ("retainable type"). There are
+three kinds of retainable object pointer types:
+
+* block pointers (formed by applying the caret (``^``) declarator sigil to a
+ function type)
+* Objective-C object pointers (``id``, ``Class``, ``NSFoo*``, etc.)
+* typedefs marked with ``__attribute__((NSObject))``
+
+Other pointer types, such as ``int*`` and ``CFStringRef``, are not subject to
+ARC's semantics and restrictions.
+
+.. admonition:: Rationale
+
+ We are not at liberty to require all code to be recompiled with ARC;
+ therefore, ARC must interoperate with Objective-C code which manages retains
+ and releases manually. In general, there are three requirements in order for
+ a compiler-supported reference-count system to provide reliable
+ interoperation:
+
+ * The type system must reliably identify which objects are to be managed. An
+ ``int*`` might be a pointer to a ``malloc``'ed array, or it might be an
+ interior pointer to such an array, or it might point to some field or local
+ variable. In contrast, values of the retainable object pointer types are
+ never interior.
+
+ * The type system must reliably indicate how to manage objects of a type.
+ This usually means that the type must imply a procedure for incrementing
+ and decrementing retain counts. Supporting single-ownership objects
+ requires a lot more explicit mediation in the language.
+
+ * There must be reliable conventions for whether and when "ownership" is
+ passed between caller and callee, for both arguments and return values.
+ Objective-C methods follow such a convention very reliably, at least for
+ system libraries on Mac OS X, and functions always pass objects at +0. The
+ C-based APIs for Core Foundation objects, on the other hand, have much more
+ varied transfer semantics.
+
+The use of ``__attribute__((NSObject))`` typedefs is not recommended. If it's
+absolutely necessary to use this attribute, be very explicit about using the
+typedef, and do not assume that it will be preserved by language features like
+``__typeof`` and C++ template argument substitution.
+
+.. admonition:: Rationale
+
+ Any compiler operation which incidentally strips type "sugar" from a type
+ will yield a type without the attribute, which may result in unexpected
+ behavior.
+
+.. _arc.objects.retains:
+
+Retain count semantics
+----------------------
+
+A retainable object pointer is either a :arc-term:`null pointer` or a pointer
+to a valid object. Furthermore, if it has block pointer type and is not
+``null`` then it must actually be a pointer to a block object, and if it has
+``Class`` type (possibly protocol-qualified) then it must actually be a pointer
+to a class object. Otherwise ARC does not enforce the Objective-C type system
+as long as the implementing methods follow the signature of the static type.
+It is undefined behavior if ARC is exposed to an invalid pointer.
+
+For ARC's purposes, a valid object is one with "well-behaved" retaining
+operations. Specifically, the object must be laid out such that the
+Objective-C message send machinery can successfully send it the following
+messages:
+
+* ``retain``, taking no arguments and returning a pointer to the object.
+* ``release``, taking no arguments and returning ``void``.
+* ``autorelease``, taking no arguments and returning a pointer to the object.
+
+The behavior of these methods is constrained in the following ways. The term
+:arc-term:`high-level semantics` is an intentionally vague term; the intent is
+that programmers must implement these methods in a way such that the compiler,
+modifying code in ways it deems safe according to these constraints, will not
+violate their requirements. For example, if the user puts logging statements
+in ``retain``, they should not be surprised if those statements are executed
+more or less often depending on optimization settings. These constraints are
+not exhaustive of the optimization opportunities: values held in local
+variables are subject to additional restrictions, described later in this
+document.
+
+It is undefined behavior if a computation history featuring a send of
+``retain`` followed by a send of ``release`` to the same object, with no
+intervening ``release`` on that object, is not equivalent under the high-level
+semantics to a computation history in which these sends are removed. Note that
+this implies that these methods may not raise exceptions.
+
+It is undefined behavior if a computation history features any use whatsoever
+of an object following the completion of a send of ``release`` that is not
+preceded by a send of ``retain`` to the same object.
+
+The behavior of ``autorelease`` must be equivalent to sending ``release`` when
+one of the autorelease pools currently in scope is popped. It may not throw an
+exception.
+
+When the semantics call for performing one of these operations on a retainable
+object pointer, if that pointer is ``null`` then the effect is a no-op.
+
+All of the semantics described in this document are subject to additional
+:ref:`optimization rules <arc.optimization>` which permit the removal or
+optimization of operations based on local knowledge of data flow. The
+semantics describe the high-level behaviors that the compiler implements, not
+an exact sequence of operations that a program will be compiled into.
+
+.. _arc.objects.operands:
+
+Retainable object pointers as operands and arguments
+----------------------------------------------------
+
+In general, ARC does not perform retain or release operations when simply using
+a retainable object pointer as an operand within an expression. This includes:
+
+* loading a retainable pointer from an object with non-weak :ref:`ownership
+ <arc.ownership>`,
+* passing a retainable pointer as an argument to a function or method, and
+* receiving a retainable pointer as the result of a function or method call.
+
+.. admonition:: Rationale
+
+ While this might seem uncontroversial, it is actually unsafe when multiple
+ expressions are evaluated in "parallel", as with binary operators and calls,
+ because (for example) one expression might load from an object while another
+ writes to it. However, C and C++ already call this undefined behavior
+ because the evaluations are unsequenced, and ARC simply exploits that here to
+ avoid needing to retain arguments across a large number of calls.
+
+The remainder of this section describes exceptions to these rules, how those
+exceptions are detected, and what those exceptions imply semantically.
+
+.. _arc.objects.operands.consumed:
+
+Consumed parameters
+^^^^^^^^^^^^^^^^^^^
+
+A function or method parameter of retainable object pointer type may be marked
+as :arc-term:`consumed`, signifying that the callee expects to take ownership
+of a +1 retain count. This is done by adding the ``ns_consumed`` attribute to
+the parameter declaration, like so:
+
+.. code-block:: objc
+
+ void foo(__attribute((ns_consumed)) id x);
+ - (void) foo: (id) __attribute((ns_consumed)) x;
+
+This attribute is part of the type of the function or method, not the type of
+the parameter. It controls only how the argument is passed and received.
+
+When passing such an argument, ARC retains the argument prior to making the
+call.
+
+When receiving such an argument, ARC releases the argument at the end of the
+function, subject to the usual optimizations for local values.
+
+.. admonition:: Rationale
+
+ This formalizes direct transfers of ownership from a caller to a callee. The
+ most common scenario here is passing the ``self`` parameter to ``init``, but
+ it is useful to generalize. Typically, local optimization will remove any
+ extra retains and releases: on the caller side the retain will be merged with
+ a +1 source, and on the callee side the release will be rolled into the
+ initialization of the parameter.
+
+The implicit ``self`` parameter of a method may be marked as consumed by adding
+``__attribute__((ns_consumes_self))`` to the method declaration. Methods in
+the ``init`` :ref:`family <arc.method-families>` are treated as if they were
+implicitly marked with this attribute.
+
+It is undefined behavior if an Objective-C message send to a method with
+``ns_consumed`` parameters (other than self) is made with a null receiver. It
+is undefined behavior if the method to which an Objective-C message send
+statically resolves to has a different set of ``ns_consumed`` parameters than
+the method it dynamically resolves to. It is undefined behavior if a block or
+function call is made through a static type with a different set of
+``ns_consumed`` parameters than the implementation of the called block or
+function.
+
+.. admonition:: Rationale
+
+ Consumed parameters with null receiver are a guaranteed leak. Mismatches
+ with consumed parameters will cause over-retains or over-releases, depending
+ on the direction. The rule about function calls is really just an
+ application of the existing C/C++ rule about calling functions through an
+ incompatible function type, but it's useful to state it explicitly.
+
+.. _arc.object.operands.retained-return-values:
+
+Retained return values
+^^^^^^^^^^^^^^^^^^^^^^
+
+A function or method which returns a retainable object pointer type may be
+marked as returning a retained value, signifying that the caller expects to take
+ownership of a +1 retain count. This is done by adding the
+``ns_returns_retained`` attribute to the function or method declaration, like
+so:
+
+.. code-block:: objc
+
+ id foo(void) __attribute((ns_returns_retained));
+ - (id) foo __attribute((ns_returns_retained));
+
+This attribute is part of the type of the function or method.
+
+When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, before leaving all local scopes.
+
+When receiving a return result from such a function or method, ARC releases the
+value at the end of the full-expression it is contained within, subject to the
+usual optimizations for local values.
+
+.. admonition:: Rationale
+
+ This formalizes direct transfers of ownership from a callee to a caller. The
+ most common scenario this models is the retained return from ``init``,
+ ``alloc``, ``new``, and ``copy`` methods, but there are other cases in the
+ frameworks. After optimization there are typically no extra retains and
+ releases required.
+
+Methods in the ``alloc``, ``copy``, ``init``, ``mutableCopy``, and ``new``
+:ref:`families <arc.method-families>` are implicitly marked
+``__attribute__((ns_returns_retained))``. This may be suppressed by explicitly
+marking the method ``__attribute__((ns_returns_not_retained))``.
+
+It is undefined behavior if the method to which an Objective-C message send
+statically resolves has different retain semantics on its result from the
+method it dynamically resolves to. It is undefined behavior if a block or
+function call is made through a static type with different retain semantics on
+its result from the implementation of the called block or function.
+
+.. admonition:: Rationale
+
+ Mismatches with returned results will cause over-retains or over-releases,
+ depending on the direction. Again, the rule about function calls is really
+ just an application of the existing C/C++ rule about calling functions
+ through an incompatible function type.
+
+.. _arc.objects.operands.unretained-returns:
+
+Unretained return values
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A method or function which returns a retainable object type but does not return
+a retained value must ensure that the object is still valid across the return
+boundary.
+
+When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, then leaves all local scopes, and
+then balances out the retain while ensuring that the value lives across the
+call boundary. In the worst case, this may involve an ``autorelease``, but
+callers must not assume that the value is actually in the autorelease pool.
+
+ARC performs no extra mandatory work on the caller side, although it may elect
+to do something to shorten the lifetime of the returned value.
+
+.. admonition:: Rationale
+
+ It is common in non-ARC code to not return an autoreleased value; therefore
+ the convention does not force either path. It is convenient to not be
+ required to do unnecessary retains and autoreleases; this permits
+ optimizations such as eliding retain/autoreleases when it can be shown that
+ the original pointer will still be valid at the point of return.
+
+A method or function may be marked with
+``__attribute__((ns_returns_autoreleased))`` to indicate that it returns a
+pointer which is guaranteed to be valid at least as long as the innermost
+autorelease pool. There are no additional semantics enforced in the definition
+of such a method; it merely enables optimizations in callers.
+
+.. _arc.objects.operands.casts:
+
+Bridged casts
+^^^^^^^^^^^^^
+
+A :arc-term:`bridged cast` is a C-style cast annotated with one of three
+keywords:
+
+* ``(__bridge T) op`` casts the operand to the destination type ``T``. If
+ ``T`` is a retainable object pointer type, then ``op`` must have a
+ non-retainable pointer type. If ``T`` is a non-retainable pointer type,
+ then ``op`` must have a retainable object pointer type. Otherwise the cast
+ is ill-formed. There is no transfer of ownership, and ARC inserts no retain
+ operations.
+* ``(__bridge_retained T) op`` casts the operand, which must have retainable
+ object pointer type, to the destination type, which must be a non-retainable
+ pointer type. ARC retains the value, subject to the usual optimizations on
+ local values, and the recipient is responsible for balancing that +1.
+* ``(__bridge_transfer T) op`` casts the operand, which must have
+ non-retainable pointer type, to the destination type, which must be a
+ retainable object pointer type. ARC will release the value at the end of
+ the enclosing full-expression, subject to the usual optimizations on local
+ values.
+
+These casts are required in order to transfer objects in and out of ARC
+control; see the rationale in the section on :ref:`conversion of retainable
+object pointers <arc.objects.restrictions.conversion>`.
+
+Using a ``__bridge_retained`` or ``__bridge_transfer`` cast purely to convince
+ARC to emit an unbalanced retain or release, respectively, is poor form.
+
+.. _arc.objects.restrictions:
+
+Restrictions
+------------
+
+.. _arc.objects.restrictions.conversion:
+
+Conversion of retainable object pointers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In general, a program which attempts to implicitly or explicitly convert a
+value of retainable object pointer type to any non-retainable type, or
+vice-versa, is ill-formed. For example, an Objective-C object pointer shall
+not be converted to ``void*``. As an exception, cast to ``intptr_t`` is
+allowed because such casts are not transferring ownership. The :ref:`bridged
+casts <arc.objects.operands.casts>` may be used to perform these conversions
+where necessary.
+
+.. admonition:: Rationale
+
+ We cannot ensure the correct management of the lifetime of objects if they
+ may be freely passed around as unmanaged types. The bridged casts are
+ provided so that the programmer may explicitly describe whether the cast
+ transfers control into or out of ARC.
+
+However, the following exceptions apply.
+
+.. _arc.objects.restrictions.conversion.with.known.semantics:
+
+Conversion to retainable object pointer type of expressions with known semantics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+:revision:`These exceptions have been greatly expanded; they previously applied
+only to a much-reduced subset which is difficult to categorize but which
+included null pointers, message sends (under the given rules), and the various
+global constants.`
+
+An unbridged conversion to a retainable object pointer type from a type other
+than a retainable object pointer type is ill-formed, as discussed above, unless
+the operand of the cast has a syntactic form which is known retained, known
+unretained, or known retain-agnostic.
+
+An expression is :arc-term:`known retain-agnostic` if it is:
+
+* an Objective-C string literal,
+* a load from a ``const`` system global variable of :ref:`C retainable pointer
+ type <arc.misc.c-retainable>`, or
+* a null pointer constant.
+
+An expression is :arc-term:`known unretained` if it is an rvalue of :ref:`C
+retainable pointer type <arc.misc.c-retainable>` and it is:
+
+* a direct call to a function, and either that function has the
+ ``cf_returns_not_retained`` attribute or it is an :ref:`audited
+ <arc.misc.c-retainable.audit>` function that does not have the
+ ``cf_returns_retained`` attribute and does not follow the create/copy naming
+ convention,
+* a message send, and the declared method either has the
+ ``cf_returns_not_retained`` attribute or it has neither the
+ ``cf_returns_retained`` attribute nor a :ref:`selector family
+ <arc.method-families>` that implies a retained result, or
+* :when-revised:`[beginning LLVM 3.6]` :revision:`a load from a` ``const``
+ :revision:`non-system global variable.`
+
+An expression is :arc-term:`known retained` if it is an rvalue of :ref:`C
+retainable pointer type <arc.misc.c-retainable>` and it is:
+
+* a message send, and the declared method either has the
+ ``cf_returns_retained`` attribute, or it does not have the
+ ``cf_returns_not_retained`` attribute but it does have a :ref:`selector
+ family <arc.method-families>` that implies a retained result.
+
+Furthermore:
+
+* a comma expression is classified according to its right-hand side,
+* a statement expression is classified according to its result expression, if
+ it has one,
+* an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
+ classified according to the underlying message send, and
+* a conditional operator is classified according to its second and third
+ operands, if they agree in classification, or else the other if one is known
+ retain-agnostic.
+
+If the cast operand is known retained, the conversion is treated as a
+``__bridge_transfer`` cast. If the cast operand is known unretained or known
+retain-agnostic, the conversion is treated as a ``__bridge`` cast.
+
+.. admonition:: Rationale
+
+ Bridging casts are annoying. Absent the ability to completely automate the
+ management of CF objects, however, we are left with relatively poor attempts
+ to reduce the need for a glut of explicit bridges. Hence these rules.
+
+ We've so far consciously refrained from implicitly turning retained CF
+ results from function calls into ``__bridge_transfer`` casts. The worry is
+ that some code patterns --- for example, creating a CF value, assigning it
+ to an ObjC-typed local, and then calling ``CFRelease`` when done --- are a
+ bit too likely to be accidentally accepted, leading to mysterious behavior.
+
+ For loads from ``const`` global variables of :ref:`C retainable pointer type
+ <arc.misc.c-retainable>`, it is reasonable to assume that global system
+ constants were initialitzed with true constants (e.g. string literals), but
+ user constants might have been initialized with something dynamically
+ allocated, using a global initializer.
+
+.. _arc.objects.restrictions.conversion-exception-contextual:
+
+Conversion from retainable object pointer type in certain contexts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+
+If an expression of retainable object pointer type is explicitly cast to a
+:ref:`C retainable pointer type <arc.misc.c-retainable>`, the program is
+ill-formed as discussed above unless the result is immediately used:
+
+* to initialize a parameter in an Objective-C message send where the parameter
+ is not marked with the ``cf_consumed`` attribute, or
+* to initialize a parameter in a direct call to an
+ :ref:`audited <arc.misc.c-retainable.audit>` function where the parameter is
+ not marked with the ``cf_consumed`` attribute.
+
+.. admonition:: Rationale
+
+ Consumed parameters are left out because ARC would naturally balance them
+ with a retain, which was judged too treacherous. This is in part because
+ several of the most common consuming functions are in the ``Release`` family,
+ and it would be quite unfortunate for explicit releases to be silently
+ balanced out in this way.
+
+.. _arc.ownership:
+
+Ownership qualification
+=======================
+
+This section describes the behavior of *objects* of retainable object pointer
+type; that is, locations in memory which store retainable object pointers.
+
+A type is a :arc-term:`retainable object owner type` if it is a retainable
+object pointer type or an array type whose element type is a retainable object
+owner type.
+
+An :arc-term:`ownership qualifier` is a type qualifier which applies only to
+retainable object owner types. An array type is ownership-qualified according
+to its element type, and adding an ownership qualifier to an array type so
+qualifies its element type.
+
+A program is ill-formed if it attempts to apply an ownership qualifier to a
+type which is already ownership-qualified, even if it is the same qualifier.
+There is a single exception to this rule: an ownership qualifier may be applied
+to a substituted template type parameter, which overrides the ownership
+qualifier provided by the template argument.
+
+When forming a function type, the result type is adjusted so that any
+top-level ownership qualifier is deleted.
+
+Except as described under the :ref:`inference rules <arc.ownership.inference>`,
+a program is ill-formed if it attempts to form a pointer or reference type to a
+retainable object owner type which lacks an ownership qualifier.
+
+.. admonition:: Rationale
+
+ These rules, together with the inference rules, ensure that all objects and
+ lvalues of retainable object pointer type have an ownership qualifier. The
+ ability to override an ownership qualifier during template substitution is
+ required to counteract the :ref:`inference of __strong for template type
+ arguments <arc.ownership.inference.template.arguments>`. Ownership qualifiers
+ on return types are dropped because they serve no purpose there except to
+ cause spurious problems with overloading and templates.
+
+There are four ownership qualifiers:
+
+* ``__autoreleasing``
+* ``__strong``
+* ``__unsafe_unretained``
+* ``__weak``
+
+A type is :arc-term:`nontrivially ownership-qualified` if it is qualified with
+``__autoreleasing``, ``__strong``, or ``__weak``.
+
+.. _arc.ownership.spelling:
+
+Spelling
+--------
+
+The names of the ownership qualifiers are reserved for the implementation. A
+program may not assume that they are or are not implemented with macros, or
+what those macros expand to.
+
+An ownership qualifier may be written anywhere that any other type qualifier
+may be written.
+
+If an ownership qualifier appears in the *declaration-specifiers*, the
+following rules apply:
+
+* if the type specifier is a retainable object owner type, the qualifier
+ initially applies to that type;
+
+* otherwise, if the outermost non-array declarator is a pointer
+ or block pointer declarator, the qualifier initially applies to
+ that type;
+
+* otherwise the program is ill-formed.
+
+* If the qualifier is so applied at a position in the declaration
+ where the next-innermost declarator is a function declarator, and
+ there is an block declarator within that function declarator, then
+ the qualifier applies instead to that block declarator and this rule
+ is considered afresh beginning from the new position.
+
+If an ownership qualifier appears on the declarator name, or on the declared
+object, it is applied to the innermost pointer or block-pointer type.
+
+If an ownership qualifier appears anywhere else in a declarator, it applies to
+the type there.
+
+.. admonition:: Rationale
+
+ Ownership qualifiers are like ``const`` and ``volatile`` in the sense
+ that they may sensibly apply at multiple distinct positions within a
+ declarator. However, unlike those qualifiers, there are many
+ situations where they are not meaningful, and so we make an effort
+ to "move" the qualifier to a place where it will be meaningful. The
+ general goal is to allow the programmer to write, say, ``__strong``
+ before the entire declaration and have it apply in the leftmost
+ sensible place.
+
+.. _arc.ownership.spelling.property:
+
+Property declarations
+^^^^^^^^^^^^^^^^^^^^^
+
+A property of retainable object pointer type may have ownership. If the
+property's type is ownership-qualified, then the property has that ownership.
+If the property has one of the following modifiers, then the property has the
+corresponding ownership. A property is ill-formed if it has conflicting
+sources of ownership, or if it has redundant ownership modifiers, or if it has
+``__autoreleasing`` ownership.
+
+* ``assign`` implies ``__unsafe_unretained`` ownership.
+* ``copy`` implies ``__strong`` ownership, as well as the usual behavior of
+ copy semantics on the setter.
+* ``retain`` implies ``__strong`` ownership.
+* ``strong`` implies ``__strong`` ownership.
+* ``unsafe_unretained`` implies ``__unsafe_unretained`` ownership.
+* ``weak`` implies ``__weak`` ownership.
+
+With the exception of ``weak``, these modifiers are available in non-ARC
+modes.
+
+A property's specified ownership is preserved in its metadata, but otherwise
+the meaning is purely conventional unless the property is synthesized. If a
+property is synthesized, then the :arc-term:`associated instance variable` is
+the instance variable which is named, possibly implicitly, by the
+``@synthesize`` declaration. If the associated instance variable already
+exists, then its ownership qualification must equal the ownership of the
+property; otherwise, the instance variable is created with that ownership
+qualification.
+
+A property of retainable object pointer type which is synthesized without a
+source of ownership has the ownership of its associated instance variable, if it
+already exists; otherwise, :when-revised:`[beginning Apple 3.1, LLVM 3.1]`
+:revision:`its ownership is implicitly` ``strong``. Prior to this revision, it
+was ill-formed to synthesize such a property.
+
+.. admonition:: Rationale
+
+ Using ``strong`` by default is safe and consistent with the generic ARC rule
+ about :ref:`inferring ownership <arc.ownership.inference.variables>`. It is,
+ unfortunately, inconsistent with the non-ARC rule which states that such
+ properties are implicitly ``assign``. However, that rule is clearly
+ untenable in ARC, since it leads to default-unsafe code. The main merit to
+ banning the properties is to avoid confusion with non-ARC practice, which did
+ not ultimately strike us as sufficient to justify requiring extra syntax and
+ (more importantly) forcing novices to understand ownership rules just to
+ declare a property when the default is so reasonable. Changing the rule away
+ from non-ARC practice was acceptable because we had conservatively banned the
+ synthesis in order to give ourselves exactly this leeway.
+
+Applying ``__attribute__((NSObject))`` to a property not of retainable object
+pointer type has the same behavior it does outside of ARC: it requires the
+property type to be some sort of pointer and permits the use of modifiers other
+than ``assign``. These modifiers only affect the synthesized getter and
+setter; direct accesses to the ivar (even if synthesized) still have primitive
+semantics, and the value in the ivar will not be automatically released during
+deallocation.
+
+.. _arc.ownership.semantics:
+
+Semantics
+---------
+
+There are five :arc-term:`managed operations` which may be performed on an
+object of retainable object pointer type. Each qualifier specifies different
+semantics for each of these operations. It is still undefined behavior to
+access an object outside of its lifetime.
+
+A load or store with "primitive semantics" has the same semantics as the
+respective operation would have on an ``void*`` lvalue with the same alignment
+and non-ownership qualification.
+
+:arc-term:`Reading` occurs when performing a lvalue-to-rvalue conversion on an
+object lvalue.
+
+* For ``__weak`` objects, the current pointee is retained and then released at
+ the end of the current full-expression. This must execute atomically with
+ respect to assignments and to the final release of the pointee.
+* For all other objects, the lvalue is loaded with primitive semantics.
+
+:arc-term:`Assignment` occurs when evaluating an assignment operator. The
+semantics vary based on the qualification:
+
+* For ``__strong`` objects, the new pointee is first retained; second, the
+ lvalue is loaded with primitive semantics; third, the new pointee is stored
+ into the lvalue with primitive semantics; and finally, the old pointee is
+ released. This is not performed atomically; external synchronization must be
+ used to make this safe in the face of concurrent loads and stores.
+* For ``__weak`` objects, the lvalue is updated to point to the new pointee,
+ unless the new pointee is an object currently undergoing deallocation, in
+ which case the lvalue is updated to a null pointer. This must execute
+ atomically with respect to other assignments to the object, to reads from the
+ object, and to the final release of the new pointee.
+* For ``__unsafe_unretained`` objects, the new pointee is stored into the
+ lvalue using primitive semantics.
+* For ``__autoreleasing`` objects, the new pointee is retained, autoreleased,
+ and stored into the lvalue using primitive semantics.
+
+:arc-term:`Initialization` occurs when an object's lifetime begins, which
+depends on its storage duration. Initialization proceeds in two stages:
+
+#. First, a null pointer is stored into the lvalue using primitive semantics.
+ This step is skipped if the object is ``__unsafe_unretained``.
+#. Second, if the object has an initializer, that expression is evaluated and
+ then assigned into the object using the usual assignment semantics.
+
+:arc-term:`Destruction` occurs when an object's lifetime ends. In all cases it
+is semantically equivalent to assigning a null pointer to the object, with the
+proviso that of course the object cannot be legally read after the object's
+lifetime ends.
+
+:arc-term:`Moving` occurs in specific situations where an lvalue is "moved
+from", meaning that its current pointee will be used but the object may be left
+in a different (but still valid) state. This arises with ``__block`` variables
+and rvalue references in C++. For ``__strong`` lvalues, moving is equivalent
+to loading the lvalue with primitive semantics, writing a null pointer to it
+with primitive semantics, and then releasing the result of the load at the end
+of the current full-expression. For all other lvalues, moving is equivalent to
+reading the object.
+
+.. _arc.ownership.restrictions:
+
+Restrictions
+------------
+
+.. _arc.ownership.restrictions.weak:
+
+Weak-unavailable types
+^^^^^^^^^^^^^^^^^^^^^^
+
+It is explicitly permitted for Objective-C classes to not support ``__weak``
+references. It is undefined behavior to perform an operation with weak
+assignment semantics with a pointer to an Objective-C object whose class does
+not support ``__weak`` references.
+
+.. admonition:: Rationale
+
+ Historically, it has been possible for a class to provide its own
+ reference-count implementation by overriding ``retain``, ``release``, etc.
+ However, weak references to an object require coordination with its class's
+ reference-count implementation because, among other things, weak loads and
+ stores must be atomic with respect to the final release. Therefore, existing
+ custom reference-count implementations will generally not support weak
+ references without additional effort. This is unavoidable without breaking
+ binary compatibility.
+
+A class may indicate that it does not support weak references by providing the
+``objc_arc_weak_reference_unavailable`` attribute on the class's interface declaration. A
+retainable object pointer type is **weak-unavailable** if
+is a pointer to an (optionally protocol-qualified) Objective-C class ``T`` where
+``T`` or one of its superclasses has the ``objc_arc_weak_reference_unavailable``
+attribute. A program is ill-formed if it applies the ``__weak`` ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.
+
+.. _arc.ownership.restrictions.autoreleasing:
+
+Storage duration of ``__autoreleasing`` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares an ``__autoreleasing`` object of
+non-automatic storage duration. A program is ill-formed if it captures an
+``__autoreleasing`` object in a block or, unless by reference, in a C++11
+lambda.
+
+.. admonition:: Rationale
+
+ Autorelease pools are tied to the current thread and scope by their nature.
+ While it is possible to have temporary objects whose instance variables are
+ filled with autoreleased objects, there is no way that ARC can provide any
+ sort of safety guarantee there.
+
+It is undefined behavior if a non-null pointer is assigned to an
+``__autoreleasing`` object while an autorelease pool is in scope and then that
+object is read after the autorelease pool's scope is left.
+
+.. _arc.ownership.restrictions.conversion.indirect:
+
+Conversion of pointers to ownership-qualified types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if an expression of type ``T*`` is converted,
+explicitly or implicitly, to the type ``U*``, where ``T`` and ``U`` have
+different ownership qualification, unless:
+
+* ``T`` is qualified with ``__strong``, ``__autoreleasing``, or
+ ``__unsafe_unretained``, and ``U`` is qualified with both ``const`` and
+ ``__unsafe_unretained``; or
+* either ``T`` or ``U`` is ``cv void``, where ``cv`` is an optional sequence
+ of non-ownership qualifiers; or
+* the conversion is requested with a ``reinterpret_cast`` in Objective-C++; or
+* the conversion is a well-formed :ref:`pass-by-writeback
+ <arc.ownership.restrictions.pass_by_writeback>`.
+
+The analogous rule applies to ``T&`` and ``U&`` in Objective-C++.
+
+.. admonition:: Rationale
+
+ These rules provide a reasonable level of type-safety for indirect pointers,
+ as long as the underlying memory is not deallocated. The conversion to
+ ``const __unsafe_unretained`` is permitted because the semantics of reads are
+ equivalent across all these ownership semantics, and that's a very useful and
+ common pattern. The interconversion with ``void*`` is useful for allocating
+ memory or otherwise escaping the type system, but use it carefully.
+ ``reinterpret_cast`` is considered to be an obvious enough sign of taking
+ responsibility for any problems.
+
+It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-``__weak`` object
+may be read through an ``__unsafe_unretained`` lvalue.
+
+It is undefined behavior if a managed operation is performed on a ``__strong``
+or ``__weak`` object without a guarantee that it contains a primitive zero
+bit-pattern, or if the storage for such an object is freed or reused without the
+object being first assigned a null pointer.
+
+.. admonition:: Rationale
+
+ ARC cannot differentiate between an assignment operator which is intended to
+ "initialize" dynamic memory and one which is intended to potentially replace
+ a value. Therefore the object's pointer must be valid before letting ARC at
+ it. Similarly, C and Objective-C do not provide any language hooks for
+ destroying objects held in dynamic memory, so it is the programmer's
+ responsibility to avoid leaks (``__strong`` objects) and consistency errors
+ (``__weak`` objects).
+
+These requirements are followed automatically in Objective-C++ when creating
+objects of retainable object owner type with ``new`` or ``new[]`` and destroying
+them with ``delete``, ``delete[]``, or a pseudo-destructor expression. Note
+that arrays of nontrivially-ownership-qualified type are not ABI compatible with
+non-ARC code because the element type is non-POD: such arrays that are
+``new[]``'d in ARC translation units cannot be ``delete[]``'d in non-ARC
+translation units and vice-versa.
+
+.. _arc.ownership.restrictions.pass_by_writeback:
+
+Passing to an out parameter by writeback
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the argument passed to a parameter of type ``T __autoreleasing *`` has type
+``U oq *``, where ``oq`` is an ownership qualifier, then the argument is a
+candidate for :arc-term:`pass-by-writeback`` if:
+
+* ``oq`` is ``__strong`` or ``__weak``, and
+* it would be legal to initialize a ``T __strong *`` with a ``U __strong *``.
+
+For purposes of overload resolution, an implicit conversion sequence requiring
+a pass-by-writeback is always worse than an implicit conversion sequence not
+requiring a pass-by-writeback.
+
+The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:
+
+* ``&var``, where ``var`` is a scalar variable of automatic storage duration
+ with retainable object pointer type
+* a conditional expression where the second and third operands are both legal
+ forms
+* a cast whose operand is a legal form
+* a null pointer constant
+
+.. admonition:: Rationale
+
+ The restriction in the form of the argument serves two purposes. First, it
+ makes it impossible to pass the address of an array to the argument, which
+ serves to protect against an otherwise serious risk of mis-inferring an
+ "array" argument as an out-parameter. Second, it makes it much less likely
+ that the user will see confusing aliasing problems due to the implementation,
+ below, where their store to the writeback temporary is not immediately seen
+ in the original argument variable.
+
+A pass-by-writeback is evaluated as follows:
+
+#. The argument is evaluated to yield a pointer ``p`` of type ``U oq *``.
+#. If ``p`` is a null pointer, then a null pointer is passed as the argument,
+ and no further work is required for the pass-by-writeback.
+#. Otherwise, a temporary of type ``T __autoreleasing`` is created and
+ initialized to a null pointer.
+#. If the parameter is not an Objective-C method parameter marked ``out``,
+ then ``*p`` is read, and the result is written into the temporary with
+ primitive semantics.
+#. The address of the temporary is passed as the argument to the actual call.
+#. After the call completes, the temporary is loaded with primitive
+ semantics, and that value is assigned into ``*p``.
+
+.. admonition:: Rationale
+
+ This is all admittedly convoluted. In an ideal world, we would see that a
+ local variable is being passed to an out-parameter and retroactively modify
+ its type to be ``__autoreleasing`` rather than ``__strong``. This would be
+ remarkably difficult and not always well-founded under the C type system.
+ However, it was judged unacceptably invasive to require programmers to write
+ ``__autoreleasing`` on all the variables they intend to use for
+ out-parameters. This was the least bad solution.
+
+.. _arc.ownership.restrictions.records:
+
+Ownership-qualified fields of structs and unions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.
+
+.. admonition:: Rationale
+
+ The resulting type would be non-POD in the C++ sense, but C does not give us
+ very good language tools for managing the lifetime of aggregates, so it is
+ more convenient to simply forbid them. It is still possible to manage this
+ with a ``void*`` or an ``__unsafe_unretained`` object.
+
+This restriction does not apply in Objective-C++. However, nontrivally
+ownership-qualified types are considered non-POD: in C++11 terms, they are not
+trivially default constructible, copy constructible, move constructible, copy
+assignable, move assignable, or destructible. It is a violation of C++'s One
+Definition Rule to use a class outside of ARC that, under ARC, would have a
+nontrivially ownership-qualified member.
+
+.. admonition:: Rationale
+
+ Unlike in C, we can express all the necessary ARC semantics for
+ ownership-qualified subobjects as suboperations of the (default) special
+ member functions for the class. These functions then become non-trivial.
+ This has the non-obvious result that the class will have a non-trivial copy
+ constructor and non-trivial destructor; if this would not normally be true
+ outside of ARC, objects of the type will be passed and returned in an
+ ABI-incompatible manner.
+
+.. _arc.ownership.inference:
+
+Ownership inference
+-------------------
+
+.. _arc.ownership.inference.variables:
+
+Objects
+^^^^^^^
+
+If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+``__strong`` qualification.
+
+As a special case, if the object's base type is ``Class`` (possibly
+protocol-qualified), the type is adjusted to have ``__unsafe_unretained``
+qualification instead.
+
+.. _arc.ownership.inference.indirect_parameters:
+
+Indirect parameters
+^^^^^^^^^^^^^^^^^^^
+
+If a function or method parameter has type ``T*``, where ``T`` is an
+ownership-unqualified retainable object pointer type, then:
+
+* if ``T`` is ``const``-qualified or ``Class``, then it is implicitly
+ qualified with ``__unsafe_unretained``;
+* otherwise, it is implicitly qualified with ``__autoreleasing``.
+
+.. admonition:: Rationale
+
+ ``__autoreleasing`` exists mostly for this case, the Cocoa convention for
+ out-parameters. Since a pointer to ``const`` is obviously not an
+ out-parameter, we instead use a type more useful for passing arrays. If the
+ user instead intends to pass in a *mutable* array, inferring
+ ``__autoreleasing`` is the wrong thing to do; this directs some of the
+ caution in the following rules about writeback.
+
+Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.
+
+This rule does not apply in Objective-C++ if a parameter's type is dependent in
+a template pattern and is only *instantiated* to a type which would be a
+pointer to an unqualified retainable object pointer type. Such code is still
+ill-formed.
+
+.. admonition:: Rationale
+
+ The convention is very unlikely to be intentional in template code.
+
+.. _arc.ownership.inference.template.arguments:
+
+Template arguments
+^^^^^^^^^^^^^^^^^^
+
+If a template argument for a template type parameter is an retainable object
+owner type that does not have an explicit ownership qualifier, it is adjusted
+to have ``__strong`` qualification. This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.
+
+.. admonition:: Rationale
+
+ ``__strong`` is a useful default for containers (e.g., ``std::vector<id>``),
+ which would otherwise require explicit qualification. Moreover, unqualified
+ retainable object pointer types are unlikely to be useful within templates,
+ since they generally need to have a qualifier applied to the before being
+ used.
+
+.. _arc.method-families:
+
+Method families
+===============
+
+An Objective-C method may fall into a :arc-term:`method family`, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.
+
+A method is in a certain method family if:
+
+* it has a ``objc_method_family`` attribute placing it in that family; or if
+ not that,
+* it does not have an ``objc_method_family`` attribute placing it in a
+ different or no family, and
+* its selector falls into the corresponding selector family, and
+* its signature obeys the added restrictions of the method family.
+
+A selector is in a certain selector family if, ignoring any leading
+underscores, the first component of the selector either consists entirely of
+the name of the method family or it begins with that name followed by a
+character other than a lowercase letter. For example, ``_perform:with:`` and
+``performWith:`` would fall into the ``perform`` family (if we recognized one),
+but ``performing:with`` would not.
+
+The families and their added restrictions are:
+
+* ``alloc`` methods must return a retainable object pointer type.
+* ``copy`` methods must return a retainable object pointer type.
+* ``mutableCopy`` methods must return a retainable object pointer type.
+* ``new`` methods must return a retainable object pointer type.
+* ``init`` methods must be instance methods and must return an Objective-C
+ pointer type. Additionally, a program is ill-formed if it declares or
+ contains a call to an ``init`` method whose return type is neither ``id`` nor
+ a pointer to a super-class or sub-class of the declaring class (if the method
+ was declared on a class) or the static receiver type of the call (if it was
+ declared on a protocol).
+
+ .. admonition:: Rationale
+
+ There are a fair number of existing methods with ``init``-like selectors
+ which nonetheless don't follow the ``init`` conventions. Typically these
+ are either accidental naming collisions or helper methods called during
+ initialization. Because of the peculiar retain/release behavior of
+ ``init`` methods, it's very important not to treat these methods as
+ ``init`` methods if they aren't meant to be. It was felt that implicitly
+ defining these methods out of the family based on the exact relationship
+ between the return type and the declaring class would be much too subtle
+ and fragile. Therefore we identify a small number of legitimate-seeming
+ return types and call everything else an error. This serves the secondary
+ purpose of encouraging programmers not to accidentally give methods names
+ in the ``init`` family.
+
+ Note that a method with an ``init``-family selector which returns a
+ non-Objective-C type (e.g. ``void``) is perfectly well-formed; it simply
+ isn't in the ``init`` family.
+
+A program is ill-formed if a method's declarations, implementations, and
+overrides do not all have the same method family.
+
+.. _arc.family.attribute:
+
+Explicit method family control
+------------------------------
+
+A method may be annotated with the ``objc_method_family`` attribute to
+precisely control which method family it belongs to. If a method in an
+``@implementation`` does not have this attribute, but there is a method
+declared in the corresponding ``@interface`` that does, then the attribute is
+copied to the declaration in the ``@implementation``. The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+``__has_attribute(objc_method_family)``.
+
+The attribute is spelled
+``__attribute__((objc_method_family(`` *family* ``)))``. If *family* is
+``none``, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type. Otherwise, *family* must be one of
+``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``, in which case the
+method is considered to belong to the corresponding family regardless of its
+selector. It is an error if a method that is explicitly added to a family in
+this way does not meet the requirements of the family other than the selector
+naming convention.
+
+.. admonition:: Rationale
+
+ The rules codified in this document describe the standard conventions of
+ Objective-C. However, as these conventions have not heretofore been enforced
+ by an unforgiving mechanical system, they are only imperfectly kept,
+ especially as they haven't always even been precisely defined. While it is
+ possible to define low-level ownership semantics with attributes like
+ ``ns_returns_retained``, this attribute allows the user to communicate
+ semantic intent, which is of use both to ARC (which, e.g., treats calls to
+ ``init`` specially) and the static analyzer.
+
+.. _arc.family.semantics:
+
+Semantics of method families
+----------------------------
+
+A method's membership in a method family may imply non-standard semantics for
+its parameters and return type.
+
+Methods in the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families ---
+that is, methods in all the currently-defined families except ``init`` ---
+implicitly :ref:`return a retained object
+<arc.object.operands.retained-return-values>` as if they were annotated with
+the ``ns_returns_retained`` attribute. This can be overridden by annotating
+the method with either of the ``ns_returns_autoreleased`` or
+``ns_returns_not_retained`` attributes.
+
+Properties also follow same naming rules as methods. This means that those in
+the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families provide access
+to :ref:`retained objects <arc.object.operands.retained-return-values>`. This
+can be overridden by annotating the property with ``ns_returns_not_retained``
+attribute.
+
+.. _arc.family.semantics.init:
+
+Semantics of ``init``
+^^^^^^^^^^^^^^^^^^^^^
+
+Methods in the ``init`` family implicitly :ref:`consume
+<arc.objects.operands.consumed>` their ``self`` parameter and :ref:`return a
+retained object <arc.object.operands.retained-return-values>`. Neither of
+these properties can be altered through attributes.
+
+A call to an ``init`` method with a receiver that is either ``self`` (possibly
+parenthesized or casted) or ``super`` is called a :arc-term:`delegate init
+call`. It is an error for a delegate init call to be made except from an
+``init`` method, and excluding blocks within such methods.
+
+As an exception to the :ref:`usual rule <arc.misc.self>`, the variable ``self``
+is mutable in an ``init`` method and has the usual semantics for a ``__strong``
+variable. However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an ``init`` method attempts to use the previous value
+of ``self`` after the completion of a delegate init call. It is conventional,
+but not required, for an ``init`` method to return ``self``.
+
+It is undefined behavior for a program to cause two or more calls to ``init``
+methods on the same object, except that each ``init`` method invocation may
+perform at most one delegate init call.
+
+.. _arc.family.semantics.result_type:
+
+Related result types
+^^^^^^^^^^^^^^^^^^^^
+
+Certain methods are candidates to have :arc-term:`related result types`:
+
+* class methods in the ``alloc`` and ``new`` method families
+* instance methods in the ``init`` family
+* the instance method ``self``
+* outside of ARC, the instance methods ``retain`` and ``autorelease``
+
+If the formal result type of such a method is ``id`` or protocol-qualified
+``id``, or a type equal to the declaring class or a superclass, then it is said
+to have a related result type. In this case, when invoked in an explicit
+message send, it is assumed to return a type related to the type of the
+receiver:
+
+* if it is a class method, and the receiver is a class name ``T``, the message
+ send expression has type ``T*``; otherwise
+* if it is an instance method, and the receiver has type ``T``, the message
+ send expression has type ``T``; otherwise
+* the message send expression has the normal result type of the method.
+
+This is a new rule of the Objective-C language and applies outside of ARC.
+
+.. admonition:: Rationale
+
+ ARC's automatic code emission is more prone than most code to signature
+ errors, i.e. errors where a call was emitted against one method signature,
+ but the implementing method has an incompatible signature. Having more
+ precise type information helps drastically lower this risk, as well as
+ catching a number of latent bugs.
+
+.. _arc.optimization:
+
+Optimization
+============
+
+Within this section, the word :arc-term:`function` will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.
+
+This specification describes ARC as performing specific ``retain`` and
+``release`` operations on retainable object pointers at specific
+points during the execution of a program. These operations make up a
+non-contiguous subsequence of the computation history of the program.
+The portion of this sequence for a particular retainable object
+pointer for which a specific function execution is directly
+responsible is the :arc-term:`formal local retain history` of the
+object pointer. The corresponding actual sequence executed is the
+`dynamic local retain history`.
+
+However, under certain circumstances, ARC is permitted to re-order and
+eliminate operations in a manner which may alter the overall
+computation history beyond what is permitted by the general "as if"
+rule of C/C++ and the :ref:`restrictions <arc.objects.retains>` on
+the implementation of ``retain`` and ``release``.
+
+.. admonition:: Rationale
+
+ Specifically, ARC is sometimes permitted to optimize ``release``
+ operations in ways which might cause an object to be deallocated
+ before it would otherwise be. Without this, it would be almost
+ impossible to eliminate any ``retain``/``release`` pairs. For
+ example, consider the following code:
+
+ .. code-block:: objc
+
+ id x = _ivar;
+ [x foo];
+
+ If we were not permitted in any event to shorten the lifetime of the
+ object in ``x``, then we would not be able to eliminate this retain
+ and release unless we could prove that the message send could not
+ modify ``_ivar`` (or deallocate ``self``). Since message sends are
+ opaque to the optimizer, this is not possible, and so ARC's hands
+ would be almost completely tied.
+
+ARC makes no guarantees about the execution of a computation history
+which contains undefined behavior. In particular, ARC makes no
+guarantees in the presence of race conditions.
+
+ARC may assume that any retainable object pointers it receives or
+generates are instantaneously valid from that point until a point
+which, by the concurrency model of the host language, happens-after
+the generation of the pointer and happens-before a release of that
+object (possibly via an aliasing pointer or indirectly due to
+destruction of a different object).
+
+.. admonition:: Rationale
+
+ There is very little point in trying to guarantee correctness in the
+ presence of race conditions. ARC does not have a stack-scanning
+ garbage collector, and guaranteeing the atomicity of every load and
+ store operation would be prohibitive and preclude a vast amount of
+ optimization.
+
+ARC may assume that non-ARC code engages in sensible balancing
+behavior and does not rely on exact or minimum retain count values
+except as guaranteed by ``__strong`` object invariants or +1 transfer
+conventions. For example, if an object is provably double-retained
+and double-released, ARC may eliminate the inner retain and release;
+it does not need to guard against code which performs an unbalanced
+release followed by a "balancing" retain.
+
+.. _arc.optimization.liveness:
+
+Object liveness
+---------------
+
+ARC may not allow a retainable object ``X`` to be deallocated at a
+time ``T`` in a computation history if:
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+ :ref:`precise lifetime semantics <arc.optimization.precise>`, or
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+ imprecise lifetime semantics and, at some point after ``T`` but
+ before the next store to ``S``, the computation history features a
+ load from ``S`` and in some way depends on the value loaded, or
+
+* ``X`` is a value described as being released at the end of the
+ current full-expression and, at some point after ``T`` but before
+ the end of the full-expression, the computation history depends
+ on that value.
+
+.. admonition:: Rationale
+
+ The intent of the second rule is to say that objects held in normal
+ ``__strong`` local variables may be released as soon as the value in
+ the variable is no longer being used: either the variable stops
+ being used completely or a new value is stored in the variable.
+
+ The intent of the third rule is to say that return values may be
+ released after they've been used.
+
+A computation history depends on a pointer value ``P`` if it:
+
+* performs a pointer comparison with ``P``,
+* loads from ``P``,
+* stores to ``P``,
+* depends on a pointer value ``Q`` derived via pointer arithmetic
+ from ``P`` (including an instance-variable or field access), or
+* depends on a pointer value ``Q`` loaded from ``P``.
+
+Dependency applies only to values derived directly or indirectly from
+a particular expression result and does not occur merely because a
+separate pointer value dynamically aliases ``P``. Furthermore, this
+dependency is not carried by values that are stored to objects.
+
+.. admonition:: Rationale
+
+ The restrictions on dependency are intended to make this analysis
+ feasible by an optimizer with only incomplete information about a
+ program. Essentially, dependence is carried to "obvious" uses of a
+ pointer. Merely passing a pointer argument to a function does not
+ itself cause dependence, but since generally the optimizer will not
+ be able to prove that the function doesn't depend on that parameter,
+ it will be forced to conservatively assume it does.
+
+ Dependency propagates to values loaded from a pointer because those
+ values might be invalidated by deallocating the object. For
+ example, given the code ``__strong id x = p->ivar;``, ARC must not
+ move the release of ``p`` to between the load of ``p->ivar`` and the
+ retain of that value for storing into ``x``.
+
+ Dependency does not propagate through stores of dependent pointer
+ values because doing so would allow dependency to outlive the
+ full-expression which produced the original value. For example, the
+ address of an instance variable could be written to some global
+ location and then freely accessed during the lifetime of the local,
+ or a function could return an inner pointer of an object and store
+ it to a local. These cases would be potentially impossible to
+ reason about and so would basically prevent any optimizations based
+ on imprecise lifetime. There are also uncommon enough to make it
+ reasonable to require the precise-lifetime annotation if someone
+ really wants to rely on them.
+
+ Dependency does propagate through return values of pointer type.
+ The compelling source of need for this rule is a property accessor
+ which returns an un-autoreleased result; the calling function must
+ have the chance to operate on the value, e.g. to retain it, before
+ ARC releases the original pointer. Note again, however, that
+ dependence does not survive a store, so ARC does not guarantee the
+ continued validity of the return value past the end of the
+ full-expression.
+
+.. _arc.optimization.object_lifetime:
+
+No object lifetime extension
+----------------------------
+
+If, in the formal computation history of the program, an object ``X``
+has been deallocated by the time of an observable side-effect, then
+ARC must cause ``X`` to be deallocated by no later than the occurrence
+of that side-effect, except as influenced by the re-ordering of the
+destruction of objects.
+
+.. admonition:: Rationale
+
+ This rule is intended to prohibit ARC from observably extending the
+ lifetime of a retainable object, other than as specified in this
+ document. Together with the rule limiting the transformation of
+ releases, this rule requires ARC to eliminate retains and release
+ only in pairs.
+
+ ARC's power to reorder the destruction of objects is critical to its
+ ability to do any optimization, for essentially the same reason that
+ it must retain the power to decrease the lifetime of an object.
+ Unfortunately, while it's generally poor style for the destruction
+ of objects to have arbitrary side-effects, it's certainly possible.
+ Hence the caveat.
+
+.. _arc.optimization.precise:
+
+Precise lifetime semantics
+--------------------------
+
+In general, ARC maintains an invariant that a retainable object pointer held in
+a ``__strong`` object will be retained for the full formal lifetime of the
+object. Objects subject to this invariant have :arc-term:`precise lifetime
+semantics`.
+
+By default, local variables of automatic storage duration do not have precise
+lifetime semantics. Such objects are simply strong references which hold
+values of retainable object pointer type, and these values are still fully
+subject to the optimizations on values under local control.
+
+.. admonition:: Rationale
+
+ Applying these precise-lifetime semantics strictly would be prohibitive.
+ Many useful optimizations that might theoretically decrease the lifetime of
+ an object would be rendered impossible. Essentially, it promises too much.
+
+A local variable of retainable object owner type and automatic storage duration
+may be annotated with the ``objc_precise_lifetime`` attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.
+
+.. admonition:: Rationale
+
+ Nonetheless, it is sometimes useful to be able to force an object to be
+ released at a precise time, even if that object does not appear to be used.
+ This is likely to be uncommon enough that the syntactic weight of explicitly
+ requesting these semantics will not be burdensome, and may even make the code
+ clearer.
+
+.. _arc.misc:
+
+Miscellaneous
+=============
+
+.. _arc.misc.special_methods:
+
+Special methods
+---------------
+
+.. _arc.misc.special_methods.retain:
+
+Memory management methods
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it contains a method definition, message send, or
+``@selector`` expression for any of the following selectors:
+
+* ``autorelease``
+* ``release``
+* ``retain``
+* ``retainCount``
+
+.. admonition:: Rationale
+
+ ``retainCount`` is banned because ARC robs it of consistent semantics. The
+ others were banned after weighing three options for how to deal with message
+ sends:
+
+ **Honoring** them would work out very poorly if a programmer naively or
+ accidentally tried to incorporate code written for manual retain/release code
+ into an ARC program. At best, such code would do twice as much work as
+ necessary; quite frequently, however, ARC and the explicit code would both
+ try to balance the same retain, leading to crashes. The cost is losing the
+ ability to perform "unrooted" retains, i.e. retains not logically
+ corresponding to a strong reference in the object graph.
+
+ **Ignoring** them would badly violate user expectations about their code.
+ While it *would* make it easier to develop code simultaneously for ARC and
+ non-ARC, there is very little reason to do so except for certain library
+ developers. ARC and non-ARC translation units share an execution model and
+ can seamlessly interoperate. Within a translation unit, a developer who
+ faithfully maintains their code in non-ARC mode is suffering all the
+ restrictions of ARC for zero benefit, while a developer who isn't testing the
+ non-ARC mode is likely to be unpleasantly surprised if they try to go back to
+ it.
+
+ **Banning** them has the disadvantage of making it very awkward to migrate
+ existing code to ARC. The best answer to that, given a number of other
+ changes and restrictions in ARC, is to provide a specialized tool to assist
+ users in that migration.
+
+ Implementing these methods was banned because they are too integral to the
+ semantics of ARC; many tricks which worked tolerably under manual reference
+ counting will misbehave if ARC performs an ephemeral extra retain or two. If
+ absolutely required, it is still possible to implement them in non-ARC code,
+ for example in a category; the implementations must obey the :ref:`semantics
+ <arc.objects.retains>` laid out elsewhere in this document.
+
+.. _arc.misc.special_methods.dealloc:
+
+``dealloc``
+^^^^^^^^^^^
+
+A program is ill-formed if it contains a message send or ``@selector``
+expression for the selector ``dealloc``.
+
+.. admonition:: Rationale
+
+ There are no legitimate reasons to call ``dealloc`` directly.
+
+A class may provide a method definition for an instance method named
+``dealloc``. This method will be called after the final ``release`` of the
+object but before it is deallocated or any of its instance variables are
+destroyed. The superclass's implementation of ``dealloc`` will be called
+automatically when the method returns.
+
+.. admonition:: Rationale
+
+ Even though ARC destroys instance variables automatically, there are still
+ legitimate reasons to write a ``dealloc`` method, such as freeing
+ non-retainable resources. Failing to call ``[super dealloc]`` in such a
+ method is nearly always a bug. Sometimes, the object is simply trying to
+ prevent itself from being destroyed, but ``dealloc`` is really far too late
+ for the object to be raising such objections. Somewhat more legitimately, an
+ object may have been pool-allocated and should not be deallocated with
+ ``free``; for now, this can only be supported with a ``dealloc``
+ implementation outside of ARC. Such an implementation must be very careful
+ to do all the other work that ``NSObject``'s ``dealloc`` would, which is
+ outside the scope of this document to describe.
+
+The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the ``dealloc`` method for the root class of the
+class. The ordering of the destruction of instance variables is unspecified,
+both within a single class and between subclasses and superclasses.
+
+.. admonition:: Rationale
+
+ The traditional, non-ARC pattern for destroying instance variables is to
+ destroy them immediately before calling ``[super dealloc]``. Unfortunately,
+ message sends from the superclass are quite capable of reaching methods in
+ the subclass, and those methods may well read or write to those instance
+ variables. Making such message sends from dealloc is generally discouraged,
+ since the subclass may well rely on other invariants that were broken during
+ ``dealloc``, but it's not so inescapably dangerous that we felt comfortable
+ calling it undefined behavior. Therefore we chose to delay destroying the
+ instance variables to a point at which message sends are clearly disallowed:
+ the point at which the root class's deallocation routines take over.
+
+ In most code, the difference is not observable. It can, however, be observed
+ if an instance variable holds a strong reference to an object whose
+ deallocation will trigger a side-effect which must be carefully ordered with
+ respect to the destruction of the super class. Such code violates the design
+ principle that semantically important behavior should be explicit. A simple
+ fix is to clear the instance variable manually during ``dealloc``; a more
+ holistic solution is to move semantically important side-effects out of
+ ``dealloc`` and into a separate teardown phase which can rely on working with
+ well-formed objects.
+
+.. _arc.misc.autoreleasepool:
+
+``@autoreleasepool``
+--------------------
+
+To simplify the use of autorelease pools, and to bring them under the control
+of the compiler, a new kind of statement is available in Objective-C. It is
+written ``@autoreleasepool`` followed by a *compound-statement*, i.e. by a new
+scope delimited by curly braces. Upon entry to this block, the current state
+of the autorelease pool is captured. When the block is exited normally,
+whether by fallthrough or directed control flow (such as ``return`` or
+``break``), the autorelease pool is restored to the saved state, releasing all
+the objects in it. When the block is exited with an exception, the pool is not
+drained.
+
+``@autoreleasepool`` may be used in non-ARC translation units, with equivalent
+semantics.
+
+A program is ill-formed if it refers to the ``NSAutoreleasePool`` class.
+
+.. admonition:: Rationale
+
+ Autorelease pools are clearly important for the compiler to reason about, but
+ it is far too much to expect the compiler to accurately reason about control
+ dependencies between two calls. It is also very easy to accidentally forget
+ to drain an autorelease pool when using the manual API, and this can
+ significantly inflate the process's high-water-mark. The introduction of a
+ new scope is unfortunate but basically required for sane interaction with the
+ rest of the language. Not draining the pool during an unwind is apparently
+ required by the Objective-C exceptions implementation.
+
+.. _arc.misc.self:
+
+``self``
+--------
+
+The ``self`` parameter variable of an Objective-C method is never actually
+retained by the implementation. It is undefined behavior, or at least
+dangerous, to cause an object to be deallocated during a message send to that
+object.
+
+To make this safe, for Objective-C instance methods ``self`` is implicitly
+``const`` unless the method is in the :ref:`init family
+<arc.family.semantics.init>`. Further, ``self`` is **always** implicitly
+``const`` within a class method.
+
+.. admonition:: Rationale
+
+ The cost of retaining ``self`` in all methods was found to be prohibitive, as
+ it tends to be live across calls, preventing the optimizer from proving that
+ the retain and release are unnecessary --- for good reason, as it's quite
+ possible in theory to cause an object to be deallocated during its execution
+ without this retain and release. Since it's extremely uncommon to actually
+ do so, even unintentionally, and since there's no natural way for the
+ programmer to remove this retain/release pair otherwise (as there is for
+ other parameters by, say, making the variable ``__unsafe_unretained``), we
+ chose to make this optimizing assumption and shift some amount of risk to the
+ user.
+
+.. _arc.misc.enumeration:
+
+Fast enumeration iteration variables
+------------------------------------
+
+If a variable is declared in the condition of an Objective-C fast enumeration
+loop, and the variable has no explicit ownership qualifier, then it is
+qualified with ``const __strong`` and objects encountered during the
+enumeration are not actually retained.
+
+.. admonition:: Rationale
+
+ This is an optimization made possible because fast enumeration loops promise
+ to keep the objects retained during enumeration, and the collection itself
+ cannot be synchronously modified. It can be overridden by explicitly
+ qualifying the variable with ``__strong``, which will make the variable
+ mutable again and cause the loop to retain the objects it encounters.
+
+.. _arc.misc.blocks:
+
+Blocks
+------
+
+The implicit ``const`` capture variables created when evaluating a block
+literal expression have the same ownership semantics as the local variables
+they capture. The capture is performed by reading from the captured variable
+and initializing the capture variable with that value; the capture variable is
+destroyed when the block literal is, i.e. at the end of the enclosing scope.
+
+The :ref:`inference <arc.ownership.inference>` rules apply equally to
+``__block`` variables, which is a shift in semantics from non-ARC, where
+``__block`` variables did not implicitly retain during capture.
+
+``__block`` variables of retainable object owner type are moved off the stack
+by initializing the heap copy with the result of moving from the stack copy.
+
+With the exception of retains done as part of initializing a ``__strong``
+parameter variable or reading a ``__weak`` variable, whenever these semantics
+call for retaining a value of block-pointer type, it has the effect of a
+``Block_copy``. The optimizer may remove such copies when it sees that the
+result is used only as an argument to a call.
+
+.. _arc.misc.exceptions:
+
+Exceptions
+----------
+
+By default in Objective C, ARC is not exception-safe for normal releases:
+
+* It does not end the lifetime of ``__strong`` variables when their scopes are
+ abnormally terminated by an exception.
+* It does not perform releases which would occur at the end of a
+ full-expression if that full-expression throws an exception.
+
+A program may be compiled with the option ``-fobjc-arc-exceptions`` in order to
+enable these, or with the option ``-fno-objc-arc-exceptions`` to explicitly
+disable them, with the last such argument "winning".
+
+.. admonition:: Rationale
+
+ The standard Cocoa convention is that exceptions signal programmer error and
+ are not intended to be recovered from. Making code exceptions-safe by
+ default would impose severe runtime and code size penalties on code that
+ typically does not actually care about exceptions safety. Therefore,
+ ARC-generated code leaks by default on exceptions, which is just fine if the
+ process is going to be immediately terminated anyway. Programs which do care
+ about recovering from exceptions should enable the option.
+
+In Objective-C++, ``-fobjc-arc-exceptions`` is enabled by default.
+
+.. admonition:: Rationale
+
+ C++ already introduces pervasive exceptions-cleanup code of the sort that ARC
+ introduces. C++ programmers who have not already disabled exceptions are
+ much more likely to actual require exception-safety.
+
+ARC does end the lifetimes of ``__weak`` objects when an exception terminates
+their scope unless exceptions are disabled in the compiler.
+
+.. admonition:: Rationale
+
+ The consequence of a local ``__weak`` object not being destroyed is very
+ likely to be corruption of the Objective-C runtime, so we want to be safer
+ here. Of course, potentially massive leaks are about as likely to take down
+ the process as this corruption is if the program does try to recover from
+ exceptions.
+
+.. _arc.misc.interior:
+
+Interior pointers
+-----------------
+
+An Objective-C method returning a non-retainable pointer may be annotated with
+the ``objc_returns_inner_pointer`` attribute to indicate that it returns a
+handle to the internal data of an object, and that this reference will be
+invalidated if the object is destroyed. When such a message is sent to an
+object, the object's lifetime will be extended until at least the earliest of:
+
+* the last use of the returned pointer, or any pointer derived from it, in the
+ calling function or
+* the autorelease pool is restored to a previous state.
+
+.. admonition:: Rationale
+
+ Rationale: not all memory and resources are managed with reference counts; it
+ is common for objects to manage private resources in their own, private way.
+ Typically these resources are completely encapsulated within the object, but
+ some classes offer their users direct access for efficiency. If ARC is not
+ aware of methods that return such "interior" pointers, its optimizations can
+ cause the owning object to be reclaimed too soon. This attribute informs ARC
+ that it must tread lightly.
+
+ The extension rules are somewhat intentionally vague. The autorelease pool
+ limit is there to permit a simple implementation to simply retain and
+ autorelease the receiver. The other limit permits some amount of
+ optimization. The phrase "derived from" is intended to encompass the results
+ both of pointer transformations, such as casts and arithmetic, and of loading
+ from such derived pointers; furthermore, it applies whether or not such
+ derivations are applied directly in the calling code or by other utility code
+ (for example, the C library routine ``strchr``). However, the implementation
+ never need account for uses after a return from the code which calls the
+ method returning an interior pointer.
+
+As an exception, no extension is required if the receiver is loaded directly
+from a ``__strong`` object with :ref:`precise lifetime semantics
+<arc.optimization.precise>`.
+
+.. admonition:: Rationale
+
+ Implicit autoreleases carry the risk of significantly inflating memory use,
+ so it's important to provide users a way of avoiding these autoreleases.
+ Tying this to precise lifetime semantics is ideal, as for local variables
+ this requires a very explicit annotation, which allows ARC to trust the user
+ with good cheer.
+
+.. _arc.misc.c-retainable:
+
+C retainable pointer types
+--------------------------
+
+A type is a :arc-term:`C retainable pointer type` if it is a pointer to
+(possibly qualified) ``void`` or a pointer to a (possibly qualifier) ``struct``
+or ``class`` type.
+
+.. admonition:: Rationale
+
+ ARC does not manage pointers of CoreFoundation type (or any of the related
+ families of retainable C pointers which interoperate with Objective-C for
+ retain/release operation). In fact, ARC does not even know how to
+ distinguish these types from arbitrary C pointer types. The intent of this
+ concept is to filter out some obviously non-object types while leaving a hook
+ for later tightening if a means of exhaustively marking CF types is made
+ available.
+
+.. _arc.misc.c-retainable.audit:
+
+Auditing of C retainable pointer interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+
+A C function may be marked with the ``cf_audited_transfer`` attribute to
+express that, except as otherwise marked with attributes, it obeys the
+parameter (consuming vs. non-consuming) and return (retained vs. non-retained)
+conventions for a C function of its name, namely:
+
+* A parameter of C retainable pointer type is assumed to not be consumed
+ unless it is marked with the ``cf_consumed`` attribute, and
+* A result of C retainable pointer type is assumed to not be returned retained
+ unless the function is either marked ``cf_returns_retained`` or it follows
+ the create/copy naming convention and is not marked
+ ``cf_returns_not_retained``.
+
+A function obeys the :arc-term:`create/copy` naming convention if its name
+contains as a substring:
+
+* either "Create" or "Copy" not followed by a lowercase letter, or
+* either "create" or "copy" not followed by a lowercase letter and
+ not preceded by any letter, whether uppercase or lowercase.
+
+A second attribute, ``cf_unknown_transfer``, signifies that a function's
+transfer semantics cannot be accurately captured using any of these
+annotations. A program is ill-formed if it annotates the same function with
+both ``cf_audited_transfer`` and ``cf_unknown_transfer``.
+
+A pragma is provided to facilitate the mass annotation of interfaces:
+
+.. code-block:: objc
+
+ #pragma clang arc_cf_code_audited begin
+ ...
+ #pragma clang arc_cf_code_audited end
+
+All C functions declared within the extent of this pragma are treated as if
+annotated with the ``cf_audited_transfer`` attribute unless they otherwise have
+the ``cf_unknown_transfer`` attribute. The pragma is accepted in all language
+modes. A program is ill-formed if it attempts to change files, whether by
+including a file or ending the current file, within the extent of this pragma.
+
+It is possible to test for all the features in this section with
+``__has_feature(arc_cf_code_audited)``.
+
+.. admonition:: Rationale
+
+ A significant inconvenience in ARC programming is the necessity of
+ interacting with APIs based around C retainable pointers. These features are
+ designed to make it relatively easy for API authors to quickly review and
+ annotate their interfaces, in turn improving the fidelity of tools such as
+ the static analyzer and ARC. The single-file restriction on the pragma is
+ designed to eliminate the risk of accidentally annotating some other header's
+ interfaces.
+
+.. _arc.runtime:
+
+Runtime support
+===============
+
+This section describes the interaction between the ARC runtime and the code
+generated by the ARC compiler. This is not part of the ARC language
+specification; instead, it is effectively a language-specific ABI supplement,
+akin to the "Itanium" generic ABI for C++.
+
+Ownership qualification does not alter the storage requirements for objects,
+except that it is undefined behavior if a ``__weak`` object is inadequately
+aligned for an object of type ``id``. The other qualifiers may be used on
+explicitly under-aligned memory.
+
+The runtime tracks ``__weak`` objects which holds non-null values. It is
+undefined behavior to direct modify a ``__weak`` object which is being tracked
+by the runtime except through an
+:ref:`objc_storeWeak <arc.runtime.objc_storeWeak>`,
+:ref:`objc_destroyWeak <arc.runtime.objc_destroyWeak>`, or
+:ref:`objc_moveWeak <arc.runtime.objc_moveWeak>` call.
+
+The runtime must provide a number of new entrypoints which the compiler may
+emit, which are described in the remainder of this section.
+
+.. admonition:: Rationale
+
+ Several of these functions are semantically equivalent to a message send; we
+ emit calls to C functions instead because:
+
+ * the machine code to do so is significantly smaller,
+ * it is much easier to recognize the C functions in the ARC optimizer, and
+ * a sufficient sophisticated runtime may be able to avoid the message send in
+ common cases.
+
+ Several other of these functions are "fused" operations which can be
+ described entirely in terms of other operations. We use the fused operations
+ primarily as a code-size optimization, although in some cases there is also a
+ real potential for avoiding redundant operations in the runtime.
+
+.. _arc.runtime.objc_autorelease:
+
+``id objc_autorelease(id value);``
+----------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it adds the object
+to the innermost autorelease pool exactly as if the object had been sent the
+``autorelease`` message.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_autoreleasePoolPop:
+
+``void objc_autoreleasePoolPop(void *pool);``
+---------------------------------------------
+
+*Precondition:* ``pool`` is the result of a previous call to
+:ref:`objc_autoreleasePoolPush <arc.runtime.objc_autoreleasePoolPush>` on the
+current thread, where neither ``pool`` nor any enclosing pool have previously
+been popped.
+
+Releases all the objects added to the given autorelease pool and any
+autorelease pools it encloses, then sets the current autorelease pool to the
+pool directly enclosing ``pool``.
+
+.. _arc.runtime.objc_autoreleasePoolPush:
+
+``void *objc_autoreleasePoolPush(void);``
+-----------------------------------------
+
+Creates a new autorelease pool that is enclosed by the current pool, makes that
+the current pool, and returns an opaque "handle" to it.
+
+.. admonition:: Rationale
+
+ While the interface is described as an explicit hierarchy of pools, the rules
+ allow the implementation to just keep a stack of objects, using the stack
+ depth as the opaque pool handle.
+
+.. _arc.runtime.objc_autoreleaseReturnValue:
+
+``id objc_autoreleaseReturnValue(id value);``
+---------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it makes a best
+effort to hand off ownership of a retain count on the object to a call to
+:ref:`objc_retainAutoreleasedReturnValue
+<arc.runtime.objc_retainAutoreleasedReturnValue>` for the same object in an
+enclosing call frame. If this is not possible, the object is autoreleased as
+above.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_copyWeak:
+
+``void objc_copyWeak(id *dest, id *src);``
+------------------------------------------
+
+*Precondition:* ``src`` is a valid pointer which either contains a null pointer
+or has been registered as a ``__weak`` object. ``dest`` is a valid pointer
+which has not been registered as a ``__weak`` object.
+
+``dest`` is initialized to be equivalent to ``src``, potentially registering it
+with the runtime. Equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_copyWeak(id *dest, id *src) {
+ objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
+ }
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``.
+
+.. _arc.runtime.objc_destroyWeak:
+
+``void objc_destroyWeak(id *object);``
+--------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+``object`` is unregistered as a weak object, if it ever was. The current value
+of ``object`` is left unspecified; otherwise, equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_destroyWeak(id *object) {
+ objc_storeWeak(object, nil);
+ }
+
+Does not need to be atomic with respect to calls to ``objc_storeWeak`` on
+``object``.
+
+.. _arc.runtime.objc_initWeak:
+
+``id objc_initWeak(id *object, id value);``
+-------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which has not been registered as
+a ``__weak`` object. ``value`` is null or a pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is zero-initialized. Otherwise, ``object`` is
+registered as a ``__weak`` object pointing to ``value``. Equivalent to the
+following code:
+
+.. code-block:: objc
+
+ id objc_initWeak(id *object, id value) {
+ *object = nil;
+ return objc_storeWeak(object, value);
+ }
+
+Returns the value of ``object`` after the call.
+
+Does not need to be atomic with respect to calls to ``objc_storeWeak`` on
+``object``.
+
+.. _arc.runtime.objc_loadWeak:
+
+``id objc_loadWeak(id *object);``
+---------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+If ``object`` is registered as a ``__weak`` object, and the last value stored
+into ``object`` has not yet been deallocated or begun deallocation, retains and
+autoreleases that value and returns it. Otherwise returns null. Equivalent to
+the following code:
+
+.. code-block:: objc
+
+ id objc_loadWeak(id *object) {
+ return objc_autorelease(objc_loadWeakRetained(object));
+ }
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``.
+
+.. admonition:: Rationale
+
+ Loading weak references would be inherently prone to race conditions without
+ the retain.
+
+.. _arc.runtime.objc_loadWeakRetained:
+
+``id objc_loadWeakRetained(id *object);``
+-----------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+If ``object`` is registered as a ``__weak`` object, and the last value stored
+into ``object`` has not yet been deallocated or begun deallocation, retains
+that value and returns it. Otherwise returns null.
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``.
+
+.. _arc.runtime.objc_moveWeak:
+
+``void objc_moveWeak(id *dest, id *src);``
+------------------------------------------
+
+*Precondition:* ``src`` is a valid pointer which either contains a null pointer
+or has been registered as a ``__weak`` object. ``dest`` is a valid pointer
+which has not been registered as a ``__weak`` object.
+
+``dest`` is initialized to be equivalent to ``src``, potentially registering it
+with the runtime. ``src`` may then be left in its original state, in which
+case this call is equivalent to :ref:`objc_copyWeak
+<arc.runtime.objc_copyWeak>`, or it may be left as null.
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``.
+
+.. _arc.runtime.objc_release:
+
+``void objc_release(id value);``
+--------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a
+release operation exactly as if the object had been sent the ``release``
+message.
+
+.. _arc.runtime.objc_retain:
+
+``id objc_retain(id value);``
+-----------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation exactly as if the object had been sent the ``retain`` message.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutorelease:
+
+``id objc_retainAutorelease(id value);``
+----------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation followed by an autorelease operation. Equivalent to the following
+code:
+
+.. code-block:: objc
+
+ id objc_retainAutorelease(id value) {
+ return objc_autorelease(objc_retain(value));
+ }
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutoreleaseReturnValue:
+
+``id objc_retainAutoreleaseReturnValue(id value);``
+---------------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation followed by the operation described in
+:ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>`.
+Equivalent to the following code:
+
+.. code-block:: objc
+
+ id objc_retainAutoreleaseReturnValue(id value) {
+ return objc_autoreleaseReturnValue(objc_retain(value));
+ }
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutoreleasedReturnValue:
+
+``id objc_retainAutoreleasedReturnValue(id value);``
+----------------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it attempts to
+accept a hand off of a retain count from a call to
+:ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>` on
+``value`` in a recently-called function or something it calls. If that fails,
+it performs a retain operation exactly like :ref:`objc_retain
+<arc.runtime.objc_retain>`.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainBlock:
+
+``id objc_retainBlock(id value);``
+----------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid block object.
+
+If ``value`` is null, this call has no effect. Otherwise, if the block pointed
+to by ``value`` is still on the stack, it is copied to the heap and the address
+of the copy is returned. Otherwise a retain operation is performed on the
+block exactly as if it had been sent the ``retain`` message.
+
+.. _arc.runtime.objc_storeStrong:
+
+``id objc_storeStrong(id *object, id value);``
+----------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer to a ``__strong`` object which is
+adequately aligned for a pointer. ``value`` is null or a pointer to a valid
+object.
+
+Performs the complete sequence for assigning to a ``__strong`` object of
+non-block type [*]_. Equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_storeStrong(id *object, id value) {
+ id oldValue = *object;
+ value = [value retain];
+ *object = value;
+ [oldValue release];
+ }
+
+.. [*] This does not imply that a ``__strong`` object of block type is an
+ invalid argument to this function. Rather it implies that an ``objc_retain``
+ and not an ``objc_retainBlock`` operation will be emitted if the argument is
+ a block.
+
+.. _arc.runtime.objc_storeWeak:
+
+``id objc_storeWeak(id *object, id value);``
+--------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object. ``value`` is null or a
+pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is assigned null and unregistered as a ``__weak``
+object. Otherwise, ``object`` is registered as a ``__weak`` object or has its
+registration updated to point to ``value``.
+
+Returns the value of ``object`` after the call.
+
Added: www-releases/trunk/5.0.2/tools/clang/docs/_sources/Block-ABI-Apple.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_sources/Block-ABI-Apple.txt?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/_sources/Block-ABI-Apple.txt (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/_sources/Block-ABI-Apple.txt Thu May 10 06:54:16 2018
@@ -0,0 +1,935 @@
+==================================
+Block Implementation Specification
+==================================
+
+.. contents::
+ :local:
+
+History
+=======
+
+* 2008/7/14 - created.
+* 2008/8/21 - revised, C++.
+* 2008/9/24 - add ``NULL`` ``isa`` field to ``__block`` storage.
+* 2008/10/1 - revise block layout to use a ``static`` descriptor structure.
+* 2008/10/6 - revise block layout to use an unsigned long int flags.
+* 2008/10/28 - specify use of ``_Block_object_assign`` and
+ ``_Block_object_dispose`` for all "Object" types in helper functions.
+* 2008/10/30 - revise new layout to have invoke function in same place.
+* 2008/10/30 - add ``__weak`` support.
+* 2010/3/16 - rev for stret return, signature field.
+* 2010/4/6 - improved wording.
+* 2013/1/6 - improved wording and converted to rst.
+
+This document describes the Apple ABI implementation specification of Blocks.
+
+The first shipping version of this ABI is found in Mac OS X 10.6, and shall be
+referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI
+contract with the runtime and the compiler, and, as necessary, will be referred
+to as ABI.2010.3.16.
+
+Since the Apple ABI references symbols from other elements of the system, any
+attempt to use this ABI on systems prior to SnowLeopard is undefined.
+
+High Level
+==========
+
+The ABI of ``Blocks`` consist of their layout and the runtime functions required
+by the compiler. A ``Block`` consists of a structure of the following form:
+
+.. code-block:: c
+
+ struct Block_literal_1 {
+ void *isa; // initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock
+ int flags;
+ int reserved;
+ void (*invoke)(void *, ...);
+ struct Block_descriptor_1 {
+ unsigned long int reserved; // NULL
+ unsigned long int size; // sizeof(struct Block_literal_1)
+ // optional helper functions
+ void (*copy_helper)(void *dst, void *src); // IFF (1<<25)
+ void (*dispose_helper)(void *src); // IFF (1<<25)
+ // required ABI.2010.3.16
+ const char *signature; // IFF (1<<30)
+ } *descriptor;
+ // imported variables
+ };
+
+The following flags bits are in use thusly for a possible ABI.2010.3.16:
+
+.. code-block:: c
+
+ enum {
+ BLOCK_HAS_COPY_DISPOSE = (1 << 25),
+ BLOCK_HAS_CTOR = (1 << 26), // helpers have C++ code
+ BLOCK_IS_GLOBAL = (1 << 28),
+ BLOCK_HAS_STRET = (1 << 29), // IFF BLOCK_HAS_SIGNATURE
+ BLOCK_HAS_SIGNATURE = (1 << 30),
+ };
+
+In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime -
+it had been a transitional marker that did not get deleted after the
+transition. This bit is now paired with (1<<30), and represented as the pair
+(3<<30), for the following combinations of valid bit settings, and their
+meanings:
+
+.. code-block:: c
+
+ switch (flags & (3<<29)) {
+ case (0<<29): 10.6.ABI, no signature field available
+ case (1<<29): 10.6.ABI, no signature field available
+ case (2<<29): ABI.2010.3.16, regular calling convention, presence of signature field
+ case (3<<29): ABI.2010.3.16, stret calling convention, presence of signature field,
+ }
+
+The signature field is not always populated.
+
+The following discussions are presented as 10.6.ABI otherwise.
+
+``Block`` literals may occur within functions where the structure is created in
+stack local memory. They may also appear as initialization expressions for
+``Block`` variables of global or ``static`` local variables.
+
+When a ``Block`` literal expression is evaluated the stack based structure is
+initialized as follows:
+
+1. A ``static`` descriptor structure is declared and initialized as follows:
+
+ a. The ``invoke`` function pointer is set to a function that takes the
+ ``Block`` structure as its first argument and the rest of the arguments (if
+ any) to the ``Block`` and executes the ``Block`` compound statement.
+
+ b. The ``size`` field is set to the size of the following ``Block`` literal
+ structure.
+
+ c. The ``copy_helper`` and ``dispose_helper`` function pointers are set to
+ respective helper functions if they are required by the ``Block`` literal.
+
+2. A stack (or global) ``Block`` literal data structure is created and
+ initialized as follows:
+
+ a. The ``isa`` field is set to the address of the external
+ ``_NSConcreteStackBlock``, which is a block of uninitialized memory supplied
+ in ``libSystem``, or ``_NSConcreteGlobalBlock`` if this is a static or file
+ level ``Block`` literal.
+
+ b. The ``flags`` field is set to zero unless there are variables imported
+ into the ``Block`` that need helper functions for program level
+ ``Block_copy()`` and ``Block_release()`` operations, in which case the
+ (1<<25) flags bit is set.
+
+As an example, the ``Block`` literal expression:
+
+.. code-block:: c
+
+ ^ { printf("hello world\n"); }
+
+would cause the following to be created on a 32-bit system:
+
+.. code-block:: c
+
+ struct __block_literal_1 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_1 *);
+ struct __block_descriptor_1 *descriptor;
+ };
+
+ void __block_invoke_1(struct __block_literal_1 *_block) {
+ printf("hello world\n");
+ }
+
+ static struct __block_descriptor_1 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ } __block_descriptor_1 = { 0, sizeof(struct __block_literal_1), __block_invoke_1 };
+
+and where the ``Block`` literal itself appears:
+
+.. code-block:: c
+
+ struct __block_literal_1 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<29), <uninitialized>,
+ __block_invoke_1,
+ &__block_descriptor_1
+ };
+
+A ``Block`` imports other ``Block`` references, ``const`` copies of other
+variables, and variables marked ``__block``. In Objective-C, variables may
+additionally be objects.
+
+When a ``Block`` literal expression is used as the initial value of a global
+or ``static`` local variable, it is initialized as follows:
+
+.. code-block:: c
+
+ struct __block_literal_1 __block_literal_1 = {
+ &_NSConcreteGlobalBlock,
+ (1<<28)|(1<<29), <uninitialized>,
+ __block_invoke_1,
+ &__block_descriptor_1
+ };
+
+that is, a different address is provided as the first value and a particular
+(1<<28) bit is set in the ``flags`` field, and otherwise it is the same as for
+stack based ``Block`` literals. This is an optimization that can be used for
+any ``Block`` literal that imports no ``const`` or ``__block`` storage
+variables.
+
+Imported Variables
+==================
+
+Variables of ``auto`` storage class are imported as ``const`` copies. Variables
+of ``__block`` storage class are imported as a pointer to an enclosing data
+structure. Global variables are simply referenced and not considered as
+imported.
+
+Imported ``const`` copy variables
+---------------------------------
+
+Automatic storage variables not marked with ``__block`` are imported as
+``const`` copies.
+
+The simplest example is that of importing a variable of type ``int``:
+
+.. code-block:: c
+
+ int x = 10;
+ void (^vv)(void) = ^{ printf("x is %d\n", x); }
+ x = 11;
+ vv();
+
+which would be compiled to:
+
+.. code-block:: c
+
+ struct __block_literal_2 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_2 *);
+ struct __block_descriptor_2 *descriptor;
+ const int x;
+ };
+
+ void __block_invoke_2(struct __block_literal_2 *_block) {
+ printf("x is %d\n", _block->x);
+ }
+
+ static struct __block_descriptor_2 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ } __block_descriptor_2 = { 0, sizeof(struct __block_literal_2) };
+
+and:
+
+.. code-block:: c
+
+ struct __block_literal_2 __block_literal_2 = {
+ &_NSConcreteStackBlock,
+ (1<<29), <uninitialized>,
+ __block_invoke_2,
+ &__block_descriptor_2,
+ x
+ };
+
+In summary, scalars, structures, unions, and function pointers are generally
+imported as ``const`` copies with no need for helper functions.
+
+Imported ``const`` copy of ``Block`` reference
+----------------------------------------------
+
+The first case where copy and dispose helper functions are required is for the
+case of when a ``Block`` itself is imported. In this case both a
+``copy_helper`` function and a ``dispose_helper`` function are needed. The
+``copy_helper`` function is passed both the existing stack based pointer and the
+pointer to the new heap version and should call back into the runtime to
+actually do the copy operation on the imported fields within the ``Block``. The
+runtime functions are all described in :ref:`RuntimeHelperFunctions`.
+
+A quick example:
+
+.. code-block:: c
+
+ void (^existingBlock)(void) = ...;
+ void (^vv)(void) = ^{ existingBlock(); }
+ vv();
+
+ struct __block_literal_3 {
+ ...; // existing block
+ };
+
+ struct __block_literal_4 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_4 *);
+ struct __block_literal_3 *const existingBlock;
+ };
+
+ void __block_invoke_4(struct __block_literal_2 *_block) {
+ __block->existingBlock->invoke(__block->existingBlock);
+ }
+
+ void __block_copy_4(struct __block_literal_4 *dst, struct __block_literal_4 *src) {
+ //_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0);
+ _Block_object_assign(&dst->existingBlock, src->existingBlock, BLOCK_FIELD_IS_BLOCK);
+ }
+
+ void __block_dispose_4(struct __block_literal_4 *src) {
+ // was _Block_destroy
+ _Block_object_dispose(src->existingBlock, BLOCK_FIELD_IS_BLOCK);
+ }
+
+ static struct __block_descriptor_4 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_4 *dst, struct __block_literal_4 *src);
+ void (*dispose_helper)(struct __block_literal_4 *);
+ } __block_descriptor_4 = {
+ 0,
+ sizeof(struct __block_literal_4),
+ __block_copy_4,
+ __block_dispose_4,
+ };
+
+and where said ``Block`` is used:
+
+.. code-block:: c
+
+ struct __block_literal_4 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>
+ __block_invoke_4,
+ & __block_descriptor_4
+ existingBlock,
+ };
+
+Importing ``__attribute__((NSObject))`` variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GCC introduces ``__attribute__((NSObject))`` on structure pointers to mean "this
+is an object". This is useful because many low level data structures are
+declared as opaque structure pointers, e.g. ``CFStringRef``, ``CFArrayRef``,
+etc. When used from C, however, these are still really objects and are the
+second case where that requires copy and dispose helper functions to be
+generated. The copy helper functions generated by the compiler should use the
+``_Block_object_assign`` runtime helper function and in the dispose helper the
+``_Block_object_dispose`` runtime helper function should be called.
+
+For example, ``Block`` foo in the following:
+
+.. code-block:: c
+
+ struct Opaque *__attribute__((NSObject)) objectPointer = ...;
+ ...
+ void (^foo)(void) = ^{ CFPrint(objectPointer); };
+
+would have the following helper functions generated:
+
+.. code-block:: c
+
+ void __block_copy_foo(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ _Block_object_assign(&dst->objectPointer, src-> objectPointer, BLOCK_FIELD_IS_OBJECT);
+ }
+
+ void __block_dispose_foo(struct __block_literal_5 *src) {
+ _Block_object_dispose(src->objectPointer, BLOCK_FIELD_IS_OBJECT);
+ }
+
+Imported ``__block`` marked variables
+-------------------------------------
+
+Layout of ``__block`` marked variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The compiler must embed variables that are marked ``__block`` in a specialized
+structure of the form:
+
+.. code-block:: c
+
+ struct _block_byref_foo {
+ void *isa;
+ struct Block_byref *forwarding;
+ int flags; //refcount;
+ int size;
+ typeof(marked_variable) marked_variable;
+ };
+
+Variables of certain types require helper functions for when ``Block_copy()``
+and ``Block_release()`` are performed upon a referencing ``Block``. At the "C"
+level only variables that are of type ``Block`` or ones that have
+``__attribute__((NSObject))`` marked require helper functions. In Objective-C
+objects require helper functions and in C++ stack based objects require helper
+functions. Variables that require helper functions use the form:
+
+.. code-block:: c
+
+ struct _block_byref_foo {
+ void *isa;
+ struct _block_byref_foo *forwarding;
+ int flags; //refcount;
+ int size;
+ // helper functions called via Block_copy() and Block_release()
+ void (*byref_keep)(void *dst, void *src);
+ void (*byref_dispose)(void *);
+ typeof(marked_variable) marked_variable;
+ };
+
+The structure is initialized such that:
+
+ a. The ``forwarding`` pointer is set to the beginning of its enclosing
+ structure.
+
+ b. The ``size`` field is initialized to the total size of the enclosing
+ structure.
+
+ c. The ``flags`` field is set to either 0 if no helper functions are needed
+ or (1<<25) if they are.
+
+ d. The helper functions are initialized (if present).
+
+ e. The variable itself is set to its initial value.
+
+ f. The ``isa`` field is set to ``NULL``.
+
+Access to ``__block`` variables from within its lexical scope
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to "move" the variable to the heap upon a ``copy_helper`` operation the
+compiler must rewrite access to such a variable to be indirect through the
+structures ``forwarding`` pointer. For example:
+
+.. code-block:: c
+
+ int __block i = 10;
+ i = 11;
+
+would be rewritten to be:
+
+.. code-block:: c
+
+ struct _block_byref_i {
+ void *isa;
+ struct _block_byref_i *forwarding;
+ int flags; //refcount;
+ int size;
+ int captured_i;
+ } i = { NULL, &i, 0, sizeof(struct _block_byref_i), 10 };
+
+ i.forwarding->captured_i = 11;
+
+In the case of a ``Block`` reference variable being marked ``__block`` the
+helper code generated must use the ``_Block_object_assign`` and
+``_Block_object_dispose`` routines supplied by the runtime to make the
+copies. For example:
+
+.. code-block:: c
+
+ __block void (voidBlock)(void) = blockA;
+ voidBlock = blockB;
+
+would translate into:
+
+.. code-block:: c
+
+ struct _block_byref_voidBlock {
+ void *isa;
+ struct _block_byref_voidBlock *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src);
+ void (*byref_dispose)(struct _block_byref_voidBlock *);
+ void (^captured_voidBlock)(void);
+ };
+
+ void _block_byref_keep_helper(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) {
+ //_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0);
+ _Block_object_assign(&dst->captured_voidBlock, src->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER);
+ }
+
+ void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) {
+ //_Block_destroy(param->captured_voidBlock, 0);
+ _Block_object_dispose(param->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER)}
+
+and:
+
+.. code-block:: c
+
+ struct _block_byref_voidBlock voidBlock = {( .forwarding=&voidBlock, .flags=(1<<25), .size=sizeof(struct _block_byref_voidBlock *),
+ .byref_keep=_block_byref_keep_helper, .byref_dispose=_block_byref_dispose_helper,
+ .captured_voidBlock=blockA )};
+
+ voidBlock.forwarding->captured_voidBlock = blockB;
+
+Importing ``__block`` variables into ``Blocks``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``Block`` that uses a ``__block`` variable in its compound statement body must
+import the variable and emit ``copy_helper`` and ``dispose_helper`` helper
+functions that, in turn, call back into the runtime to actually copy or release
+the ``byref`` data block using the functions ``_Block_object_assign`` and
+``_Block_object_dispose``.
+
+For example:
+
+.. code-block:: c
+
+ int __block i = 2;
+ functioncall(^{ i = 10; });
+
+would translate to:
+
+.. code-block:: c
+
+ struct _block_byref_i {
+ void *isa; // set to NULL
+ struct _block_byref_voidBlock *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src);
+ void (*byref_dispose)(struct _block_byref_i *);
+ int captured_i;
+ };
+
+
+ struct __block_literal_5 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_5 *);
+ struct __block_descriptor_5 *descriptor;
+ struct _block_byref_i *i_holder;
+ };
+
+ void __block_invoke_5(struct __block_literal_5 *_block) {
+ _block->forwarding->captured_i = 10;
+ }
+
+ void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ //_Block_byref_assign_copy(&dst->captured_i, src->captured_i);
+ _Block_object_assign(&dst->captured_i, src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER);
+ }
+
+ void __block_dispose_5(struct __block_literal_5 *src) {
+ //_Block_byref_release(src->captured_i);
+ _Block_object_dispose(src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER);
+ }
+
+ static struct __block_descriptor_5 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src);
+ void (*dispose_helper)(struct __block_literal_5 *);
+ } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5) __block_copy_5, __block_dispose_5 };
+
+and:
+
+.. code-block:: c
+
+ struct _block_byref_i i = {( .isa=NULL, .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i), .captured_i=2 )};
+ struct __block_literal_5 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>,
+ __block_invoke_5,
+ &__block_descriptor_5,
+ &i,
+ };
+
+Importing ``__attribute__((NSObject))`` ``__block`` variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``__block`` variable that is also marked ``__attribute__((NSObject))`` should
+have ``byref_keep`` and ``byref_dispose`` helper functions that use
+``_Block_object_assign`` and ``_Block_object_dispose``.
+
+``__block`` escapes
+^^^^^^^^^^^^^^^^^^^
+
+Because ``Blocks`` referencing ``__block`` variables may have ``Block_copy()``
+performed upon them the underlying storage for the variables may move to the
+heap. In Objective-C Garbage Collection Only compilation environments the heap
+used is the garbage collected one and no further action is required. Otherwise
+the compiler must issue a call to potentially release any heap storage for
+``__block`` variables at all escapes or terminations of their scope. The call
+should be:
+
+.. code-block:: c
+
+ _Block_object_dispose(&_block_byref_foo, BLOCK_FIELD_IS_BYREF);
+
+Nesting
+^^^^^^^
+
+``Blocks`` may contain ``Block`` literal expressions. Any variables used within
+inner blocks are imported into all enclosing ``Block`` scopes even if the
+variables are not used. This includes ``const`` imports as well as ``__block``
+variables.
+
+Objective C Extensions to ``Blocks``
+====================================
+
+Importing Objects
+-----------------
+
+Objects should be treated as ``__attribute__((NSObject))`` variables; all
+``copy_helper``, ``dispose_helper``, ``byref_keep``, and ``byref_dispose``
+helper functions should use ``_Block_object_assign`` and
+``_Block_object_dispose``. There should be no code generated that uses
+``*-retain`` or ``*-release`` methods.
+
+``Blocks`` as Objects
+---------------------
+
+The compiler will treat ``Blocks`` as objects when synthesizing property setters
+and getters, will characterize them as objects when generating garbage
+collection strong and weak layout information in the same manner as objects, and
+will issue strong and weak write-barrier assignments in the same manner as
+objects.
+
+``__weak __block`` Support
+--------------------------
+
+Objective-C (and Objective-C++) support the ``__weak`` attribute on ``__block``
+variables. Under normal circumstances the compiler uses the Objective-C runtime
+helper support functions ``objc_assign_weak`` and ``objc_read_weak``. Both
+should continue to be used for all reads and writes of ``__weak __block``
+variables:
+
+.. code-block:: c
+
+ objc_read_weak(&block->byref_i->forwarding->i)
+
+The ``__weak`` variable is stored in a ``_block_byref_foo`` structure and the
+``Block`` has copy and dispose helpers for this structure that call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src-> _block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF);
+
+and:
+
+.. code-block:: c
+
+ _Block_object_dispose(src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF);
+
+In turn, the ``block_byref`` copy support helpers distinguish between whether
+the ``__block`` variable is a ``Block`` or not and should either call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_OBJECT | BLOCK_BYREF_CALLER);
+
+for something declared as an object or:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER);
+
+for something declared as a ``Block``.
+
+A full example follows:
+
+.. code-block:: c
+
+ __block __weak id obj = <initialization expression>;
+ functioncall(^{ [obj somemessage]; });
+
+would translate to:
+
+.. code-block:: c
+
+ struct _block_byref_obj {
+ void *isa; // uninitialized
+ struct _block_byref_obj *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src);
+ void (*byref_dispose)(struct _block_byref_i *);
+ id captured_obj;
+ };
+
+ void _block_byref_obj_keep(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) {
+ //_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0);
+ _Block_object_assign(&dst->captured_obj, src->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER);
+ }
+
+ void _block_byref_obj_dispose(struct _block_byref_voidBlock *param) {
+ //_Block_destroy(param->captured_obj, 0);
+ _Block_object_dispose(param->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER);
+ };
+
+for the block ``byref`` part and:
+
+.. code-block:: c
+
+ struct __block_literal_5 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_5 *);
+ struct __block_descriptor_5 *descriptor;
+ struct _block_byref_obj *byref_obj;
+ };
+
+ void __block_invoke_5(struct __block_literal_5 *_block) {
+ [objc_read_weak(&_block->byref_obj->forwarding->captured_obj) somemessage];
+ }
+
+ void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ //_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj);
+ _Block_object_assign(&dst->byref_obj, src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK);
+ }
+
+ void __block_dispose_5(struct __block_literal_5 *src) {
+ //_Block_byref_release(src->byref_obj);
+ _Block_object_dispose(src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK);
+ }
+
+ static struct __block_descriptor_5 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src);
+ void (*dispose_helper)(struct __block_literal_5 *);
+ } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5), __block_copy_5, __block_dispose_5 };
+
+and within the compound statement:
+
+.. code-block:: c
+
+ truct _block_byref_obj obj = {( .forwarding=&obj, .flags=(1<<25), .size=sizeof(struct _block_byref_obj),
+ .byref_keep=_block_byref_obj_keep, .byref_dispose=_block_byref_obj_dispose,
+ .captured_obj = <initialization expression> )};
+
+ truct __block_literal_5 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>,
+ __block_invoke_5,
+ &__block_descriptor_5,
+ &obj, // a reference to the on-stack structure containing "captured_obj"
+ };
+
+
+ functioncall(_block_literal->invoke(&_block_literal));
+
+C++ Support
+===========
+
+Within a block stack based C++ objects are copied into ``const`` copies using
+the copy constructor. It is an error if a stack based C++ object is used within
+a block if it does not have a copy constructor. In addition both copy and
+destroy helper routines must be synthesized for the block to support the
+``Block_copy()`` operation, and the flags work marked with the (1<<26) bit in
+addition to the (1<<25) bit. The copy helper should call the constructor using
+appropriate offsets of the variable within the supplied stack based block source
+and heap based destination for all ``const`` constructed copies, and similarly
+should call the destructor in the destroy routine.
+
+As an example, suppose a C++ class ``FOO`` existed with a copy constructor.
+Within a code block a stack version of a ``FOO`` object is declared and used
+within a ``Block`` literal expression:
+
+.. code-block:: c++
+
+ {
+ FOO foo;
+ void (^block)(void) = ^{ printf("%d\n", foo.value()); };
+ }
+
+The compiler would synthesize:
+
+.. code-block:: c++
+
+ struct __block_literal_10 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_10 *);
+ struct __block_descriptor_10 *descriptor;
+ const FOO foo;
+ };
+
+ void __block_invoke_10(struct __block_literal_10 *_block) {
+ printf("%d\n", _block->foo.value());
+ }
+
+ void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) {
+ FOO_ctor(&dst->foo, &src->foo);
+ }
+
+ void __block_dispose_10(struct __block_literal_10 *src) {
+ FOO_dtor(&src->foo);
+ }
+
+ static struct __block_descriptor_10 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_10 *dst, struct __block_literal_10 *src);
+ void (*dispose_helper)(struct __block_literal_10 *);
+ } __block_descriptor_10 = { 0, sizeof(struct __block_literal_10), __block_copy_10, __block_dispose_10 };
+
+and the code would be:
+
+.. code-block:: c++
+
+ {
+ FOO foo;
+ comp_ctor(&foo); // default constructor
+ struct __block_literal_10 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<26)|(1<<29), <uninitialized>,
+ __block_invoke_10,
+ &__block_descriptor_10,
+ };
+ comp_ctor(&_block_literal->foo, &foo); // const copy into stack version
+ struct __block_literal_10 &block = &_block_literal; // assign literal to block variable
+ block->invoke(block); // invoke block
+ comp_dtor(&_block_literal->foo); // destroy stack version of const block copy
+ comp_dtor(&foo); // destroy original version
+ }
+
+
+C++ objects stored in ``__block`` storage start out on the stack in a
+``block_byref`` data structure as do other variables. Such objects (if not
+``const`` objects) must support a regular copy constructor. The ``block_byref``
+data structure will have copy and destroy helper routines synthesized by the
+compiler. The copy helper will have code created to perform the copy
+constructor based on the initial stack ``block_byref`` data structure, and will
+also set the (1<<26) bit in addition to the (1<<25) bit. The destroy helper
+will have code to do the destructor on the object stored within the supplied
+``block_byref`` heap data structure. For example,
+
+.. code-block:: c++
+
+ __block FOO blockStorageFoo;
+
+requires the normal constructor for the embedded ``blockStorageFoo`` object:
+
+.. code-block:: c++
+
+ FOO_ctor(& _block_byref_blockStorageFoo->blockStorageFoo);
+
+and at scope termination the destructor:
+
+.. code-block:: c++
+
+ FOO_dtor(& _block_byref_blockStorageFoo->blockStorageFoo);
+
+Note that the forwarding indirection is *NOT* used.
+
+The compiler would need to generate (if used from a block literal) the following
+copy/dispose helpers:
+
+.. code-block:: c++
+
+ void _block_byref_obj_keep(struct _block_byref_blockStorageFoo *dst, struct _block_byref_blockStorageFoo *src) {
+ FOO_ctor(&dst->blockStorageFoo, &src->blockStorageFoo);
+ }
+
+ void _block_byref_obj_dispose(struct _block_byref_blockStorageFoo *src) {
+ FOO_dtor(&src->blockStorageFoo);
+ }
+
+for the appropriately named constructor and destructor for the class/struct
+``FOO``.
+
+To support member variable and function access the compiler will synthesize a
+``const`` pointer to a block version of the ``this`` pointer.
+
+.. _RuntimeHelperFunctions:
+
+Runtime Helper Functions
+========================
+
+The runtime helper functions are described in
+``/usr/local/include/Block_private.h``. To summarize their use, a ``Block``
+requires copy/dispose helpers if it imports any block variables, ``__block``
+storage variables, ``__attribute__((NSObject))`` variables, or C++ ``const``
+copied objects with constructor/destructors. The (1<<26) bit is set and
+functions are generated.
+
+The block copy helper function should, for each of the variables of the type
+mentioned above, call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_<apropos>);
+
+in the copy helper and:
+
+.. code-block:: c
+
+ _Block_object_dispose(->target, BLOCK_FIELD_<apropos>);
+
+in the dispose helper where ``<apropos>`` is:
+
+.. code-block:: c
+
+ enum {
+ BLOCK_FIELD_IS_OBJECT = 3, // id, NSObject, __attribute__((NSObject)), block, ...
+ BLOCK_FIELD_IS_BLOCK = 7, // a block variable
+ BLOCK_FIELD_IS_BYREF = 8, // the on stack structure holding the __block variable
+
+ BLOCK_FIELD_IS_WEAK = 16, // declared __weak
+
+ BLOCK_BYREF_CALLER = 128, // called from byref copy/dispose helpers
+ };
+
+and of course the constructors/destructors for ``const`` copied C++ objects.
+
+The ``block_byref`` data structure similarly requires copy/dispose helpers for
+block variables, ``__attribute__((NSObject))`` variables, or C++ ``const``
+copied objects with constructor/destructors, and again the (1<<26) bit is set
+and functions are generated in the same manner.
+
+Under ObjC we allow ``__weak`` as an attribute on ``__block`` variables, and
+this causes the addition of ``BLOCK_FIELD_IS_WEAK`` orred onto the
+``BLOCK_FIELD_IS_BYREF`` flag when copying the ``block_byref`` structure in the
+``Block`` copy helper, and onto the ``BLOCK_FIELD_<apropos>`` field within the
+``block_byref`` copy/dispose helper calls.
+
+The prototypes, and summary, of the helper functions are:
+
+.. code-block:: c
+
+ /* Certain field types require runtime assistance when being copied to the
+ heap. The following function is used to copy fields of types: blocks,
+ pointers to byref structures, and objects (including
+ __attribute__((NSObject)) pointers. BLOCK_FIELD_IS_WEAK is orthogonal to
+ the other choices which are mutually exclusive. Only in a Block copy
+ helper will one see BLOCK_FIELD_IS_BYREF.
+ */
+ void _Block_object_assign(void *destAddr, const void *object, const int flags);
+
+ /* Similarly a compiler generated dispose helper needs to call back for each
+ field of the byref data structure. (Currently the implementation only
+ packs one field into the byref structure but in principle there could be
+ more). The same flags used in the copy helper should be used for each
+ call generated to this function:
+ */
+ void _Block_object_dispose(const void *object, const int flags);
+
+Copyright
+=========
+
+Copyright 2008-2010 Apple, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
Added: www-releases/trunk/5.0.2/tools/clang/docs/_sources/BlockLanguageSpec.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_sources/BlockLanguageSpec.txt?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/_sources/BlockLanguageSpec.txt (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/_sources/BlockLanguageSpec.txt Thu May 10 06:54:16 2018
@@ -0,0 +1,361 @@
+
+.. role:: block-term
+
+=================================
+Language Specification for Blocks
+=================================
+
+.. contents::
+ :local:
+
+Revisions
+=========
+
+- 2008/2/25 --- created
+- 2008/7/28 --- revised, ``__block`` syntax
+- 2008/8/13 --- revised, Block globals
+- 2008/8/21 --- revised, C++ elaboration
+- 2008/11/1 --- revised, ``__weak`` support
+- 2009/1/12 --- revised, explicit return types
+- 2009/2/10 --- revised, ``__block`` objects need retain
+
+Overview
+========
+
+A new derived type is introduced to C and, by extension, Objective-C,
+C++, and Objective-C++
+
+The Block Type
+==============
+
+Like function types, the :block-term:`Block type` is a pair consisting
+of a result value type and a list of parameter types very similar to a
+function type. Blocks are intended to be used much like functions with
+the key distinction being that in addition to executable code they
+also contain various variable bindings to automatic (stack) or managed
+(heap) memory.
+
+The abstract declarator,
+
+.. code-block:: c
+
+ int (^)(char, float)
+
+describes a reference to a Block that, when invoked, takes two
+parameters, the first of type char and the second of type float, and
+returns a value of type int. The Block referenced is of opaque data
+that may reside in automatic (stack) memory, global memory, or heap
+memory.
+
+Block Variable Declarations
+===========================
+
+A :block-term:`variable with Block type` is declared using function
+pointer style notation substituting ``^`` for ``*``. The following are
+valid Block variable declarations:
+
+.. code-block:: c
+
+ void (^blockReturningVoidWithVoidArgument)(void);
+ int (^blockReturningIntWithIntAndCharArguments)(int, char);
+ void (^arrayOfTenBlocksReturningVoidWithIntArgument[10])(int);
+
+Variadic ``...`` arguments are supported. [variadic.c] A Block that
+takes no arguments must specify void in the argument list [voidarg.c].
+An empty parameter list does not represent, as K&R provide, an
+unspecified argument list. Note: both gcc and clang support K&R style
+as a convenience.
+
+A Block reference may be cast to a pointer of arbitrary type and vice
+versa. [cast.c] A Block reference may not be dereferenced via the
+pointer dereference operator ``*``, and thus a Block's size may not be
+computed at compile time. [sizeof.c]
+
+Block Literal Expressions
+=========================
+
+A :block-term:`Block literal expression` produces a reference to a
+Block. It is introduced by the use of the ``^`` token as a unary
+operator.
+
+.. code-block:: c
+
+ Block_literal_expression ::= ^ block_decl compound_statement_body
+ block_decl ::=
+ block_decl ::= parameter_list
+ block_decl ::= type_expression
+
+where type expression is extended to allow ``^`` as a Block reference
+(pointer) where ``*`` is allowed as a function reference (pointer).
+
+The following Block literal:
+
+.. code-block:: c
+
+ ^ void (void) { printf("hello world\n"); }
+
+produces a reference to a Block with no arguments with no return value.
+
+The return type is optional and is inferred from the return
+statements. If the return statements return a value, they all must
+return a value of the same type. If there is no value returned the
+inferred type of the Block is void; otherwise it is the type of the
+return statement value.
+
+If the return type is omitted and the argument list is ``( void )``,
+the ``( void )`` argument list may also be omitted.
+
+So:
+
+.. code-block:: c
+
+ ^ ( void ) { printf("hello world\n"); }
+
+and:
+
+.. code-block:: c
+
+ ^ { printf("hello world\n"); }
+
+are exactly equivalent constructs for the same expression.
+
+The type_expression extends C expression parsing to accommodate Block
+reference declarations as it accommodates function pointer
+declarations.
+
+Given:
+
+.. code-block:: c
+
+ typedef int (*pointerToFunctionThatReturnsIntWithCharArg)(char);
+ pointerToFunctionThatReturnsIntWithCharArg functionPointer;
+ ^ pointerToFunctionThatReturnsIntWithCharArg (float x) { return functionPointer; }
+
+and:
+
+.. code-block:: c
+
+ ^ int ((*)(float x))(char) { return functionPointer; }
+
+are equivalent expressions, as is:
+
+.. code-block:: c
+
+ ^(float x) { return functionPointer; }
+
+[returnfunctionptr.c]
+
+The compound statement body establishes a new lexical scope within
+that of its parent. Variables used within the scope of the compound
+statement are bound to the Block in the normal manner with the
+exception of those in automatic (stack) storage. Thus one may access
+functions and global variables as one would expect, as well as static
+local variables. [testme]
+
+Local automatic (stack) variables referenced within the compound
+statement of a Block are imported and captured by the Block as const
+copies. The capture (binding) is performed at the time of the Block
+literal expression evaluation.
+
+The compiler is not required to capture a variable if it can prove
+that no references to the variable will actually be evaluated.
+Programmers can force a variable to be captured by referencing it in a
+statement at the beginning of the Block, like so:
+
+.. code-block:: c
+
+ (void) foo;
+
+This matters when capturing the variable has side-effects, as it can
+in Objective-C or C++.
+
+The lifetime of variables declared in a Block is that of a function;
+each activation frame contains a new copy of variables declared within
+the local scope of the Block. Such variable declarations should be
+allowed anywhere [testme] rather than only when C99 parsing is
+requested, including for statements. [testme]
+
+Block literal expressions may occur within Block literal expressions
+(nest) and all variables captured by any nested blocks are implicitly
+also captured in the scopes of their enclosing Blocks.
+
+A Block literal expression may be used as the initialization value for
+Block variables at global or local static scope.
+
+The Invoke Operator
+===================
+
+Blocks are :block-term:`invoked` using function call syntax with a
+list of expression parameters of types corresponding to the
+declaration and returning a result type also according to the
+declaration. Given:
+
+.. code-block:: c
+
+ int (^x)(char);
+ void (^z)(void);
+ int (^(*y))(char) = &x;
+
+the following are all legal Block invocations:
+
+.. code-block:: c
+
+ x('a');
+ (*y)('a');
+ (true ? x : *y)('a')
+
+The Copy and Release Operations
+===============================
+
+The compiler and runtime provide :block-term:`copy` and
+:block-term:`release` operations for Block references that create and,
+in matched use, release allocated storage for referenced Blocks.
+
+The copy operation ``Block_copy()`` is styled as a function that takes
+an arbitrary Block reference and returns a Block reference of the same
+type. The release operation, ``Block_release()``, is styled as a
+function that takes an arbitrary Block reference and, if dynamically
+matched to a Block copy operation, allows recovery of the referenced
+allocated memory.
+
+
+The ``__block`` Storage Qualifier
+=================================
+
+In addition to the new Block type we also introduce a new storage
+qualifier, :block-term:`__block`, for local variables. [testme: a
+__block declaration within a block literal] The ``__block`` storage
+qualifier is mutually exclusive to the existing local storage
+qualifiers auto, register, and static. [testme] Variables qualified by
+``__block`` act as if they were in allocated storage and this storage
+is automatically recovered after last use of said variable. An
+implementation may choose an optimization where the storage is
+initially automatic and only "moved" to allocated (heap) storage upon
+a Block_copy of a referencing Block. Such variables may be mutated as
+normal variables are.
+
+In the case where a ``__block`` variable is a Block one must assume
+that the ``__block`` variable resides in allocated storage and as such
+is assumed to reference a Block that is also in allocated storage
+(that it is the result of a ``Block_copy`` operation). Despite this
+there is no provision to do a ``Block_copy`` or a ``Block_release`` if
+an implementation provides initial automatic storage for Blocks. This
+is due to the inherent race condition of potentially several threads
+trying to update the shared variable and the need for synchronization
+around disposing of older values and copying new ones. Such
+synchronization is beyond the scope of this language specification.
+
+
+Control Flow
+============
+
+The compound statement of a Block is treated much like a function body
+with respect to control flow in that goto, break, and continue do not
+escape the Block. Exceptions are treated *normally* in that when
+thrown they pop stack frames until a catch clause is found.
+
+
+Objective-C Extensions
+======================
+
+Objective-C extends the definition of a Block reference type to be
+that also of id. A variable or expression of Block type may be
+messaged or used as a parameter wherever an id may be. The converse is
+also true. Block references may thus appear as properties and are
+subject to the assign, retain, and copy attribute logic that is
+reserved for objects.
+
+All Blocks are constructed to be Objective-C objects regardless of
+whether the Objective-C runtime is operational in the program or
+not. Blocks using automatic (stack) memory are objects and may be
+messaged, although they may not be assigned into ``__weak`` locations
+if garbage collection is enabled.
+
+Within a Block literal expression within a method definition
+references to instance variables are also imported into the lexical
+scope of the compound statement. These variables are implicitly
+qualified as references from self, and so self is imported as a const
+copy. The net effect is that instance variables can be mutated.
+
+The :block-term:`Block_copy` operator retains all objects held in
+variables of automatic storage referenced within the Block expression
+(or form strong references if running under garbage collection).
+Object variables of ``__block`` storage type are assumed to hold
+normal pointers with no provision for retain and release messages.
+
+Foundation defines (and supplies) ``-copy`` and ``-release`` methods for
+Blocks.
+
+In the Objective-C and Objective-C++ languages, we allow the
+``__weak`` specifier for ``__block`` variables of object type. If
+garbage collection is not enabled, this qualifier causes these
+variables to be kept without retain messages being sent. This
+knowingly leads to dangling pointers if the Block (or a copy) outlives
+the lifetime of this object.
+
+In garbage collected environments, the ``__weak`` variable is set to
+nil when the object it references is collected, as long as the
+``__block`` variable resides in the heap (either by default or via
+``Block_copy()``). The initial Apple implementation does in fact
+start ``__block`` variables on the stack and migrate them to the heap
+only as a result of a ``Block_copy()`` operation.
+
+It is a runtime error to attempt to assign a reference to a
+stack-based Block into any storage marked ``__weak``, including
+``__weak`` ``__block`` variables.
+
+
+C++ Extensions
+==============
+
+Block literal expressions within functions are extended to allow const
+use of C++ objects, pointers, or references held in automatic storage.
+
+As usual, within the block, references to captured variables become
+const-qualified, as if they were references to members of a const
+object. Note that this does not change the type of a variable of
+reference type.
+
+For example, given a class Foo:
+
+.. code-block:: c
+
+ Foo foo;
+ Foo &fooRef = foo;
+ Foo *fooPtr = &foo;
+
+A Block that referenced these variables would import the variables as
+const variations:
+
+.. code-block:: c
+
+ const Foo block_foo = foo;
+ Foo &block_fooRef = fooRef;
+ Foo *const block_fooPtr = fooPtr;
+
+Captured variables are copied into the Block at the instant of
+evaluating the Block literal expression. They are also copied when
+calling ``Block_copy()`` on a Block allocated on the stack. In both
+cases, they are copied as if the variable were const-qualified, and
+it's an error if there's no such constructor.
+
+Captured variables in Blocks on the stack are destroyed when control
+leaves the compound statement that contains the Block literal
+expression. Captured variables in Blocks on the heap are destroyed
+when the reference count of the Block drops to zero.
+
+Variables declared as residing in ``__block`` storage may be initially
+allocated in the heap or may first appear on the stack and be copied
+to the heap as a result of a ``Block_copy()`` operation. When copied
+from the stack, ``__block`` variables are copied using their normal
+qualification (i.e. without adding const). In C++11, ``__block``
+variables are copied as x-values if that is possible, then as l-values
+if not; if both fail, it's an error. The destructor for any initial
+stack-based version is called at the variable's normal end of scope.
+
+References to ``this``, as well as references to non-static members of
+any enclosing class, are evaluated by capturing ``this`` just like a
+normal variable of C pointer type.
+
+Member variables that are Blocks may not be overloaded by the types of
+their arguments.
Added: www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangCheck.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangCheck.txt?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangCheck.txt (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangCheck.txt Thu May 10 06:54:16 2018
@@ -0,0 +1,36 @@
+==========
+ClangCheck
+==========
+
+`ClangCheck` is a small wrapper around :doc:`LibTooling` which can be used to
+do basic error checking and AST dumping.
+
+.. code-block:: console
+
+ $ cat <<EOF > snippet.cc
+ > void f() {
+ > int a = 0
+ > }
+ > EOF
+ $ ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+ Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.
+ /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of
+ declaration
+ int a = 0
+ ^
+ ;
+ (TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>>
+ (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')
+ (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')
+ (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')
+ (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'
+ (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1>
+ (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1>
+ (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'
+ (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))
+ 1 error generated.
+ Error while processing snippet.cc.
+
+The '--' at the end is important as it prevents :program:`clang-check` from
+searching for a compilation database. For more information on how to setup and
+use :program:`clang-check` in a project, see :doc:`HowToSetupToolingForLLVM`.
Added: www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangCommandLineReference.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangCommandLineReference.txt?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangCommandLineReference.txt (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangCommandLineReference.txt Thu May 10 06:54:16 2018
@@ -0,0 +1,2633 @@
+..
+ -------------------------------------------------------------------
+ NOTE: This file is automatically generated by running clang-tblgen
+ -gen-opt-docs. Do not edit this file by hand!!
+ -------------------------------------------------------------------
+
+=====================================
+Clang command line argument reference
+=====================================
+.. contents::
+ :local:
+
+Introduction
+============
+
+This page lists the command line arguments currently supported by the
+GCC-compatible ``clang`` and ``clang++`` drivers.
+
+
+.. program:: clang
+.. option:: -B<dir>, --prefix <arg>, --prefix=<arg>
+
+Add <dir> to search path for binaries and object files used implicitly
+
+.. option:: -F<arg>
+
+Add directory to framework include search path
+
+.. option:: -ObjC
+
+Treat source input files as Objective-C inputs
+
+.. program:: clang1
+.. option:: -ObjC++
+.. program:: clang
+
+Treat source input files as Objective-C++ inputs
+
+.. option:: -Qunused-arguments
+
+Don't emit warning for unused driver arguments
+
+.. option:: -Wa,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the assembler
+
+.. option:: -Wlarge-by-value-copy=<arg>
+
+.. option:: -Xarch\_<arg1> <arg2>
+
+.. option:: -Xcuda-fatbinary <arg>
+
+Pass <arg> to fatbinary invocation
+
+.. option:: -Xcuda-ptxas <arg>
+
+Pass <arg> to the ptxas assembler
+
+.. option:: -Z<arg>
+
+.. option:: -a<arg>, --profile-blocks
+
+.. option:: -all\_load
+
+.. option:: -allowable\_client <arg>
+
+.. option:: --analyze
+
+Run the static analyzer
+
+.. option:: --analyze-auto
+
+.. option:: --analyzer-no-default-checks
+
+.. option:: --analyzer-output<arg>
+
+Static analyzer report output format (html\|plist\|plist-multi-file\|plist-html\|text).
+
+.. option:: -ansi, --ansi
+
+.. option:: -arch <arg>
+
+.. program:: clang1
+.. option:: -arch\_errors\_fatal
+.. program:: clang
+
+.. program:: clang2
+.. option:: -arch\_only <arg>
+.. program:: clang
+
+.. option:: -arcmt-migrate-emit-errors
+
+Emit ARC errors even if the migrator can fix them
+
+.. option:: -arcmt-migrate-report-output <arg>
+
+Output path for the plist report
+
+.. option:: --autocomplete=<arg>
+
+.. option:: -bind\_at\_load
+
+.. option:: -bundle
+
+.. program:: clang1
+.. option:: -bundle\_loader <arg>
+.. program:: clang
+
+.. option:: -client\_name<arg>
+
+.. option:: -compatibility\_version<arg>
+
+.. option:: --constant-cfstrings
+
+.. option:: -coverage, --coverage
+
+.. option:: --cuda-compile-host-device
+
+Compile CUDA code for both host and device (default). Has no effect on non-CUDA compilations.
+
+.. option:: --cuda-device-only
+
+Compile CUDA code for device only
+
+.. option:: --cuda-gpu-arch=<arg>, --no-cuda-gpu-arch=<arg>
+
+CUDA GPU architecture (e.g. sm\_35). May be specified more than once.
+
+.. option:: --cuda-host-only
+
+Compile CUDA code for host only. Has no effect on non-CUDA compilations.
+
+.. option:: --cuda-noopt-device-debug, --no-cuda-noopt-device-debug
+
+Enable device-side debug info generation. Disables ptxas optimizations.
+
+.. option:: -current\_version<arg>
+
+.. option:: -dead\_strip
+
+.. option:: -dependency-dot <arg>
+
+Filename to write DOT-formatted header dependencies to
+
+.. option:: -dependency-file <arg>
+
+Filename (or -) to write dependency output to
+
+.. option:: -dumpmachine
+
+.. option:: -dumpversion
+
+.. option:: --dyld-prefix=<arg>, --dyld-prefix <arg>
+
+.. option:: -dylib\_file <arg>
+
+.. option:: -dylinker
+
+.. program:: clang1
+.. option:: -dylinker\_install\_name<arg>
+.. program:: clang
+
+.. option:: -dynamic
+
+.. option:: -dynamiclib
+
+.. option:: -emit-ast
+
+Emit Clang AST files for source inputs
+
+.. option:: -exported\_symbols\_list <arg>
+
+.. option:: -faligned-new=<arg>
+
+.. option:: -fcuda-approx-transcendentals, -fno-cuda-approx-transcendentals
+
+Use approximate transcendental functions
+
+.. option:: -fcuda-flush-denormals-to-zero, -fno-cuda-flush-denormals-to-zero
+
+Flush denormal floating point values to zero in CUDA device mode.
+
+.. option:: -fheinous-gnu-extensions
+
+.. option:: -flat\_namespace
+
+.. option:: -fopenmp-targets=<arg1>,<arg2>...
+
+Specify comma-separated list of triples OpenMP offloading targets to be supported
+
+.. option:: -force\_cpusubtype\_ALL
+
+.. program:: clang1
+.. option:: -force\_flat\_namespace
+.. program:: clang
+
+.. program:: clang2
+.. option:: -force\_load <arg>
+.. program:: clang
+
+.. option:: -framework <arg>
+
+.. option:: -frtlib-add-rpath, -fno-rtlib-add-rpath
+
+Add -rpath with architecture-specific resource directory to the linker flags
+
+.. option:: --gcc-toolchain=<arg>, -gcc-toolchain <arg>
+
+Use the gcc toolchain at the given directory
+
+.. option:: -gcodeview
+
+Generate CodeView debug information
+
+.. option:: -headerpad\_max\_install\_names<arg>
+
+.. option:: -help, --help
+
+Display available options
+
+.. option:: --help-hidden
+
+.. option:: -image\_base <arg>
+
+.. option:: -index-header-map
+
+Make the next included directory (-I or -F) an indexer header map
+
+.. option:: -init <arg>
+
+.. option:: -install\_name <arg>
+
+.. option:: -keep\_private\_externs
+
+.. option:: -lazy\_framework <arg>
+
+.. program:: clang1
+.. option:: -lazy\_library <arg>
+.. program:: clang
+
+.. option:: -mbig-endian, -EB
+
+.. option:: --migrate
+
+Run the migrator
+
+.. option:: -mios-simulator-version-min=<arg>, -miphonesimulator-version-min=<arg>
+
+.. option:: -mlinker-version=<arg>
+
+.. option:: -mlittle-endian, -EL
+
+.. option:: -mllvm <arg>
+
+Additional arguments to forward to LLVM's option processing
+
+.. option:: -module-dependency-dir <arg>
+
+Directory to dump module dependencies to
+
+.. option:: -mtvos-simulator-version-min=<arg>, -mappletvsimulator-version-min=<arg>
+
+.. option:: -multi\_module
+
+.. option:: -multiply\_defined <arg>
+
+.. program:: clang1
+.. option:: -multiply\_defined\_unused <arg>
+.. program:: clang
+
+.. option:: -mwatchos-simulator-version-min=<arg>, -mwatchsimulator-version-min=<arg>
+
+.. option:: --no-cuda-version-check
+
+Don't error out if the detected version of the CUDA install is too low for the requested CUDA gpu architecture.
+
+.. option:: -no-integrated-cpp, --no-integrated-cpp
+
+.. option:: -no\_dead\_strip\_inits\_and\_terms
+
+.. option:: -nobuiltininc
+
+Disable builtin #include directories
+
+.. option:: -nocudainc
+
+.. option:: -nocudalib
+
+.. option:: -nodefaultlibs
+
+.. option:: -nofixprebinding
+
+.. option:: -nolibc
+
+.. option:: -nomultidefs
+
+.. option:: -nopie, -no-pie
+
+.. option:: -noprebind
+
+.. option:: -noseglinkedit
+
+.. option:: -nostartfiles
+
+.. option:: -nostdinc, --no-standard-includes
+
+.. program:: clang1
+.. option:: -nostdinc++
+.. program:: clang
+
+Disable standard #include directories for the C++ standard library
+
+.. option:: -nostdlib, --no-standard-libraries
+
+.. option:: -nostdlibinc
+
+.. option:: -o<file>, --output <arg>, --output=<arg>
+
+Write output to <file>
+
+.. option:: -objcmt-atomic-property
+
+Make migration to 'atomic' properties
+
+.. option:: -objcmt-migrate-all
+
+Enable migration to modern ObjC
+
+.. option:: -objcmt-migrate-annotation
+
+Enable migration to property and method annotations
+
+.. option:: -objcmt-migrate-designated-init
+
+Enable migration to infer NS\_DESIGNATED\_INITIALIZER for initializer methods
+
+.. option:: -objcmt-migrate-instancetype
+
+Enable migration to infer instancetype for method result type
+
+.. option:: -objcmt-migrate-literals
+
+Enable migration to modern ObjC literals
+
+.. option:: -objcmt-migrate-ns-macros
+
+Enable migration to NS\_ENUM/NS\_OPTIONS macros
+
+.. option:: -objcmt-migrate-property
+
+Enable migration to modern ObjC property
+
+.. option:: -objcmt-migrate-property-dot-syntax
+
+Enable migration of setter/getter messages to property-dot syntax
+
+.. option:: -objcmt-migrate-protocol-conformance
+
+Enable migration to add protocol conformance on classes
+
+.. option:: -objcmt-migrate-readonly-property
+
+Enable migration to modern ObjC readonly property
+
+.. option:: -objcmt-migrate-readwrite-property
+
+Enable migration to modern ObjC readwrite property
+
+.. option:: -objcmt-migrate-subscripting
+
+Enable migration to modern ObjC subscripting
+
+.. option:: -objcmt-ns-nonatomic-iosonly
+
+Enable migration to use NS\_NONATOMIC\_IOSONLY macro for setting property's 'atomic' attribute
+
+.. option:: -objcmt-returns-innerpointer-property
+
+Enable migration to annotate property with NS\_RETURNS\_INNER\_POINTER
+
+.. option:: -objcmt-whitelist-dir-path=<arg>, -objcmt-white-list-dir-path=<arg>
+
+Only modify files with a filename contained in the provided directory path
+
+.. option:: -object
+
+.. option:: -p, --profile
+
+.. option:: -pagezero\_size<arg>
+
+.. option:: -pg
+
+Enable mcount instrumentation
+
+.. option:: -pie
+
+.. option:: -pipe, --pipe
+
+Use pipes between commands, when possible
+
+.. option:: -prebind
+
+.. program:: clang1
+.. option:: -prebind\_all\_twolevel\_modules
+.. program:: clang
+
+.. option:: -preload
+
+.. option:: --print-diagnostic-categories
+
+.. option:: -print-file-name=<file>, --print-file-name=<file>, --print-file-name <arg>
+
+Print the full library path of <file>
+
+.. option:: -print-ivar-layout
+
+Enable Objective-C Ivar layout bitmap print trace
+
+.. option:: -print-libgcc-file-name, --print-libgcc-file-name
+
+Print the library path for the currently used compiler runtime library ("libgcc.a" or "libclang\_rt.builtins.\*.a")
+
+.. option:: -print-multi-directory, --print-multi-directory
+
+.. option:: -print-multi-lib, --print-multi-lib
+
+.. option:: -print-prog-name=<name>, --print-prog-name=<name>, --print-prog-name <arg>
+
+Print the full program path of <name>
+
+.. option:: -print-resource-dir, --print-resource-dir
+
+Print the resource directory pathname
+
+.. option:: -print-search-dirs, --print-search-dirs
+
+Print the paths used for finding libraries and programs
+
+.. option:: -private\_bundle
+
+.. option:: -pthread, -no-pthread
+
+Support POSIX threads in generated code
+
+.. option:: -pthreads
+
+.. option:: -rdynamic
+
+.. option:: -read\_only\_relocs <arg>
+
+.. option:: -relocatable-pch, --relocatable-pch
+
+Whether to build a relocatable precompiled header
+
+.. option:: -remap
+
+.. option:: -rewrite-legacy-objc
+
+Rewrite Legacy Objective-C source to C++
+
+.. option:: -rtlib=<arg>, --rtlib=<arg>, --rtlib <arg>
+
+Compiler runtime library to use
+
+.. option:: -save-stats=<arg>, --save-stats=<arg>, -save-stats (equivalent to -save-stats=cwd), --save-stats (equivalent to -save-stats=cwd)
+
+Save llvm statistics.
+
+.. option:: -save-temps=<arg>, --save-temps=<arg>, -save-temps (equivalent to -save-temps=cwd), --save-temps (equivalent to -save-temps=cwd)
+
+Save intermediate compilation results.
+
+.. option:: -sectalign <arg1> <arg2> <arg3>
+
+.. option:: -sectcreate <arg1> <arg2> <arg3>
+
+.. option:: -sectobjectsymbols <arg1> <arg2>
+
+.. option:: -sectorder <arg1> <arg2> <arg3>
+
+.. option:: -seg1addr<arg>
+
+.. option:: -seg\_addr\_table <arg>
+
+.. program:: clang1
+.. option:: -seg\_addr\_table\_filename <arg>
+.. program:: clang
+
+.. option:: -segaddr <arg1> <arg2>
+
+.. option:: -segcreate <arg1> <arg2> <arg3>
+
+.. option:: -seglinkedit
+
+.. option:: -segprot <arg1> <arg2> <arg3>
+
+.. option:: -segs\_read\_<arg>
+
+.. program:: clang1
+.. option:: -segs\_read\_only\_addr <arg>
+.. program:: clang
+
+.. program:: clang2
+.. option:: -segs\_read\_write\_addr <arg>
+.. program:: clang
+
+.. option:: -serialize-diagnostics <arg>, --serialize-diagnostics <arg>
+
+Serialize compiler diagnostics to a file
+
+.. option:: -shared, --shared
+
+.. option:: -shared-libasan
+
+.. option:: -shared-libgcc
+
+.. option:: -single\_module
+
+.. option:: -specs=<arg>, --specs=<arg>
+
+.. option:: -static, --static
+
+.. option:: -static-libgcc
+
+.. option:: -static-libstdc++
+
+.. option:: -std-default=<arg>
+
+.. option:: -stdlib=<arg>, --stdlib=<arg>, --stdlib <arg>
+
+C++ standard library to use
+
+.. option:: -sub\_library<arg>
+
+.. program:: clang1
+.. option:: -sub\_umbrella<arg>
+.. program:: clang
+
+.. option:: --sysroot=<arg>, --sysroot <arg>
+
+.. option:: --target-help
+
+.. option:: --target=<arg>, -target <arg>
+
+Generate code for the given target
+
+.. option:: -time
+
+Time individual commands
+
+.. option:: -traditional, --traditional
+
+.. option:: -traditional-cpp, --traditional-cpp
+
+Enable some traditional CPP emulation
+
+.. option:: -twolevel\_namespace
+
+.. program:: clang1
+.. option:: -twolevel\_namespace\_hints
+.. program:: clang
+
+.. option:: -umbrella <arg>
+
+.. option:: -unexported\_symbols\_list <arg>
+
+.. option:: -v, --verbose
+
+Show commands to run and use verbose output
+
+.. option:: --verify-debug-info
+
+Verify the binary representation of debug output
+
+.. option:: --version
+
+.. option:: -w, --no-warnings
+
+Suppress all warnings
+
+.. option:: -weak-l<arg>
+
+.. option:: -weak\_framework <arg>
+
+.. program:: clang1
+.. option:: -weak\_library <arg>
+.. program:: clang
+
+.. program:: clang2
+.. option:: -weak\_reference\_mismatches <arg>
+.. program:: clang
+
+.. option:: -whatsloaded
+
+.. option:: -whyload
+
+.. option:: -working-directory<arg>, -working-directory=<arg>
+
+Resolve file paths relative to the specified directory
+
+.. option:: -x<language>, --language <arg>, --language=<arg>
+
+Treat subsequent input files as having type <language>
+
+.. option:: -y<arg>
+
+Actions
+=======
+The action to perform on the input.
+
+.. option:: -E, --preprocess
+
+Only run the preprocessor
+
+.. option:: -S, --assemble
+
+Only run preprocess and compilation steps
+
+.. option:: -c, --compile
+
+Only run preprocess, compile, and assemble steps
+
+.. option:: -emit-llvm
+
+Use the LLVM representation for assembler and object files
+
+.. option:: -fsyntax-only
+
+.. option:: -module-file-info
+
+Provide information about a particular module file
+
+.. option:: --precompile
+
+Only precompile the input
+
+.. option:: -rewrite-objc
+
+Rewrite Objective-C source to C++
+
+.. option:: -verify-pch
+
+Load and verify that a pre-compiled header file is not stale
+
+Compilation flags
+=================
+
+Flags controlling the behavior of Clang during compilation. These flags have
+no effect during actions that do not perform compilation.
+
+.. option:: -Xassembler <arg>
+
+Pass <arg> to the assembler
+
+.. option:: -Xclang <arg>
+
+Pass <arg> to the clang compiler
+
+.. option:: -fclang-abi-compat=<version>
+
+Attempt to match the ABI of Clang <version>
+
+.. option:: -fcomment-block-commands=<arg>,<arg2>...
+
+Treat each comma separated argument in <arg> as a documentation comment block command
+
+.. option:: -fdeclspec, -fno-declspec
+
+Allow \_\_declspec as a keyword
+
+.. option:: -fdepfile-entry=<arg>
+
+.. option:: -fdiagnostics-fixit-info, -fno-diagnostics-fixit-info
+
+.. option:: -fdiagnostics-format=<arg>
+
+.. option:: -fdiagnostics-parseable-fixits
+
+Print fix-its in machine parseable form
+
+.. option:: -fdiagnostics-print-source-range-info
+
+Print source range spans in numeric form
+
+.. option:: -fdiagnostics-show-category=<arg>
+
+.. option:: -fexperimental-new-pass-manager, -fno-experimental-new-pass-manager
+
+Enables an experimental new pass manager in LLVM.
+
+.. option:: -finline-functions, -fno-inline-functions
+
+Inline suitable functions
+
+.. option:: -finline-hint-functions
+
+Inline functions which are (explicitly or implicitly) marked inline
+
+.. option:: -fno-crash-diagnostics
+
+Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash
+
+.. option:: -fno-sanitize-blacklist
+
+Don't use blacklist file for sanitizers
+
+.. option:: -fparse-all-comments
+
+.. option:: -fsanitize-address-field-padding=<arg>
+
+Level of field padding for AddressSanitizer
+
+.. option:: -fsanitize-address-globals-dead-stripping
+
+Enable linker dead stripping of globals in AddressSanitizer
+
+.. option:: -fsanitize-address-use-after-scope, -fno-sanitize-address-use-after-scope
+
+Enable use-after-scope detection in AddressSanitizer
+
+.. option:: -fsanitize-blacklist=<arg>
+
+Path to blacklist file for sanitizers
+
+.. option:: -fsanitize-cfi-cross-dso, -fno-sanitize-cfi-cross-dso
+
+Enable control flow integrity (CFI) checks for cross-DSO calls.
+
+.. option:: -fsanitize-coverage=<arg1>,<arg2>..., -fno-sanitize-coverage=<arg1>,<arg2>...
+
+Specify the type of coverage instrumentation for Sanitizers
+
+.. option:: -fsanitize-link-c++-runtime
+
+.. option:: -fsanitize-memory-track-origins, -fno-sanitize-memory-track-origins
+
+Enable origins tracking in MemorySanitizer
+
+.. program:: clang1
+.. option:: -fsanitize-memory-track-origins=<arg>
+.. program:: clang
+
+Enable origins tracking in MemorySanitizer
+
+.. option:: -fsanitize-memory-use-after-dtor
+
+Enable use-after-destroy detection in MemorySanitizer
+
+.. option:: -fsanitize-recover, -fno-sanitize-recover
+
+.. program:: clang1
+.. option:: -fsanitize-recover=<arg1>,<arg2>..., -fno-sanitize-recover=<arg1>,<arg2>...
+.. program:: clang
+
+Enable recovery for specified sanitizers
+
+.. option:: -fsanitize-stats, -fno-sanitize-stats
+
+Enable sanitizer statistics gathering.
+
+.. option:: -fsanitize-thread-atomics, -fno-sanitize-thread-atomics
+
+Enable atomic operations instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-thread-func-entry-exit, -fno-sanitize-thread-func-entry-exit
+
+Enable function entry/exit instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-thread-memory-access, -fno-sanitize-thread-memory-access
+
+Enable memory access instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-trap=<arg1>,<arg2>..., -fno-sanitize-trap=<arg1>,<arg2>...
+
+Enable trapping for specified sanitizers
+
+.. option:: -fsanitize-undefined-strip-path-components=<number>
+
+Strip (or keep only, if negative) a given number of path components when emitting check metadata.
+
+.. option:: -fsanitize-undefined-trap-on-error, -fno-sanitize-undefined-trap-on-error
+
+.. option:: -fsanitize=<check>,<arg2>..., -fno-sanitize=<arg1>,<arg2>...
+
+Turn on runtime checks for various forms of undefined or suspicious behavior. See user manual for available checks
+
+.. option:: --param <arg>, --param=<arg>
+
+.. option:: -std=<arg>, --std=<arg>, --std <arg>
+
+Language standard to compile for
+
+Preprocessor flags
+~~~~~~~~~~~~~~~~~~
+
+Flags controlling the behavior of the Clang preprocessor.
+
+.. option:: -C, --comments
+
+Include comments in preprocessed output
+
+.. option:: -CC, --comments-in-macros
+
+Include comments from within macros in preprocessed output
+
+.. option:: -D<macro>=<value>, --define-macro <arg>, --define-macro=<arg>
+
+Define <macro> to <value> (or 1 if <value> omitted)
+
+.. option:: -H, --trace-includes
+
+Show header includes and nesting depth
+
+.. option:: -P, --no-line-commands
+
+Disable linemarker output in -E mode
+
+.. option:: -U<macro>, --undefine-macro <arg>, --undefine-macro=<arg>
+
+Undefine macro <macro>
+
+.. option:: -Wp,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the preprocessor
+
+.. option:: -Xpreprocessor <arg>
+
+Pass <arg> to the preprocessor
+
+Include path management
+-----------------------
+
+Flags controlling how ``#include``\s are resolved to files.
+
+.. option:: -I<dir>, --include-directory <arg>, --include-directory=<arg>
+
+Add directory to include search path
+
+.. option:: -I-, --include-barrier
+
+Restrict all prior -I flags to double-quoted inclusion and remove current directory from include path
+
+.. option:: --cuda-path=<arg>
+
+CUDA installation path
+
+.. option:: -cxx-isystem<directory>
+
+Add directory to the C++ SYSTEM include search path
+
+.. option:: -fbuild-session-file=<file>
+
+Use the last modification time of <file> as the build session timestamp
+
+.. option:: -fbuild-session-timestamp=<time since Epoch in seconds>
+
+Time when the current build session started
+
+.. option:: -fmodules-cache-path=<directory>
+
+Specify the module cache path
+
+.. option:: -fmodules-disable-diagnostic-validation
+
+Disable validation of the diagnostic options when loading the module
+
+.. option:: -fmodules-prune-after=<seconds>
+
+Specify the interval (in seconds) after which a module file will be considered unused
+
+.. option:: -fmodules-prune-interval=<seconds>
+
+Specify the interval (in seconds) between attempts to prune the module cache
+
+.. option:: -fmodules-user-build-path <directory>
+
+Specify the module user build path
+
+.. option:: -fmodules-validate-once-per-build-session
+
+Don't verify input files for the modules if the module has been successfully validated or loaded during this build session
+
+.. option:: -fmodules-validate-system-headers
+
+Validate the system headers that a module depends on when loading the module
+
+.. option:: -fprebuilt-module-path=<directory>
+
+Specify the prebuilt module path
+
+.. option:: -i<arg>
+
+.. option:: -idirafter<arg>, --include-directory-after <arg>, --include-directory-after=<arg>
+
+Add directory to AFTER include search path
+
+.. option:: -iframework<arg>
+
+Add directory to SYSTEM framework search path
+
+.. option:: -iframeworkwithsysroot<directory>
+
+Add directory to SYSTEM framework search path, absolute paths are relative to -isysroot
+
+.. option:: -imacros<file>, --imacros<file>, --imacros=<arg>
+
+Include macros from file before parsing
+
+.. option:: -include<file>, --include<file>, --include=<arg>
+
+Include file before parsing
+
+.. option:: -include-pch <file>
+
+Include precompiled header file
+
+.. option:: -iprefix<dir>, --include-prefix <arg>, --include-prefix=<arg>
+
+Set the -iwithprefix/-iwithprefixbefore prefix
+
+.. option:: -iquote<directory>
+
+Add directory to QUOTE include search path
+
+.. option:: -isysroot<dir>
+
+Set the system root directory (usually /)
+
+.. option:: -isystem<directory>
+
+Add directory to SYSTEM include search path
+
+.. option:: -isystem-after<directory>
+
+Add directory to end of the SYSTEM include search path
+
+.. option:: -ivfsoverlay<arg>
+
+Overlay the virtual filesystem described by file over the real file system
+
+.. option:: -iwithprefix<dir>, --include-with-prefix <arg>, --include-with-prefix-after <arg>, --include-with-prefix-after=<arg>, --include-with-prefix=<arg>
+
+Set directory to SYSTEM include search path with prefix
+
+.. option:: -iwithprefixbefore<dir>, --include-with-prefix-before <arg>, --include-with-prefix-before=<arg>
+
+Set directory to include search path with prefix
+
+.. option:: -iwithsysroot<directory>
+
+Add directory to SYSTEM include search path, absolute paths are relative to -isysroot
+
+.. option:: --ptxas-path=<arg>
+
+Path to ptxas (used for compiling CUDA code)
+
+.. option:: --system-header-prefix=<prefix>, --no-system-header-prefix=<prefix>, --system-header-prefix <arg>
+
+Treat all #include paths starting with <prefix> as including a system header.
+
+Dependency file generation
+--------------------------
+
+Flags controlling generation of a dependency file for ``make``-like build
+systems.
+
+.. option:: -M, --dependencies
+
+Like -MD, but also implies -E and writes to stdout by default
+
+.. option:: -MD, --write-dependencies
+
+Write a depfile containing user and system headers
+
+.. option:: -MF<file>
+
+Write depfile output from -MMD, -MD, -MM, or -M to <file>
+
+.. option:: -MG, --print-missing-file-dependencies
+
+Add missing headers to depfile
+
+.. option:: -MJ<arg>
+
+Write a compilation database entry per input
+
+.. option:: -MM, --user-dependencies
+
+Like -MMD, but also implies -E and writes to stdout by default
+
+.. option:: -MMD, --write-user-dependencies
+
+Write a depfile containing user headers
+
+.. option:: -MP
+
+Create phony target for each dependency (other than main file)
+
+.. option:: -MQ<arg>
+
+Specify name of main file output to quote in depfile
+
+.. option:: -MT<arg>
+
+Specify name of main file output in depfile
+
+.. option:: -MV
+
+Use NMake/Jom format for the depfile
+
+Dumping preprocessor state
+--------------------------
+
+Flags allowing the state of the preprocessor to be dumped in various ways.
+
+.. option:: -d
+
+.. program:: clang1
+.. option:: -d<arg>
+.. program:: clang
+
+.. option:: -dA
+
+.. option:: -dD
+
+Print macro definitions in -E mode in addition to normal output
+
+.. option:: -dI
+
+Print include directives in -E mode in addition to normal output
+
+.. option:: -dM
+
+Print macro definitions in -E mode instead of normal output
+
+Diagnostic flags
+~~~~~~~~~~~~~~~~
+
+Flags controlling which warnings, errors, and remarks Clang will generate.
+See the :doc:`full list of warning and remark flags <DiagnosticsReference>`.
+
+.. option:: -R<remark>
+
+Enable the specified remark
+
+.. option:: -Rpass-analysis=<arg>
+
+Report transformation analysis from optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -Rpass-missed=<arg>
+
+Report missed transformations by optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -Rpass=<arg>
+
+Report transformations performed by optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -W<warning>, --extra-warnings, --warn-<arg>, --warn-=<arg>
+
+Enable the specified warning
+
+.. option:: -Wdeprecated, -Wno-deprecated
+
+Enable warnings for deprecated constructs and define \_\_DEPRECATED
+
+.. option:: -Wnonportable-cfstrings<arg>, -Wno-nonportable-cfstrings<arg>
+
+Target-independent compilation options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. option:: -Wframe-larger-than=<arg>
+
+.. option:: -fPIC, -fno-PIC
+
+.. option:: -fPIE, -fno-PIE
+
+.. option:: -faccess-control, -fno-access-control
+
+.. program:: clang1
+.. option:: -faligned-allocation, -faligned-new, -fno-aligned-allocation
+.. program:: clang
+
+Enable C++17 aligned allocation functions
+
+.. option:: -fallow-editor-placeholders, -fno-allow-editor-placeholders
+
+Treat editor placeholders as valid source code
+
+.. option:: -fallow-unsupported
+
+.. option:: -faltivec, -fno-altivec
+
+.. option:: -fansi-escape-codes
+
+Use ANSI escape codes for diagnostics
+
+.. option:: -fapple-kext, -findirect-virtual-calls, -fterminated-vtables
+
+Use Apple's kernel extensions ABI
+
+.. option:: -fapple-pragma-pack, -fno-apple-pragma-pack
+
+Enable Apple gcc-compatible #pragma pack handling
+
+.. option:: -fapplication-extension, -fno-application-extension
+
+Restrict code to those available for App Extensions
+
+.. option:: -fasm, -fno-asm
+
+.. option:: -fasm-blocks, -fno-asm-blocks
+
+.. option:: -fassociative-math, -fno-associative-math
+
+.. option:: -fassume-sane-operator-new, -fno-assume-sane-operator-new
+
+.. option:: -fast
+
+.. option:: -fastcp
+
+.. option:: -fastf
+
+.. option:: -fasynchronous-unwind-tables, -fno-asynchronous-unwind-tables
+
+.. option:: -fautolink, -fno-autolink
+
+.. option:: -fblocks, -fno-blocks
+
+Enable the 'blocks' language feature
+
+.. option:: -fbootclasspath=<arg>, --bootclasspath <arg>, --bootclasspath=<arg>
+
+.. option:: -fborland-extensions, -fno-borland-extensions
+
+Accept non-standard constructs supported by the Borland compiler
+
+.. option:: -fbracket-depth=<arg>
+
+.. option:: -fbuiltin, -fno-builtin
+
+.. option:: -fbuiltin-module-map
+
+Load the clang builtins module map file.
+
+.. option:: -fcaret-diagnostics, -fno-caret-diagnostics
+
+.. option:: -fclasspath=<arg>, --CLASSPATH <arg>, --CLASSPATH=<arg>, --classpath <arg>, --classpath=<arg>
+
+.. option:: -fcolor-diagnostics, -fno-color-diagnostics
+
+Use colors in diagnostics
+
+.. option:: -fcommon, -fno-common
+
+.. option:: -fcompile-resource=<arg>, --resource <arg>, --resource=<arg>
+
+.. option:: -fconstant-cfstrings, -fno-constant-cfstrings
+
+.. option:: -fconstant-string-class=<arg>
+
+.. option:: -fconstexpr-backtrace-limit=<arg>
+
+.. option:: -fconstexpr-depth=<arg>
+
+.. option:: -fconstexpr-steps=<arg>
+
+.. option:: -fcoroutines-ts, -fno-coroutines-ts
+
+Enable support for the C++ Coroutines TS
+
+.. option:: -fcoverage-mapping, -fno-coverage-mapping
+
+Generate coverage mapping to enable code coverage analysis
+
+.. option:: -fcreate-profile
+
+.. option:: -fcxx-exceptions, -fno-cxx-exceptions
+
+Enable C++ exceptions
+
+.. option:: -fcxx-modules, -fno-cxx-modules
+
+.. option:: -fdata-sections, -fno-data-sections
+
+Place each data in its own section (ELF Only)
+
+.. option:: -fdebug-info-for-profiling, -fno-debug-info-for-profiling
+
+Emit extra debug info to make sample profile more accurate.
+
+.. option:: -fdebug-macro, -fno-debug-macro
+
+Emit macro debug information
+
+.. option:: -fdebug-pass-arguments
+
+.. option:: -fdebug-pass-structure
+
+.. option:: -fdebug-prefix-map=<arg>
+
+remap file source paths in debug info
+
+.. option:: -fdebug-types-section, -fno-debug-types-section
+
+Place debug types in their own section (ELF Only)
+
+.. option:: -fdelayed-template-parsing, -fno-delayed-template-parsing
+
+Parse templated function definitions at the end of the translation unit
+
+.. option:: -fdenormal-fp-math=<arg>
+
+.. option:: -fdiagnostics-absolute-paths
+
+Print absolute paths in diagnostics
+
+.. option:: -fdiagnostics-color, -fno-diagnostics-color
+
+.. program:: clang1
+.. option:: -fdiagnostics-color=<arg>
+.. program:: clang
+
+.. option:: -fdiagnostics-hotness-threshold=<number>
+
+Prevent optimization remarks from being output if they do not have at least this profile count
+
+.. option:: -fdiagnostics-show-hotness, -fno-diagnostics-show-hotness
+
+Enable profile hotness information in diagnostic line
+
+.. option:: -fdiagnostics-show-note-include-stack, -fno-diagnostics-show-note-include-stack
+
+Display include stacks for diagnostic notes
+
+.. option:: -fdiagnostics-show-option, -fno-diagnostics-show-option
+
+Print option name with mappable diagnostics
+
+.. option:: -fdiagnostics-show-template-tree
+
+Print a template comparison tree for differing templates
+
+.. option:: -fdollars-in-identifiers, -fno-dollars-in-identifiers
+
+Allow '$' in identifiers
+
+.. option:: -fdwarf-directory-asm, -fno-dwarf-directory-asm
+
+.. option:: -felide-constructors, -fno-elide-constructors
+
+.. option:: -feliminate-unused-debug-symbols, -fno-eliminate-unused-debug-symbols
+
+.. option:: -fembed-bitcode=<option>, -fembed-bitcode (equivalent to -fembed-bitcode=all), -fembed-bitcode-marker (equivalent to -fembed-bitcode=marker)
+
+Embed LLVM bitcode (option: off, all, bitcode, marker)
+
+.. option:: -femit-all-decls
+
+Emit all declarations, even if unused
+
+.. option:: -femulated-tls, -fno-emulated-tls
+
+Use emutls functions to access thread\_local variables
+
+.. option:: -fencoding=<arg>, --encoding <arg>, --encoding=<arg>
+
+.. option:: -ferror-limit=<arg>
+
+.. option:: -fexceptions, -fno-exceptions
+
+Enable support for exception handling
+
+.. option:: -fexec-charset=<arg>
+
+.. option:: -fextdirs=<arg>, --extdirs <arg>, --extdirs=<arg>
+
+.. option:: -ffast-math, -fno-fast-math
+
+Allow aggressive, lossy floating-point optimizations
+
+.. option:: -ffinite-math-only, -fno-finite-math-only
+
+.. option:: -ffor-scope, -fno-for-scope
+
+.. option:: -ffp-contract=<arg>
+
+Form fused FP ops (e.g. FMAs): fast (everywhere) \| on (according to FP\_CONTRACT pragma, default) \| off (never fuse)
+
+.. option:: -ffreestanding
+
+Assert that the compilation takes place in a freestanding environment
+
+.. option:: -ffunction-sections, -fno-function-sections
+
+Place each function in its own section (ELF Only)
+
+.. option:: -fgnu-inline-asm, -fno-gnu-inline-asm
+
+.. option:: -fgnu-keywords, -fno-gnu-keywords
+
+Allow GNU-extension keywords regardless of language standard
+
+.. option:: -fgnu-runtime
+
+Generate output compatible with the standard GNU Objective-C runtime
+
+.. option:: -fgnu89-inline, -fno-gnu89-inline
+
+Use the gnu89 inline semantics
+
+.. option:: -fhonor-infinities, -fhonor-infinites, -fno-honor-infinities
+
+.. option:: -fhonor-nans, -fno-honor-nans
+
+.. option:: -fhosted
+
+.. option:: -fimplicit-module-maps, -fmodule-maps, -fno-implicit-module-maps
+
+Implicitly search the file system for module map files.
+
+.. option:: -fimplicit-modules, -fno-implicit-modules
+
+.. option:: -finput-charset=<arg>
+
+.. option:: -finstrument-functions
+
+Generate calls to instrument function entry and exit
+
+.. option:: -fintegrated-as, -fno-integrated-as, -integrated-as
+
+Enable the integrated assembler
+
+.. option:: -fjump-tables, -fno-jump-tables
+
+.. option:: -flax-vector-conversions, -fno-lax-vector-conversions
+
+.. option:: -flimited-precision=<arg>
+
+.. option:: -flto, -fno-lto
+
+Enable LTO in 'full' mode
+
+.. option:: -flto-jobs=<arg>
+
+Controls the backend parallelism of -flto=thin (default of 0 means the number of threads will be derived from the number of CPUs detected)
+
+.. program:: clang1
+.. option:: -flto=<arg>
+.. program:: clang
+
+Set LTO mode to either 'full' or 'thin'
+
+.. option:: -fmacro-backtrace-limit=<arg>
+
+.. option:: -fmath-errno, -fno-math-errno
+
+Require math functions to indicate errors by setting errno
+
+.. option:: -fmax-type-align=<arg>
+
+Specify the maximum alignment to enforce on pointers lacking an explicit alignment
+
+.. option:: -fmerge-all-constants, -fno-merge-all-constants
+
+.. option:: -fmessage-length=<arg>
+
+.. option:: -fmodule-file-deps, -fno-module-file-deps
+
+.. option:: -fmodule-file=<file>
+
+Load this precompiled module file
+
+.. option:: -fmodule-map-file=<file>
+
+Load this module map file
+
+.. option:: -fmodule-name=<name>, -fmodule-implementation-of <arg>, -fmodule-name <arg>
+
+Specify the name of the module to build
+
+.. option:: -fmodules, -fno-modules
+
+Enable the 'modules' language feature
+
+.. option:: -fmodules-decluse, -fno-modules-decluse
+
+Require declaration of modules used within a module
+
+.. option:: -fmodules-ignore-macro=<arg>
+
+Ignore the definition of the given macro when building and loading modules
+
+.. option:: -fmodules-search-all, -fno-modules-search-all
+
+Search even non-imported modules to resolve references
+
+.. option:: -fmodules-strict-decluse
+
+Like -fmodules-decluse but requires all headers to be in modules
+
+.. option:: -fmodules-ts
+
+Enable support for the C++ Modules TS
+
+.. option:: -fms-compatibility, -fno-ms-compatibility
+
+Enable full Microsoft Visual C++ compatibility
+
+.. option:: -fms-compatibility-version=<arg>
+
+Dot-separated value representing the Microsoft compiler version number to report in \_MSC\_VER (0 = don't define it (default))
+
+.. option:: -fms-extensions, -fno-ms-extensions
+
+Accept some non-standard constructs supported by the Microsoft compiler
+
+.. option:: -fms-memptr-rep=<arg>
+
+.. option:: -fms-volatile<arg>
+
+.. option:: -fmsc-version=<arg>
+
+Microsoft compiler version number to report in \_MSC\_VER (0 = don't define it (default))
+
+.. option:: -fmudflap
+
+.. option:: -fmudflapth
+
+.. option:: -fnested-functions
+
+.. option:: -fnew-alignment=<align>, -fnew-alignment <arg>
+
+Specifies the largest alignment guaranteed by '::operator new(size\_t)'
+
+.. option:: -fnext-runtime
+
+.. option:: -fno-builtin-<arg>
+
+Disable implicit builtin knowledge of a specific function
+
+.. option:: -fno-elide-type
+
+Do not elide types when printing diagnostics
+
+.. option:: -fno-max-type-align
+
+.. option:: -fno-operator-names
+
+Do not treat C++ operator name keywords as synonyms for operators
+
+.. option:: -fno-strict-modules-decluse
+
+.. option:: -fno-working-directory
+
+.. option:: -fnoopenmp-use-tls
+
+.. option:: -fobjc-abi-version=<arg>
+
+.. option:: -fobjc-arc, -fno-objc-arc
+
+Synthesize retain and release calls for Objective-C pointers
+
+.. option:: -fobjc-arc-exceptions, -fno-objc-arc-exceptions
+
+Use EH-safe code when synthesizing retains and releases in -fobjc-arc
+
+.. option:: -fobjc-exceptions, -fno-objc-exceptions
+
+Enable Objective-C exceptions
+
+.. option:: -fobjc-infer-related-result-type, -fno-objc-infer-related-result-type
+
+.. option:: -fobjc-legacy-dispatch, -fno-objc-legacy-dispatch
+
+.. option:: -fobjc-link-runtime
+
+.. option:: -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
+
+.. option:: -fobjc-nonfragile-abi-version=<arg>
+
+.. option:: -fobjc-runtime=<arg>
+
+Specify the target Objective-C runtime kind and version
+
+.. option:: -fobjc-sender-dependent-dispatch
+
+.. option:: -fobjc-weak, -fno-objc-weak
+
+Enable ARC-style weak references in Objective-C
+
+.. option:: -fomit-frame-pointer, -fno-omit-frame-pointer
+
+.. option:: -fopenmp, -fno-openmp
+
+.. option:: -fopenmp-dump-offload-linker-script
+
+.. option:: -fopenmp-use-tls
+
+.. option:: -fopenmp-version=<arg>
+
+.. program:: clang1
+.. option:: -fopenmp=<arg>
+.. program:: clang
+
+.. option:: -foperator-arrow-depth=<arg>
+
+.. option:: -foptimization-record-file=<arg>
+
+Specify the file name of any generated YAML optimization record
+
+.. option:: -foptimize-sibling-calls, -fno-optimize-sibling-calls
+
+.. option:: -foutput-class-dir=<arg>, --output-class-directory <arg>, --output-class-directory=<arg>
+
+.. option:: -fpack-struct, -fno-pack-struct
+
+.. program:: clang1
+.. option:: -fpack-struct=<arg>
+.. program:: clang
+
+Specify the default maximum struct packing alignment
+
+.. option:: -fpascal-strings, -fno-pascal-strings, -mpascal-strings
+
+Recognize and construct Pascal-style string literals
+
+.. option:: -fpcc-struct-return
+
+Override the default ABI to return all structs on the stack
+
+.. option:: -fpch-preprocess
+
+.. option:: -fpic, -fno-pic
+
+.. option:: -fpie, -fno-pie
+
+.. option:: -fplugin=<dsopath>
+
+Load the named plugin (dynamic shared object)
+
+.. option:: -fpreserve-as-comments, -fno-preserve-as-comments
+
+.. option:: -fprofile-arcs, -fno-profile-arcs
+
+.. option:: -fprofile-dir=<arg>
+
+.. option:: -fprofile-generate, -fno-profile-generate
+
+Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. program:: clang1
+.. option:: -fprofile-generate=<directory>
+.. program:: clang
+
+Generate instrumented code to collect execution counts into <directory>/default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. option:: -fprofile-instr-generate, -fno-profile-instr-generate
+
+Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM\_PROFILE\_FILE env var)
+
+.. program:: clang1
+.. option:: -fprofile-instr-generate=<file>
+.. program:: clang
+
+Generate instrumented code to collect execution counts into <file> (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. option:: -fprofile-instr-use, -fno-profile-instr-use, -fprofile-use
+
+.. program:: clang1
+.. option:: -fprofile-instr-use=<arg>
+.. program:: clang
+
+Use instrumentation data for profile-guided optimization
+
+.. option:: -fprofile-sample-use, -fauto-profile, -fno-profile-sample-use
+
+.. program:: clang1
+.. option:: -fprofile-sample-use=<arg>, -fauto-profile=<arg>
+.. program:: clang
+
+Enable sample-based profile guided optimizations
+
+.. program:: clang1
+.. option:: -fprofile-use=<pathname>
+.. program:: clang
+
+Use instrumentation data for profile-guided optimization. If pathname is a directory, it reads from <pathname>/default.profdata. Otherwise, it reads from file <pathname>.
+
+.. option:: -freciprocal-math, -fno-reciprocal-math
+
+Allow division operations to be reassociated
+
+.. option:: -freg-struct-return
+
+Override the default ABI to return small structs in registers
+
+.. option:: -frelaxed-template-template-args, -fno-relaxed-template-template-args
+
+Enable C++17 relaxed template template argument matching
+
+.. option:: -freroll-loops, -fno-reroll-loops
+
+Turn on loop reroller
+
+.. option:: -fretain-comments-from-system-headers
+
+.. option:: -frewrite-imports, -fno-rewrite-imports
+
+.. option:: -frewrite-includes, -fno-rewrite-includes
+
+.. option:: -frewrite-map-file <arg>
+
+.. program:: clang1
+.. option:: -frewrite-map-file=<arg>
+.. program:: clang
+
+.. option:: -fropi, -fno-ropi
+
+.. option:: -frtti, -fno-rtti
+
+.. option:: -frwpi, -fno-rwpi
+
+.. option:: -fsave-optimization-record, -fno-save-optimization-record
+
+Generate a YAML optimization record file
+
+.. option:: -fshort-enums, -fno-short-enums
+
+Allocate to an enum type only as many bytes as it needs for the declared range of possible values
+
+.. option:: -fshort-wchar, -fno-short-wchar
+
+Force wchar\_t to be a short unsigned int
+
+.. option:: -fshow-column, -fno-show-column
+
+.. option:: -fshow-overloads=<arg>
+
+Which overload candidates to show when overload resolution fails: best\|all; defaults to all
+
+.. option:: -fshow-source-location, -fno-show-source-location
+
+.. option:: -fsignaling-math, -fno-signaling-math
+
+.. option:: -fsigned-bitfields
+
+.. option:: -fsigned-char, -fno-signed-char, --signed-char
+
+.. option:: -fsigned-zeros, -fno-signed-zeros
+
+.. option:: -fsized-deallocation, -fno-sized-deallocation
+
+Enable C++14 sized global deallocation functions
+
+.. option:: -fsjlj-exceptions
+
+Use SjLj style exceptions
+
+.. option:: -fslp-vectorize, -fno-slp-vectorize, -ftree-slp-vectorize
+
+Enable the superword-level parallelism vectorization passes
+
+.. option:: -fspell-checking, -fno-spell-checking
+
+.. option:: -fspell-checking-limit=<arg>
+
+.. option:: -fsplit-dwarf-inlining, -fno-split-dwarf-inlining
+
+Place debug types in their own section (ELF Only)
+
+.. option:: -fsplit-stack
+
+.. option:: -fstack-protector, -fno-stack-protector
+
+Enable stack protectors for functions potentially vulnerable to stack smashing
+
+.. option:: -fstack-protector-all
+
+Force the usage of stack protectors for all functions
+
+.. option:: -fstack-protector-strong
+
+Use a strong heuristic to apply stack protectors to functions
+
+.. option:: -fstandalone-debug, -fno-limit-debug-info, -fno-standalone-debug
+
+Emit full debug info for all types used by the program
+
+.. option:: -fstrict-aliasing, -fno-strict-aliasing
+
+.. option:: -fstrict-enums, -fno-strict-enums
+
+Enable optimizations based on the strict definition of an enum's value range
+
+.. option:: -fstrict-overflow, -fno-strict-overflow
+
+.. option:: -fstrict-return, -fno-strict-return
+
+Always treat control flow paths that fall off the end of a non-void function as unreachable
+
+.. option:: -fstrict-vtable-pointers, -fno-strict-vtable-pointers
+
+Enable optimizations based on the strict rules for overwriting polymorphic C++ objects
+
+.. option:: -fstruct-path-tbaa, -fno-struct-path-tbaa
+
+.. option:: -ftabstop=<arg>
+
+.. option:: -ftemplate-backtrace-limit=<arg>
+
+.. option:: -ftemplate-depth-<arg>
+
+.. option:: -ftemplate-depth=<arg>
+
+.. option:: -ftest-coverage
+
+.. option:: -fthinlto-index=<arg>
+
+Perform ThinLTO importing using provided function summary index
+
+.. option:: -fthreadsafe-statics, -fno-threadsafe-statics
+
+.. option:: -ftime-report
+
+.. option:: -ftls-model=<arg>
+
+.. option:: -ftrap-function=<arg>
+
+Issue call to specified function rather than a trap instruction
+
+.. option:: -ftrapping-math, -fno-trapping-math
+
+.. option:: -ftrapv
+
+Trap on integer overflow
+
+.. option:: -ftrapv-handler <arg>
+
+.. program:: clang1
+.. option:: -ftrapv-handler=<function name>
+.. program:: clang
+
+Specify the function to be called on overflow
+
+.. option:: -ftrigraphs, -fno-trigraphs, -trigraphs, --trigraphs
+
+Process trigraph sequences
+
+.. option:: -funique-section-names, -fno-unique-section-names
+
+Use unique names for text and data sections (ELF Only)
+
+.. option:: -funit-at-a-time, -fno-unit-at-a-time
+
+.. option:: -funroll-loops, -fno-unroll-loops
+
+Turn on loop unroller
+
+.. option:: -funsafe-math-optimizations, -fno-unsafe-math-optimizations
+
+.. option:: -funsigned-bitfields
+
+.. option:: -funsigned-char, -fno-unsigned-char, --unsigned-char
+
+.. option:: -funwind-tables, -fno-unwind-tables
+
+.. option:: -fuse-cxa-atexit, -fno-use-cxa-atexit
+
+.. option:: -fuse-init-array, -fno-use-init-array
+
+Use .init\_array instead of .ctors
+
+.. option:: -fuse-ld=<arg>
+
+.. option:: -fuse-line-directives, -fno-use-line-directives
+
+.. option:: -fveclib=<arg>
+
+Use the given vector functions library
+
+.. option:: -fvectorize, -fno-vectorize, -ftree-vectorize
+
+Enable the loop vectorization passes
+
+.. option:: -fverbose-asm, -fno-verbose-asm
+
+.. option:: -fvisibility-inlines-hidden
+
+Give inline C++ member functions default visibility by default
+
+.. option:: -fvisibility-ms-compat
+
+Give global types 'default' visibility and global functions and variables 'hidden' visibility by default
+
+.. option:: -fvisibility=<arg>
+
+Set the default symbol visibility for all global declarations
+
+.. option:: -fwhole-program-vtables, -fno-whole-program-vtables
+
+Enables whole-program vtable optimization. Requires -flto
+
+.. option:: -fwrapv, -fno-wrapv
+
+Treat signed integer overflow as two's complement
+
+.. option:: -fwritable-strings
+
+Store string literals as writable data
+
+.. option:: -fxray-always-instrument=<arg>
+
+Filename defining the whitelist for imbuing the 'always instrument' XRay attribute.
+
+.. option:: -fxray-instruction-threshold<arg>
+
+.. program:: clang1
+.. option:: -fxray-instruction-threshold=<arg>
+.. program:: clang
+
+Sets the minimum function size to instrument with XRay
+
+.. option:: -fxray-instrument, -fno-xray-instrument
+
+Generate XRay instrumentation sleds on function entry and exit
+
+.. option:: -fxray-never-instrument=<arg>
+
+Filename defining the whitelist for imbuing the 'never instrument' XRay attribute.
+
+.. option:: -fzero-initialized-in-bss, -fno-zero-initialized-in-bss
+
+.. option:: -fzvector, -fno-zvector, -mzvector
+
+Enable System z vector language extension
+
+.. option:: -pedantic, --pedantic, -no-pedantic, --no-pedantic
+
+.. option:: -pedantic-errors, --pedantic-errors
+
+OpenCL flags
+------------
+.. option:: -cl-denorms-are-zero
+
+OpenCL only. Allow denormals to be flushed to zero.
+
+.. option:: -cl-fast-relaxed-math
+
+OpenCL only. Sets -cl-finite-math-only and -cl-unsafe-math-optimizations, and defines \_\_FAST\_RELAXED\_MATH\_\_.
+
+.. option:: -cl-finite-math-only
+
+OpenCL only. Allow floating-point optimizations that assume arguments and results are not NaNs or +-Inf.
+
+.. option:: -cl-fp32-correctly-rounded-divide-sqrt
+
+OpenCL only. Specify that single precision floating-point divide and sqrt used in the program source are correctly rounded.
+
+.. option:: -cl-kernel-arg-info
+
+OpenCL only. Generate kernel argument metadata.
+
+.. option:: -cl-mad-enable
+
+OpenCL only. Allow use of less precise MAD computations in the generated binary.
+
+.. option:: -cl-no-signed-zeros
+
+OpenCL only. Allow use of less precise no signed zeros computations in the generated binary.
+
+.. option:: -cl-opt-disable
+
+OpenCL only. This option disables all optimizations. By default optimizations are enabled.
+
+.. option:: -cl-single-precision-constant
+
+OpenCL only. Treat double precision floating-point constant as single precision constant.
+
+.. option:: -cl-std=<arg>
+
+OpenCL language standard to compile for.
+
+.. option:: -cl-strict-aliasing
+
+OpenCL only. This option is added for compatibility with OpenCL 1.0.
+
+.. option:: -cl-unsafe-math-optimizations
+
+OpenCL only. Allow unsafe floating-point optimizations. Also implies -cl-no-signed-zeros and -cl-mad-enable.
+
+Target-dependent compilation options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. option:: -G<size>, -G=<arg>, -msmall-data-threshold=<arg>
+
+Put objects of at most <size> bytes into small data section (MIPS / Hexagon)
+
+.. option:: -m16
+
+.. option:: -m32
+
+.. option:: -m64
+
+.. option:: -mabi=<arg>
+
+.. option:: -mabicalls, -mno-abicalls
+
+Enable SVR4-style position-independent code (Mips only)
+
+.. option:: -malign-double
+
+Align doubles to two words in structs (x86 only)
+
+.. option:: -march=<arg>
+
+.. option:: -masm=<arg>
+
+.. option:: -mbackchain, -mno-backchain
+
+Link stack frames through backchain on System Z
+
+.. option:: -mcheck-zero-division, -mno-check-zero-division
+
+.. option:: -mcmodel=<arg>
+
+.. option:: -mcompact-branches=<arg>
+
+.. option:: -mconsole<arg>
+
+.. option:: -mcpu=<arg>, -mv4 (equivalent to -mcpu=hexagonv4), -mv5 (equivalent to -mcpu=hexagonv5), -mv55 (equivalent to -mcpu=hexagonv55), -mv60 (equivalent to -mcpu=hexagonv60), -mv62 (equivalent to -mcpu=hexagonv62)
+
+.. option:: -mdefault-build-attributes<arg>, -mno-default-build-attributes<arg>
+
+.. option:: -mdll<arg>
+
+.. option:: -mdouble-float
+
+.. option:: -mdsp, -mno-dsp
+
+.. option:: -mdspr2, -mno-dspr2
+
+.. option:: -mdynamic-no-pic<arg>
+
+.. option:: -meabi <arg>
+
+Set EABI type, e.g. 4, 5 or gnu (default depends on triple)
+
+.. option:: -mfentry
+
+Insert calls to fentry at function entry (x86 only)
+
+.. option:: -mfloat-abi=<arg>
+
+.. option:: -mfp32
+
+Use 32-bit floating point registers (MIPS only)
+
+.. option:: -mfp64
+
+Use 64-bit floating point registers (MIPS only)
+
+.. option:: -mfpmath=<arg>
+
+.. option:: -mfpu=<arg>
+
+.. option:: -mglobal-merge, -mno-global-merge
+
+Enable merging of globals
+
+.. option:: -mhard-float
+
+.. option:: -mhwdiv=<arg>, --mhwdiv <arg>, --mhwdiv=<arg>
+
+.. option:: -miamcu, -mno-iamcu
+
+Use Intel MCU ABI
+
+.. option:: -mimplicit-float, -mno-implicit-float
+
+.. option:: -mimplicit-it=<arg>
+
+.. option:: -mincremental-linker-compatible, -mno-incremental-linker-compatible
+
+(integrated-as) Emit an object file which can be used with an incremental linker
+
+.. option:: -miphoneos-version-min=<arg>, -mios-version-min=<arg>
+
+.. option:: -mips16
+
+.. option:: -mkernel
+
+.. option:: -mldc1-sdc1, -mno-ldc1-sdc1
+
+.. option:: -mlong-calls, -mno-long-calls
+
+Generate branches with extended addressability, usually via indirect jumps.
+
+.. option:: -mmacosx-version-min=<arg>, -mmacos-version-min=<arg>
+
+Set Mac OS X deployment target
+
+.. option:: -mmadd4, -mno-madd4
+
+Enable the generation of 4-operand madd.s, madd.d and related instructions.
+
+.. option:: -mmcu=<arg>
+
+.. option:: -mmicromips, -mno-micromips
+
+.. option:: -mms-bitfields, -mno-ms-bitfields
+
+Set the default structure layout to be compatible with the Microsoft compiler standard
+
+.. option:: -mmsa, -mno-msa
+
+Enable MSA ASE (MIPS only)
+
+.. option:: -mmt, -mno-mt
+
+Enable MT ASE (MIPS only)
+
+.. option:: -mnan=<arg>
+
+.. option:: -mno-mips16
+
+.. option:: -momit-leaf-frame-pointer, -mno-omit-leaf-frame-pointer
+
+Omit frame pointer setup for leaf functions
+
+.. option:: -moslib=<arg>
+
+.. option:: -mpie-copy-relocations, -mno-pie-copy-relocations
+
+Use copy relocations support for PIE builds
+
+.. option:: -mqdsp6-compat
+
+Enable hexagon-qdsp6 backward compatibility
+
+.. option:: -mrecip
+
+.. program:: clang1
+.. option:: -mrecip=<arg1>,<arg2>...
+.. program:: clang
+
+.. option:: -mred-zone, -mno-red-zone
+
+.. option:: -mregparm=<arg>
+
+.. option:: -mrelax-all, -mno-relax-all
+
+(integrated-as) Relax all machine instructions
+
+.. option:: -mrtd, -mno-rtd
+
+Make StdCall calling convention the default
+
+.. option:: -msingle-float
+
+.. option:: -msoft-float, -mno-soft-float
+
+Use software floating point
+
+.. option:: -mstack-alignment=<arg>
+
+Set the stack alignment
+
+.. option:: -mstack-probe-size=<arg>
+
+Set the stack probe size
+
+.. option:: -mstackrealign, -mno-stackrealign
+
+Force realign the stack at entry to every function
+
+.. option:: -mthread-model <arg>
+
+The thread model to use, e.g. posix, single (posix by default)
+
+.. option:: -mthreads<arg>
+
+.. option:: -mthumb, -mno-thumb
+
+.. option:: -mtune=<arg>
+
+.. option:: -mtvos-version-min=<arg>, -mappletvos-version-min=<arg>
+
+.. option:: -municode<arg>
+
+.. option:: -mvx, -mno-vx
+
+.. option:: -mwarn-nonportable-cfstrings, -mno-warn-nonportable-cfstrings
+
+.. option:: -mwatchos-version-min=<arg>
+
+.. option:: -mwindows<arg>
+
+.. option:: -mx32
+
+.. option:: -mxgot, -mno-xgot
+
+AARCH64
+-------
+.. option:: -ffixed-x18
+
+Reserve the x18 register (AArch64 only)
+
+.. option:: -mfix-cortex-a53-835769, -mno-fix-cortex-a53-835769
+
+Workaround Cortex-A53 erratum 835769 (AArch64 only)
+
+.. option:: -mgeneral-regs-only
+
+Generate code which only uses the general purpose registers (AArch64 only)
+
+AMDGPU
+------
+ARM
+---
+.. option:: -ffixed-r9
+
+Reserve the r9 register (ARM only)
+
+.. option:: -mcrc
+
+Allow use of CRC instructions (ARM only)
+
+.. option:: -mexecute-only, -mno-execute-only, -mpure-code
+
+Disallow generation of data access to code sections (ARM only)
+
+.. option:: -mno-movt
+
+Disallow use of movt/movw pairs (ARM only)
+
+.. option:: -mno-neg-immediates
+
+Disallow converting instructions with negative immediates to their negation or inversion.
+
+.. option:: -mnocrc
+
+Disallow use of CRC instructions (ARM only)
+
+.. option:: -mrestrict-it, -mno-restrict-it
+
+Disallow generation of deprecated IT blocks for ARMv8. It is on by default for ARMv8 Thumb mode.
+
+.. option:: -munaligned-access, -mno-unaligned-access
+
+Allow memory accesses to be unaligned (AArch32/AArch64 only)
+
+Hexagon
+-------
+.. option:: -mhvx, -mno-hvx
+
+Enable Hexagon Vector eXtensions
+
+.. option:: -mhvx-double, -mno-hvx-double
+
+Enable Hexagon Double Vector eXtensions
+
+.. option:: -mieee-rnd-near
+
+PowerPC
+-------
+.. option:: -maltivec, -mno-altivec
+
+.. option:: -mcmpb, -mno-cmpb
+
+.. option:: -mcrbits, -mno-crbits
+
+.. option:: -mcrypto, -mno-crypto
+
+.. option:: -mdirect-move, -mno-direct-move
+
+.. option:: -mfloat128, -mno-float128
+
+.. option:: -mfprnd, -mno-fprnd
+
+.. option:: -mhtm, -mno-htm
+
+.. option:: -minvariant-function-descriptors, -mno-invariant-function-descriptors
+
+.. option:: -misel, -mno-isel
+
+.. option:: -mlongcall, -mno-longcall
+
+.. option:: -mmfocrf, -mmfcrf, -mno-mfocrf
+
+.. option:: -mpopcntd, -mno-popcntd
+
+.. option:: -mpower8-vector, -mno-power8-vector
+
+.. option:: -mpower9-vector, -mno-power9-vector
+
+.. option:: -mqpx, -mno-qpx
+
+.. option:: -mvsx, -mno-vsx
+
+WebAssembly
+-----------
+.. option:: -msimd128, -mno-simd128
+
+X86
+---
+.. option:: -m3dnow, -mno-3dnow
+
+.. option:: -m3dnowa, -mno-3dnowa
+
+.. option:: -madx, -mno-adx
+
+.. option:: -maes, -mno-aes
+
+.. option:: -mavx, -mno-avx
+
+.. option:: -mavx2, -mno-avx2
+
+.. option:: -mavx512bw, -mno-avx512bw
+
+.. option:: -mavx512cd, -mno-avx512cd
+
+.. option:: -mavx512dq, -mno-avx512dq
+
+.. option:: -mavx512er, -mno-avx512er
+
+.. option:: -mavx512f, -mno-avx512f
+
+.. option:: -mavx512ifma, -mno-avx512ifma
+
+.. option:: -mavx512pf, -mno-avx512pf
+
+.. option:: -mavx512vbmi, -mno-avx512vbmi
+
+.. option:: -mavx512vl, -mno-avx512vl
+
+.. option:: -mavx512vpopcntdq, -mno-avx512vpopcntdq
+
+.. option:: -mbmi, -mno-bmi
+
+.. option:: -mbmi2, -mno-bmi2
+
+.. option:: -mclflushopt, -mno-clflushopt
+
+.. option:: -mclwb, -mno-clwb
+
+.. option:: -mclzero, -mno-clzero
+
+.. option:: -mcx16, -mno-cx16
+
+.. option:: -mf16c, -mno-f16c
+
+.. option:: -mfma, -mno-fma
+
+.. option:: -mfma4, -mno-fma4
+
+.. option:: -mfsgsbase, -mno-fsgsbase
+
+.. option:: -mfxsr, -mno-fxsr
+
+.. option:: -mlwp, -mno-lwp
+
+.. option:: -mlzcnt, -mno-lzcnt
+
+.. option:: -mmmx, -mno-mmx
+
+.. option:: -mmovbe, -mno-movbe
+
+.. option:: -mmpx, -mno-mpx
+
+.. option:: -mmwaitx, -mno-mwaitx
+
+.. option:: -mpclmul, -mno-pclmul
+
+.. option:: -mpku, -mno-pku
+
+.. option:: -mpopcnt, -mno-popcnt
+
+.. option:: -mprefetchwt1, -mno-prefetchwt1
+
+.. option:: -mprfchw, -mno-prfchw
+
+.. option:: -mrdrnd, -mno-rdrnd
+
+.. option:: -mrdseed, -mno-rdseed
+
+.. option:: -mrtm, -mno-rtm
+
+.. option:: -msgx, -mno-sgx
+
+.. option:: -msha, -mno-sha
+
+.. option:: -msse, -mno-sse
+
+.. option:: -msse2, -mno-sse2
+
+.. option:: -msse3, -mno-sse3
+
+.. option:: -msse4.1, -mno-sse4.1
+
+.. program:: clang1
+.. option:: -msse4.2, -mno-sse4.2, -msse4
+.. program:: clang
+
+.. option:: -msse4a, -mno-sse4a
+
+.. option:: -mssse3, -mno-ssse3
+
+.. option:: -mtbm, -mno-tbm
+
+.. option:: -mx87, -m80387, -mno-x87
+
+.. option:: -mxop, -mno-xop
+
+.. option:: -mxsave, -mno-xsave
+
+.. option:: -mxsavec, -mno-xsavec
+
+.. option:: -mxsaveopt, -mno-xsaveopt
+
+.. option:: -mxsaves, -mno-xsaves
+
+Optimization level
+~~~~~~~~~~~~~~~~~~
+
+Flags controlling how much optimization should be performed.
+
+.. option:: -O<arg>, -O (equivalent to -O2), --optimize, --optimize=<arg>
+
+.. option:: -Ofast<arg>
+
+Debug information generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Flags controlling how much and what kind of debug information should be
+generated.
+
+Kind and level of debug information
+-----------------------------------
+.. option:: -g, --debug, --debug=<arg>
+
+Generate source-level debug information
+
+.. option:: -gdwarf-2
+
+Generate source-level debug information with dwarf version 2
+
+.. option:: -gdwarf-3
+
+Generate source-level debug information with dwarf version 3
+
+.. option:: -gdwarf-4, -gdwarf
+
+Generate source-level debug information with dwarf version 4
+
+.. option:: -gdwarf-5
+
+Generate source-level debug information with dwarf version 5
+
+.. option:: -gfull
+
+.. option:: -gused
+
+Debug level
+___________
+.. option:: -g0
+
+.. option:: -g2
+
+.. option:: -g3
+
+.. option:: -ggdb0
+
+.. option:: -ggdb1
+
+.. option:: -ggdb2
+
+.. option:: -ggdb3
+
+.. option:: -gline-tables-only, -g1, -gmlt
+
+Emit debug line number tables only
+
+.. option:: -gmodules
+
+Generate debug info with external references to clang modules or precompiled headers
+
+Debugger to tune debug information for
+______________________________________
+.. option:: -ggdb
+
+.. option:: -glldb
+
+.. option:: -gsce
+
+Debug information flags
+-----------------------
+.. option:: -gcolumn-info, -gno-column-info
+
+.. option:: -gdwarf-aranges
+
+.. option:: -ggnu-pubnames
+
+.. option:: -grecord-gcc-switches, -gno-record-gcc-switches
+
+.. option:: -gsplit-dwarf
+
+.. option:: -gstrict-dwarf, -gno-strict-dwarf
+
+.. option:: -gz
+
+DWARF debug sections compression type
+
+.. program:: clang1
+.. option:: -gz=<arg>
+.. program:: clang
+
+DWARF debug sections compression type
+
+Static analyzer flags
+=====================
+
+Flags controlling the behavior of the Clang Static Analyzer.
+
+.. option:: -Xanalyzer <arg>
+
+Pass <arg> to the static analyzer
+
+Fortran compilation flags
+=========================
+
+Flags that will be passed onto the ``gfortran`` compiler when Clang is given
+a Fortran input.
+
+.. option:: -A<arg>, --assert <arg>, --assert=<arg>
+
+.. option:: -A-<arg>
+
+.. option:: -J<arg>
+
+.. option:: -cpp
+
+.. option:: -faggressive-function-elimination, -fno-aggressive-function-elimination
+
+.. option:: -falign-commons, -fno-align-commons
+
+.. option:: -fall-intrinsics, -fno-all-intrinsics
+
+.. option:: -fautomatic, -fno-automatic
+
+.. option:: -fbackslash, -fno-backslash
+
+.. option:: -fbacktrace, -fno-backtrace
+
+.. option:: -fblas-matmul-limit=<arg>
+
+.. option:: -fbounds-check, -fno-bounds-check
+
+.. option:: -fcheck-array-temporaries, -fno-check-array-temporaries
+
+.. option:: -fcheck=<arg>
+
+.. option:: -fcoarray=<arg>
+
+.. option:: -fconvert=<arg>
+
+.. option:: -fcray-pointer, -fno-cray-pointer
+
+.. option:: -fd-lines-as-code, -fno-d-lines-as-code
+
+.. option:: -fd-lines-as-comments, -fno-d-lines-as-comments
+
+.. option:: -fdefault-double-8, -fno-default-double-8
+
+.. option:: -fdefault-integer-8, -fno-default-integer-8
+
+.. option:: -fdefault-real-8, -fno-default-real-8
+
+.. option:: -fdollar-ok, -fno-dollar-ok
+
+.. option:: -fdump-fortran-optimized, -fno-dump-fortran-optimized
+
+.. option:: -fdump-fortran-original, -fno-dump-fortran-original
+
+.. option:: -fdump-parse-tree, -fno-dump-parse-tree
+
+.. option:: -fexternal-blas, -fno-external-blas
+
+.. option:: -ff2c, -fno-f2c
+
+.. option:: -ffixed-form, -fno-fixed-form
+
+.. option:: -ffixed-line-length-<arg>
+
+.. option:: -ffpe-trap=<arg>
+
+.. option:: -ffree-form, -fno-free-form
+
+.. option:: -ffree-line-length-<arg>
+
+.. option:: -ffrontend-optimize, -fno-frontend-optimize
+
+.. option:: -fimplicit-none, -fno-implicit-none
+
+.. option:: -finit-character=<arg>
+
+.. option:: -finit-integer=<arg>
+
+.. option:: -finit-local-zero, -fno-init-local-zero
+
+.. option:: -finit-logical=<arg>
+
+.. option:: -finit-real=<arg>
+
+.. option:: -finteger-4-integer-8, -fno-integer-4-integer-8
+
+.. option:: -fintrinsic-modules-path, -fno-intrinsic-modules-path
+
+.. option:: -fmax-array-constructor=<arg>
+
+.. option:: -fmax-errors=<arg>
+
+.. option:: -fmax-identifier-length, -fno-max-identifier-length
+
+.. option:: -fmax-stack-var-size=<arg>
+
+.. option:: -fmax-subrecord-length=<arg>
+
+.. option:: -fmodule-private, -fno-module-private
+
+.. option:: -fpack-derived, -fno-pack-derived
+
+.. option:: -fprotect-parens, -fno-protect-parens
+
+.. option:: -frange-check, -fno-range-check
+
+.. option:: -freal-4-real-10, -fno-real-4-real-10
+
+.. option:: -freal-4-real-16, -fno-real-4-real-16
+
+.. option:: -freal-4-real-8, -fno-real-4-real-8
+
+.. option:: -freal-8-real-10, -fno-real-8-real-10
+
+.. option:: -freal-8-real-16, -fno-real-8-real-16
+
+.. option:: -freal-8-real-4, -fno-real-8-real-4
+
+.. option:: -frealloc-lhs, -fno-realloc-lhs
+
+.. option:: -frecord-marker=<arg>
+
+.. option:: -frecursive, -fno-recursive
+
+.. option:: -frepack-arrays, -fno-repack-arrays
+
+.. option:: -fsecond-underscore, -fno-second-underscore
+
+.. option:: -fsign-zero, -fno-sign-zero
+
+.. option:: -fstack-arrays, -fno-stack-arrays
+
+.. option:: -funderscoring, -fno-underscoring
+
+.. option:: -fwhole-file, -fno-whole-file
+
+.. option:: -nocpp
+
+.. option:: -static-libgfortran
+
+Linker flags
+============
+Flags that are passed on to the linker
+
+.. option:: -L<dir>, --library-directory <arg>, --library-directory=<arg>
+
+Add directory to library search path
+
+.. option:: -Mach
+
+.. option:: -T<script>
+
+Specify <script> as linker script
+
+.. option:: -Tbss<addr>
+
+Set starting address of BSS to <addr>
+
+.. option:: -Tdata<addr>
+
+Set starting address of BSS to <addr>
+
+.. option:: -Ttext<addr>
+
+Set starting address of BSS to <addr>
+
+.. option:: -Wl,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the linker
+
+.. option:: -X
+
+.. option:: -Xlinker <arg>, --for-linker <arg>, --for-linker=<arg>
+
+Pass <arg> to the linker
+
+.. program:: clang1
+.. option:: -Z
+.. program:: clang
+
+.. option:: -e<arg>, --entry
+
+.. option:: -filelist <arg>
+
+.. option:: -l<arg>
+
+.. option:: -r
+
+.. option:: -rpath <arg>
+
+.. option:: -s
+
+.. option:: -t
+
+.. option:: -u<arg>, --force-link <arg>, --force-link=<arg>
+
+.. option:: -undef
+
+undef all system defines
+
+.. option:: -undefined<arg>, --no-undefined
+
+.. option:: -z <arg>
+
+Pass -z <arg> to the linker
+
Added: www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangFormat.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangFormat.txt?rev=331981&view=auto
==============================================================================
--- www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangFormat.txt (added)
+++ www-releases/trunk/5.0.2/tools/clang/docs/_sources/ClangFormat.txt Thu May 10 06:54:16 2018
@@ -0,0 +1,209 @@
+===========
+ClangFormat
+===========
+
+`ClangFormat` describes a set of tools that are built on top of
+:doc:`LibFormat`. It can support your workflow in a variety of ways including a
+standalone tool and editor integrations.
+
+
+Standalone Tool
+===============
+
+:program:`clang-format` is located in `clang/tools/clang-format` and can be used
+to format C/C++/Obj-C code.
+
+.. code-block:: console
+
+ $ clang-format -help
+ OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf code.
+
+ If no arguments are specified, it formats the code from standard input
+ and writes the result to the standard output.
+ If <file>s are given, it reformats the files. If -i is specified
+ together with <file>s, the files are edited in-place. Otherwise, the
+ result is written to the standard output.
+
+ USAGE: clang-format [options] [<file> ...]
+
+ OPTIONS:
+
+ Clang-format options:
+
+ -assume-filename=<string> - When reading from stdin, clang-format assumes this
+ filename to look for a style config file (with
+ -style=file) and to determine the language.
+ -cursor=<uint> - The position of the cursor when invoking
+ clang-format from an editor integration
+ -dump-config - Dump configuration options to stdout and exit.
+ Can be used with -style option.
+ -fallback-style=<string> - The name of the predefined style used as a
+ fallback in case clang-format is invoked with
+ -style=file, but can not find the .clang-format
+ file to use.
+ Use -fallback-style=none to skip formatting.
+ -i - Inplace edit <file>s, if specified.
+ -length=<uint> - Format a range of this length (in bytes).
+ Multiple ranges can be formatted by specifying
+ several -offset and -length pairs.
+ When only a single -offset is specified without
+ -length, clang-format will format up to the end
+ of the file.
+ Can only be used with one input file.
+ -lines=<string> - <start line>:<end line> - format a range of
+ lines (both 1-based).
+ Multiple ranges can be formatted by specifying
+ several -lines arguments.
+ Can't be used with -offset and -length.
+ Can only be used with one input file.
+ -offset=<uint> - Format a range starting at this byte offset.
+ Multiple ranges can be formatted by specifying
+ several -offset and -length pairs.
+ Can only be used with one input file.
+ -output-replacements-xml - Output replacements as XML.
+ -sort-includes - Sort touched include lines
+ -style=<string> - Coding style, currently supports:
+ LLVM, Google, Chromium, Mozilla, WebKit.
+ Use -style=file to load style configuration from
+ .clang-format file located in one of the parent
+ directories of the source file (or current
+ directory for stdin).
+ Use -style="{key: value, ...}" to set specific
+ parameters, e.g.:
+ -style="{BasedOnStyle: llvm, IndentWidth: 8}"
+
+ Generic Options:
+
+ -help - Display available options (-help-hidden for more)
+ -help-list - Display list of available options (-help-list-hidden for more)
+ -version - Display the version of this program
+
+
+When the desired code formatting style is different from the available options,
+the style can be customized using the ``-style="{key: value, ...}"`` option or
+by putting your style configuration in the ``.clang-format`` or ``_clang-format``
+file in your project's directory and using ``clang-format -style=file``.
+
+An easy way to create the ``.clang-format`` file is:
+
+.. code-block:: console
+
+ clang-format -style=llvm -dump-config > .clang-format
+
+Available style options are described in :doc:`ClangFormatStyleOptions`.
+
+
+Vim Integration
+===============
+
+There is an integration for :program:`vim` which lets you run the
+:program:`clang-format` standalone tool on your current buffer, optionally
+selecting regions to reformat. The integration has the form of a `python`-file
+which can be found under `clang/tools/clang-format/clang-format.py`.
+
+This can be integrated by adding the following to your `.vimrc`:
+
+.. code-block:: vim
+
+ map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
+ imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>
+
+The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
+second line adds support for INSERT mode. Change "C-K" to another binding if
+you need :program:`clang-format` on a different key (C-K stands for Ctrl+k).
+
+With this integration you can press the bound key and clang-format will
+format the current line in NORMAL and INSERT mode or the selected region in
+VISUAL mode. The line or region is extended to the next bigger syntactic
+entity.
+
+It operates on the current, potentially unsaved buffer and does not create
+or save any files. To revert a formatting, just undo.
+
+An alternative option is to format changes when saving a file and thus to
+have a zero-effort integration into the coding workflow. To do this, add this to
+your `.vimrc`:
+
+.. code-block:: vim
+
+ function! Formatonsave()
+ let l:formatdiff = 1
+ pyf ~/llvm/tools/clang/tools/clang-format/clang-format.py
+ endfunction
+ autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()
+
+
+Emacs Integration
+=================
+
+Similar to the integration for :program:`vim`, there is an integration for
+:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`
+and used by adding this to your `.emacs`:
+
+.. code-block:: common-lisp
+
+ (load "<path-to-clang>/tools/clang-format/clang-format.el")
+ (global-set-key [C-M-tab] 'clang-format-region)
+
+This binds the function `clang-format-region` to C-M-tab, which then formats the
+current line or selected region.
+
+
+BBEdit Integration
+==================
+
+:program:`clang-format` cannot be used as a text filter with BBEdit, but works
+well via a script. The AppleScript to do this integration can be found at
+`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in
+`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to
+point to your local copy of :program:`clang-format`.
+
+With this integration you can select the script from the Script menu and
+:program:`clang-format` will format the selection. Note that you can rename the
+menu item by renaming the script, and can assign the menu item a keyboard
+shortcut in the BBEdit preferences, under Menus & Shortcuts.
+
+
+Visual Studio Integration
+=========================
+
+Download the latest Visual Studio extension from the `alpha build site
+<http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
+
+
+Script for patch reformatting
+=============================
+
+The python script `clang/tools/clang-format/clang-format-diff.py` parses the
+output of a unified diff and reformats all contained lines with
+:program:`clang-format`.
+
+.. code-block:: console
+
+ usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]
+
+ Reformat changed lines in diff. Without -i option just output the diff that
+ would be introduced.
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -i apply edits to files instead of displaying a diff
+ -p NUM strip the smallest prefix containing P slashes
+ -regex PATTERN custom pattern selecting file paths to reformat
+ -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla,
+ WebKit)
+
+So to reformat all the lines in the latest :program:`git` commit, just do:
+
+.. code-block:: console
+
+ git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1
+
+In an SVN client, you can do:
+
+.. code-block:: console
+
+ svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i
+
+The option `-U0` will create a diff without context lines (the script would format
+those as well).
More information about the llvm-commits
mailing list