[www-releases] r211020 - Add 3.4.2 binaries and source.

Mon Jun 16 06:19:10 PDT 2014

Added: www-releases/trunk/3.4.2/docs/tutorial/OCamlLangImpl7.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/docs/tutorial/OCamlLangImpl7.html?rev=211020&view=auto
==============================================================================

--- www-releases/trunk/3.4.2/docs/tutorial/OCamlLangImpl7.html (added)
+++ www-releases/trunk/3.4.2/docs/tutorial/OCamlLangImpl7.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,1749 @@
+
+
+<!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>7. Kaleidoscope: Extending the Language: Mutable Variables — LLVM 3.4 documentation</title>
+    
+    <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     '3.4',
+        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>
+    <link rel="top" title="LLVM 3.4 documentation" href="../index.html" />
+    <link rel="up" title="LLVM Tutorial: Table of Contents" href="index.html" />
+    <link rel="next" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits" href="OCamlLangImpl8.html" />
+    <link rel="prev" title="6. Kaleidoscope: Extending the Language: User-defined Operators" href="OCamlLangImpl6.html" />
+<style type="text/css">
+  table.right { float: right; margin-left: 20px; }
+  table.right td { border: 1px solid #ccc; }
+</style>
+
+  </head>
+  <body>
+<div class="logo">
+  <a href="../index.html">
+    <img src="../_static/logo.png"
+         alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="../genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="OCamlLangImpl8.html" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="OCamlLangImpl6.html" title="6. Kaleidoscope: Extending the Language: User-defined Operators"
+             accesskey="P">previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+
+          <li><a href="index.html" accesskey="U">LLVM Tutorial: Table of Contents</a> »</li> 
+      </ul>
+    </div>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+          <div class="body">
+            
+  <div class="section" id="kaleidoscope-extending-the-language-mutable-variables">
+<h1>7. Kaleidoscope: Extending the Language: Mutable Variables<a class="headerlink" href="#kaleidoscope-extending-the-language-mutable-variables" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#chapter-7-introduction" id="id2">Chapter 7 Introduction</a></li>
+<li><a class="reference internal" href="#why-is-this-a-hard-problem" id="id3">Why is this a hard problem?</a></li>
+<li><a class="reference internal" href="#memory-in-llvm" id="id4">Memory in LLVM</a></li>
+<li><a class="reference internal" href="#mutable-variables-in-kaleidoscope" id="id5">Mutable Variables in Kaleidoscope</a></li>
+<li><a class="reference internal" href="#adjusting-existing-variables-for-mutation" id="id6">Adjusting Existing Variables for Mutation</a></li>
+<li><a class="reference internal" href="#new-assignment-operator" id="id7">New Assignment Operator</a></li>
+<li><a class="reference internal" href="#user-defined-local-variables" id="id8">User-defined Local Variables</a></li>
+<li><a class="reference internal" href="#id1" id="id9">Full Code Listing</a></li>
+</ul>
+</div>
+<div class="section" id="chapter-7-introduction">
+<h2><a class="toc-backref" href="#id2">7.1. Chapter 7 Introduction</a><a class="headerlink" href="#chapter-7-introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>Welcome to Chapter 7 of the “<a class="reference external" href="index.html">Implementing a language with
+LLVM</a>” tutorial. In chapters 1 through 6, we’ve built a
+very respectable, albeit simple, <a class="reference external" href="http://en.wikipedia.org/wiki/Functional_programming">functional programming
+language</a>. In our
+journey, we learned some parsing techniques, how to build and represent
+an AST, how to build LLVM IR, and how to optimize the resultant code as
+well as JIT compile it.</p>
+<p>While Kaleidoscope is interesting as a functional language, the fact
+that it is functional makes it “too easy” to generate LLVM IR for it. In
+particular, a functional language makes it very easy to build LLVM IR
+directly in <a class="reference external" href="http://en.wikipedia.org/wiki/Static_single_assignment_form">SSA
+form</a>.
+Since LLVM requires that the input code be in SSA form, this is a very
+nice property and it is often unclear to newcomers how to generate code
+for an imperative language with mutable variables.</p>
+<p>The short (and happy) summary of this chapter is that there is no need
+for your front-end to build SSA form: LLVM provides highly tuned and
+well tested support for this, though the way it works is a bit
+unexpected for some.</p>
+</div>
+<div class="section" id="why-is-this-a-hard-problem">
+<h2><a class="toc-backref" href="#id3">7.2. Why is this a hard problem?</a><a class="headerlink" href="#why-is-this-a-hard-problem" title="Permalink to this headline">Â¶</a></h2>
+<p>To understand why mutable variables cause complexities in SSA
+construction, consider this extremely simple C example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">G</span><span class="p">,</span> <span class="n">H</span><span class="p">;</span>
+<span class="kt">int</span> <span class="nf">test</span><span class="p">(</span><span class="kt">_Bool</span> <span class="n">Condition</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">X</span><span class="p">;</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">Condition</span><span class="p">)</span>
+    <span class="n">X</span> <span class="o">=</span> <span class="n">G</span><span class="p">;</span>
+  <span class="k">else</span>
+    <span class="n">X</span> <span class="o">=</span> <span class="n">H</span><span class="p">;</span>
+  <span class="k">return</span> <span class="n">X</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case, we have the variable “X”, whose value depends on the path
+executed in the program. Because there are two different possible values
+for X before the return instruction, a PHI node is inserted to merge the
+two values. The LLVM IR that we want for this example looks like this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@G</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span>   <span class="c">; type of @G is i32*</span>
+<span class="vg">@H</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span>   <span class="c">; type of @H is i32*</span>
+
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%Condition</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="k">br</span> <span class="k">i1</span> <span class="nv">%Condition</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cond_true</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cond_false</span>
+
+<span class="nl">cond_true:</span>
+  <span class="nv">%X.0</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@G</span>
+  <span class="k">br</span> <span class="kt">label</span> <span class="nv">%cond_next</span>
+
+<span class="nl">cond_false:</span>
+  <span class="nv">%X.1</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@H</span>
+  <span class="k">br</span> <span class="kt">label</span> <span class="nv">%cond_next</span>
+
+<span class="nl">cond_next:</span>
+  <span class="nv">%X.2</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i32</span> <span class="p">[</span> <span class="nv">%X.1</span><span class="p">,</span> <span class="nv">%cond_false</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%X.0</span><span class="p">,</span> <span class="nv">%cond_true</span> <span class="p">]</span>
+  <span class="k">ret</span> <span class="k">i32</span> <span class="nv">%X.2</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this example, the loads from the G and H global variables are
+explicit in the LLVM IR, and they live in the then/else branches of the
+if statement (cond_true/cond_false). In order to merge the incoming
+values, the X.2 phi node in the cond_next block selects the right value
+to use based on where control flow is coming from: if control flow comes
+from the cond_false block, X.2 gets the value of X.1. Alternatively, if
+control flow comes from cond_true, it gets the value of X.0. The intent
+of this chapter is not to explain the details of SSA form. For more
+information, see one of the many <a class="reference external" href="http://en.wikipedia.org/wiki/Static_single_assignment_form">online
+references</a>.</p>
+<p>The question for this article is “who places the phi nodes when lowering
+assignments to mutable variables?”. The issue here is that LLVM
+<em>requires</em> that its IR be in SSA form: there is no “non-ssa” mode for
+it. However, SSA construction requires non-trivial algorithms and data
+structures, so it is inconvenient and wasteful for every front-end to
+have to reproduce this logic.</p>
+</div>
+<div class="section" id="memory-in-llvm">
+<h2><a class="toc-backref" href="#id4">7.3. Memory in LLVM</a><a class="headerlink" href="#memory-in-llvm" title="Permalink to this headline">Â¶</a></h2>
+<p>The ‘trick’ here is that while LLVM does require all register values to
+be in SSA form, it does not require (or permit) memory objects to be in
+SSA form. In the example above, note that the loads from G and H are
+direct accesses to G and H: they are not renamed or versioned. This
+differs from some other compiler systems, which do try to version memory
+objects. In LLVM, instead of encoding dataflow analysis of memory into
+the LLVM IR, it is handled with <a class="reference external" href="../WritingAnLLVMPass.html">Analysis
+Passes</a> which are computed on demand.</p>
+<p>With this in mind, the high-level idea is that we want to make a stack
+variable (which lives in memory, because it is on the stack) for each
+mutable object in a function. To take advantage of this trick, we need
+to talk about how LLVM represents stack variables.</p>
+<p>In LLVM, all memory accesses are explicit with load/store instructions,
+and it is carefully designed not to have (or need) an “address-of”
+operator. Notice how the type of the @G/@H global variables is actually
+“i32*” even though the variable is defined as “i32”. What this means is
+that @G defines <em>space</em> for an i32 in the global data area, but its
+<em>name</em> actually refers to the address for that space. Stack variables
+work the same way, except that instead of being declared with global
+variable definitions, they are declared with the <a class="reference external" href="../LangRef.html#i_alloca">LLVM alloca
+instruction</a>:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@example</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span>           <span class="c">; type of %X is i32*.</span>
+  <span class="p">...</span>
+  <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span>       <span class="c">; load the stack value %X from the stack.</span>
+  <span class="nv">%tmp2</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%tmp</span><span class="p">,</span> <span class="m">1</span>   <span class="c">; increment it</span>
+  <span class="k">store</span> <span class="k">i32</span> <span class="nv">%tmp2</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span>  <span class="c">; store it back</span>
+  <span class="p">...</span>
+</pre></div>
+</div>
+<p>This code shows an example of how you can declare and manipulate a stack
+variable in the LLVM IR. Stack memory allocated with the alloca
+instruction is fully general: you can pass the address of the stack slot
+to functions, you can store it in other variables, etc. In our example
+above, we could rewrite the example to use the alloca technique to avoid
+using a PHI node:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@G</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span>   <span class="c">; type of @G is i32*</span>
+<span class="vg">@H</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span>   <span class="c">; type of @H is i32*</span>
+
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%Condition</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span>           <span class="c">; type of %X is i32*.</span>
+  <span class="k">br</span> <span class="k">i1</span> <span class="nv">%Condition</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cond_true</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cond_false</span>
+
+<span class="nl">cond_true:</span>
+  <span class="nv">%X.0</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@G</span>
+        <span class="k">store</span> <span class="k">i32</span> <span class="nv">%X.0</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span>   <span class="c">; Update X</span>
+  <span class="k">br</span> <span class="kt">label</span> <span class="nv">%cond_next</span>
+
+<span class="nl">cond_false:</span>
+  <span class="nv">%X.1</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@H</span>
+        <span class="k">store</span> <span class="k">i32</span> <span class="nv">%X.1</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span>   <span class="c">; Update X</span>
+  <span class="k">br</span> <span class="kt">label</span> <span class="nv">%cond_next</span>
+
+<span class="nl">cond_next:</span>
+  <span class="nv">%X.2</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span>       <span class="c">; Read X</span>
+  <span class="k">ret</span> <span class="k">i32</span> <span class="nv">%X.2</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>With this, we have discovered a way to handle arbitrary mutable
+variables without the need to create Phi nodes at all:</p>
+<ol class="arabic simple">
+<li>Each mutable variable becomes a stack allocation.</li>
+<li>Each read of the variable becomes a load from the stack.</li>
+<li>Each update of the variable becomes a store to the stack.</li>
+<li>Taking the address of a variable just uses the stack address
+directly.</li>
+</ol>
+<p>While this solution has solved our immediate problem, it introduced
+another one: we have now apparently introduced a lot of stack traffic
+for very simple and common operations, a major performance problem.
+Fortunately for us, the LLVM optimizer has a highly-tuned optimization
+pass named “mem2reg” that handles this case, promoting allocas like this
+into SSA registers, inserting Phi nodes as appropriate. If you run this
+example through the pass, for example, you’ll get:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>llvm-as < example.ll | opt -mem2reg | llvm-dis
+ at G <span class="o">=</span> weak global i32 0
+ at H <span class="o">=</span> weak global i32 0
+
+define i32 @test<span class="o">(</span>i1 %Condition<span class="o">)</span> <span class="o">{</span>
+entry:
+  br i1 %Condition, label %cond_true, label %cond_false
+
+cond_true:
+  %X.0 <span class="o">=</span> load i32* @G
+  br label %cond_next
+
+cond_false:
+  %X.1 <span class="o">=</span> load i32* @H
+  br label %cond_next
+
+cond_next:
+  %X.01 <span class="o">=</span> phi i32 <span class="o">[</span> %X.1, %cond_false <span class="o">]</span>, <span class="o">[</span> %X.0, %cond_true <span class="o">]</span>
+  ret i32 %X.01
+<span class="o">}</span>
+</pre></div>
+</div>
+<p>The mem2reg pass implements the standard “iterated dominance frontier”
+algorithm for constructing SSA form and has a number of optimizations
+that speed up (very common) degenerate cases. The mem2reg optimization
+pass is the answer to dealing with mutable variables, and we highly
+recommend that you depend on it. Note that mem2reg only works on
+variables in certain circumstances:</p>
+<ol class="arabic simple">
+<li>mem2reg is alloca-driven: it looks for allocas and if it can handle
+them, it promotes them. It does not apply to global variables or heap
+allocations.</li>
+<li>mem2reg only looks for alloca instructions in the entry block of the
+function. Being in the entry block guarantees that the alloca is only
+executed once, which makes analysis simpler.</li>
+<li>mem2reg only promotes allocas whose uses are direct loads and stores.
+If the address of the stack object is passed to a function, or if any
+funny pointer arithmetic is involved, the alloca will not be
+promoted.</li>
+<li>mem2reg only works on allocas of <a class="reference external" href="../LangRef.html#t_classifications">first
+class</a> values (such as pointers,
+scalars and vectors), and only if the array size of the allocation is
+1 (or missing in the .ll file). mem2reg is not capable of promoting
+structs or arrays to registers. Note that the “scalarrepl” pass is
+more powerful and can promote structs, “unions”, and arrays in many
+cases.</li>
+</ol>
+<p>All of these properties are easy to satisfy for most imperative
+languages, and we’ll illustrate it below with Kaleidoscope. The final
+question you may be asking is: should I bother with this nonsense for my
+front-end? Wouldn’t it be better if I just did SSA construction
+directly, avoiding use of the mem2reg optimization pass? In short, we
+strongly recommend that you use this technique for building SSA form,
+unless there is an extremely good reason not to. Using this technique
+is:</p>
+<ul class="simple">
+<li>Proven and well tested: llvm-gcc and clang both use this technique
+for local mutable variables. As such, the most common clients of LLVM
+are using this to handle a bulk of their variables. You can be sure
+that bugs are found fast and fixed early.</li>
+<li>Extremely Fast: mem2reg has a number of special cases that make it
+fast in common cases as well as fully general. For example, it has
+fast-paths for variables that are only used in a single block,
+variables that only have one assignment point, good heuristics to
+avoid insertion of unneeded phi nodes, etc.</li>
+<li>Needed for debug info generation: <a class="reference external" href="../SourceLevelDebugging.html">Debug information in
+LLVM</a> relies on having the address of
+the variable exposed so that debug info can be attached to it. This
+technique dovetails very naturally with this style of debug info.</li>
+</ul>
+<p>If nothing else, this makes it much easier to get your front-end up and
+running, and is very simple to implement. Lets extend Kaleidoscope with
+mutable variables now!</p>
+</div>
+<div class="section" id="mutable-variables-in-kaleidoscope">
+<h2><a class="toc-backref" href="#id5">7.4. Mutable Variables in Kaleidoscope</a><a class="headerlink" href="#mutable-variables-in-kaleidoscope" title="Permalink to this headline">Â¶</a></h2>
+<p>Now that we know the sort of problem we want to tackle, lets see what
+this looks like in the context of our little Kaleidoscope language.
+We’re going to add two features:</p>
+<ol class="arabic simple">
+<li>The ability to mutate variables with the ‘=’ operator.</li>
+<li>The ability to define new variables.</li>
+</ol>
+<p>While the first item is really what this is about, we only have
+variables for incoming arguments as well as for induction variables, and
+redefining those only goes so far :). Also, the ability to define new
+variables is a useful thing regardless of whether you will be mutating
+them. Here’s a motivating example that shows how we could use these:</p>
+<div class="highlight-python"><pre># Define ':' for sequencing: as a low-precedence operator that ignores operands
+# and just returns the RHS.
+def binary : 1 (x y) y;
+
+# Recursive fib, we could do this before.
+def fib(x)
+  if (x < 3) then
+    1
+  else
+    fib(x-1)+fib(x-2);
+
+# Iterative fib.
+def fibi(x)
+  var a = 1, b = 1, c in
+  (for i = 3, i < x in
+     c = a + b :
+     a = b :
+     b = c) :
+  b;
+
+# Call it.
+fibi(10);</pre>
+</div>
+<p>In order to mutate variables, we have to change our existing variables
+to use the “alloca trick”. Once we have that, we’ll add our new
+operator, then extend Kaleidoscope to support new variable definitions.</p>
+</div>
+<div class="section" id="adjusting-existing-variables-for-mutation">
+<h2><a class="toc-backref" href="#id6">7.5. Adjusting Existing Variables for Mutation</a><a class="headerlink" href="#adjusting-existing-variables-for-mutation" title="Permalink to this headline">Â¶</a></h2>
+<p>The symbol table in Kaleidoscope is managed at code generation time by
+the ‘<tt class="docutils literal"><span class="pre">named_values</span></tt>‘ map. This map currently keeps track of the LLVM
+“Value*” that holds the double value for the named variable. In order
+to support mutation, we need to change this slightly, so that it
+<tt class="docutils literal"><span class="pre">named_values</span></tt> holds the <em>memory location</em> of the variable in
+question. Note that this change is a refactoring: it changes the
+structure of the code, but does not (by itself) change the behavior of
+the compiler. All of these changes are isolated in the Kaleidoscope code
+generator.</p>
+<p>At this point in Kaleidoscope’s development, it only supports variables
+for two things: incoming arguments to functions and the induction
+variable of ‘for’ loops. For consistency, we’ll allow mutation of these
+variables in addition to other user-defined variables. This means that
+these will both need memory locations.</p>
+<p>To start our transformation of Kaleidoscope, we’ll change the
+<tt class="docutils literal"><span class="pre">named_values</span></tt> map so that it maps to AllocaInst* instead of Value*.
+Once we do this, the C++ compiler will tell us what parts of the code we
+need to update:</p>
+<p><strong>Note:</strong> the ocaml bindings currently model both <tt class="docutils literal"><span class="pre">Value*</span></tt>‘s and
+<tt class="docutils literal"><span class="pre">AllocInst*</span></tt>‘s as <tt class="docutils literal"><span class="pre">Llvm.llvalue</span></tt>‘s, but this may change in the future
+to be more type safe.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="n">named_values</span><span class="o">:(</span><span class="kt">string</span><span class="o">,</span> <span class="n">llvalue</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+</pre></div>
+</div>
+<p>Also, since we will need to create these alloca’s, we’ll use a helper
+function that ensures that the allocas are created in the entry block of
+the function:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Create an alloca instruction in the entry block of the function. This</span>
+<span class="c"> * is used for mutable variables etc. *)</span>
+<span class="k">let</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="o">=</span>
+  <span class="k">let</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">builder_at</span> <span class="o">(</span><span class="n">instr_begin</span> <span class="o">(</span><span class="n">entry_block</span> <span class="n">the_function</span><span class="o">))</span> <span class="k">in</span>
+  <span class="n">build_alloca</span> <span class="n">double_type</span> <span class="n">var_name</span> <span class="n">builder</span>
+</pre></div>
+</div>
+<p>This funny looking code creates an <tt class="docutils literal"><span class="pre">Llvm.llbuilder</span></tt> object that is
+pointing at the first instruction of the entry block. It then creates an
+alloca with the expected name and returns it. Because all values in
+Kaleidoscope are doubles, there is no need to pass in a type to use.</p>
+<p>With this in place, the first functionality change we want to make is to
+variable references. In our new scheme, variables live on the stack, so
+code generating a reference to them actually needs to produce a load
+from the stack slot:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+  <span class="o">...</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">v</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+        <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">)</span>
+      <span class="k">in</span>
+      <span class="c">(* Load the value. *)</span>
+      <span class="n">build_load</span> <span class="n">v</span> <span class="n">name</span> <span class="n">builder</span>
+</pre></div>
+</div>
+<p>As you can see, this is pretty straightforward. Now we need to update
+the things that define the variables to set up the alloca. We’ll start
+with <tt class="docutils literal"><span class="pre">codegen_expr</span> <span class="pre">Ast.For</span> <span class="pre">...</span></tt> (see the <a class="reference external" href="#code">full code listing</a>
+for the unabridged code):</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+    <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="o">(</span><span class="n">insertion_block</span> <span class="n">builder</span><span class="o">)</span> <span class="k">in</span>
+
+    <span class="c">(* Create an alloca for the variable in the entry block. *)</span>
+    <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+
+    <span class="c">(* Emit the start code first, without 'variable' in scope. *)</span>
+    <span class="k">let</span> <span class="n">start_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">start</span> <span class="k">in</span>
+
+    <span class="c">(* Store the value into the alloca. *)</span>
+    <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">start_val</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+    <span class="o">...</span>
+
+    <span class="c">(* Within the loop, the variable is defined equal to the PHI node. If it</span>
+<span class="c">     * shadows an existing variable, we have to restore it, so save it</span>
+<span class="c">     * now. *)</span>
+    <span class="k">let</span> <span class="n">old_val</span> <span class="o">=</span>
+      <span class="k">try</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span><span class="o">)</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="nc">None</span>
+    <span class="k">in</span>
+    <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+
+    <span class="o">...</span>
+
+    <span class="c">(* Compute the end condition. *)</span>
+    <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">end_</span> <span class="k">in</span>
+
+    <span class="c">(* Reload, increment, and restore the alloca. This handles the case where</span>
+<span class="c">     * the body of the loop mutates the variable. *)</span>
+    <span class="k">let</span> <span class="n">cur_var</span> <span class="o">=</span> <span class="n">build_load</span> <span class="n">alloca</span> <span class="n">var_name</span> <span class="n">builder</span> <span class="k">in</span>
+    <span class="k">let</span> <span class="n">next_var</span> <span class="o">=</span> <span class="n">build_add</span> <span class="n">cur_var</span> <span class="n">step_val</span> <span class="s2">"nextvar"</span> <span class="n">builder</span> <span class="k">in</span>
+    <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">next_var</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+    <span class="o">...</span>
+</pre></div>
+</div>
+<p>This code is virtually identical to the code <a class="reference external" href="OCamlLangImpl5.html#forcodegen">before we allowed mutable
+variables</a>. The big difference is that
+we no longer have to construct a PHI node, and we use load/store to
+access the variable as needed.</p>
+<p>To support mutable argument variables, we need to also make allocas for
+them. The code for this is also pretty simple:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Create an alloca for each argument and register the argument in the symbol</span>
+<span class="c"> * table so that references to it will succeed. *)</span>
+<span class="k">let</span> <span class="n">create_argument_allocas</span> <span class="n">the_function</span> <span class="n">proto</span> <span class="o">=</span>
+  <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="k">match</span> <span class="n">proto</span> <span class="k">with</span>
+    <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(_,</span> <span class="n">args</span><span class="o">)</span> <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(_,</span> <span class="n">args</span><span class="o">,</span> <span class="o">_)</span> <span class="o">-></span> <span class="n">args</span>
+  <span class="k">in</span>
+  <span class="nn">Array</span><span class="p">.</span><span class="n">iteri</span> <span class="o">(</span><span class="k">fun</span> <span class="n">i</span> <span class="n">ai</span> <span class="o">-></span>
+    <span class="k">let</span> <span class="n">var_name</span> <span class="o">=</span> <span class="n">args</span><span class="o">.(</span><span class="n">i</span><span class="o">)</span> <span class="k">in</span>
+    <span class="c">(* Create an alloca for this variable. *)</span>
+    <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+
+    <span class="c">(* Store the initial value into the alloca. *)</span>
+    <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">ai</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+    <span class="c">(* Add arguments to variable symbol table. *)</span>
+    <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+  <span class="o">)</span> <span class="o">(</span><span class="n">params</span> <span class="n">the_function</span><span class="o">)</span>
+</pre></div>
+</div>
+<p>For each argument, we make an alloca, store the input value to the
+function into the alloca, and register the alloca as the memory location
+for the argument. This method gets invoked by <tt class="docutils literal"><span class="pre">Codegen.codegen_func</span></tt>
+right after it sets up the entry block for the function.</p>
+<p>The final missing piece is adding the mem2reg pass, which allows us to
+get good codegen once again:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="n">main</span> <span class="bp">()</span> <span class="o">=</span>
+  <span class="o">...</span>
+  <span class="k">let</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">create_function</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+
+  <span class="c">(* Set up the optimizer pipeline.  Start with registering info about how the</span>
+<span class="c">   * target lays out data structures. *)</span>
+  <span class="nn">DataLayout</span><span class="p">.</span><span class="n">add</span> <span class="o">(</span><span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">target_data</span> <span class="n">the_execution_engine</span><span class="o">)</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="c">(* Promote allocas to registers. *)</span>
+  <span class="n">add_memory_to_register_promotion</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="c">(* Do simple "peephole" optimizations and bit-twiddling optzn. *)</span>
+  <span class="n">add_instruction_combining</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="c">(* reassociate expressions. *)</span>
+  <span class="n">add_reassociation</span> <span class="n">the_fpm</span><span class="o">;</span>
+</pre></div>
+</div>
+<p>It is interesting to see what the code looks like before and after the
+mem2reg optimization runs. For example, this is the before/after code
+for our recursive fib function. Before the optimization:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%x1</span> <span class="p">=</span> <span class="k">alloca</span> <span class="kt">double</span>
+  <span class="k">store</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="kt">double</span><span class="p">*</span> <span class="nv">%x1</span>
+  <span class="nv">%x2</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">double</span><span class="p">*</span> <span class="nv">%x1</span>
+  <span class="nv">%cmptmp</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ult</span> <span class="kt">double</span> <span class="nv">%x2</span><span class="p">,</span> <span class="m">3.000000e+00</span>
+  <span class="nv">%booltmp</span> <span class="p">=</span> <span class="k">uitofp</span> <span class="k">i1</span> <span class="nv">%cmptmp</span> <span class="k">to</span> <span class="kt">double</span>
+  <span class="nv">%ifcond</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">one</span> <span class="kt">double</span> <span class="nv">%booltmp</span><span class="p">,</span> <span class="m">0.000000e+00</span>
+  <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ifcond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%else</span>
+
+<span class="nl">then:</span>    <span class="c">; preds = %entry</span>
+  <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">else:</span>    <span class="c">; preds = %entry</span>
+  <span class="nv">%x3</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">double</span><span class="p">*</span> <span class="nv">%x1</span>
+  <span class="nv">%subtmp</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x3</span><span class="p">,</span> <span class="m">1.000000e+00</span>
+  <span class="nv">%calltmp</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp</span><span class="p">)</span>
+  <span class="nv">%x4</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">double</span><span class="p">*</span> <span class="nv">%x1</span>
+  <span class="nv">%subtmp5</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x4</span><span class="p">,</span> <span class="m">2.000000e+00</span>
+  <span class="nv">%calltmp6</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp5</span><span class="p">)</span>
+  <span class="nv">%addtmp</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">double</span> <span class="nv">%calltmp</span><span class="p">,</span> <span class="nv">%calltmp6</span>
+  <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">ifcont:</span>    <span class="c">; preds = %else, %then</span>
+  <span class="nv">%iftmp</span> <span class="p">=</span> <span class="k">phi</span> <span class="kt">double</span> <span class="p">[</span> <span class="m">1.000000e+00</span><span class="p">,</span> <span class="nv">%then</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%addtmp</span><span class="p">,</span> <span class="nv">%else</span> <span class="p">]</span>
+  <span class="k">ret</span> <span class="kt">double</span> <span class="nv">%iftmp</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here there is only one variable (x, the input argument) but you can
+still see the extremely simple-minded code generation strategy we are
+using. In the entry block, an alloca is created, and the initial input
+value is stored into it. Each reference to the variable does a reload
+from the stack. Also, note that we didn’t modify the if/then/else
+expression, so it still inserts a PHI node. While we could make an
+alloca for it, it is actually easier to create a PHI node for it, so we
+still just make the PHI.</p>
+<p>Here is the code after the mem2reg pass runs:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%cmptmp</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ult</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">3.000000e+00</span>
+  <span class="nv">%booltmp</span> <span class="p">=</span> <span class="k">uitofp</span> <span class="k">i1</span> <span class="nv">%cmptmp</span> <span class="k">to</span> <span class="kt">double</span>
+  <span class="nv">%ifcond</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">one</span> <span class="kt">double</span> <span class="nv">%booltmp</span><span class="p">,</span> <span class="m">0.000000e+00</span>
+  <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ifcond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%else</span>
+
+<span class="nl">then:</span>
+  <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">else:</span>
+  <span class="nv">%subtmp</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">1.000000e+00</span>
+  <span class="nv">%calltmp</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp</span><span class="p">)</span>
+  <span class="nv">%subtmp5</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">2.000000e+00</span>
+  <span class="nv">%calltmp6</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp5</span><span class="p">)</span>
+  <span class="nv">%addtmp</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">double</span> <span class="nv">%calltmp</span><span class="p">,</span> <span class="nv">%calltmp6</span>
+  <span class="k">br</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">ifcont:</span>    <span class="c">; preds = %else, %then</span>
+  <span class="nv">%iftmp</span> <span class="p">=</span> <span class="k">phi</span> <span class="kt">double</span> <span class="p">[</span> <span class="m">1.000000e+00</span><span class="p">,</span> <span class="nv">%then</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%addtmp</span><span class="p">,</span> <span class="nv">%else</span> <span class="p">]</span>
+  <span class="k">ret</span> <span class="kt">double</span> <span class="nv">%iftmp</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This is a trivial case for mem2reg, since there are no redefinitions of
+the variable. The point of showing this is to calm your tension about
+inserting such blatent inefficiencies :).</p>
+<p>After the rest of the optimizers run, we get:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%cmptmp</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ult</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">3.000000e+00</span>
+  <span class="nv">%booltmp</span> <span class="p">=</span> <span class="k">uitofp</span> <span class="k">i1</span> <span class="nv">%cmptmp</span> <span class="k">to</span> <span class="kt">double</span>
+  <span class="nv">%ifcond</span> <span class="p">=</span> <span class="k">fcmp</span> <span class="k">ueq</span> <span class="kt">double</span> <span class="nv">%booltmp</span><span class="p">,</span> <span class="m">0.000000e+00</span>
+  <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ifcond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%else</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%ifcont</span>
+
+<span class="nl">else:</span>
+  <span class="nv">%subtmp</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">1.000000e+00</span>
+  <span class="nv">%calltmp</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp</span><span class="p">)</span>
+  <span class="nv">%subtmp5</span> <span class="p">=</span> <span class="k">fsub</span> <span class="kt">double</span> <span class="nv">%x</span><span class="p">,</span> <span class="m">2.000000e+00</span>
+  <span class="nv">%calltmp6</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">double</span> <span class="vg">@fib</span><span class="p">(</span><span class="kt">double</span> <span class="nv">%subtmp5</span><span class="p">)</span>
+  <span class="nv">%addtmp</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">double</span> <span class="nv">%calltmp</span><span class="p">,</span> <span class="nv">%calltmp6</span>
+  <span class="k">ret</span> <span class="kt">double</span> <span class="nv">%addtmp</span>
+
+<span class="nl">ifcont:</span>
+  <span class="k">ret</span> <span class="kt">double</span> <span class="m">1.000000e+00</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here we see that the simplifycfg pass decided to clone the return
+instruction into the end of the ‘else’ block. This allowed it to
+eliminate some branches and the PHI node.</p>
+<p>Now that all symbol table references are updated to use stack variables,
+we’ll add the assignment operator.</p>
+</div>
+<div class="section" id="new-assignment-operator">
+<h2><a class="toc-backref" href="#id7">7.6. New Assignment Operator</a><a class="headerlink" href="#new-assignment-operator" title="Permalink to this headline">Â¶</a></h2>
+<p>With our current framework, adding a new assignment operator is really
+simple. We will parse it just like any other binary operator, but handle
+it internally (instead of allowing the user to define it). The first
+step is to set a precedence:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="n">main</span> <span class="bp">()</span> <span class="o">=</span>
+  <span class="c">(* Install standard binary operators.</span>
+<span class="c">   * 1 is the lowest precedence. *)</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'='</span> <span class="mi">2</span><span class="o">;</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'<'</span> <span class="mi">10</span><span class="o">;</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'+'</span> <span class="mi">20</span><span class="o">;</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'-'</span> <span class="mi">20</span><span class="o">;</span>
+  <span class="o">...</span>
+</pre></div>
+</div>
+<p>Now that the parser knows the precedence of the binary operator, it
+takes care of all the parsing and AST generation. We just need to
+implement codegen for the assignment operator. This looks like:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+      <span class="k">begin</span> <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+      <span class="o">|</span> <span class="sc">'='</span> <span class="o">-></span>
+          <span class="c">(* Special case '=' because we don't want to emit the LHS as an</span>
+<span class="c">           * expression. *)</span>
+          <span class="k">let</span> <span class="n">name</span> <span class="o">=</span>
+            <span class="k">match</span> <span class="n">lhs</span> <span class="k">with</span>
+            <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span> <span class="n">name</span>
+            <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"destination of '=' must be a variable"</span><span class="o">)</span>
+          <span class="k">in</span>
+</pre></div>
+</div>
+<p>Unlike the rest of the binary operators, our assignment operator doesn’t
+follow the “emit LHS, emit RHS, do computation” model. As such, it is
+handled as a special case before the other binary operators are handled.
+The other strange thing is that it requires the LHS to be a variable. It
+is invalid to have “(x+1) = expr” - only things like “x = expr” are
+allowed.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre>    <span class="c">(* Codegen the rhs. *)</span>
+    <span class="k">let</span> <span class="n">val_</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+
+    <span class="c">(* Lookup the name. *)</span>
+    <span class="k">let</span> <span class="n">variable</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+    <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">)</span>
+    <span class="k">in</span>
+    <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">val_</span> <span class="n">variable</span> <span class="n">builder</span><span class="o">);</span>
+    <span class="n">val_</span>
+<span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+      <span class="o">...</span>
+</pre></div>
+</div>
+<p>Once we have the variable, codegen’ing the assignment is
+straightforward: we emit the RHS of the assignment, create a store, and
+return the computed value. Returning a value allows for chained
+assignments like “X = (Y = Z)”.</p>
+<p>Now that we have an assignment operator, we can mutate loop variables
+and arguments. For example, we can now run code like this:</p>
+<div class="highlight-python"><pre># Function to print a double.
+extern printd(x);
+
+# Define ':' for sequencing: as a low-precedence operator that ignores operands
+# and just returns the RHS.
+def binary : 1 (x y) y;
+
+def test(x)
+  printd(x) :
+  x = 4 :
+  printd(x);
+
+test(123);</pre>
+</div>
+<p>When run, this example prints “123” and then “4”, showing that we did
+actually mutate the value! Okay, we have now officially implemented our
+goal: getting this to work requires SSA construction in the general
+case. However, to be really useful, we want the ability to define our
+own local variables, lets add this next!</p>
+</div>
+<div class="section" id="user-defined-local-variables">
+<h2><a class="toc-backref" href="#id8">7.7. User-defined Local Variables</a><a class="headerlink" href="#user-defined-local-variables" title="Permalink to this headline">Â¶</a></h2>
+<p>Adding var/in is just like any other other extensions we made to
+Kaleidoscope: we extend the lexer, the parser, the AST and the code
+generator. The first step for adding our new ‘var/in’ construct is to
+extend the lexer. As before, this is pretty trivial, the code looks like
+this:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">type</span> <span class="n">token</span> <span class="o">=</span>
+  <span class="o">...</span>
+  <span class="c">(* var definition *)</span>
+  <span class="o">|</span> <span class="nn">Var</span>
+
+<span class="p">...</span>
+
+<span class="n">and</span> <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+      <span class="o">...</span>
+      <span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"binary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"unary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"var"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Var</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">...</span>
+</pre></div>
+</div>
+<p>The next step is to define the AST node that we will construct. For
+var/in, it looks like this:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+  <span class="o">...</span>
+  <span class="c">(* variant for var/in. *)</span>
+  <span class="o">|</span> <span class="nc">Var</span> <span class="k">of</span> <span class="o">(</span><span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span><span class="o">)</span> <span class="kt">array</span> <span class="o">*</span> <span class="n">expr</span>
+  <span class="o">...</span>
+</pre></div>
+</div>
+<p>var/in allows a list of names to be defined all at once, and each name
+can optionally have an initializer value. As such, we capture this
+information in the VarNames vector. Also, var/in has a body, this body
+is allowed to access the variables defined by the var/in.</p>
+<p>With this in place, we can define the parser pieces. The first thing we
+do is add it as a primary expression:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* primary</span>
+<span class="c"> *   ::= identifier</span>
+<span class="c"> *   ::= numberexpr</span>
+<span class="c"> *   ::= parenexpr</span>
+<span class="c"> *   ::= ifexpr</span>
+<span class="c"> *   ::= forexpr</span>
+<span class="c"> *   ::= varexpr *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">parse_primary</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">...</span>
+  <span class="c">(* varexpr</span>
+<span class="c">   *   ::= 'var' identifier ('=' expression?</span>
+<span class="c">   *             (',' identifier ('=' expression)?)* 'in' expression *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Var</span><span class="o">;</span>
+       <span class="c">(* At least one variable name is required. *)</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after var"</span><span class="o">;</span>
+       <span class="n">init</span><span class="o">=</span><span class="n">parse_var_init</span><span class="o">;</span>
+       <span class="n">var_names</span><span class="o">=</span><span class="n">parse_var_names</span> <span class="o">[(</span><span class="n">id</span><span class="o">,</span> <span class="n">init</span><span class="o">)];</span>
+       <span class="c">(* At this point, we have to have 'in'. *)</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span> <span class="o">??</span> <span class="s2">"expected 'in' keyword after 'var'"</span><span class="o">;</span>
+       <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="nn">Ast</span><span class="p">.</span><span class="nc">Var</span> <span class="o">(</span><span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">var_names</span><span class="o">),</span> <span class="n">body</span><span class="o">)</span>
+
+<span class="o">...</span>
+
+<span class="ow">and</span> <span class="n">parse_var_init</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="c">(* read in the optional initializer. *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">e</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+
+<span class="ow">and</span> <span class="n">parse_var_names</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier list after var"</span><span class="o">;</span>
+       <span class="n">init</span><span class="o">=</span><span class="n">parse_var_init</span><span class="o">;</span>
+       <span class="n">e</span><span class="o">=</span><span class="n">parse_var_names</span> <span class="o">((</span><span class="n">id</span><span class="o">,</span> <span class="n">init</span><span class="o">)</span> <span class="o">::</span> <span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+</pre></div>
+</div>
+<p>Now that we can parse and represent the code, we need to support
+emission of LLVM IR for it. This code starts out with:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+  <span class="o">...</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Var</span> <span class="o">(</span><span class="n">var_names</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span>
+      <span class="k">let</span> <span class="n">old_bindings</span> <span class="o">=</span> <span class="n">ref</span> <span class="bp">[]</span> <span class="k">in</span>
+
+      <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="o">(</span><span class="n">insertion_block</span> <span class="n">builder</span><span class="o">)</span> <span class="k">in</span>
+
+      <span class="c">(* Register all variables and emit their initializer. *)</span>
+      <span class="nn">Array</span><span class="p">.</span><span class="n">iter</span> <span class="o">(</span><span class="k">fun</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">init</span><span class="o">)</span> <span class="o">-></span>
+</pre></div>
+</div>
+<p>Basically it loops over all the variables, installing them one at a
+time. For each variable we put into the symbol table, we remember the
+previous value that we replace in OldBindings.</p>
+<div class="highlight-ocaml"><div class="highlight"><pre>  <span class="c">(* Emit the initializer before adding the variable to scope, this</span>
+<span class="c">   * prevents the initializer from referencing the variable itself, and</span>
+<span class="c">   * permits stuff like this:</span>
+<span class="c">   *   var a = 1 in</span>
+<span class="c">   *     var a = a in ...   # refers to outer 'a'. *)</span>
+  <span class="k">let</span> <span class="n">init_val</span> <span class="o">=</span>
+    <span class="k">match</span> <span class="n">init</span> <span class="k">with</span>
+    <span class="o">|</span> <span class="nc">Some</span> <span class="n">init</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">init</span>
+    <span class="c">(* If not specified, use 0.0. *)</span>
+    <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span>
+  <span class="k">in</span>
+
+  <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+  <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">init_val</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+  <span class="c">(* Remember the old variable binding so that we can restore the binding</span>
+<span class="c">   * when we unrecurse. *)</span>
+
+  <span class="k">begin</span>
+    <span class="k">try</span>
+      <span class="k">let</span> <span class="n">old_value</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="k">in</span>
+      <span class="n">old_bindings</span> <span class="o">:=</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">old_value</span><span class="o">)</span> <span class="o">::</span> <span class="o">!</span><span class="n">old_bindings</span><span class="o">;</span>
+    <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">></span> <span class="bp">()</span>
+  <span class="k">end</span><span class="o">;</span>
+
+  <span class="c">(* Remember this binding. *)</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+<span class="o">)</span> <span class="n">var_names</span><span class="o">;</span>
+</pre></div>
+</div>
+<p>There are more comments here than code. The basic idea is that we emit
+the initializer, create the alloca, then update the symbol table to
+point to it. Once all the variables are installed in the symbol table,
+we evaluate the body of the var/in expression:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Codegen the body, now that all vars are in scope. *)</span>
+<span class="k">let</span> <span class="n">body_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">body</span> <span class="k">in</span>
+</pre></div>
+</div>
+<p>Finally, before returning, we restore the previous variable bindings:</p>
+<div class="highlight-ocaml"><div class="highlight"><pre><span class="c">(* Pop all our variables from scope. *)</span>
+<span class="nn">List</span><span class="p">.</span><span class="n">iter</span> <span class="o">(</span><span class="k">fun</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">old_value</span><span class="o">)</span> <span class="o">-></span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_value</span>
+<span class="o">)</span> <span class="o">!</span><span class="n">old_bindings</span><span class="o">;</span>
+
+<span class="c">(* Return the body computation. *)</span>
+<span class="n">body_val</span>
+</pre></div>
+</div>
+<p>The end result of all of this is that we get properly scoped variable
+definitions, and we even (trivially) allow mutation of them :).</p>
+<p>With this, we completed what we set out to do. Our nice iterative fib
+example from the intro compiles and runs just fine. The mem2reg pass
+optimizes all of our stack variables into SSA registers, inserting PHI
+nodes where needed, and our front-end remains simple: no “iterated
+dominance frontier” computation anywhere in sight.</p>
+</div>
+<div class="section" id="id1">
+<h2><a class="toc-backref" href="#id9">7.8. Full Code Listing</a><a class="headerlink" href="#id1" title="Permalink to this headline">Â¶</a></h2>
+<p>Here is the complete code listing for our running example, enhanced with
+mutable variables and var/in support. To build this example, use:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Compile</span>
+ocamlbuild toy.byte
+<span class="c"># Run</span>
+./toy.byte
+</pre></div>
+</div>
+<p>Here is the code:</p>
+<dl class="docutils">
+<dt>_tags:</dt>
+<dd><div class="first last highlight-python"><pre><{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
+<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
+<*.{byte,native}>: use_llvm_executionengine, use_llvm_target
+<*.{byte,native}>: use_llvm_scalar_opts, use_bindings</pre>
+</div>
+</dd>
+<dt>myocamlbuild.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="k">open</span> <span class="nc">Ocamlbuild_plugin</span><span class="o">;;</span>
+
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_analysis"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_executionengine"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_target"</span><span class="o">;;</span>
+<span class="n">ocaml_lib</span> <span class="o">~</span><span class="n">extern</span><span class="o">:</span><span class="bp">true</span> <span class="s2">"llvm_scalar_opts"</span><span class="o">;;</span>
+
+<span class="n">flag</span> <span class="o">[</span><span class="s2">"link"</span><span class="o">;</span> <span class="s2">"ocaml"</span><span class="o">;</span> <span class="s2">"g++"</span><span class="o">]</span> <span class="o">(</span><span class="nc">S</span><span class="o">[</span><span class="nc">A</span><span class="s2">"-cc"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"g++"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"-cclib"</span><span class="o">;</span> <span class="nc">A</span><span class="s2">"-rdynamic"</span><span class="o">]);;</span>
+<span class="n">dep</span> <span class="o">[</span><span class="s2">"link"</span><span class="o">;</span> <span class="s2">"ocaml"</span><span class="o">;</span> <span class="s2">"use_bindings"</span><span class="o">]</span> <span class="o">[</span><span class="s2">"bindings.o"</span><span class="o">];;</span>
+</pre></div>
+</div>
+</dd>
+<dt>token.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Lexer Tokens</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="c">(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of</span>
+<span class="c"> * these others for known things. *)</span>
+<span class="k">type</span> <span class="n">token</span> <span class="o">=</span>
+  <span class="c">(* commands *)</span>
+  <span class="o">|</span> <span class="nc">Def</span> <span class="o">|</span> <span class="nc">Extern</span>
+
+  <span class="c">(* primary *)</span>
+  <span class="o">|</span> <span class="nc">Ident</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">|</span> <span class="nc">Number</span> <span class="k">of</span> <span class="kt">float</span>
+
+  <span class="c">(* unknown *)</span>
+  <span class="o">|</span> <span class="nc">Kwd</span> <span class="k">of</span> <span class="kt">char</span>
+
+  <span class="c">(* control *)</span>
+  <span class="o">|</span> <span class="nc">If</span> <span class="o">|</span> <span class="nc">Then</span> <span class="o">|</span> <span class="nc">Else</span>
+  <span class="o">|</span> <span class="nc">For</span> <span class="o">|</span> <span class="nc">In</span>
+
+  <span class="c">(* operators *)</span>
+  <span class="o">|</span> <span class="nc">Binary</span> <span class="o">|</span> <span class="nc">Unary</span>
+
+  <span class="c">(* var definition *)</span>
+  <span class="o">|</span> <span class="nc">Var</span>
+</pre></div>
+</div>
+</dd>
+<dt>lexer.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Lexer</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">let</span> <span class="k">rec</span> <span class="n">lex</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="c">(* Skip any whitespace. *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">' '</span> <span class="o">|</span> <span class="sc">'\n'</span> <span class="o">|</span> <span class="sc">'\r'</span> <span class="o">|</span> <span class="sc">'\t'</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">lex</span> <span class="n">stream</span>
+
+  <span class="c">(* identifier: [a-zA-Z][a-zA-Z0-9] *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'A'</span> <span class="o">..</span> <span class="sc">'Z'</span> <span class="o">|</span> <span class="sc">'a'</span> <span class="o">..</span> <span class="sc">'z'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">create</span> <span class="mi">1</span> <span class="k">in</span>
+      <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+      <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="n">stream</span>
+
+  <span class="c">(* number: [0-9.]+ *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">create</span> <span class="mi">1</span> <span class="k">in</span>
+      <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+      <span class="n">lex_number</span> <span class="n">buffer</span> <span class="n">stream</span>
+
+  <span class="c">(* Comment until end of line. *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'#'</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="n">lex_comment</span> <span class="n">stream</span>
+
+  <span class="c">(* Otherwise, just return the character as its ascii value. *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="n">c</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c</span><span class="o">;</span> <span class="n">lex</span> <span class="n">stream</span> <span class="o">>]</span>
+
+  <span class="c">(* end of stream. *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="o">[<</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_number</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="o">|</span> <span class="sc">'.'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+      <span class="n">lex_number</span> <span class="n">buffer</span> <span class="n">stream</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="o">(</span><span class="n">float_of_string</span> <span class="o">(</span><span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span><span class="o">));</span> <span class="n">stream</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'A'</span> <span class="o">..</span> <span class="sc">'Z'</span> <span class="o">|</span> <span class="sc">'a'</span> <span class="o">..</span> <span class="sc">'z'</span> <span class="o">|</span> <span class="sc">'0'</span> <span class="o">..</span> <span class="sc">'9'</span> <span class="k">as</span> <span class="n">c</span><span class="o">);</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="nn">Buffer</span><span class="p">.</span><span class="n">add_char</span> <span class="n">buffer</span> <span class="n">c</span><span class="o">;</span>
+      <span class="n">lex_ident</span> <span class="n">buffer</span> <span class="n">stream</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="k">match</span> <span class="nn">Buffer</span><span class="p">.</span><span class="n">contents</span> <span class="n">buffer</span> <span class="k">with</span>
+      <span class="o">|</span> <span class="s2">"def"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"extern"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"if"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"then"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"else"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"for"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"in"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"binary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"unary"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="s2">"var"</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Var</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+      <span class="o">|</span> <span class="n">id</span> <span class="o">-></span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span>
+
+<span class="ow">and</span> <span class="n">lex_comment</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span> <span class="o">(</span><span class="sc">'\n'</span><span class="o">);</span> <span class="n">stream</span><span class="o">=</span><span class="n">lex</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">stream</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="n">c</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">lex_comment</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="o">[<</span> <span class="o">>]</span>
+</pre></div>
+</div>
+</dd>
+<dt>ast.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Abstract Syntax Tree (aka Parse Tree)</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="c">(* expr - Base type for all expression nodes. *)</span>
+<span class="k">type</span> <span class="n">expr</span> <span class="o">=</span>
+  <span class="c">(* variant for numeric literals like "1.0". *)</span>
+  <span class="o">|</span> <span class="nc">Number</span> <span class="k">of</span> <span class="kt">float</span>
+
+  <span class="c">(* variant for referencing a variable, like "a". *)</span>
+  <span class="o">|</span> <span class="nc">Variable</span> <span class="k">of</span> <span class="kt">string</span>
+
+  <span class="c">(* variant for a unary operator. *)</span>
+  <span class="o">|</span> <span class="nc">Unary</span> <span class="k">of</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">expr</span>
+
+  <span class="c">(* variant for a binary operator. *)</span>
+  <span class="o">|</span> <span class="nc">Binary</span> <span class="k">of</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+
+  <span class="c">(* variant for function calls. *)</span>
+  <span class="o">|</span> <span class="nc">Call</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="kt">array</span>
+
+  <span class="c">(* variant for if/then/else. *)</span>
+  <span class="o">|</span> <span class="nc">If</span> <span class="k">of</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span>
+
+  <span class="c">(* variant for for/in. *)</span>
+  <span class="o">|</span> <span class="nc">For</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span> <span class="o">*</span> <span class="n">expr</span>
+
+  <span class="c">(* variant for var/in. *)</span>
+  <span class="o">|</span> <span class="nc">Var</span> <span class="k">of</span> <span class="o">(</span><span class="kt">string</span> <span class="o">*</span> <span class="n">expr</span> <span class="n">option</span><span class="o">)</span> <span class="kt">array</span> <span class="o">*</span> <span class="n">expr</span>
+
+<span class="c">(* proto - This type represents the "prototype" for a function, which captures</span>
+<span class="c"> * its name, and its argument names (thus implicitly the number of arguments the</span>
+<span class="c"> * function takes). *)</span>
+<span class="k">type</span> <span class="n">proto</span> <span class="o">=</span>
+  <span class="o">|</span> <span class="nc">Prototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span>
+  <span class="o">|</span> <span class="nc">BinOpPrototype</span> <span class="k">of</span> <span class="kt">string</span> <span class="o">*</span> <span class="kt">string</span> <span class="kt">array</span> <span class="o">*</span> <span class="kt">int</span>
+
+<span class="c">(* func - This type represents a function definition itself. *)</span>
+<span class="k">type</span> <span class="n">func</span> <span class="o">=</span> <span class="nc">Function</span> <span class="k">of</span> <span class="n">proto</span> <span class="o">*</span> <span class="n">expr</span>
+</pre></div>
+</div>
+</dd>
+<dt>parser.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===---------------------------------------------------------------------===</span>
+<span class="c"> * Parser</span>
+<span class="c"> *===---------------------------------------------------------------------===*)</span>
+
+<span class="c">(* binop_precedence - This holds the precedence for each binary operator that is</span>
+<span class="c"> * defined *)</span>
+<span class="k">let</span> <span class="n">binop_precedence</span><span class="o">:(</span><span class="kt">char</span><span class="o">,</span> <span class="kt">int</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+
+<span class="c">(* precedence - Get the precedence of the pending binary operator token. *)</span>
+<span class="k">let</span> <span class="n">precedence</span> <span class="n">c</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">binop_precedence</span> <span class="n">c</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="o">-</span><span class="mi">1</span>
+
+<span class="c">(* primary</span>
+<span class="c"> *   ::= identifier</span>
+<span class="c"> *   ::= numberexpr</span>
+<span class="c"> *   ::= parenexpr</span>
+<span class="c"> *   ::= ifexpr</span>
+<span class="c"> *   ::= forexpr</span>
+<span class="c"> *   ::= varexpr *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">parse_primary</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="c">(* numberexpr ::= number *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span>
+
+  <span class="c">(* parenexpr ::= '(' expression ')' *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')'"</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+
+  <span class="c">(* identifierexpr</span>
+<span class="c">   *   ::= identifier</span>
+<span class="c">   *   ::= identifier '(' argumentexpr ')' *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+        <span class="o">|</span> <span class="o">[<</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+            <span class="k">begin</span> <span class="n">parser</span>
+              <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">e</span> <span class="o">::</span> <span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+              <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span> <span class="o">::</span> <span class="n">accumulator</span>
+            <span class="k">end</span> <span class="n">stream</span>
+        <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+      <span class="k">in</span>
+      <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_ident</span> <span class="n">id</span> <span class="o">=</span> <span class="n">parser</span>
+        <span class="c">(* Call. *)</span>
+        <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span><span class="o">;</span>
+             <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+             <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')'"</span><span class="o">>]</span> <span class="o">-></span>
+            <span class="nn">Ast</span><span class="p">.</span><span class="nc">Call</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+
+        <span class="c">(* Simple variable ref. *)</span>
+        <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">id</span>
+      <span class="k">in</span>
+      <span class="n">parse_ident</span> <span class="n">id</span> <span class="n">stream</span>
+
+  <span class="c">(* ifexpr ::= 'if' expr 'then' expr 'else' expr *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">If</span><span class="o">;</span> <span class="n">c</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Then</span> <span class="o">??</span> <span class="s2">"expected 'then'"</span><span class="o">;</span> <span class="n">t</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Else</span> <span class="o">??</span> <span class="s2">"expected 'else'"</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">t</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+
+  <span class="c">(* forexpr</span>
+<span class="c">        ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">For</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after for"</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span> <span class="o">??</span> <span class="s2">"expected '=' after for"</span><span class="o">;</span>
+       <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="k">begin</span> <span class="n">parser</span>
+        <span class="o">|</span> <span class="o">[<</span>
+             <span class="n">start</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+             <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span> <span class="o">??</span> <span class="s2">"expected ',' after for"</span><span class="o">;</span>
+             <span class="n">end_</span><span class="o">=</span><span class="n">parse_expr</span><span class="o">;</span>
+             <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span>
+            <span class="k">let</span> <span class="n">step</span> <span class="o">=</span>
+              <span class="k">begin</span> <span class="n">parser</span>
+              <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span> <span class="n">step</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">step</span>
+              <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+              <span class="k">end</span> <span class="n">stream</span>
+            <span class="k">in</span>
+            <span class="k">begin</span> <span class="n">parser</span>
+            <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span><span class="o">;</span> <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+                <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span>
+            <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+                <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected 'in' after for"</span><span class="o">)</span>
+            <span class="k">end</span> <span class="n">stream</span>
+        <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+            <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected '=' after for"</span><span class="o">)</span>
+      <span class="k">end</span> <span class="n">stream</span>
+
+  <span class="c">(* varexpr</span>
+<span class="c">   *   ::= 'var' identifier ('=' expression?</span>
+<span class="c">   *             (',' identifier ('=' expression)?)* 'in' expression *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Var</span><span class="o">;</span>
+       <span class="c">(* At least one variable name is required. *)</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier after var"</span><span class="o">;</span>
+       <span class="n">init</span><span class="o">=</span><span class="n">parse_var_init</span><span class="o">;</span>
+       <span class="n">var_names</span><span class="o">=</span><span class="n">parse_var_names</span> <span class="o">[(</span><span class="n">id</span><span class="o">,</span> <span class="n">init</span><span class="o">)];</span>
+       <span class="c">(* At this point, we have to have 'in'. *)</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">In</span> <span class="o">??</span> <span class="s2">"expected 'in' keyword after 'var'"</span><span class="o">;</span>
+       <span class="n">body</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="nn">Ast</span><span class="p">.</span><span class="nc">Var</span> <span class="o">(</span><span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">var_names</span><span class="o">),</span> <span class="n">body</span><span class="o">)</span>
+
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"unknown token when expecting an expression."</span><span class="o">)</span>
+
+<span class="c">(* unary</span>
+<span class="c"> *   ::= primary</span>
+<span class="c"> *   ::= '!' unary *)</span>
+<span class="ow">and</span> <span class="n">parse_unary</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="c">(* If this is a unary operator, read it. *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="k">when</span> <span class="n">op</span> <span class="o">!=</span> <span class="sc">'('</span> <span class="o">&&</span> <span class="n">op</span> <span class="o">!=</span> <span class="sc">')'</span><span class="o">;</span> <span class="n">operand</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="nn">Ast</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">operand</span><span class="o">)</span>
+
+  <span class="c">(* If the current token is not an operator, it must be a primary expr. *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_primary</span> <span class="n">stream</span>
+
+<span class="c">(* binoprhs</span>
+<span class="c"> *   ::= ('+' primary)* *)</span>
+<span class="ow">and</span> <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span> <span class="o">=</span>
+  <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+  <span class="c">(* If this is a binop, find its precedence. *)</span>
+  <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c</span><span class="o">)</span> <span class="k">when</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">mem</span> <span class="n">binop_precedence</span> <span class="n">c</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">token_prec</span> <span class="o">=</span> <span class="n">precedence</span> <span class="n">c</span> <span class="k">in</span>
+
+      <span class="c">(* If this is a binop that binds at least as tightly as the current binop,</span>
+<span class="c">       * consume it, otherwise we are done. *)</span>
+      <span class="k">if</span> <span class="n">token_prec</span> <span class="o"><</span> <span class="n">expr_prec</span> <span class="k">then</span> <span class="n">lhs</span> <span class="k">else</span> <span class="k">begin</span>
+        <span class="c">(* Eat the binop. *)</span>
+        <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+
+        <span class="c">(* Parse the primary expression after the binary operator. *)</span>
+        <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span> <span class="n">parse_unary</span> <span class="n">stream</span> <span class="k">in</span>
+
+        <span class="c">(* Okay, we know this is a binop. *)</span>
+        <span class="k">let</span> <span class="n">rhs</span> <span class="o">=</span>
+          <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+          <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">c2</span><span class="o">)</span> <span class="o">-></span>
+              <span class="c">(* If BinOp binds less tightly with rhs than the operator after</span>
+<span class="c">               * rhs, let the pending operator take rhs as its lhs. *)</span>
+              <span class="k">let</span> <span class="n">next_prec</span> <span class="o">=</span> <span class="n">precedence</span> <span class="n">c2</span> <span class="k">in</span>
+              <span class="k">if</span> <span class="n">token_prec</span> <span class="o"><</span> <span class="n">next_prec</span>
+              <span class="k">then</span> <span class="n">parse_bin_rhs</span> <span class="o">(</span><span class="n">token_prec</span> <span class="o">+</span> <span class="mi">1</span><span class="o">)</span> <span class="n">rhs</span> <span class="n">stream</span>
+              <span class="k">else</span> <span class="n">rhs</span>
+          <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="n">rhs</span>
+        <span class="k">in</span>
+
+        <span class="c">(* Merge lhs/rhs. *)</span>
+        <span class="k">let</span> <span class="n">lhs</span> <span class="o">=</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">c</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="k">in</span>
+        <span class="n">parse_bin_rhs</span> <span class="n">expr_prec</span> <span class="n">lhs</span> <span class="n">stream</span>
+      <span class="k">end</span>
+  <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="n">lhs</span>
+
+<span class="ow">and</span> <span class="n">parse_var_init</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="c">(* read in the optional initializer. *)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'='</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">Some</span> <span class="n">e</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="nc">None</span>
+
+<span class="ow">and</span> <span class="n">parse_var_names</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">','</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span> <span class="o">??</span> <span class="s2">"expected identifier list after var"</span><span class="o">;</span>
+       <span class="n">init</span><span class="o">=</span><span class="n">parse_var_init</span><span class="o">;</span>
+       <span class="n">e</span><span class="o">=</span><span class="n">parse_var_names</span> <span class="o">((</span><span class="n">id</span><span class="o">,</span> <span class="n">init</span><span class="o">)</span> <span class="o">::</span> <span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+
+<span class="c">(* expression</span>
+<span class="c"> *   ::= primary binoprhs *)</span>
+<span class="ow">and</span> <span class="n">parse_expr</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="n">lhs</span><span class="o">=</span><span class="n">parse_unary</span><span class="o">;</span> <span class="n">stream</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">parse_bin_rhs</span> <span class="mi">0</span> <span class="n">lhs</span> <span class="n">stream</span>
+
+<span class="c">(* prototype</span>
+<span class="c"> *   ::= id '(' id* ')'</span>
+<span class="c"> *   ::= binary LETTER number? (id, id)</span>
+<span class="c"> *   ::= unary LETTER number? (id) *)</span>
+<span class="k">let</span> <span class="n">parse_prototype</span> <span class="o">=</span>
+  <span class="k">let</span> <span class="k">rec</span> <span class="n">parse_args</span> <span class="n">accumulator</span> <span class="o">=</span> <span class="n">parser</span>
+    <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_args</span> <span class="o">(</span><span class="n">id</span><span class="o">::</span><span class="n">accumulator</span><span class="o">)</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+    <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">accumulator</span>
+  <span class="k">in</span>
+  <span class="k">let</span> <span class="n">parse_operator</span> <span class="o">=</span> <span class="n">parser</span>
+    <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"unary"</span><span class="o">,</span> <span class="mi">1</span>
+    <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">>]</span> <span class="o">-></span> <span class="s2">"binary"</span><span class="o">,</span> <span class="mi">2</span>
+  <span class="k">in</span>
+  <span class="k">let</span> <span class="n">parse_binary_precedence</span> <span class="o">=</span> <span class="n">parser</span>
+    <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">int_of_float</span> <span class="n">n</span>
+    <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span> <span class="mi">30</span>
+  <span class="k">in</span>
+  <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Ident</span> <span class="n">id</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+       <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="c">(* success. *)</span>
+      <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">id</span><span class="o">,</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">))</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">(</span><span class="n">prefix</span><span class="o">,</span> <span class="n">kind</span><span class="o">)=</span><span class="n">parse_operator</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="n">op</span> <span class="o">??</span> <span class="s2">"expected an operator"</span><span class="o">;</span>
+       <span class="c">(* Read the precedence if present. *)</span>
+       <span class="n">binary_precedence</span><span class="o">=</span><span class="n">parse_binary_precedence</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">'('</span> <span class="o">??</span> <span class="s2">"expected '(' in prototype"</span><span class="o">;</span>
+        <span class="n">args</span><span class="o">=</span><span class="n">parse_args</span> <span class="bp">[]</span><span class="o">;</span>
+       <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">')'</span> <span class="o">??</span> <span class="s2">"expected ')' in prototype"</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">name</span> <span class="o">=</span> <span class="n">prefix</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">of_list</span> <span class="o">(</span><span class="nn">List</span><span class="p">.</span><span class="n">rev</span> <span class="n">args</span><span class="o">)</span> <span class="k">in</span>
+
+      <span class="c">(* Verify right number of arguments for operator. *)</span>
+      <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="o">!=</span> <span class="n">kind</span>
+      <span class="k">then</span> <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"invalid number of operands for operator"</span><span class="o">)</span>
+      <span class="k">else</span>
+        <span class="k">if</span> <span class="n">kind</span> <span class="o">==</span> <span class="mi">1</span> <span class="k">then</span>
+          <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span>
+        <span class="k">else</span>
+          <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">binary_precedence</span><span class="o">)</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="k">raise</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="s2">"expected function name in prototype"</span><span class="o">)</span>
+
+<span class="c">(* definition ::= 'def' prototype expression *)</span>
+<span class="k">let</span> <span class="n">parse_definition</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span><span class="o">;</span> <span class="n">p</span><span class="o">=</span><span class="n">parse_prototype</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">p</span><span class="o">,</span> <span class="n">e</span><span class="o">)</span>
+
+<span class="c">(* toplevelexpr ::= expression *)</span>
+<span class="k">let</span> <span class="n">parse_toplevel</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_expr</span> <span class="o">>]</span> <span class="o">-></span>
+      <span class="c">(* Make an anonymous proto. *)</span>
+      <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="s2">""</span><span class="o">,</span> <span class="o">[||]),</span> <span class="n">e</span><span class="o">)</span>
+
+<span class="c">(*  external ::= 'extern' prototype *)</span>
+<span class="k">let</span> <span class="n">parse_extern</span> <span class="o">=</span> <span class="n">parser</span>
+  <span class="o">|</span> <span class="o">[<</span> <span class="k">'</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span><span class="o">;</span> <span class="n">e</span><span class="o">=</span><span class="n">parse_prototype</span> <span class="o">>]</span> <span class="o">-></span> <span class="n">e</span>
+</pre></div>
+</div>
+</dd>
+<dt>codegen.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Code Generation</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+
+<span class="k">exception</span> <span class="nc">Error</span> <span class="k">of</span> <span class="kt">string</span>
+
+<span class="k">let</span> <span class="n">context</span> <span class="o">=</span> <span class="n">global_context</span> <span class="bp">()</span>
+<span class="k">let</span> <span class="n">the_module</span> <span class="o">=</span> <span class="n">create_module</span> <span class="n">context</span> <span class="s2">"my cool jit"</span>
+<span class="k">let</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span> <span class="n">context</span>
+<span class="k">let</span> <span class="n">named_values</span><span class="o">:(</span><span class="kt">string</span><span class="o">,</span> <span class="n">llvalue</span><span class="o">)</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">t</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">create</span> <span class="mi">10</span>
+<span class="k">let</span> <span class="n">double_type</span> <span class="o">=</span> <span class="n">double_type</span> <span class="n">context</span>
+
+<span class="c">(* Create an alloca instruction in the entry block of the function. This</span>
+<span class="c"> * is used for mutable variables etc. *)</span>
+<span class="k">let</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="o">=</span>
+  <span class="k">let</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">builder_at</span> <span class="n">context</span> <span class="o">(</span><span class="n">instr_begin</span> <span class="o">(</span><span class="n">entry_block</span> <span class="n">the_function</span><span class="o">))</span> <span class="k">in</span>
+  <span class="n">build_alloca</span> <span class="n">double_type</span> <span class="n">var_name</span> <span class="n">builder</span>
+
+<span class="k">let</span> <span class="k">rec</span> <span class="n">codegen_expr</span> <span class="o">=</span> <span class="k">function</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Number</span> <span class="n">n</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="n">n</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">v</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+        <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">)</span>
+      <span class="k">in</span>
+      <span class="c">(* Load the value. *)</span>
+      <span class="n">build_load</span> <span class="n">v</span> <span class="n">name</span> <span class="n">builder</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Unary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">operand</span><span class="o">)</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">operand</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">operand</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span> <span class="s2">"unary"</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+        <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+        <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+        <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown unary operator"</span><span class="o">)</span>
+      <span class="k">in</span>
+      <span class="n">build_call</span> <span class="n">callee</span> <span class="o">[|</span><span class="n">operand</span><span class="o">|]</span> <span class="s2">"unop"</span> <span class="n">builder</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Binary</span> <span class="o">(</span><span class="n">op</span><span class="o">,</span> <span class="n">lhs</span><span class="o">,</span> <span class="n">rhs</span><span class="o">)</span> <span class="o">-></span>
+      <span class="k">begin</span> <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+      <span class="o">|</span> <span class="sc">'='</span> <span class="o">-></span>
+          <span class="c">(* Special case '=' because we don't want to emit the LHS as an</span>
+<span class="c">           * expression. *)</span>
+          <span class="k">let</span> <span class="n">name</span> <span class="o">=</span>
+            <span class="k">match</span> <span class="n">lhs</span> <span class="k">with</span>
+            <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Variable</span> <span class="n">name</span> <span class="o">-></span> <span class="n">name</span>
+            <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"destination of '=' must be a variable"</span><span class="o">)</span>
+          <span class="k">in</span>
+
+          <span class="c">(* Codegen the rhs. *)</span>
+          <span class="k">let</span> <span class="n">val_</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+
+          <span class="c">(* Lookup the name. *)</span>
+          <span class="k">let</span> <span class="n">variable</span> <span class="o">=</span> <span class="k">try</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">name</span> <span class="k">with</span>
+          <span class="o">|</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown variable name"</span><span class="o">)</span>
+          <span class="k">in</span>
+          <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">val_</span> <span class="n">variable</span> <span class="n">builder</span><span class="o">);</span>
+          <span class="n">val_</span>
+      <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+          <span class="k">let</span> <span class="n">lhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">lhs</span> <span class="k">in</span>
+          <span class="k">let</span> <span class="n">rhs_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">rhs</span> <span class="k">in</span>
+          <span class="k">begin</span>
+            <span class="k">match</span> <span class="n">op</span> <span class="k">with</span>
+            <span class="o">|</span> <span class="sc">'+'</span> <span class="o">-></span> <span class="n">build_add</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"addtmp"</span> <span class="n">builder</span>
+            <span class="o">|</span> <span class="sc">'-'</span> <span class="o">-></span> <span class="n">build_sub</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"subtmp"</span> <span class="n">builder</span>
+            <span class="o">|</span> <span class="sc">'*'</span> <span class="o">-></span> <span class="n">build_mul</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"multmp"</span> <span class="n">builder</span>
+            <span class="o">|</span> <span class="sc">'<'</span> <span class="o">-></span>
+                <span class="c">(* Convert bool 0/1 to double 0.0 or 1.0 *)</span>
+                <span class="k">let</span> <span class="n">i</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">Ult</span> <span class="n">lhs_val</span> <span class="n">rhs_val</span> <span class="s2">"cmptmp"</span> <span class="n">builder</span> <span class="k">in</span>
+                <span class="n">build_uitofp</span> <span class="n">i</span> <span class="n">double_type</span> <span class="s2">"booltmp"</span> <span class="n">builder</span>
+            <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+                <span class="c">(* If it wasn't a builtin binary operator, it must be a user defined</span>
+<span class="c">                 * one. Emit a call to it. *)</span>
+                <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span> <span class="s2">"binary"</span> <span class="o">^</span> <span class="o">(</span><span class="nn">String</span><span class="p">.</span><span class="n">make</span> <span class="mi">1</span> <span class="n">op</span><span class="o">)</span> <span class="k">in</span>
+                <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+                  <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+                  <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+                  <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"binary operator not found!"</span><span class="o">)</span>
+                <span class="k">in</span>
+                <span class="n">build_call</span> <span class="n">callee</span> <span class="o">[|</span><span class="n">lhs_val</span><span class="o">;</span> <span class="n">rhs_val</span><span class="o">|]</span> <span class="s2">"binop"</span> <span class="n">builder</span>
+          <span class="k">end</span>
+      <span class="k">end</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Call</span> <span class="o">(</span><span class="n">callee</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span> <span class="o">-></span>
+      <span class="c">(* Look up the name in the module table. *)</span>
+      <span class="k">let</span> <span class="n">callee</span> <span class="o">=</span>
+        <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">callee</span> <span class="n">the_module</span> <span class="k">with</span>
+        <span class="o">|</span> <span class="nc">Some</span> <span class="n">callee</span> <span class="o">-></span> <span class="n">callee</span>
+        <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"unknown function referenced"</span><span class="o">)</span>
+      <span class="k">in</span>
+      <span class="k">let</span> <span class="n">params</span> <span class="o">=</span> <span class="n">params</span> <span class="n">callee</span> <span class="k">in</span>
+
+      <span class="c">(* If argument mismatch error. *)</span>
+      <span class="k">if</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">params</span> <span class="o">==</span> <span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span> <span class="k">then</span> <span class="bp">()</span> <span class="k">else</span>
+        <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"incorrect # arguments passed"</span><span class="o">);</span>
+      <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">map</span> <span class="n">codegen_expr</span> <span class="n">args</span> <span class="k">in</span>
+      <span class="n">build_call</span> <span class="n">callee</span> <span class="n">args</span> <span class="s2">"calltmp"</span> <span class="n">builder</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">If</span> <span class="o">(</span><span class="n">cond</span><span class="o">,</span> <span class="n">then_</span><span class="o">,</span> <span class="n">else_</span><span class="o">)</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">cond</span> <span class="k">in</span>
+
+      <span class="c">(* Convert condition to a bool by comparing equal to 0.0 *)</span>
+      <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">cond_val</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">cond</span> <span class="n">zero</span> <span class="s2">"ifcond"</span> <span class="n">builder</span> <span class="k">in</span>
+
+      <span class="c">(* Grab the first block so that we might later add the conditional branch</span>
+<span class="c">       * to it at the end of the function. *)</span>
+      <span class="k">let</span> <span class="n">start_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="n">start_bb</span> <span class="k">in</span>
+
+      <span class="k">let</span> <span class="n">then_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"then"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+      <span class="c">(* Emit 'then' value. *)</span>
+      <span class="n">position_at_end</span> <span class="n">then_bb</span> <span class="n">builder</span><span class="o">;</span>
+      <span class="k">let</span> <span class="n">then_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">then_</span> <span class="k">in</span>
+
+      <span class="c">(* Codegen of 'then' can change the current block, update then_bb for the</span>
+<span class="c">       * phi. We create a new name because one is used for the phi node, and the</span>
+<span class="c">       * other is used for the conditional branch. *)</span>
+      <span class="k">let</span> <span class="n">new_then_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+
+      <span class="c">(* Emit 'else' value. *)</span>
+      <span class="k">let</span> <span class="n">else_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"else"</span> <span class="n">the_function</span> <span class="k">in</span>
+      <span class="n">position_at_end</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">;</span>
+      <span class="k">let</span> <span class="n">else_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">else_</span> <span class="k">in</span>
+
+      <span class="c">(* Codegen of 'else' can change the current block, update else_bb for the</span>
+<span class="c">       * phi. *)</span>
+      <span class="k">let</span> <span class="n">new_else_bb</span> <span class="o">=</span> <span class="n">insertion_block</span> <span class="n">builder</span> <span class="k">in</span>
+
+      <span class="c">(* Emit merge block. *)</span>
+      <span class="k">let</span> <span class="n">merge_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"ifcont"</span> <span class="n">the_function</span> <span class="k">in</span>
+      <span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+      <span class="k">let</span> <span class="n">incoming</span> <span class="o">=</span> <span class="o">[(</span><span class="n">then_val</span><span class="o">,</span> <span class="n">new_then_bb</span><span class="o">);</span> <span class="o">(</span><span class="n">else_val</span><span class="o">,</span> <span class="n">new_else_bb</span><span class="o">)]</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">phi</span> <span class="o">=</span> <span class="n">build_phi</span> <span class="n">incoming</span> <span class="s2">"iftmp"</span> <span class="n">builder</span> <span class="k">in</span>
+
+      <span class="c">(* Return to the start block to add the conditional branch. *)</span>
+      <span class="n">position_at_end</span> <span class="n">start_bb</span> <span class="n">builder</span><span class="o">;</span>
+      <span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">cond_val</span> <span class="n">then_bb</span> <span class="n">else_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+      <span class="c">(* Set a unconditional branch at the end of the 'then' block and the</span>
+<span class="c">       * 'else' block to the 'merge' block. *)</span>
+      <span class="n">position_at_end</span> <span class="n">new_then_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+      <span class="n">position_at_end</span> <span class="n">new_else_bb</span> <span class="n">builder</span><span class="o">;</span> <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+      <span class="c">(* Finally, set the builder to the end of the merge block. *)</span>
+      <span class="n">position_at_end</span> <span class="n">merge_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+      <span class="n">phi</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">For</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">start</span><span class="o">,</span> <span class="n">end_</span><span class="o">,</span> <span class="n">step</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+      <span class="c">(* Output this as:</span>
+<span class="c">       *   var = alloca double</span>
+<span class="c">       *   ...</span>
+<span class="c">       *   start = startexpr</span>
+<span class="c">       *   store start -> var</span>
+<span class="c">       *   goto loop</span>
+<span class="c">       * loop:</span>
+<span class="c">       *   ...</span>
+<span class="c">       *   bodyexpr</span>
+<span class="c">       *   ...</span>
+<span class="c">       * loopend:</span>
+<span class="c">       *   step = stepexpr</span>
+<span class="c">       *   endcond = endexpr</span>
+<span class="c">       *</span>
+<span class="c">       *   curvar = load var</span>
+<span class="c">       *   nextvar = curvar + step</span>
+<span class="c">       *   store nextvar -> var</span>
+<span class="c">       *   br endcond, loop, endloop</span>
+<span class="c">       * outloop: *)</span>
+
+      <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="o">(</span><span class="n">insertion_block</span> <span class="n">builder</span><span class="o">)</span> <span class="k">in</span>
+
+      <span class="c">(* Create an alloca for the variable in the entry block. *)</span>
+      <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+
+      <span class="c">(* Emit the start code first, without 'variable' in scope. *)</span>
+      <span class="k">let</span> <span class="n">start_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">start</span> <span class="k">in</span>
+
+      <span class="c">(* Store the value into the alloca. *)</span>
+      <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">start_val</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+      <span class="c">(* Make the new basic block for the loop header, inserting after current</span>
+<span class="c">       * block. *)</span>
+      <span class="k">let</span> <span class="n">loop_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"loop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+      <span class="c">(* Insert an explicit fall through from the current block to the</span>
+<span class="c">       * loop_bb. *)</span>
+      <span class="n">ignore</span> <span class="o">(</span><span class="n">build_br</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+      <span class="c">(* Start insertion in loop_bb. *)</span>
+      <span class="n">position_at_end</span> <span class="n">loop_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+      <span class="c">(* Within the loop, the variable is defined equal to the PHI node. If it</span>
+<span class="c">       * shadows an existing variable, we have to restore it, so save it</span>
+<span class="c">       * now. *)</span>
+      <span class="k">let</span> <span class="n">old_val</span> <span class="o">=</span>
+        <span class="k">try</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span><span class="o">)</span> <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="nc">None</span>
+      <span class="k">in</span>
+      <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+
+      <span class="c">(* Emit the body of the loop.  This, like any other expr, can change the</span>
+<span class="c">       * current BB.  Note that we ignore the value computed by the body, but</span>
+<span class="c">       * don't allow an error *)</span>
+      <span class="n">ignore</span> <span class="o">(</span><span class="n">codegen_expr</span> <span class="n">body</span><span class="o">);</span>
+
+      <span class="c">(* Emit the step value. *)</span>
+      <span class="k">let</span> <span class="n">step_val</span> <span class="o">=</span>
+        <span class="k">match</span> <span class="n">step</span> <span class="k">with</span>
+        <span class="o">|</span> <span class="nc">Some</span> <span class="n">step</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">step</span>
+        <span class="c">(* If not specified, use 1.0. *)</span>
+        <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">1</span><span class="o">.</span><span class="mi">0</span>
+      <span class="k">in</span>
+
+      <span class="c">(* Compute the end condition. *)</span>
+      <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">end_</span> <span class="k">in</span>
+
+      <span class="c">(* Reload, increment, and restore the alloca. This handles the case where</span>
+<span class="c">       * the body of the loop mutates the variable. *)</span>
+      <span class="k">let</span> <span class="n">cur_var</span> <span class="o">=</span> <span class="n">build_load</span> <span class="n">alloca</span> <span class="n">var_name</span> <span class="n">builder</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">next_var</span> <span class="o">=</span> <span class="n">build_add</span> <span class="n">cur_var</span> <span class="n">step_val</span> <span class="s2">"nextvar"</span> <span class="n">builder</span> <span class="k">in</span>
+      <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">next_var</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+      <span class="c">(* Convert condition to a bool by comparing equal to 0.0. *)</span>
+      <span class="k">let</span> <span class="n">zero</span> <span class="o">=</span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">end_cond</span> <span class="o">=</span> <span class="n">build_fcmp</span> <span class="nn">Fcmp</span><span class="p">.</span><span class="nc">One</span> <span class="n">end_cond</span> <span class="n">zero</span> <span class="s2">"loopcond"</span> <span class="n">builder</span> <span class="k">in</span>
+
+      <span class="c">(* Create the "after loop" block and insert it. *)</span>
+      <span class="k">let</span> <span class="n">after_bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"afterloop"</span> <span class="n">the_function</span> <span class="k">in</span>
+
+      <span class="c">(* Insert the conditional branch into the end of loop_end_bb. *)</span>
+      <span class="n">ignore</span> <span class="o">(</span><span class="n">build_cond_br</span> <span class="n">end_cond</span> <span class="n">loop_bb</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">);</span>
+
+      <span class="c">(* Any new code will be inserted in after_bb. *)</span>
+      <span class="n">position_at_end</span> <span class="n">after_bb</span> <span class="n">builder</span><span class="o">;</span>
+
+      <span class="c">(* Restore the unshadowed variable. *)</span>
+      <span class="k">begin</span> <span class="k">match</span> <span class="n">old_val</span> <span class="k">with</span>
+      <span class="o">|</span> <span class="nc">Some</span> <span class="n">old_val</span> <span class="o">-></span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_val</span>
+      <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+      <span class="k">end</span><span class="o">;</span>
+
+      <span class="c">(* for expr always returns 0.0. *)</span>
+      <span class="n">const_null</span> <span class="n">double_type</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Var</span> <span class="o">(</span><span class="n">var_names</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+      <span class="k">let</span> <span class="n">old_bindings</span> <span class="o">=</span> <span class="n">ref</span> <span class="bp">[]</span> <span class="k">in</span>
+
+      <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">block_parent</span> <span class="o">(</span><span class="n">insertion_block</span> <span class="n">builder</span><span class="o">)</span> <span class="k">in</span>
+
+      <span class="c">(* Register all variables and emit their initializer. *)</span>
+      <span class="nn">Array</span><span class="p">.</span><span class="n">iter</span> <span class="o">(</span><span class="k">fun</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">init</span><span class="o">)</span> <span class="o">-></span>
+        <span class="c">(* Emit the initializer before adding the variable to scope, this</span>
+<span class="c">         * prevents the initializer from referencing the variable itself, and</span>
+<span class="c">         * permits stuff like this:</span>
+<span class="c">         *   var a = 1 in</span>
+<span class="c">         *     var a = a in ...   # refers to outer 'a'. *)</span>
+        <span class="k">let</span> <span class="n">init_val</span> <span class="o">=</span>
+          <span class="k">match</span> <span class="n">init</span> <span class="k">with</span>
+          <span class="o">|</span> <span class="nc">Some</span> <span class="n">init</span> <span class="o">-></span> <span class="n">codegen_expr</span> <span class="n">init</span>
+          <span class="c">(* If not specified, use 0.0. *)</span>
+          <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">const_float</span> <span class="n">double_type</span> <span class="mi">0</span><span class="o">.</span><span class="mi">0</span>
+        <span class="k">in</span>
+
+        <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+        <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">init_val</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+        <span class="c">(* Remember the old variable binding so that we can restore the binding</span>
+<span class="c">         * when we unrecurse. *)</span>
+        <span class="k">begin</span>
+          <span class="k">try</span>
+            <span class="k">let</span> <span class="n">old_value</span> <span class="o">=</span> <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">find</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="k">in</span>
+            <span class="n">old_bindings</span> <span class="o">:=</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">old_value</span><span class="o">)</span> <span class="o">::</span> <span class="o">!</span><span class="n">old_bindings</span><span class="o">;</span>
+          <span class="k">with</span> <span class="nc">Not_found</span> <span class="o">-></span> <span class="bp">()</span>
+        <span class="k">end</span><span class="o">;</span>
+
+        <span class="c">(* Remember this binding. *)</span>
+        <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+      <span class="o">)</span> <span class="n">var_names</span><span class="o">;</span>
+
+      <span class="c">(* Codegen the body, now that all vars are in scope. *)</span>
+      <span class="k">let</span> <span class="n">body_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">body</span> <span class="k">in</span>
+
+      <span class="c">(* Pop all our variables from scope. *)</span>
+      <span class="nn">List</span><span class="p">.</span><span class="n">iter</span> <span class="o">(</span><span class="k">fun</span> <span class="o">(</span><span class="n">var_name</span><span class="o">,</span> <span class="n">old_value</span><span class="o">)</span> <span class="o">-></span>
+        <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">old_value</span>
+      <span class="o">)</span> <span class="o">!</span><span class="n">old_bindings</span><span class="o">;</span>
+
+      <span class="c">(* Return the body computation. *)</span>
+      <span class="n">body_val</span>
+
+<span class="k">let</span> <span class="n">codegen_proto</span> <span class="o">=</span> <span class="k">function</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">)</span> <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="o">_)</span> <span class="o">-></span>
+      <span class="c">(* Make the function type: double(double,double) etc. *)</span>
+      <span class="k">let</span> <span class="n">doubles</span> <span class="o">=</span> <span class="nn">Array</span><span class="p">.</span><span class="n">make</span> <span class="o">(</span><span class="nn">Array</span><span class="p">.</span><span class="n">length</span> <span class="n">args</span><span class="o">)</span> <span class="n">double_type</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">ft</span> <span class="o">=</span> <span class="n">function_type</span> <span class="n">double_type</span> <span class="n">doubles</span> <span class="k">in</span>
+      <span class="k">let</span> <span class="n">f</span> <span class="o">=</span>
+        <span class="k">match</span> <span class="n">lookup_function</span> <span class="n">name</span> <span class="n">the_module</span> <span class="k">with</span>
+        <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="n">declare_function</span> <span class="n">name</span> <span class="n">ft</span> <span class="n">the_module</span>
+
+        <span class="c">(* If 'f' conflicted, there was already something named 'name'. If it</span>
+<span class="c">         * has a body, don't allow redefinition or reextern. *)</span>
+        <span class="o">|</span> <span class="nc">Some</span> <span class="n">f</span> <span class="o">-></span>
+            <span class="c">(* If 'f' already has a body, reject this. *)</span>
+            <span class="k">if</span> <span class="n">block_begin</span> <span class="n">f</span> <span class="o"><></span> <span class="nc">At_end</span> <span class="n">f</span> <span class="k">then</span>
+              <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"redefinition of function"</span><span class="o">);</span>
+
+            <span class="c">(* If 'f' took a different number of arguments, reject. *)</span>
+            <span class="k">if</span> <span class="n">element_type</span> <span class="o">(</span><span class="n">type_of</span> <span class="n">f</span><span class="o">)</span> <span class="o"><></span> <span class="n">ft</span> <span class="k">then</span>
+              <span class="k">raise</span> <span class="o">(</span><span class="nc">Error</span> <span class="s2">"redefinition of function with different # args"</span><span class="o">);</span>
+            <span class="n">f</span>
+      <span class="k">in</span>
+
+      <span class="c">(* Set names for all arguments. *)</span>
+      <span class="nn">Array</span><span class="p">.</span><span class="n">iteri</span> <span class="o">(</span><span class="k">fun</span> <span class="n">i</span> <span class="n">a</span> <span class="o">-></span>
+        <span class="k">let</span> <span class="n">n</span> <span class="o">=</span> <span class="n">args</span><span class="o">.(</span><span class="n">i</span><span class="o">)</span> <span class="k">in</span>
+        <span class="n">set_value_name</span> <span class="n">n</span> <span class="n">a</span><span class="o">;</span>
+        <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">n</span> <span class="n">a</span><span class="o">;</span>
+      <span class="o">)</span> <span class="o">(</span><span class="n">params</span> <span class="n">f</span><span class="o">);</span>
+      <span class="n">f</span>
+
+<span class="c">(* Create an alloca for each argument and register the argument in the symbol</span>
+<span class="c"> * table so that references to it will succeed. *)</span>
+<span class="k">let</span> <span class="n">create_argument_allocas</span> <span class="n">the_function</span> <span class="n">proto</span> <span class="o">=</span>
+  <span class="k">let</span> <span class="n">args</span> <span class="o">=</span> <span class="k">match</span> <span class="n">proto</span> <span class="k">with</span>
+    <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Prototype</span> <span class="o">(_,</span> <span class="n">args</span><span class="o">)</span> <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(_,</span> <span class="n">args</span><span class="o">,</span> <span class="o">_)</span> <span class="o">-></span> <span class="n">args</span>
+  <span class="k">in</span>
+  <span class="nn">Array</span><span class="p">.</span><span class="n">iteri</span> <span class="o">(</span><span class="k">fun</span> <span class="n">i</span> <span class="n">ai</span> <span class="o">-></span>
+    <span class="k">let</span> <span class="n">var_name</span> <span class="o">=</span> <span class="n">args</span><span class="o">.(</span><span class="n">i</span><span class="o">)</span> <span class="k">in</span>
+    <span class="c">(* Create an alloca for this variable. *)</span>
+    <span class="k">let</span> <span class="n">alloca</span> <span class="o">=</span> <span class="n">create_entry_block_alloca</span> <span class="n">the_function</span> <span class="n">var_name</span> <span class="k">in</span>
+
+    <span class="c">(* Store the initial value into the alloca. *)</span>
+    <span class="n">ignore</span><span class="o">(</span><span class="n">build_store</span> <span class="n">ai</span> <span class="n">alloca</span> <span class="n">builder</span><span class="o">);</span>
+
+    <span class="c">(* Add arguments to variable symbol table. *)</span>
+    <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="n">named_values</span> <span class="n">var_name</span> <span class="n">alloca</span><span class="o">;</span>
+  <span class="o">)</span> <span class="o">(</span><span class="n">params</span> <span class="n">the_function</span><span class="o">)</span>
+
+<span class="k">let</span> <span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="k">function</span>
+  <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">Function</span> <span class="o">(</span><span class="n">proto</span><span class="o">,</span> <span class="n">body</span><span class="o">)</span> <span class="o">-></span>
+      <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">clear</span> <span class="n">named_values</span><span class="o">;</span>
+      <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="n">codegen_proto</span> <span class="n">proto</span> <span class="k">in</span>
+
+      <span class="c">(* If this is an operator, install it. *)</span>
+      <span class="k">begin</span> <span class="k">match</span> <span class="n">proto</span> <span class="k">with</span>
+      <span class="o">|</span> <span class="nn">Ast</span><span class="p">.</span><span class="nc">BinOpPrototype</span> <span class="o">(</span><span class="n">name</span><span class="o">,</span> <span class="n">args</span><span class="o">,</span> <span class="n">prec</span><span class="o">)</span> <span class="o">-></span>
+          <span class="k">let</span> <span class="n">op</span> <span class="o">=</span> <span class="n">name</span><span class="o">.[</span><span class="nn">String</span><span class="p">.</span><span class="n">length</span> <span class="n">name</span> <span class="o">-</span> <span class="mi">1</span><span class="o">]</span> <span class="k">in</span>
+          <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="n">op</span> <span class="n">prec</span><span class="o">;</span>
+      <span class="o">|</span> <span class="o">_</span> <span class="o">-></span> <span class="bp">()</span>
+      <span class="k">end</span><span class="o">;</span>
+
+      <span class="c">(* Create a new basic block to start insertion into. *)</span>
+      <span class="k">let</span> <span class="n">bb</span> <span class="o">=</span> <span class="n">append_block</span> <span class="n">context</span> <span class="s2">"entry"</span> <span class="n">the_function</span> <span class="k">in</span>
+      <span class="n">position_at_end</span> <span class="n">bb</span> <span class="n">builder</span><span class="o">;</span>
+
+      <span class="k">try</span>
+        <span class="c">(* Add all arguments to the symbol table and create their allocas. *)</span>
+        <span class="n">create_argument_allocas</span> <span class="n">the_function</span> <span class="n">proto</span><span class="o">;</span>
+
+        <span class="k">let</span> <span class="n">ret_val</span> <span class="o">=</span> <span class="n">codegen_expr</span> <span class="n">body</span> <span class="k">in</span>
+
+        <span class="c">(* Finish off the function. *)</span>
+        <span class="k">let</span> <span class="o">_</span> <span class="o">=</span> <span class="n">build_ret</span> <span class="n">ret_val</span> <span class="n">builder</span> <span class="k">in</span>
+
+        <span class="c">(* Validate the generated code, checking for consistency. *)</span>
+        <span class="nn">Llvm_analysis</span><span class="p">.</span><span class="n">assert_valid_function</span> <span class="n">the_function</span><span class="o">;</span>
+
+        <span class="c">(* Optimize the function. *)</span>
+        <span class="k">let</span> <span class="o">_</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">run_function</span> <span class="n">the_function</span> <span class="n">the_fpm</span> <span class="k">in</span>
+
+        <span class="n">the_function</span>
+      <span class="k">with</span> <span class="n">e</span> <span class="o">-></span>
+        <span class="n">delete_function</span> <span class="n">the_function</span><span class="o">;</span>
+        <span class="k">raise</span> <span class="n">e</span>
+</pre></div>
+</div>
+</dd>
+<dt>toplevel.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Top-Level parsing and JIT Driver</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+<span class="k">open</span> <span class="nc">Llvm_executionengine</span>
+
+<span class="c">(* top ::= definition | external | expression | ';' *)</span>
+<span class="k">let</span> <span class="k">rec</span> <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span> <span class="o">=</span>
+  <span class="k">match</span> <span class="nn">Stream</span><span class="p">.</span><span class="n">peek</span> <span class="n">stream</span> <span class="k">with</span>
+  <span class="o">|</span> <span class="nc">None</span> <span class="o">-></span> <span class="bp">()</span>
+
+  <span class="c">(* ignore top-level semicolons. *)</span>
+  <span class="o">|</span> <span class="nc">Some</span> <span class="o">(</span><span class="nn">Token</span><span class="p">.</span><span class="nc">Kwd</span> <span class="sc">';'</span><span class="o">)</span> <span class="o">-></span>
+      <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+      <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span>
+
+  <span class="o">|</span> <span class="nc">Some</span> <span class="n">token</span> <span class="o">-></span>
+      <span class="k">begin</span>
+        <span class="k">try</span> <span class="k">match</span> <span class="n">token</span> <span class="k">with</span>
+        <span class="o">|</span> <span class="nn">Token</span><span class="p">.</span><span class="nc">Def</span> <span class="o">-></span>
+            <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_definition</span> <span class="n">stream</span> <span class="k">in</span>
+            <span class="n">print_endline</span> <span class="s2">"parsed a function definition."</span><span class="o">;</span>
+            <span class="n">dump_value</span> <span class="o">(</span><span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="n">e</span><span class="o">);</span>
+        <span class="o">|</span> <span class="nn">Token</span><span class="p">.</span><span class="nc">Extern</span> <span class="o">-></span>
+            <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_extern</span> <span class="n">stream</span> <span class="k">in</span>
+            <span class="n">print_endline</span> <span class="s2">"parsed an extern."</span><span class="o">;</span>
+            <span class="n">dump_value</span> <span class="o">(</span><span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_proto</span> <span class="n">e</span><span class="o">);</span>
+        <span class="o">|</span> <span class="o">_</span> <span class="o">-></span>
+            <span class="c">(* Evaluate a top-level expression into an anonymous function. *)</span>
+            <span class="k">let</span> <span class="n">e</span> <span class="o">=</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">parse_toplevel</span> <span class="n">stream</span> <span class="k">in</span>
+            <span class="n">print_endline</span> <span class="s2">"parsed a top-level expr"</span><span class="o">;</span>
+            <span class="k">let</span> <span class="n">the_function</span> <span class="o">=</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">codegen_func</span> <span class="n">the_fpm</span> <span class="n">e</span> <span class="k">in</span>
+            <span class="n">dump_value</span> <span class="n">the_function</span><span class="o">;</span>
+
+            <span class="c">(* JIT the function, returning a function pointer. *)</span>
+            <span class="k">let</span> <span class="n">result</span> <span class="o">=</span> <span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">run_function</span> <span class="n">the_function</span> <span class="o">[||]</span>
+              <span class="n">the_execution_engine</span> <span class="k">in</span>
+
+            <span class="n">print_string</span> <span class="s2">"Evaluated to "</span><span class="o">;</span>
+            <span class="n">print_float</span> <span class="o">(</span><span class="nn">GenericValue</span><span class="p">.</span><span class="n">as_float</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">double_type</span> <span class="n">result</span><span class="o">);</span>
+            <span class="n">print_newline</span> <span class="bp">()</span><span class="o">;</span>
+        <span class="k">with</span> <span class="nn">Stream</span><span class="p">.</span><span class="nc">Error</span> <span class="n">s</span> <span class="o">|</span> <span class="nn">Codegen</span><span class="p">.</span><span class="nc">Error</span> <span class="n">s</span> <span class="o">-></span>
+          <span class="c">(* Skip token for error recovery. *)</span>
+          <span class="nn">Stream</span><span class="p">.</span><span class="n">junk</span> <span class="n">stream</span><span class="o">;</span>
+          <span class="n">print_endline</span> <span class="n">s</span><span class="o">;</span>
+      <span class="k">end</span><span class="o">;</span>
+      <span class="n">print_string</span> <span class="s2">"ready> "</span><span class="o">;</span> <span class="n">flush</span> <span class="n">stdout</span><span class="o">;</span>
+      <span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span>
+</pre></div>
+</div>
+</dd>
+<dt>toy.ml:</dt>
+<dd><div class="first last highlight-ocaml"><div class="highlight"><pre><span class="c">(*===----------------------------------------------------------------------===</span>
+<span class="c"> * Main driver code.</span>
+<span class="c"> *===----------------------------------------------------------------------===*)</span>
+
+<span class="k">open</span> <span class="nc">Llvm</span>
+<span class="k">open</span> <span class="nc">Llvm_executionengine</span>
+<span class="k">open</span> <span class="nc">Llvm_target</span>
+<span class="k">open</span> <span class="nc">Llvm_scalar_opts</span>
+
+<span class="k">let</span> <span class="n">main</span> <span class="bp">()</span> <span class="o">=</span>
+  <span class="n">ignore</span> <span class="o">(</span><span class="n">initialize_native_target</span> <span class="bp">()</span><span class="o">);</span>
+
+  <span class="c">(* Install standard binary operators.</span>
+<span class="c">   * 1 is the lowest precedence. *)</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'='</span> <span class="mi">2</span><span class="o">;</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'<'</span> <span class="mi">10</span><span class="o">;</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'+'</span> <span class="mi">20</span><span class="o">;</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'-'</span> <span class="mi">20</span><span class="o">;</span>
+  <span class="nn">Hashtbl</span><span class="p">.</span><span class="n">add</span> <span class="nn">Parser</span><span class="p">.</span><span class="n">binop_precedence</span> <span class="sc">'*'</span> <span class="mi">40</span><span class="o">;</span>    <span class="c">(* highest. *)</span>
+
+  <span class="c">(* Prime the first token. *)</span>
+  <span class="n">print_string</span> <span class="s2">"ready> "</span><span class="o">;</span> <span class="n">flush</span> <span class="n">stdout</span><span class="o">;</span>
+  <span class="k">let</span> <span class="n">stream</span> <span class="o">=</span> <span class="nn">Lexer</span><span class="p">.</span><span class="n">lex</span> <span class="o">(</span><span class="nn">Stream</span><span class="p">.</span><span class="n">of_channel</span> <span class="n">stdin</span><span class="o">)</span> <span class="k">in</span>
+
+  <span class="c">(* Create the JIT. *)</span>
+  <span class="k">let</span> <span class="n">the_execution_engine</span> <span class="o">=</span> <span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">create</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+  <span class="k">let</span> <span class="n">the_fpm</span> <span class="o">=</span> <span class="nn">PassManager</span><span class="p">.</span><span class="n">create_function</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span> <span class="k">in</span>
+
+  <span class="c">(* Set up the optimizer pipeline.  Start with registering info about how the</span>
+<span class="c">   * target lays out data structures. *)</span>
+  <span class="nn">DataLayout</span><span class="p">.</span><span class="n">add</span> <span class="o">(</span><span class="nn">ExecutionEngine</span><span class="p">.</span><span class="n">target_data</span> <span class="n">the_execution_engine</span><span class="o">)</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="c">(* Promote allocas to registers. *)</span>
+  <span class="n">add_memory_to_register_promotion</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="c">(* Do simple "peephole" optimizations and bit-twiddling optzn. *)</span>
+  <span class="n">add_instruction_combination</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="c">(* reassociate expressions. *)</span>
+  <span class="n">add_reassociation</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="c">(* Eliminate Common SubExpressions. *)</span>
+  <span class="n">add_gvn</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="c">(* Simplify the control flow graph (deleting unreachable blocks, etc). *)</span>
+  <span class="n">add_cfg_simplification</span> <span class="n">the_fpm</span><span class="o">;</span>
+
+  <span class="n">ignore</span> <span class="o">(</span><span class="nn">PassManager</span><span class="p">.</span><span class="n">initialize</span> <span class="n">the_fpm</span><span class="o">);</span>
+
+  <span class="c">(* Run the main "interpreter loop" now. *)</span>
+  <span class="nn">Toplevel</span><span class="p">.</span><span class="n">main_loop</span> <span class="n">the_fpm</span> <span class="n">the_execution_engine</span> <span class="n">stream</span><span class="o">;</span>
+
+  <span class="c">(* Print out all the generated code. *)</span>
+  <span class="n">dump_module</span> <span class="nn">Codegen</span><span class="p">.</span><span class="n">the_module</span>
+<span class="o">;;</span>
+
+<span class="n">main</span> <span class="bp">()</span>
+</pre></div>
+</div>
+</dd>
+<dt>bindings.c</dt>
+<dd><div class="first last highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
+
+<span class="cm">/* putchard - putchar that takes a double and returns 0. */</span>
+<span class="k">extern</span> <span class="kt">double</span> <span class="nf">putchard</span><span class="p">(</span><span class="kt">double</span> <span class="n">X</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">putchar</span><span class="p">((</span><span class="kt">char</span><span class="p">)</span><span class="n">X</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="cm">/* printd - printf that takes a double prints it as "%f\n", returning 0. */</span>
+<span class="k">extern</span> <span class="kt">double</span> <span class="nf">printd</span><span class="p">(</span><span class="kt">double</span> <span class="n">X</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">printf</span><span class="p">(</span><span class="s">"%f</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">X</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>
+</dd>
+</dl>
+<p><a class="reference external" href="OCamlLangImpl8.html">Next: Conclusion and other useful LLVM tidbits</a></p>
+</div>
+</div>
+
+
+          </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="../genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="OCamlLangImpl8.html" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="OCamlLangImpl6.html" title="6. Kaleidoscope: Extending the Language: User-defined Operators"
+             >previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+
+          <li><a href="index.html" >LLVM Tutorial: Table of Contents</a> »</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        © Copyright 2003-2013, LLVM Project.
+      Last updated on 2014-06-16.
+      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/3.4.2/docs/tutorial/OCamlLangImpl8.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/docs/tutorial/OCamlLangImpl8.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/docs/tutorial/OCamlLangImpl8.html (added)
+++ www-releases/trunk/3.4.2/docs/tutorial/OCamlLangImpl8.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,353 @@
+
+
+<!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>8. Kaleidoscope: Conclusion and other useful LLVM tidbits — LLVM 3.4 documentation</title>
+    
+    <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     '3.4',
+        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>
+    <link rel="top" title="LLVM 3.4 documentation" href="../index.html" />
+    <link rel="up" title="LLVM Tutorial: Table of Contents" href="index.html" />
+    <link rel="next" title="LLVM 3.4.1 Release Notes" href="../ReleaseNotes.html" />
+    <link rel="prev" title="7. Kaleidoscope: Extending the Language: Mutable Variables" href="OCamlLangImpl7.html" />
+<style type="text/css">
+  table.right { float: right; margin-left: 20px; }
+  table.right td { border: 1px solid #ccc; }
+</style>
+
+  </head>
+  <body>
+<div class="logo">
+  <a href="../index.html">
+    <img src="../_static/logo.png"
+         alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="../genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="../ReleaseNotes.html" title="LLVM 3.4.1 Release Notes"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="OCamlLangImpl7.html" title="7. Kaleidoscope: Extending the Language: Mutable Variables"
+             accesskey="P">previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+
+          <li><a href="index.html" accesskey="U">LLVM Tutorial: Table of Contents</a> »</li> 
+      </ul>
+    </div>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+          <div class="body">
+            
+  <div class="section" id="kaleidoscope-conclusion-and-other-useful-llvm-tidbits">
+<h1>8. Kaleidoscope: Conclusion and other useful LLVM tidbits<a class="headerlink" href="#kaleidoscope-conclusion-and-other-useful-llvm-tidbits" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#tutorial-conclusion" id="id2">Tutorial Conclusion</a></li>
+<li><a class="reference internal" href="#properties-of-the-llvm-ir" id="id3">Properties of the LLVM IR</a><ul>
+<li><a class="reference internal" href="#target-independence" id="id4">Target Independence</a></li>
+<li><a class="reference internal" href="#safety-guarantees" id="id5">Safety Guarantees</a></li>
+<li><a class="reference internal" href="#language-specific-optimizations" id="id6">Language-Specific Optimizations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tips-and-tricks" id="id7">Tips and Tricks</a><ul>
+<li><a class="reference internal" href="#implementing-portable-offsetof-sizeof" id="id8">Implementing portable offsetof/sizeof</a></li>
+<li><a class="reference internal" href="#garbage-collected-stack-frames" id="id9">Garbage Collected Stack Frames</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="tutorial-conclusion">
+<h2><a class="toc-backref" href="#id2">8.1. Tutorial Conclusion</a><a class="headerlink" href="#tutorial-conclusion" title="Permalink to this headline">Â¶</a></h2>
+<p>Welcome to the final chapter of the “<a class="reference external" href="index.html">Implementing a language with
+LLVM</a>” tutorial. In the course of this tutorial, we have
+grown our little Kaleidoscope language from being a useless toy, to
+being a semi-interesting (but probably still useless) toy. :)</p>
+<p>It is interesting to see how far we’ve come, and how little code it has
+taken. We built the entire lexer, parser, AST, code generator, and an
+interactive run-loop (with a JIT!) by-hand in under 700 lines of
+(non-comment/non-blank) code.</p>
+<p>Our little language supports a couple of interesting features: it
+supports user defined binary and unary operators, it uses JIT
+compilation for immediate evaluation, and it supports a few control flow
+constructs with SSA construction.</p>
+<p>Part of the idea of this tutorial was to show you how easy and fun it
+can be to define, build, and play with languages. Building a compiler
+need not be a scary or mystical process! Now that you’ve seen some of
+the basics, I strongly encourage you to take the code and hack on it.
+For example, try adding:</p>
+<ul class="simple">
+<li><strong>global variables</strong> - While global variables have questional value
+in modern software engineering, they are often useful when putting
+together quick little hacks like the Kaleidoscope compiler itself.
+Fortunately, our current setup makes it very easy to add global
+variables: just have value lookup check to see if an unresolved
+variable is in the global variable symbol table before rejecting it.
+To create a new global variable, make an instance of the LLVM
+<tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> class.</li>
+<li><strong>typed variables</strong> - Kaleidoscope currently only supports variables
+of type double. This gives the language a very nice elegance, because
+only supporting one type means that you never have to specify types.
+Different languages have different ways of handling this. The easiest
+way is to require the user to specify types for every variable
+definition, and record the type of the variable in the symbol table
+along with its Value*.</li>
+<li><strong>arrays, structs, vectors, etc</strong> - Once you add types, you can start
+extending the type system in all sorts of interesting ways. Simple
+arrays are very easy and are quite useful for many different
+applications. Adding them is mostly an exercise in learning how the
+LLVM <a class="reference external" href="../LangRef.html#i_getelementptr">getelementptr</a> instruction
+works: it is so nifty/unconventional, it <a class="reference external" href="../GetElementPtr.html">has its own
+FAQ</a>! If you add support for recursive types
+(e.g. linked lists), make sure to read the <a class="reference external" href="../ProgrammersManual.html#TypeResolve">section in the LLVM
+Programmer’s Manual</a> that
+describes how to construct them.</li>
+<li><strong>standard runtime</strong> - Our current language allows the user to access
+arbitrary external functions, and we use it for things like “printd”
+and “putchard”. As you extend the language to add higher-level
+constructs, often these constructs make the most sense if they are
+lowered to calls into a language-supplied runtime. For example, if
+you add hash tables to the language, it would probably make sense to
+add the routines to a runtime, instead of inlining them all the way.</li>
+<li><strong>memory management</strong> - Currently we can only access the stack in
+Kaleidoscope. It would also be useful to be able to allocate heap
+memory, either with calls to the standard libc malloc/free interface
+or with a garbage collector. If you would like to use garbage
+collection, note that LLVM fully supports <a class="reference external" href="../GarbageCollection.html">Accurate Garbage
+Collection</a> including algorithms that
+move objects and need to scan/update the stack.</li>
+<li><strong>debugger support</strong> - LLVM supports generation of <a class="reference external" href="../SourceLevelDebugging.html">DWARF Debug
+info</a> which is understood by common
+debuggers like GDB. Adding support for debug info is fairly
+straightforward. The best way to understand it is to compile some
+C/C++ code with “<tt class="docutils literal"><span class="pre">llvm-gcc</span> <span class="pre">-g</span> <span class="pre">-O0</span></tt>” and taking a look at what it
+produces.</li>
+<li><strong>exception handling support</strong> - LLVM supports generation of <a class="reference external" href="../ExceptionHandling.html">zero
+cost exceptions</a> which interoperate with
+code compiled in other languages. You could also generate code by
+implicitly making every function return an error value and checking
+it. You could also make explicit use of setjmp/longjmp. There are
+many different ways to go here.</li>
+<li><strong>object orientation, generics, database access, complex numbers,
+geometric programming, ...</strong> - Really, there is no end of crazy
+features that you can add to the language.</li>
+<li><strong>unusual domains</strong> - We’ve been talking about applying LLVM to a
+domain that many people are interested in: building a compiler for a
+specific language. However, there are many other domains that can use
+compiler technology that are not typically considered. For example,
+LLVM has been used to implement OpenGL graphics acceleration,
+translate C++ code to ActionScript, and many other cute and clever
+things. Maybe you will be the first to JIT compile a regular
+expression interpreter into native code with LLVM?</li>
+</ul>
+<p>Have fun - try doing something crazy and unusual. Building a language
+like everyone else always has, is much less fun than trying something a
+little crazy or off the wall and seeing how it turns out. If you get
+stuck or want to talk about it, feel free to email the <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev mailing
+list</a>: it has lots
+of people who are interested in languages and are often willing to help
+out.</p>
+<p>Before we end this tutorial, I want to talk about some “tips and tricks”
+for generating LLVM IR. These are some of the more subtle things that
+may not be obvious, but are very useful if you want to take advantage of
+LLVM’s capabilities.</p>
+</div>
+<div class="section" id="properties-of-the-llvm-ir">
+<h2><a class="toc-backref" href="#id3">8.2. Properties of the LLVM IR</a><a class="headerlink" href="#properties-of-the-llvm-ir" title="Permalink to this headline">Â¶</a></h2>
+<p>We have a couple common questions about code in the LLVM IR form - lets
+just get these out of the way right now, shall we?</p>
+<div class="section" id="target-independence">
+<h3><a class="toc-backref" href="#id4">8.2.1. Target Independence</a><a class="headerlink" href="#target-independence" title="Permalink to this headline">Â¶</a></h3>
+<p>Kaleidoscope is an example of a “portable language”: any program written
+in Kaleidoscope will work the same way on any target that it runs on.
+Many other languages have this property, e.g. lisp, java, haskell,
+javascript, python, etc (note that while these languages are portable,
+not all their libraries are).</p>
+<p>One nice aspect of LLVM is that it is often capable of preserving target
+independence in the IR: you can take the LLVM IR for a
+Kaleidoscope-compiled program and run it on any target that LLVM
+supports, even emitting C code and compiling that on targets that LLVM
+doesn’t support natively. You can trivially tell that the Kaleidoscope
+compiler generates target-independent code because it never queries for
+any target-specific information when generating code.</p>
+<p>The fact that LLVM provides a compact, target-independent,
+representation for code gets a lot of people excited. Unfortunately,
+these people are usually thinking about C or a language from the C
+family when they are asking questions about language portability. I say
+“unfortunately”, because there is really no way to make (fully general)
+C code portable, other than shipping the source code around (and of
+course, C source code is not actually portable in general either - ever
+port a really old application from 32- to 64-bits?).</p>
+<p>The problem with C (again, in its full generality) is that it is heavily
+laden with target specific assumptions. As one simple example, the
+preprocessor often destructively removes target-independence from the
+code when it processes the input text:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#ifdef __i386__</span>
+  <span class="kt">int</span> <span class="n">X</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="cp">#else</span>
+  <span class="kt">int</span> <span class="n">X</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>While it is possible to engineer more and more complex solutions to
+problems like this, it cannot be solved in full generality in a way that
+is better than shipping the actual source code.</p>
+<p>That said, there are interesting subsets of C that can be made portable.
+If you are willing to fix primitive types to a fixed size (say int =
+32-bits, and long = 64-bits), don’t care about ABI compatibility with
+existing binaries, and are willing to give up some other minor features,
+you can have portable code. This can make sense for specialized domains
+such as an in-kernel language.</p>
+</div>
+<div class="section" id="safety-guarantees">
+<h3><a class="toc-backref" href="#id5">8.2.2. Safety Guarantees</a><a class="headerlink" href="#safety-guarantees" title="Permalink to this headline">Â¶</a></h3>
+<p>Many of the languages above are also “safe” languages: it is impossible
+for a program written in Java to corrupt its address space and crash the
+process (assuming the JVM has no bugs). Safety is an interesting
+property that requires a combination of language design, runtime
+support, and often operating system support.</p>
+<p>It is certainly possible to implement a safe language in LLVM, but LLVM
+IR does not itself guarantee safety. The LLVM IR allows unsafe pointer
+casts, use after free bugs, buffer over-runs, and a variety of other
+problems. Safety needs to be implemented as a layer on top of LLVM and,
+conveniently, several groups have investigated this. Ask on the <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev
+mailing list</a> if
+you are interested in more details.</p>
+</div>
+<div class="section" id="language-specific-optimizations">
+<h3><a class="toc-backref" href="#id6">8.2.3. Language-Specific Optimizations</a><a class="headerlink" href="#language-specific-optimizations" title="Permalink to this headline">Â¶</a></h3>
+<p>One thing about LLVM that turns off many people is that it does not
+solve all the world’s problems in one system (sorry ‘world hunger’,
+someone else will have to solve you some other day). One specific
+complaint is that people perceive LLVM as being incapable of performing
+high-level language-specific optimization: LLVM “loses too much
+information”.</p>
+<p>Unfortunately, this is really not the place to give you a full and
+unified version of “Chris Lattner’s theory of compiler design”. Instead,
+I’ll make a few observations:</p>
+<p>First, you’re right that LLVM does lose information. For example, as of
+this writing, there is no way to distinguish in the LLVM IR whether an
+SSA-value came from a C “int” or a C “long” on an ILP32 machine (other
+than debug info). Both get compiled down to an ‘i32’ value and the
+information about what it came from is lost. The more general issue
+here, is that the LLVM type system uses “structural equivalence” instead
+of “name equivalence”. Another place this surprises people is if you
+have two types in a high-level language that have the same structure
+(e.g. two different structs that have a single int field): these types
+will compile down into a single LLVM type and it will be impossible to
+tell what it came from.</p>
+<p>Second, while LLVM does lose information, LLVM is not a fixed target: we
+continue to enhance and improve it in many different ways. In addition
+to adding new features (LLVM did not always support exceptions or debug
+info), we also extend the IR to capture important information for
+optimization (e.g. whether an argument is sign or zero extended,
+information about pointers aliasing, etc). Many of the enhancements are
+user-driven: people want LLVM to include some specific feature, so they
+go ahead and extend it.</p>
+<p>Third, it is <em>possible and easy</em> to add language-specific optimizations,
+and you have a number of choices in how to do it. As one trivial
+example, it is easy to add language-specific optimization passes that
+“know” things about code compiled for a language. In the case of the C
+family, there is an optimization pass that “knows” about the standard C
+library functions. If you call “exit(0)” in main(), it knows that it is
+safe to optimize that into “return 0;” because C specifies what the
+‘exit’ function does.</p>
+<p>In addition to simple library knowledge, it is possible to embed a
+variety of other language-specific information into the LLVM IR. If you
+have a specific need and run into a wall, please bring the topic up on
+the llvmdev list. At the very worst, you can always treat LLVM as if it
+were a “dumb code generator” and implement the high-level optimizations
+you desire in your front-end, on the language-specific AST.</p>
+</div>
+</div>
+<div class="section" id="tips-and-tricks">
+<h2><a class="toc-backref" href="#id7">8.3. Tips and Tricks</a><a class="headerlink" href="#tips-and-tricks" title="Permalink to this headline">Â¶</a></h2>
+<p>There is a variety of useful tips and tricks that you come to know after
+working on/with LLVM that aren’t obvious at first glance. Instead of
+letting everyone rediscover them, this section talks about some of these
+issues.</p>
+<div class="section" id="implementing-portable-offsetof-sizeof">
+<h3><a class="toc-backref" href="#id8">8.3.1. Implementing portable offsetof/sizeof</a><a class="headerlink" href="#implementing-portable-offsetof-sizeof" title="Permalink to this headline">Â¶</a></h3>
+<p>One interesting thing that comes up, if you are trying to keep the code
+generated by your compiler “target independent”, is that you often need
+to know the size of some LLVM type or the offset of some field in an
+llvm structure. For example, you might need to pass the size of a type
+into a function that allocates memory.</p>
+<p>Unfortunately, this can vary widely across targets: for example the
+width of a pointer is trivially target-specific. However, there is a
+<a class="reference external" href="http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt">clever way to use the getelementptr
+instruction</a>
+that allows you to compute this in a portable way.</p>
+</div>
+<div class="section" id="garbage-collected-stack-frames">
+<h3><a class="toc-backref" href="#id9">8.3.2. Garbage Collected Stack Frames</a><a class="headerlink" href="#garbage-collected-stack-frames" title="Permalink to this headline">Â¶</a></h3>
+<p>Some languages want to explicitly manage their stack frames, often so
+that they are garbage collected or to allow easy implementation of
+closures. There are often better ways to implement these features than
+explicit stack frames, but <a class="reference external" href="http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt">LLVM does support
+them,</a>
+if you want. It requires your front-end to convert the code into
+<a class="reference external" href="http://en.wikipedia.org/wiki/Continuation-passing_style">Continuation Passing
+Style</a> and
+the use of tail calls (which LLVM also supports).</p>
+</div>
+</div>
+</div>
+
+
+          </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="../genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="../ReleaseNotes.html" title="LLVM 3.4.1 Release Notes"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="OCamlLangImpl7.html" title="7. Kaleidoscope: Extending the Language: Mutable Variables"
+             >previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+
+          <li><a href="index.html" >LLVM Tutorial: Table of Contents</a> »</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        © Copyright 2003-2013, LLVM Project.
+      Last updated on 2014-06-16.
+      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/3.4.2/docs/tutorial/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/docs/tutorial/index.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/docs/tutorial/index.html (added)
+++ www-releases/trunk/3.4.2/docs/tutorial/index.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,179 @@
+
+
+<!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>LLVM Tutorial: Table of Contents — LLVM 3.4 documentation</title>
+    
+    <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     '3.4',
+        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>
+    <link rel="top" title="LLVM 3.4 documentation" href="../index.html" />
+    <link rel="next" title="1. Kaleidoscope: Tutorial Introduction and the Lexer" href="LangImpl1.html" />
+    <link rel="prev" title="LLVM test-suite Makefile Guide" href="../TestSuiteMakefileGuide.html" />
+<style type="text/css">
+  table.right { float: right; margin-left: 20px; }
+  table.right td { border: 1px solid #ccc; }
+</style>
+
+  </head>
+  <body>
+<div class="logo">
+  <a href="../index.html">
+    <img src="../_static/logo.png"
+         alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="../genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="LangImpl1.html" title="1. Kaleidoscope: Tutorial Introduction and the Lexer"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="../TestSuiteMakefileGuide.html" title="LLVM test-suite Makefile Guide"
+             accesskey="P">previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+ 
+      </ul>
+    </div>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+          <div class="body">
+            
+  <div class="section" id="llvm-tutorial-table-of-contents">
+<h1>LLVM Tutorial: Table of Contents<a class="headerlink" href="#llvm-tutorial-table-of-contents" title="Permalink to this headline">Â¶</a></h1>
+<div class="section" id="kaleidoscope-implementing-a-language-with-llvm">
+<h2>Kaleidoscope: Implementing a Language with LLVM<a class="headerlink" href="#kaleidoscope-implementing-a-language-with-llvm" title="Permalink to this headline">Â¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl1.html">1. Kaleidoscope: Tutorial Introduction and the Lexer</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl2.html">2. Kaleidoscope: Implementing a Parser and AST</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl3.html">3. Kaleidoscope: Code generation to LLVM IR</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl4.html">4. Kaleidoscope: Adding JIT and Optimizer Support</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl5.html">5. Kaleidoscope: Extending the Language: Control Flow</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl6.html">6. Kaleidoscope: Extending the Language: User-defined Operators</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl7.html">7. Kaleidoscope: Extending the Language: Mutable Variables</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="LangImpl8.html">8. Kaleidoscope: Conclusion and other useful LLVM tidbits</a><ul class="simple">
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="kaleidoscope-implementing-a-language-with-llvm-in-objective-caml">
+<h2>Kaleidoscope: Implementing a Language with LLVM in Objective Caml<a class="headerlink" href="#kaleidoscope-implementing-a-language-with-llvm-in-objective-caml" title="Permalink to this headline">Â¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl1.html">1. Kaleidoscope: Tutorial Introduction and the Lexer</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl2.html">2. Kaleidoscope: Implementing a Parser and AST</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl3.html">3. Kaleidoscope: Code generation to LLVM IR</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl4.html">4. Kaleidoscope: Adding JIT and Optimizer Support</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl5.html">5. Kaleidoscope: Extending the Language: Control Flow</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl6.html">6. Kaleidoscope: Extending the Language: User-defined Operators</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl7.html">7. Kaleidoscope: Extending the Language: Mutable Variables</a><ul class="simple">
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="OCamlLangImpl8.html">8. Kaleidoscope: Conclusion and other useful LLVM tidbits</a><ul class="simple">
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="external-tutorials">
+<h2>External Tutorials<a class="headerlink" href="#external-tutorials" title="Permalink to this headline">Â¶</a></h2>
+<dl class="docutils">
+<dt><a class="reference external" href="http://jonathan2251.github.com/lbd/">Tutorial: Creating an LLVM Backend for the Cpu0 Architecture</a></dt>
+<dd>A step-by-step tutorial for developing an LLVM backend. Under
+active development at <a class="reference external" href="https://github.com/Jonathan2251/lbd">https://github.com/Jonathan2251/lbd</a> (please
+contribute!).</dd>
+<dt><a class="reference external" href="http://www.embecosm.com/appnotes/ean10/ean10-howto-llvmas-1.0.html">Howto: Implementing LLVM Integrated Assembler</a></dt>
+<dd>A simple guide for how to implement an LLVM integrated assembler for an
+architecture.</dd>
+</dl>
+</div>
+<div class="section" id="advanced-topics">
+<h2>Advanced Topics<a class="headerlink" href="#advanced-topics" title="Permalink to this headline">Â¶</a></h2>
+<ol class="arabic simple">
+<li><a class="reference external" href="http://llvm.org/pubs/2004-09-22-LCPCLLVMTutorial.html">Writing an Optimization for LLVM</a></li>
+</ol>
+</div>
+</div>
+
+
+          </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="../genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="LangImpl1.html" title="1. Kaleidoscope: Tutorial Introduction and the Lexer"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="../TestSuiteMakefileGuide.html" title="LLVM test-suite Makefile Guide"
+             >previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+ 
+      </ul>
+    </div>
+    <div class="footer">
+        © Copyright 2003-2013, LLVM Project.
+      Last updated on 2014-06-16.
+      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/3.4.2/docs/yaml2obj.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/docs/yaml2obj.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/docs/yaml2obj.html (added)
+++ www-releases/trunk/3.4.2/docs/yaml2obj.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,307 @@
+
+
+<!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>yaml2obj — LLVM 3.4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '',
+        VERSION:     '3.4',
+        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>
+    <link rel="top" title="LLVM 3.4 documentation" href="index.html" />
+    <link rel="next" title="How to submit an LLVM bug report" href="HowToSubmitABug.html" />
+    <link rel="prev" title="How To Add Your Build Configuration To LLVM Buildbot Infrastructure" href="HowToAddABuilder.html" />
+<style type="text/css">
+  table.right { float: right; margin-left: 20px; }
+  table.right td { border: 1px solid #ccc; }
+</style>
+
+  </head>
+  <body>
+<div class="logo">
+  <a href="index.html">
+    <img src="_static/logo.png"
+         alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="HowToAddABuilder.html" title="How To Add Your Build Configuration To LLVM Buildbot Infrastructure"
+             accesskey="P">previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="index.html">Documentation</a>»</li>
+ 
+      </ul>
+    </div>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+          <div class="body">
+            
+  <div class="section" id="yaml2obj">
+<h1>yaml2obj<a class="headerlink" href="#yaml2obj" title="Permalink to this headline">Â¶</a></h1>
+<p>yaml2obj takes a YAML description of an object file and converts it to a binary
+file.</p>
+<blockquote>
+<div>$ yaml2obj input-file</div></blockquote>
+<p>Outputs the binary to stdout.</p>
+<div class="section" id="coff-syntax">
+<h2>COFF Syntax<a class="headerlink" href="#coff-syntax" title="Permalink to this headline">Â¶</a></h2>
+<p>Here’s a sample COFF file.</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">header</span><span class="p-Indicator">:</span>
+  <span class="l-Scalar-Plain">Machine</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_FILE_MACHINE_I386</span> <span class="c1"># (0x14C)</span>
+
+<span class="l-Scalar-Plain">sections</span><span class="p-Indicator">:</span>
+  <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">.text</span>
+    <span class="l-Scalar-Plain">Characteristics</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_SCN_CNT_CODE</span>
+                     <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_16BYTES</span>
+                     <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_EXECUTE</span>
+                     <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_READ</span>
+                     <span class="p-Indicator">]</span> <span class="c1"># 0x60500020</span>
+    <span class="l-Scalar-Plain">SectionData</span><span class="p-Indicator">:</span>
+      <span class="s">"</span><span class="se">\x83\xEC\x0C\xC7\x44\x24\x08\x00\x00\x00\x00\xC7\x04\x24\x00\x00\x00\x00\xE8\x00\x00\x00\x00\xE8\x00\x00\x00\x00\x8B\x44\x24\x08\x83\xC4\x0C\xC3</span><span class="s">"</span> <span class="c1"># |....D$.......$...............D$.....|</span>
+
+<span class="l-Scalar-Plain">symbols</span><span class="p-Indicator">:</span>
+  <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">.text</span>
+    <span class="l-Scalar-Plain">Value</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0</span>
+    <span class="l-Scalar-Plain">SectionNumber</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">1</span>
+    <span class="l-Scalar-Plain">SimpleType</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_TYPE_NULL</span> <span class="c1"># (0)</span>
+    <span class="l-Scalar-Plain">ComplexType</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_DTYPE_NULL</span> <span class="c1"># (0)</span>
+    <span class="l-Scalar-Plain">StorageClass</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_CLASS_STATIC</span> <span class="c1"># (3)</span>
+    <span class="l-Scalar-Plain">NumberOfAuxSymbols</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">1</span>
+    <span class="l-Scalar-Plain">AuxiliaryData</span><span class="p-Indicator">:</span>
+      <span class="s">"</span><span class="se">\x24\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00</span><span class="s">"</span> <span class="c1"># |$.................|</span>
+
+  <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">_main</span>
+    <span class="l-Scalar-Plain">Value</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0</span>
+    <span class="l-Scalar-Plain">SectionNumber</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">1</span>
+    <span class="l-Scalar-Plain">SimpleType</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_TYPE_NULL</span> <span class="c1"># (0)</span>
+    <span class="l-Scalar-Plain">ComplexType</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_DTYPE_NULL</span> <span class="c1"># (0)</span>
+    <span class="l-Scalar-Plain">StorageClass</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">IMAGE_SYM_CLASS_EXTERNAL</span> <span class="c1"># (2)</span>
+</pre></div>
+</div>
+<p>Here’s a simplified <a class="reference external" href="http://www.kuwata-lab.com/kwalify/ruby/users-guide.html">Kwalify</a> schema with an extension to allow alternate types.</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">map</span>
+  <span class="l-Scalar-Plain">mapping</span><span class="p-Indicator">:</span>
+    <span class="l-Scalar-Plain">header</span><span class="p-Indicator">:</span>
+      <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">map</span>
+      <span class="l-Scalar-Plain">mapping</span><span class="p-Indicator">:</span>
+        <span class="l-Scalar-Plain">Machine</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">,</span> <span class="nv">enum</span><span class="p-Indicator">:</span>
+                               <span class="p-Indicator">[</span> <span class="nv">IMAGE_FILE_MACHINE_UNKNOWN</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_AM33</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_AMD64</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_ARM</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_ARMV7</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_EBC</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_I386</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_IA64</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_M32R</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_MIPS16</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_MIPSFPU</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_MIPSFPU16</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_POWERPC</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_POWERPCFP</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_R4000</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_SH3</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_SH3DSP</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_SH4</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_SH5</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_THUMB</span>
+                               <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_MACHINE_WCEMIPSV2</span>
+                               <span class="p-Indicator">]}</span>
+                 <span class="p-Indicator">,</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+                 <span class="p-Indicator">]</span>
+        <span class="l-Scalar-Plain">Characteristics</span><span class="p-Indicator">:</span>
+          <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">seq</span>
+            <span class="l-Scalar-Plain">sequence</span><span class="p-Indicator">:</span>
+              <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">str</span>
+                <span class="l-Scalar-Plain">enum</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_FILE_RELOCS_STRIPPED</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_EXECUTABLE_IMAGE</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_LINE_NUMS_STRIPPED</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_LOCAL_SYMS_STRIPPED</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_AGGRESSIVE_WS_TRIM</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_LARGE_ADDRESS_AWARE</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_BYTES_REVERSED_LO</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_32BIT_MACHINE</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_DEBUG_STRIPPED</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_NET_RUN_FROM_SWAP</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_SYSTEM</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_DLL</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_UP_SYSTEM_ONLY</span>
+                      <span class="p-Indicator">,</span> <span class="nv">IMAGE_FILE_BYTES_REVERSED_HI</span>
+                      <span class="p-Indicator">]</span>
+          <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">int</span>
+    <span class="l-Scalar-Plain">sections</span><span class="p-Indicator">:</span>
+      <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">seq</span>
+      <span class="l-Scalar-Plain">sequence</span><span class="p-Indicator">:</span>
+        <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">map</span>
+          <span class="l-Scalar-Plain">mapping</span><span class="p-Indicator">:</span>
+            <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">}</span>
+            <span class="l-Scalar-Plain">Characteristics</span><span class="p-Indicator">:</span>
+              <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">seq</span>
+                <span class="l-Scalar-Plain">sequence</span><span class="p-Indicator">:</span>
+                  <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">str</span>
+                    <span class="l-Scalar-Plain">enum</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_SCN_TYPE_NO_PAD</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_CNT_CODE</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_CNT_INITIALIZED_DATA</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_CNT_UNINITIALIZED_DATA</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_OTHER</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_INFO</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_REMOVE</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_COMDAT</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_GPREL</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_PURGEABLE</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_16BIT</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_LOCKED</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_PRELOAD</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_1BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_2BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_4BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_8BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_16BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_32BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_64BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_128BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_256BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_512BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_1024BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_2048BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_4096BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_ALIGN_8192BYTES</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_LNK_NRELOC_OVFL</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_DISCARDABLE</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_NOT_CACHED</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_NOT_PAGED</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_SHARED</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_EXECUTE</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_READ</span>
+                          <span class="p-Indicator">,</span> <span class="nv">IMAGE_SCN_MEM_WRITE</span>
+                          <span class="p-Indicator">]</span>
+              <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">int</span>
+            <span class="l-Scalar-Plain">SectionData</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">}</span>
+    <span class="l-Scalar-Plain">symbols</span><span class="p-Indicator">:</span>
+      <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">seq</span>
+      <span class="l-Scalar-Plain">sequence</span><span class="p-Indicator">:</span>
+        <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">map</span>
+          <span class="l-Scalar-Plain">mapping</span><span class="p-Indicator">:</span>
+            <span class="l-Scalar-Plain">Name</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">}</span>
+            <span class="l-Scalar-Plain">Value</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+            <span class="l-Scalar-Plain">SectionNumber</span><span class="p-Indicator">:</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+            <span class="l-Scalar-Plain">SimpleType</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">,</span> <span class="nv">enum</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_SYM_TYPE_NULL</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_VOID</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_CHAR</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_SHORT</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_INT</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_LONG</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_FLOAT</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_DOUBLE</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_STRUCT</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_UNION</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_ENUM</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_MOE</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_BYTE</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_WORD</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_UINT</span>
+                                            <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_TYPE_DWORD</span>
+                                            <span class="p-Indicator">]}</span>
+                        <span class="p-Indicator">,</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+                        <span class="p-Indicator">]</span>
+            <span class="l-Scalar-Plain">ComplexType</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">,</span> <span class="nv">enum</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="nv">IMAGE_SYM_DTYPE_NULL</span>
+                                             <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_DTYPE_POINTER</span>
+                                             <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_DTYPE_FUNCTION</span>
+                                             <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_DTYPE_ARRAY</span>
+                                             <span class="p-Indicator">]}</span>
+                         <span class="p-Indicator">,</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+                         <span class="p-Indicator">]</span>
+            <span class="l-Scalar-Plain">StorageClass</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">str</span><span class="p-Indicator">,</span> <span class="nv">enum</span><span class="p-Indicator">:</span>
+                                        <span class="p-Indicator">[</span> <span class="nv">IMAGE_SYM_CLASS_END_OF_FUNCTION</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_NULL</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_AUTOMATIC</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_EXTERNAL</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_STATIC</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_REGISTER</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_EXTERNAL_DEF</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_LABEL</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_UNDEFINED_LABEL</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_MEMBER_OF_STRUCT</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_ARGUMENT</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_STRUCT_TAG</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_MEMBER_OF_UNION</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_UNION_TAG</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_TYPE_DEFINITION</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_UNDEFINED_STATIC</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_ENUM_TAG</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_MEMBER_OF_ENUM</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_REGISTER_PARAM</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_BIT_FIELD</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_BLOCK</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_FUNCTION</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_END_OF_STRUCT</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_FILE</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_SECTION</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_WEAK_EXTERNAL</span>
+                                        <span class="p-Indicator">,</span> <span class="nv">IMAGE_SYM_CLASS_CLR_TOKEN</span>
+                                        <span class="p-Indicator">]}</span>
+                          <span class="p-Indicator">,</span> <span class="p-Indicator">{</span><span class="nv">type</span><span class="p-Indicator">:</span> <span class="nv">int</span><span class="p-Indicator">}</span>
+                          <span class="p-Indicator">]</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+          </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="HowToAddABuilder.html" title="How To Add Your Build Configuration To LLVM Buildbot Infrastructure"
+             >previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="index.html">Documentation</a>»</li>
+ 
+      </ul>
+    </div>
+    <div class="footer">
+        © Copyright 2003-2013, LLVM Project.
+      Last updated on 2014-06-16.
+      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/3.4.2/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/index.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/index.html (added)
+++ www-releases/trunk/3.4.2/index.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,7 @@
+<html>
+<head>
+  <meta http-equiv="Refresh" content="0;url=../index.html">
+</head>
+<body>
+</body>
+</html>

Added: www-releases/trunk/3.4.2/llvm-3.4.2.src.tar.gz
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/llvm-3.4.2.src.tar.gz?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/llvm-3.4.2.src.tar.gz
------------------------------------------------------------------------------
    svn:mime-type = application/x-gzip

Added: www-releases/trunk/3.4.2/llvm-3.4.2.src.tar.gz.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/llvm-3.4.2.src.tar.gz.sig?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/llvm-3.4.2.src.tar.gz.sig
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/AddressSanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/AddressSanitizer.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/AddressSanitizer.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/AutomaticReferenceCounting.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/AutomaticReferenceCounting.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/AutomaticReferenceCounting.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Block-ABI-Apple.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Block-ABI-Apple.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Block-ABI-Apple.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/BlockLanguageSpec.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/BlockLanguageSpec.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/BlockLanguageSpec.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangCheck.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangCheck.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangCheck.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangFormat.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangFormat.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangFormat.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangFormatStyleOptions.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangFormatStyleOptions.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangFormatStyleOptions.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangPlugins.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangPlugins.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangPlugins.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangTools.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangTools.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ClangTools.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/CrossCompilation.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/CrossCompilation.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/CrossCompilation.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DataFlowSanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DataFlowSanitizer.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DataFlowSanitizer.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DataFlowSanitizerDesign.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DataFlowSanitizerDesign.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DataFlowSanitizerDesign.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DriverInternals.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DriverInternals.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/DriverInternals.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ExternalClangExamples.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ExternalClangExamples.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ExternalClangExamples.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/FAQ.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/FAQ.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/FAQ.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/HowToSetupToolingForLLVM.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/HowToSetupToolingForLLVM.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/HowToSetupToolingForLLVM.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/InternalsManual.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/InternalsManual.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/InternalsManual.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/IntroductionToTheClangAST.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/IntroductionToTheClangAST.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/IntroductionToTheClangAST.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/JSONCompilationDatabase.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/JSONCompilationDatabase.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/JSONCompilationDatabase.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LanguageExtensions.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LanguageExtensions.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LanguageExtensions.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LeakSanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LeakSanitizer.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LeakSanitizer.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibASTMatchers.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibASTMatchers.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibASTMatchers.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibASTMatchersTutorial.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibASTMatchersTutorial.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibASTMatchersTutorial.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibFormat.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibFormat.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibFormat.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibTooling.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibTooling.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/LibTooling.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/MemorySanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/MemorySanitizer.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/MemorySanitizer.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Modules.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Modules.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Modules.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ObjectiveCLiterals.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ObjectiveCLiterals.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ObjectiveCLiterals.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/PCHInternals.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/PCHInternals.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/PCHInternals.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/PTHInternals.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/PTHInternals.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/PTHInternals.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/RAVFrontendAction.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/RAVFrontendAction.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/RAVFrontendAction.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ReleaseNotes.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ReleaseNotes.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ReleaseNotes.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/SanitizerSpecialCaseList.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/SanitizerSpecialCaseList.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/SanitizerSpecialCaseList.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ThreadSanitizer.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ThreadSanitizer.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/ThreadSanitizer.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Tooling.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Tooling.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/Tooling.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/UsersManual.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/UsersManual.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/UsersManual.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/environment.pickle
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/environment.pickle?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/environment.pickle
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/index.doctree
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/doctrees/index.doctree?rev=211020&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.4.2/tools/clang/docs/doctrees/index.doctree
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.4.2/tools/clang/docs/html/.buildinfo
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/.buildinfo?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/.buildinfo (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/.buildinfo Mon Jun 16 08:19:07 2014
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 1fb2bfd8e3c53010034d0b48f3d8c471
+tags: fbb0d17656682115ca4d033fb2f83ba1

Added: www-releases/trunk/3.4.2/tools/clang/docs/html/AddressSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/AddressSanitizer.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/AddressSanitizer.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/AddressSanitizer.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,268 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>AddressSanitizer — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="ThreadSanitizer" href="ThreadSanitizer.html" />
+    <link rel="prev" title="Cross-compilation using Clang" href="CrossCompilation.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>AddressSanitizer</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="ThreadSanitizer.html">ThreadSanitizer</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="addresssanitizer">
+<h1>AddressSanitizer<a class="headerlink" href="#addresssanitizer" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#how-to-build" id="id2">How to build</a></li>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a><ul>
+<li><a class="reference internal" href="#has-feature-address-sanitizer" id="id4"><tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt></a></li>
+<li><a class="reference internal" href="#attribute-no-sanitize-address" id="id5"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_address))</span></tt></a></li>
+<li><a class="reference internal" href="#initialization-order-checking" id="id6">Initialization order checking</a></li>
+<li><a class="reference internal" href="#blacklist" id="id7">Blacklist</a></li>
+<li><a class="reference internal" href="#memory-leak-detection" id="id8">Memory leak detection</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-platforms" id="id9">Supported Platforms</a></li>
+<li><a class="reference internal" href="#limitations" id="id10">Limitations</a></li>
+<li><a class="reference internal" href="#current-status" id="id11">Current Status</a></li>
+<li><a class="reference internal" href="#more-information" id="id12">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>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:</p>
+<ul class="simple">
+<li>Out-of-bounds accesses to heap, stack and globals</li>
+<li>Use-after-free</li>
+<li>Use-after-return (to some extent)</li>
+<li>Double-free, invalid free</li>
+<li>Memory leaks (experimental)</li>
+</ul>
+<p>Typical slowdown introduced by AddressSanitizer is <strong>2x</strong>.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2><a class="toc-backref" href="#id2">How to build</a><a class="headerlink" href="#how-to-build" title="Permalink to this headline">Â¶</a></h2>
+<p>Follow the <a class="reference external" href="../get_started.html">clang build instructions</a>. CMake build is
+supported.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">Â¶</a></h2>
+<p>Simply compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt> flag.  The
+AddressSanitizer run-time library should be linked to the final executable, so
+make sure to use <tt class="docutils literal"><span class="pre">clang</span></tt> (not <tt class="docutils literal"><span class="pre">ld</span></tt>) for the final link step.  When linking
+shared libraries, the AddressSanitizer run-time is not linked, so
+<tt class="docutils literal"><span class="pre">-Wl,-z,defs</span></tt> may cause link errors (don’t use it with AddressSanitizer).  To
+get a reasonable performance add <tt class="docutils literal"><span class="pre">-O1</span></tt> or higher.  To get nicer stack traces
+in error messages add <tt class="docutils literal"><span class="pre">-fno-omit-frame-pointer</span></tt>.  To get perfect stack traces
+you may need to disable inlining (just use <tt class="docutils literal"><span class="pre">-O1</span></tt>) and tail call elimination
+(<tt class="docutils literal"><span class="pre">-fno-optimize-sibling-calls</span></tt>).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat example_UseAfterFree.cc
+<span class="go">int main(int argc, char **argv) {</span>
+<span class="go">  int *array = new int[100];</span>
+<span class="go">  delete [] array;</span>
+<span class="go">  return array[argc];  // BOOM</span>
+<span class="go">}</span>
+
+<span class="gp">#</span> Compile and link
+<span class="gp">%</span> clang -O1 -g -fsanitize<span class="o">=</span>address -fno-omit-frame-pointer example_UseAfterFree.cc
+</pre></div>
+</div>
+<p>or:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Compile
+<span class="gp">%</span> clang -O1 -g -fsanitize<span class="o">=</span>address -fno-omit-frame-pointer -c example_UseAfterFree.cc
+<span class="gp">#</span> Link
+<span class="gp">%</span> clang -g -fsanitize<span class="o">=</span>address example_UseAfterFree.o
+</pre></div>
+</div>
+<p>If a bug is detected, the program will print an error message to stderr and
+exit with a non-zero exit code. Currently, AddressSanitizer does not symbolize
+its output, so you may need to use a separate script to symbolize the result
+offline (this will be fixed in future).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> ./a.out 2> log
+<span class="gp">%</span> projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+<span class="go">==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8</span>
+<span class="go">READ of size 4 at 0x7f7ddab8c084 thread T0</span>
+<span class="go">    #0 0x403c8c in main example_UseAfterFree.cc:4</span>
+<span class="go">    #1 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)</span>
+<span class="go">freed by thread T0 here:</span>
+<span class="go">    #0 0x404704 in operator delete[](void*) ??:0</span>
+<span class="go">    #1 0x403c53 in main example_UseAfterFree.cc:4</span>
+<span class="go">    #2 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">previously allocated by thread T0 here:</span>
+<span class="go">    #0 0x404544 in operator new[](unsigned long) ??:0</span>
+<span class="go">    #1 0x403c43 in main example_UseAfterFree.cc:2</span>
+<span class="go">    #2 0x7f7ddabcac4d in __libc_start_main ??:0</span>
+<span class="go">==9442== ABORTING</span>
+</pre></div>
+</div>
+<p>AddressSanitizer exits on the first detected error. This is by design.
+One reason: it makes the generated code smaller and faster (both by
+~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind,
+it is often the case that users treat Valgrind warnings as false
+positives (which they are not) and don’t fix them.</p>
+<div class="section" id="has-feature-address-sanitizer">
+<h3><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">__has_feature(address_sanitizer)</span></tt></a><a class="headerlink" href="#has-feature-address-sanitizer" title="Permalink to this headline">Â¶</a></h3>
+<p>In some cases one may need to execute different code depending on whether
+AddressSanitizer 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(address_sanitizer)</span>
+<span class="c1">// code that builds only under AddressSanitizer</span>
+<span class="cp">#  endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-address">
+<h3><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_address))</span></tt></a><a class="headerlink" href="#attribute-no-sanitize-address" title="Permalink to this headline">Â¶</a></h3>
+<p>Some code should not be instrumented by AddressSanitizer. One may use the
+function attribute
+<a class="reference internal" href="LanguageExtensions.html#langext-address-sanitizer"><em>no_sanitize_address</em></a>
+(or a deprecated synonym <cite>no_address_safety_analysis</cite>)
+to disable instrumentation of a particular function. 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(address_sanitizer)</span></tt>.</p>
+</div>
+<div class="section" id="initialization-order-checking">
+<h3><a class="toc-backref" href="#id6">Initialization order checking</a><a class="headerlink" href="#initialization-order-checking" title="Permalink to this headline">Â¶</a></h3>
+<p>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
+<tt class="docutils literal"><span class="pre">ASAN_OPTIONS=check_initialization_order=1</span></tt>.</p>
+</div>
+<div class="section" id="blacklist">
+<h3><a class="toc-backref" href="#id7">Blacklist</a><a class="headerlink" href="#blacklist" title="Permalink to this headline">Â¶</a></h3>
+<p>AddressSanitizer 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. Additionally, AddressSanitizer
+introduces <tt class="docutils literal"><span class="pre">global</span></tt> and <tt class="docutils literal"><span class="pre">type</span></tt> 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).</p>
+<p>You may use an <tt class="docutils literal"><span class="pre">init</span></tt> category to suppress reports about initialization-order
+problems happening in certain source files or with certain global variables.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Suppress error reports for code in a file or in a function:</span>
+src:bad_file.cpp
+<span class="c"># Ignore all functions with names containing MyFooBar:</span>
+fun:*MyFooBar*
+<span class="c"># Disable out-of-bound checks for global:</span>
+global:bad_array
+<span class="c"># Disable out-of-bound checks for global instances of a given class ...</span>
+<span class="nb">type</span>:class.Namespace::BadClassName
+<span class="c"># ... or a given struct. Use wildcard to deal with anonymous namespace.</span>
+<span class="nb">type</span>:struct.Namespace2::*::BadStructName
+<span class="c"># Disable initialization-order checks for globals:</span>
+global:bad_init_global<span class="o">=</span>init
+<span class="nb">type</span>:*BadInitClassSubstring*<span class="o">=</span>init
+src:bad/init/files/*<span class="o">=</span>init
+</pre></div>
+</div>
+</div>
+<div class="section" id="memory-leak-detection">
+<h3><a class="toc-backref" href="#id8">Memory leak detection</a><a class="headerlink" href="#memory-leak-detection" title="Permalink to this headline">Â¶</a></h3>
+<p>For the experimental memory leak detector in AddressSanitizer, see
+<a class="reference internal" href="LeakSanitizer.html"><em>LeakSanitizer</em></a>.</p>
+</div>
+</div>
+<div class="section" id="supported-platforms">
+<h2><a class="toc-backref" href="#id9">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">Â¶</a></h2>
+<p>AddressSanitizer is supported on</p>
+<ul class="simple">
+<li>Linux i386/x86_64 (tested on Ubuntu 10.04 and 12.04);</li>
+<li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64).</li>
+</ul>
+<p>Support for Linux ARM (and Android ARM) is in progress (it may work, but
+is not guaranteed too).</p>
+</div>
+<div class="section" id="limitations">
+<h2><a class="toc-backref" href="#id10">Limitations</a><a class="headerlink" href="#limitations" title="Permalink to this headline">Â¶</a></h2>
+<ul class="simple">
+<li>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.</li>
+<li>AddressSanitizer uses more stack memory. We have seen up to 3x increase.</li>
+<li>On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
+virtual address space. This means that tools like <tt class="docutils literal"><span class="pre">ulimit</span></tt> may not work as
+usually expected.</li>
+<li>Static linking is not supported.</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id11">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">Â¶</a></h2>
+<p>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 <tt class="docutils literal"><span class="pre">make</span>
+<span class="pre">check-asan</span></tt> command.</p>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id12">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">Â¶</a></h2>
+<p><a class="reference external" href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a></p>
+</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="ThreadSanitizer.html">ThreadSanitizer</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/AutomaticReferenceCounting.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/AutomaticReferenceCounting.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/AutomaticReferenceCounting.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/AutomaticReferenceCounting.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,2083 @@
+
+
+<!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 Automatic Reference Counting (ARC) — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="next" title="Cross-compilation using Clang" href="CrossCompilation.html" />
+    <link rel="prev" title="Block Implementation Specification" href="Block-ABI-Apple.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Objective-C Automatic Reference Counting (ARC)</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="CrossCompilation.html">Cross-compilation using Clang</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <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><div class="section" id="objective-c-automatic-reference-counting-arc">
+<h1>Objective-C Automatic Reference Counting (ARC)<a class="headerlink" href="#objective-c-automatic-reference-counting-arc" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#about-this-document" id="id4">About this document</a><ul>
+<li><a class="reference internal" href="#purpose" id="id5">Purpose</a></li>
+<li><a class="reference internal" href="#background" id="id6">Background</a></li>
+<li><a class="reference internal" href="#evolution" id="id7">Evolution</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#general" id="id8">General</a></li>
+<li><a class="reference internal" href="#retainable-object-pointers" id="id9">Retainable object pointers</a><ul>
+<li><a class="reference internal" href="#retain-count-semantics" id="id10">Retain count semantics</a></li>
+<li><a class="reference internal" href="#retainable-object-pointers-as-operands-and-arguments" id="id11">Retainable object pointers as operands and arguments</a><ul>
+<li><a class="reference internal" href="#consumed-parameters" id="id12">Consumed parameters</a></li>
+<li><a class="reference internal" href="#retained-return-values" id="id13">Retained return values</a></li>
+<li><a class="reference internal" href="#unretained-return-values" id="id14">Unretained return values</a></li>
+<li><a class="reference internal" href="#bridged-casts" id="id15">Bridged casts</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#restrictions" id="id16">Restrictions</a><ul>
+<li><a class="reference internal" href="#conversion-of-retainable-object-pointers" id="id17">Conversion of retainable object pointers</a></li>
+<li><a class="reference internal" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" id="id18">Conversion to retainable object pointer type of expressions with known semantics</a></li>
+<li><a class="reference internal" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" id="id19">Conversion from retainable object pointer type in certain contexts</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ownership-qualification" id="id20">Ownership qualification</a><ul>
+<li><a class="reference internal" href="#spelling" id="id21">Spelling</a><ul>
+<li><a class="reference internal" href="#property-declarations" id="id22">Property declarations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#semantics" id="id23">Semantics</a></li>
+<li><a class="reference internal" href="#arc-ownership-restrictions" id="id24">Restrictions</a><ul>
+<li><a class="reference internal" href="#weak-unavailable-types" id="id25">Weak-unavailable types</a></li>
+<li><a class="reference internal" href="#storage-duration-of-autoreleasing-objects" id="id26">Storage duration of <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects</a></li>
+<li><a class="reference internal" href="#conversion-of-pointers-to-ownership-qualified-types" id="id27">Conversion of pointers to ownership-qualified types</a></li>
+<li><a class="reference internal" href="#passing-to-an-out-parameter-by-writeback" id="id28">Passing to an out parameter by writeback</a></li>
+<li><a class="reference internal" href="#ownership-qualified-fields-of-structs-and-unions" id="id29">Ownership-qualified fields of structs and unions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ownership-inference" id="id30">Ownership inference</a><ul>
+<li><a class="reference internal" href="#objects" id="id31">Objects</a></li>
+<li><a class="reference internal" href="#indirect-parameters" id="id32">Indirect parameters</a></li>
+<li><a class="reference internal" href="#template-arguments" id="id33">Template arguments</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#method-families" id="id34">Method families</a><ul>
+<li><a class="reference internal" href="#explicit-method-family-control" id="id35">Explicit method family control</a></li>
+<li><a class="reference internal" href="#semantics-of-method-families" id="id36">Semantics of method families</a><ul>
+<li><a class="reference internal" href="#semantics-of-init" id="id37">Semantics of <tt class="docutils literal"><span class="pre">init</span></tt></a></li>
+<li><a class="reference internal" href="#related-result-types" id="id38">Related result types</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#optimization" id="id39">Optimization</a><ul>
+<li><a class="reference internal" href="#object-liveness" id="id40">Object liveness</a></li>
+<li><a class="reference internal" href="#no-object-lifetime-extension" id="id41">No object lifetime extension</a></li>
+<li><a class="reference internal" href="#precise-lifetime-semantics" id="id42">Precise lifetime semantics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#miscellaneous" id="id43">Miscellaneous</a><ul>
+<li><a class="reference internal" href="#special-methods" id="id44">Special methods</a><ul>
+<li><a class="reference internal" href="#memory-management-methods" id="id45">Memory management methods</a></li>
+<li><a class="reference internal" href="#dealloc" id="id46"><tt class="docutils literal"><span class="pre">dealloc</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#autoreleasepool" id="id47"><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt></a></li>
+<li><a class="reference internal" href="#self" id="id48"><tt class="docutils literal"><span class="pre">self</span></tt></a></li>
+<li><a class="reference internal" href="#fast-enumeration-iteration-variables" id="id49">Fast enumeration iteration variables</a></li>
+<li><a class="reference internal" href="#blocks" id="id50">Blocks</a></li>
+<li><a class="reference internal" href="#exceptions" id="id51">Exceptions</a></li>
+<li><a class="reference internal" href="#interior-pointers" id="id52">Interior pointers</a></li>
+<li><a class="reference internal" href="#c-retainable-pointer-types" id="id53">C retainable pointer types</a><ul>
+<li><a class="reference internal" href="#auditing-of-c-retainable-pointer-interfaces" id="id54">Auditing of C retainable pointer interfaces</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#runtime-support" id="id55">Runtime support</a><ul>
+<li><a class="reference internal" href="#arc-runtime-objc-autorelease" id="id56"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-autoreleasepoolpop-void-pool" id="id57"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-autoreleasepoolpush-void" id="id58"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue" id="id59"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-copyweak-id-dest-id-src" id="id60"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-destroyweak-id-object" id="id61"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-initweak" id="id62"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-loadweak" id="id63"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-loadweakretained" id="id64"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-moveweak-id-dest-id-src" id="id65"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-release-id-value" id="id66"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retain" id="id67"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautorelease" id="id68"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasereturnvalue" id="id69"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue" id="id70"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainblock" id="id71"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-storestrong" id="id72"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-storeweak" id="id73"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="about-this-document">
+<span id="arc-meta"></span><h2><a class="toc-backref" href="#id4">About this document</a><a class="headerlink" href="#about-this-document" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="purpose">
+<span id="arc-meta-purpose"></span><h3><a class="toc-backref" href="#id5">Purpose</a><a class="headerlink" href="#purpose" title="Permalink to this headline">Â¶</a></h3>
+<p>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.</p>
+<p>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.</p>
+</div>
+<div class="section" id="background">
+<span id="arc-meta-background"></span><h3><a class="toc-backref" href="#id6">Background</a><a class="headerlink" href="#background" title="Permalink to this headline">Â¶</a></h3>
+<p>This document assumes a basic familiarity with C.</p>
+<p><span class="arc-term">Blocks</span> are a C language extension for creating anonymous functions.
+Users interact with and transfer block objects using <span class="arc-term">block
+pointers</span>, 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 <tt class="docutils literal"><span class="pre">Block_copy</span></tt> 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
+<tt class="docutils literal"><span class="pre">Block_release</span></tt>, which decreases the reference count by 1 and destroys the
+object if the count reaches zero and is on the heap.</p>
+<p>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.</p>
+<p>Objective-C defines a new type kind, collectively called the <span class="arc-term">object
+pointer types</span>.  This kind has two notable builtin members, <tt class="docutils literal"><span class="pre">id</span></tt> and
+<tt class="docutils literal"><span class="pre">Class</span></tt>; <tt class="docutils literal"><span class="pre">id</span></tt> is the final supertype of all object pointers.  The validity
+of conversions between object pointer types is not checked at runtime.  Users
+may define <span class="arc-term">classes</span>; 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
+<span class="arc-term">ivars</span>, fields which appear on all instances of that class.  For
+every class <em>T</em> there’s an associated metaclass; it has no fields, its
+superclass is the metaclass of <em>T</em>‘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
+<tt class="docutils literal"><span class="pre">Class</span></tt>.</p>
+<p>A class declaration (<tt class="docutils literal"><span class="pre">@interface</span></tt>) declares a set of <span class="arc-term">methods</span>.  A
+method has a return type, a list of argument types, and a <span class="arc-term">selector</span>:
+a name like <tt class="docutils literal"><span class="pre">foo:bar:baz:</span></tt>, 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 <span class="arc-term">receiver</span>) and a list of formal
+arguments interspersed with the selector, like so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">receiver</span> <span class="n">foo</span><span class="o">:</span> <span class="n">fooArg</span> <span class="n">bar</span><span class="o">:</span> <span class="n">barArg</span> <span class="n">baz</span><span class="o">:</span> <span class="n">bazArg</span><span class="p">]</span>
+</pre></div>
+</div>
+<p>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 <tt class="docutils literal"><span class="pre">super</span></tt>, 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 <tt class="docutils literal"><span class="pre">@interface</span></tt>, but
+those defined in a separate <tt class="docutils literal"><span class="pre">@implementation</span></tt> declaration; however, when
+compiling a call, typechecking is done based on the methods declared in the
+<tt class="docutils literal"><span class="pre">@interface</span></tt>.</p>
+<p>Method declarations may also be grouped into <span class="arc-term">protocols</span>, 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.</p>
+<p><span class="arc-term">Class extensions</span> are collections of ivars and methods, designed to
+allow a class’s <tt class="docutils literal"><span class="pre">@interface</span></tt> to be split across multiple files; however,
+there is still a primary implementation file which must see the
+<tt class="docutils literal"><span class="pre">@interface</span></tt>s of all class extensions.  <span class="arc-term">Categories</span> allow
+methods (but not ivars) to be declared <em>post hoc</em> on an arbitrary class; the
+methods in the category’s <tt class="docutils literal"><span class="pre">@implementation</span></tt> 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.</p>
+<p>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: <tt class="docutils literal"><span class="pre">retain</span></tt>
+increases the object’s reference count by 1, whereas <tt class="docutils literal"><span class="pre">release</span></tt> decreases it
+by 1 and calls the instance method <tt class="docutils literal"><span class="pre">dealloc</span></tt> if the count reaches 0.  To
+simplify certain operations, there is also an <span class="arc-term">autorelease pool</span>, a
+thread-local list of objects to call <tt class="docutils literal"><span class="pre">release</span></tt> on later; an object can be
+added to this pool by calling <tt class="docutils literal"><span class="pre">autorelease</span></tt> on it.</p>
+<p>Block pointers may be converted to type <tt class="docutils literal"><span class="pre">id</span></tt>; 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 <tt class="docutils literal"><span class="pre">retain</span></tt> by adjusting the reference count, not by calling
+<tt class="docutils literal"><span class="pre">Block_copy</span></tt>.</p>
+</div>
+<div class="section" id="evolution">
+<span id="arc-meta-evolution"></span><h3><a class="toc-backref" href="#id7">Evolution</a><a class="headerlink" href="#evolution" title="Permalink to this headline">Â¶</a></h3>
+<p>ARC is under continual evolution, and this document must be updated as the
+language progresses.</p>
+<p>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:</p>
+<blockquote>
+<div>ARC applies to Objective-C pointer types, block pointer types, and
+<span class="when-revised">[beginning Apple 8.0, LLVM 3.8]</span> <span class="revision">BPTRs declared
+within</span> <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"BCPL"</span></tt> blocks.</div></blockquote>
+<p>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.</p>
+<p>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.</p>
+</div>
+</div>
+<div class="section" id="general">
+<span id="arc-general"></span><h2><a class="toc-backref" href="#id8">General</a><a class="headerlink" href="#general" title="Permalink to this headline">Â¶</a></h2>
+<p>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.</p>
+<p>ARC may be explicitly enabled with the compiler flag <tt class="docutils literal"><span class="pre">-fobjc-arc</span></tt>.  It may
+also be explicitly disabled with the compiler flag <tt class="docutils literal"><span class="pre">-fno-objc-arc</span></tt>.  The last
+of these two flags appearing on the compile line “wins”.</p>
+<p>If ARC is enabled, <tt class="docutils literal"><span class="pre">__has_feature(objc_arc)</span></tt> will expand to 1 in the
+preprocessor.  For more information about <tt class="docutils literal"><span class="pre">__has_feature</span></tt>, see the
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>language extensions</em></a> document.</p>
+</div>
+<div class="section" id="retainable-object-pointers">
+<span id="arc-objects"></span><h2><a class="toc-backref" href="#id9">Retainable object pointers</a><a class="headerlink" href="#retainable-object-pointers" title="Permalink to this headline">Â¶</a></h2>
+<p>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 <em>values</em> (patterns of bits indicating the location
+of a pointed-to object), not pointer <em>objects</em> (locations in memory which store
+pointer values).  The rules for objects are covered in the next section.</p>
+<p>A <span class="arc-term">retainable object pointer</span> (or “retainable pointer”) is a value of
+a <span class="arc-term">retainable object pointer type</span> (“retainable type”).  There are
+three kinds of retainable object pointer types:</p>
+<ul class="simple">
+<li>block pointers (formed by applying the caret (<tt class="docutils literal"><span class="pre">^</span></tt>) declarator sigil to a
+function type)</li>
+<li>Objective-C object pointers (<tt class="docutils literal"><span class="pre">id</span></tt>, <tt class="docutils literal"><span class="pre">Class</span></tt>, <tt class="docutils literal"><span class="pre">NSFoo*</span></tt>, etc.)</li>
+<li>typedefs marked with <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt></li>
+</ul>
+<p>Other pointer types, such as <tt class="docutils literal"><span class="pre">int*</span></tt> and <tt class="docutils literal"><span class="pre">CFStringRef</span></tt>, are not subject to
+ARC’s semantics and restrictions.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>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:</p>
+<ul class="last simple">
+<li>The type system must reliably identify which objects are to be managed.  An
+<tt class="docutils literal"><span class="pre">int*</span></tt> might be a pointer to a <tt class="docutils literal"><span class="pre">malloc</span></tt>‘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.</li>
+<li>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.</li>
+<li>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.</li>
+</ul>
+</div>
+<p>The use of <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> 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
+<tt class="docutils literal"><span class="pre">__typeof</span></tt> and C++ template argument substitution.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Any compiler operation which incidentally strips type “sugar” from a type
+will yield a type without the attribute, which may result in unexpected
+behavior.</p>
+</div>
+<div class="section" id="retain-count-semantics">
+<span id="arc-objects-retains"></span><h3><a class="toc-backref" href="#id10">Retain count semantics</a><a class="headerlink" href="#retain-count-semantics" title="Permalink to this headline">Â¶</a></h3>
+<p>A retainable object pointer is either a <span class="arc-term">null pointer</span> or a pointer
+to a valid object.  Furthermore, if it has block pointer type and is not
+<tt class="docutils literal"><span class="pre">null</span></tt> then it must actually be a pointer to a block object, and if it has
+<tt class="docutils literal"><span class="pre">Class</span></tt> 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.</p>
+<p>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:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">retain</span></tt>, taking no arguments and returning a pointer to the object.</li>
+<li><tt class="docutils literal"><span class="pre">release</span></tt>, taking no arguments and returning <tt class="docutils literal"><span class="pre">void</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">autorelease</span></tt>, taking no arguments and returning a pointer to the object.</li>
+</ul>
+<p>The behavior of these methods is constrained in the following ways.  The term
+<span class="arc-term">high-level semantics</span> 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 <tt class="docutils literal"><span class="pre">retain</span></tt>, 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.</p>
+<p>It is undefined behavior if a computation history featuring a send of
+<tt class="docutils literal"><span class="pre">retain</span></tt> followed by a send of <tt class="docutils literal"><span class="pre">release</span></tt> to the same object, with no
+intervening <tt class="docutils literal"><span class="pre">release</span></tt> 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.</p>
+<p>It is undefined behavior if a computation history features any use whatsoever
+of an object following the completion of a send of <tt class="docutils literal"><span class="pre">release</span></tt> that is not
+preceded by a send of <tt class="docutils literal"><span class="pre">retain</span></tt> to the same object.</p>
+<p>The behavior of <tt class="docutils literal"><span class="pre">autorelease</span></tt> must be equivalent to sending <tt class="docutils literal"><span class="pre">release</span></tt> when
+one of the autorelease pools currently in scope is popped.  It may not throw an
+exception.</p>
+<p>When the semantics call for performing one of these operations on a retainable
+object pointer, if that pointer is <tt class="docutils literal"><span class="pre">null</span></tt> then the effect is a no-op.</p>
+<p>All of the semantics described in this document are subject to additional
+<a class="reference internal" href="#arc-optimization"><em>optimization rules</em></a> 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.</p>
+</div>
+<div class="section" id="retainable-object-pointers-as-operands-and-arguments">
+<span id="arc-objects-operands"></span><h3><a class="toc-backref" href="#id11">Retainable object pointers as operands and arguments</a><a class="headerlink" href="#retainable-object-pointers-as-operands-and-arguments" title="Permalink to this headline">Â¶</a></h3>
+<p>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:</p>
+<ul class="simple">
+<li>loading a retainable pointer from an object with non-weak <a class="reference internal" href="#arc-ownership"><em>ownership</em></a>,</li>
+<li>passing a retainable pointer as an argument to a function or method, and</li>
+<li>receiving a retainable pointer as the result of a function or method call.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>The remainder of this section describes exceptions to these rules, how those
+exceptions are detected, and what those exceptions imply semantically.</p>
+<div class="section" id="consumed-parameters">
+<span id="arc-objects-operands-consumed"></span><h4><a class="toc-backref" href="#id12">Consumed parameters</a><a class="headerlink" href="#consumed-parameters" title="Permalink to this headline">Â¶</a></h4>
+<p>A function or method parameter of retainable object pointer type may be marked
+as <span class="arc-term">consumed</span>, signifying that the callee expects to take ownership
+of a +1 retain count.  This is done by adding the <tt class="docutils literal"><span class="pre">ns_consumed</span></tt> attribute to
+the parameter declaration, like so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="n">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="kt">id</span> <span class="n">x</span><span class="p">);</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="nf">foo:</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="n">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>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.</p>
+<p>When passing such an argument, ARC retains the argument prior to making the
+call.</p>
+<p>When receiving such an argument, ARC releases the argument at the end of the
+function, subject to the usual optimizations for local values.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This formalizes direct transfers of ownership from a caller to a callee.  The
+most common scenario here is passing the <tt class="docutils literal"><span class="pre">self</span></tt> parameter to <tt class="docutils literal"><span class="pre">init</span></tt>, 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.</p>
+</div>
+<p>The implicit <tt class="docutils literal"><span class="pre">self</span></tt> parameter of a method may be marked as consumed by adding
+<tt class="docutils literal"><span class="pre">__attribute__((ns_consumes_self))</span></tt> to the method declaration.  Methods in
+the <tt class="docutils literal"><span class="pre">init</span></tt> <a class="reference internal" href="#arc-method-families"><em>family</em></a> are treated as if they were
+implicitly marked with this attribute.</p>
+<p>It is undefined behavior if an Objective-C message send to a method with
+<tt class="docutils literal"><span class="pre">ns_consumed</span></tt> 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 <tt class="docutils literal"><span class="pre">ns_consumed</span></tt> 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
+<tt class="docutils literal"><span class="pre">ns_consumed</span></tt> parameters than the implementation of the called block or
+function.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+<div class="section" id="retained-return-values">
+<span id="arc-object-operands-retained-return-values"></span><h4><a class="toc-backref" href="#id13">Retained return values</a><a class="headerlink" href="#retained-return-values" title="Permalink to this headline">Â¶</a></h4>
+<p>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
+<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt> attribute to the function or method declaration, like
+so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="nf">foo</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This attribute is part of the type of the function or method.</p>
+<p>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.</p>
+<p>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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This formalizes direct transfers of ownership from a callee to a caller.  The
+most common scenario this models is the retained return from <tt class="docutils literal"><span class="pre">init</span></tt>,
+<tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">new</span></tt>, and <tt class="docutils literal"><span class="pre">copy</span></tt> methods, but there are other cases in the
+frameworks.  After optimization there are typically no extra retains and
+releases required.</p>
+</div>
+<p>Methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt>
+<a class="reference internal" href="#arc-method-families"><em>families</em></a> are implicitly marked
+<tt class="docutils literal"><span class="pre">__attribute__((ns_returns_retained))</span></tt>.  This may be suppressed by explicitly
+marking the method <tt class="docutils literal"><span class="pre">__attribute__((ns_returns_not_retained))</span></tt>.</p>
+<p>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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+<div class="section" id="unretained-return-values">
+<span id="arc-objects-operands-unretained-returns"></span><h4><a class="toc-backref" href="#id14">Unretained return values</a><a class="headerlink" href="#unretained-return-values" title="Permalink to this headline">Â¶</a></h4>
+<p>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.</p>
+<p>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 <tt class="docutils literal"><span class="pre">autorelease</span></tt>, but
+callers must not assume that the value is actually in the autorelease pool.</p>
+<p>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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>A method or function may be marked with
+<tt class="docutils literal"><span class="pre">__attribute__((ns_returns_autoreleased))</span></tt> 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.</p>
+</div>
+<div class="section" id="bridged-casts">
+<span id="arc-objects-operands-casts"></span><h4><a class="toc-backref" href="#id15">Bridged casts</a><a class="headerlink" href="#bridged-casts" title="Permalink to this headline">Â¶</a></h4>
+<p>A <span class="arc-term">bridged cast</span> is a C-style cast annotated with one of three
+keywords:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">(__bridge</span> <span class="pre">T)</span> <span class="pre">op</span></tt> casts the operand to the destination type <tt class="docutils literal"><span class="pre">T</span></tt>.  If
+<tt class="docutils literal"><span class="pre">T</span></tt> is a retainable object pointer type, then <tt class="docutils literal"><span class="pre">op</span></tt> must have a
+non-retainable pointer type.  If <tt class="docutils literal"><span class="pre">T</span></tt> is a non-retainable pointer type,
+then <tt class="docutils literal"><span class="pre">op</span></tt> 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.</li>
+<li><tt class="docutils literal"><span class="pre">(__bridge_retained</span> <span class="pre">T)</span> <span class="pre">op</span></tt> 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.</li>
+<li><tt class="docutils literal"><span class="pre">(__bridge_transfer</span> <span class="pre">T)</span> <span class="pre">op</span></tt> 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.</li>
+</ul>
+<p>These casts are required in order to transfer objects in and out of ARC
+control; see the rationale in the section on <a class="reference internal" href="#arc-objects-restrictions-conversion"><em>conversion of retainable
+object pointers</em></a>.</p>
+<p>Using a <tt class="docutils literal"><span class="pre">__bridge_retained</span></tt> or <tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> cast purely to convince
+ARC to emit an unbalanced retain or release, respectively, is poor form.</p>
+</div>
+</div>
+<div class="section" id="restrictions">
+<span id="arc-objects-restrictions"></span><h3><a class="toc-backref" href="#id16">Restrictions</a><a class="headerlink" href="#restrictions" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="conversion-of-retainable-object-pointers">
+<span id="arc-objects-restrictions-conversion"></span><h4><a class="toc-backref" href="#id17">Conversion of retainable object pointers</a><a class="headerlink" href="#conversion-of-retainable-object-pointers" title="Permalink to this headline">Â¶</a></h4>
+<p>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 <tt class="docutils literal"><span class="pre">void*</span></tt>.  As an exception, cast to <tt class="docutils literal"><span class="pre">intptr_t</span></tt> is
+allowed because such casts are not transferring ownership.  The <a class="reference internal" href="#arc-objects-operands-casts"><em>bridged
+casts</em></a> may be used to perform these conversions
+where necessary.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>However, the following exceptions apply.</p>
+</div>
+<div class="section" id="conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics">
+<span id="arc-objects-restrictions-conversion-with-known-semantics"></span><h4><a class="toc-backref" href="#id18">Conversion to retainable object pointer type of expressions with known semantics</a><a class="headerlink" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" title="Permalink to this headline">Â¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span>
+<span class="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.</span></p>
+<p>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.</p>
+<p>An expression is <span class="arc-term">known retain-agnostic</span> if it is:</p>
+<ul class="simple">
+<li>an Objective-C string literal,</li>
+<li>a load from a <tt class="docutils literal"><span class="pre">const</span></tt> system global variable of <a class="reference internal" href="#arc-misc-c-retainable"><em>C retainable pointer
+type</em></a>, or</li>
+<li>a null pointer constant.</li>
+</ul>
+<p>An expression is <span class="arc-term">known unretained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><em>C
+retainable pointer type</em></a> and it is:</p>
+<ul class="simple">
+<li>a direct call to a function, and either that function has the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute or it is an <a class="reference internal" href="#arc-misc-c-retainable-audit"><em>audited</em></a> function that does not have the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute and does not follow the create/copy naming
+convention,</li>
+<li>a message send, and the declared method either has the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute or it has neither the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute nor a <a class="reference internal" href="#arc-method-families"><em>selector family</em></a> that implies a retained result.</li>
+</ul>
+<p>An expression is <span class="arc-term">known retained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><em>C
+retainable pointer type</em></a> and it is:</p>
+<ul class="simple">
+<li>a message send, and the declared method either has the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute, or it does not have the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute but it does have a <a class="reference internal" href="#arc-method-families"><em>selector
+family</em></a> that implies a retained result.</li>
+</ul>
+<p>Furthermore:</p>
+<ul class="simple">
+<li>a comma expression is classified according to its right-hand side,</li>
+<li>a statement expression is classified according to its result expression, if
+it has one,</li>
+<li>an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
+classified according to the underlying message send, and</li>
+<li>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.</li>
+</ul>
+<p>If the cast operand is known retained, the conversion is treated as a
+<tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> cast.  If the cast operand is known unretained or known
+retain-agnostic, the conversion is treated as a <tt class="docutils literal"><span class="pre">__bridge</span></tt> cast.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>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.</p>
+<p class="last">We’ve so far consciously refrained from implicitly turning retained CF
+results from function calls into <tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> casts.  The worry is
+that some code patterns  —  for example, creating a CF value, assigning it
+to an ObjC-typed local, and then calling <tt class="docutils literal"><span class="pre">CFRelease</span></tt> when done  —  are a
+bit too likely to be accidentally accepted, leading to mysterious behavior.</p>
+</div>
+</div>
+<div class="section" id="conversion-from-retainable-object-pointer-type-in-certain-contexts">
+<span id="arc-objects-restrictions-conversion-exception-contextual"></span><h4><a class="toc-backref" href="#id19">Conversion from retainable object pointer type in certain contexts</a><a class="headerlink" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" title="Permalink to this headline">Â¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
+<p>If an expression of retainable object pointer type is explicitly cast to a
+<a class="reference internal" href="#arc-misc-c-retainable"><em>C retainable pointer type</em></a>, the program is
+ill-formed as discussed above unless the result is immediately used:</p>
+<ul class="simple">
+<li>to initialize a parameter in an Objective-C message send where the parameter
+is not marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute, or</li>
+<li>to initialize a parameter in a direct call to an
+<a class="reference internal" href="#arc-misc-c-retainable-audit"><em>audited</em></a> function where the parameter is
+not marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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 <tt class="docutils literal"><span class="pre">Release</span></tt> family,
+and it would be quite unfortunate for explicit releases to be silently
+balanced out in this way.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="ownership-qualification">
+<span id="arc-ownership"></span><h2><a class="toc-backref" href="#id20">Ownership qualification</a><a class="headerlink" href="#ownership-qualification" title="Permalink to this headline">Â¶</a></h2>
+<p>This section describes the behavior of <em>objects</em> of retainable object pointer
+type; that is, locations in memory which store retainable object pointers.</p>
+<p>A type is a <span class="arc-term">retainable object owner type</span> if it is a retainable
+object pointer type or an array type whose element type is a retainable object
+owner type.</p>
+<p>An <span class="arc-term">ownership qualifier</span> 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.</p>
+<p>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.</p>
+<p>When forming a function type, the result type is adjusted so that any
+top-level ownership qualifier is deleted.</p>
+<p>Except as described under the <a class="reference internal" href="#arc-ownership-inference"><em>inference rules</em></a>,
+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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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 <a class="reference internal" href="#arc-ownership-inference-template-arguments"><em>inference of __strong for template type
+arguments</em></a>.  Ownership qualifiers
+on return types are dropped because they serve no purpose there except to
+cause spurious problems with overloading and templates.</p>
+</div>
+<p>There are four ownership qualifiers:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">__autoreleasing</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__strong</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__weak</span></tt></li>
+</ul>
+<p>A type is <span class="arc-term">nontrivially ownership-qualified</span> if it is qualified with
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>, <tt class="docutils literal"><span class="pre">__strong</span></tt>, or <tt class="docutils literal"><span class="pre">__weak</span></tt>.</p>
+<div class="section" id="spelling">
+<span id="arc-ownership-spelling"></span><h3><a class="toc-backref" href="#id21">Spelling</a><a class="headerlink" href="#spelling" title="Permalink to this headline">Â¶</a></h3>
+<p>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.</p>
+<p>An ownership qualifier may be written anywhere that any other type qualifier
+may be written.</p>
+<p>If an ownership qualifier appears in the <em>declaration-specifiers</em>, the
+following rules apply:</p>
+<ul class="simple">
+<li>if the type specifier is a retainable object owner type, the qualifier
+initially applies to that type;</li>
+<li>otherwise, if the outermost non-array declarator is a pointer
+or block pointer declarator, the qualifier initially applies to
+that type;</li>
+<li>otherwise the program is ill-formed.</li>
+<li>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.</li>
+</ul>
+<p>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.</p>
+<p>If an ownership qualifier appears anywhere else in a declarator, it applies to
+the type there.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Ownership qualifiers are like <tt class="docutils literal"><span class="pre">const</span></tt> and <tt class="docutils literal"><span class="pre">volatile</span></tt> 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, <tt class="docutils literal"><span class="pre">__strong</span></tt>
+before the entire declaration and have it apply in the leftmost
+sensible place.</p>
+</div>
+<div class="section" id="property-declarations">
+<span id="arc-ownership-spelling-property"></span><h4><a class="toc-backref" href="#id22">Property declarations</a><a class="headerlink" href="#property-declarations" title="Permalink to this headline">Â¶</a></h4>
+<p>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
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> ownership.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">assign</span></tt> implies <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">copy</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership, as well as the usual behavior of
+copy semantics on the setter.</li>
+<li><tt class="docutils literal"><span class="pre">retain</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">strong</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">unsafe_unretained</span></tt> implies <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">weak</span></tt> implies <tt class="docutils literal"><span class="pre">__weak</span></tt> ownership.</li>
+</ul>
+<p>With the exception of <tt class="docutils literal"><span class="pre">weak</span></tt>, these modifiers are available in non-ARC
+modes.</p>
+<p>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 <span class="arc-term">associated instance variable</span> is
+the instance variable which is named, possibly implicitly, by the
+<tt class="docutils literal"><span class="pre">@synthesize</span></tt> 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.</p>
+<p>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, <span class="when-revised">[beginning Apple 3.1, LLVM 3.1]</span>
+<span class="revision">its ownership is implicitly</span> <tt class="docutils literal"><span class="pre">strong</span></tt>.  Prior to this revision, it
+was ill-formed to synthesize such a property.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Using <tt class="docutils literal"><span class="pre">strong</span></tt> by default is safe and consistent with the generic ARC rule
+about <a class="reference internal" href="#arc-ownership-inference-variables"><em>inferring ownership</em></a>.  It is,
+unfortunately, inconsistent with the non-ARC rule which states that such
+properties are implicitly <tt class="docutils literal"><span class="pre">assign</span></tt>.  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.</p>
+</div>
+<p>Applying <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> 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 <tt class="docutils literal"><span class="pre">assign</span></tt>.  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.</p>
+</div>
+</div>
+<div class="section" id="semantics">
+<span id="arc-ownership-semantics"></span><h3><a class="toc-backref" href="#id23">Semantics</a><a class="headerlink" href="#semantics" title="Permalink to this headline">Â¶</a></h3>
+<p>There are five <span class="arc-term">managed operations</span> 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.</p>
+<p>A load or store with “primitive semantics” has the same semantics as the
+respective operation would have on an <tt class="docutils literal"><span class="pre">void*</span></tt> lvalue with the same alignment
+and non-ownership qualification.</p>
+<p><span class="arc-term">Reading</span> occurs when performing a lvalue-to-rvalue conversion on an
+object lvalue.</p>
+<ul class="simple">
+<li>For <tt class="docutils literal"><span class="pre">__weak</span></tt> 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.</li>
+<li>For all other objects, the lvalue is loaded with primitive semantics.</li>
+</ul>
+<p><span class="arc-term">Assignment</span> occurs when evaluating an assignment operator.  The
+semantics vary based on the qualification:</p>
+<ul class="simple">
+<li>For <tt class="docutils literal"><span class="pre">__strong</span></tt> 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.</li>
+<li>For <tt class="docutils literal"><span class="pre">__weak</span></tt> 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.</li>
+<li>For <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> objects, the new pointee is stored into the
+lvalue using primitive semantics.</li>
+<li>For <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects, the new pointee is retained, autoreleased,
+and stored into the lvalue using primitive semantics.</li>
+</ul>
+<p><span class="arc-term">Initialization</span> occurs when an object’s lifetime begins, which
+depends on its storage duration.  Initialization proceeds in two stages:</p>
+<ol class="arabic simple">
+<li>First, a null pointer is stored into the lvalue using primitive semantics.
+This step is skipped if the object is <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>.</li>
+<li>Second, if the object has an initializer, that expression is evaluated and
+then assigned into the object using the usual assignment semantics.</li>
+</ol>
+<p><span class="arc-term">Destruction</span> 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.</p>
+<p><span class="arc-term">Moving</span> 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 <tt class="docutils literal"><span class="pre">__block</span></tt> variables
+and rvalue references in C++.  For <tt class="docutils literal"><span class="pre">__strong</span></tt> 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.</p>
+</div>
+<div class="section" id="arc-ownership-restrictions">
+<span id="id1"></span><h3><a class="toc-backref" href="#id24">Restrictions</a><a class="headerlink" href="#arc-ownership-restrictions" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="weak-unavailable-types">
+<span id="arc-ownership-restrictions-weak"></span><h4><a class="toc-backref" href="#id25">Weak-unavailable types</a><a class="headerlink" href="#weak-unavailable-types" title="Permalink to this headline">Â¶</a></h4>
+<p>It is explicitly permitted for Objective-C classes to not support <tt class="docutils literal"><span class="pre">__weak</span></tt>
+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 <tt class="docutils literal"><span class="pre">__weak</span></tt> references.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Historically, it has been possible for a class to provide its own
+reference-count implementation by overriding <tt class="docutils literal"><span class="pre">retain</span></tt>, <tt class="docutils literal"><span class="pre">release</span></tt>, 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.</p>
+</div>
+<p>A class may indicate that it does not support weak references by providing the
+<tt class="docutils literal"><span class="pre">objc_arc_weak_unavailable</span></tt> attribute on the class’s interface declaration.  A
+retainable object pointer type is <strong>weak-unavailable</strong> if
+is a pointer to an (optionally protocol-qualified) Objective-C class <tt class="docutils literal"><span class="pre">T</span></tt> where
+<tt class="docutils literal"><span class="pre">T</span></tt> or one of its superclasses has the <tt class="docutils literal"><span class="pre">objc_arc_weak_unavailable</span></tt>
+attribute.  A program is ill-formed if it applies the <tt class="docutils literal"><span class="pre">__weak</span></tt> ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.</p>
+</div>
+<div class="section" id="storage-duration-of-autoreleasing-objects">
+<span id="arc-ownership-restrictions-autoreleasing"></span><h4><a class="toc-backref" href="#id26">Storage duration of <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects</a><a class="headerlink" href="#storage-duration-of-autoreleasing-objects" title="Permalink to this headline">Â¶</a></h4>
+<p>A program is ill-formed if it declares an <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object of
+non-automatic storage duration.  A program is ill-formed if it captures an
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object in a block or, unless by reference, in a C++11
+lambda.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>It is undefined behavior if a non-null pointer is assigned to an
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object while an autorelease pool is in scope and then that
+object is read after the autorelease pool’s scope is left.</p>
+</div>
+<div class="section" id="conversion-of-pointers-to-ownership-qualified-types">
+<span id="arc-ownership-restrictions-conversion-indirect"></span><h4><a class="toc-backref" href="#id27">Conversion of pointers to ownership-qualified types</a><a class="headerlink" href="#conversion-of-pointers-to-ownership-qualified-types" title="Permalink to this headline">Â¶</a></h4>
+<p>A program is ill-formed if an expression of type <tt class="docutils literal"><span class="pre">T*</span></tt> is converted,
+explicitly or implicitly, to the type <tt class="docutils literal"><span class="pre">U*</span></tt>, where <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> have
+different ownership qualification, unless:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">T</span></tt> is qualified with <tt class="docutils literal"><span class="pre">__strong</span></tt>, <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>, or
+<tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>, and <tt class="docutils literal"><span class="pre">U</span></tt> is qualified with both <tt class="docutils literal"><span class="pre">const</span></tt> and
+<tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>; or</li>
+<li>either <tt class="docutils literal"><span class="pre">T</span></tt> or <tt class="docutils literal"><span class="pre">U</span></tt> is <tt class="docutils literal"><span class="pre">cv</span> <span class="pre">void</span></tt>, where <tt class="docutils literal"><span class="pre">cv</span></tt> is an optional sequence
+of non-ownership qualifiers; or</li>
+<li>the conversion is requested with a <tt class="docutils literal"><span class="pre">reinterpret_cast</span></tt> in Objective-C++; or</li>
+<li>the conversion is a well-formed <a class="reference internal" href="#arc-ownership-restrictions-pass-by-writeback"><em>pass-by-writeback</em></a>.</li>
+</ul>
+<p>The analogous rule applies to <tt class="docutils literal"><span class="pre">T&</span></tt> and <tt class="docutils literal"><span class="pre">U&</span></tt> in Objective-C++.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">These rules provide a reasonable level of type-safety for indirect pointers,
+as long as the underlying memory is not deallocated.  The conversion to
+<tt class="docutils literal"><span class="pre">const</span> <span class="pre">__unsafe_unretained</span></tt> 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 <tt class="docutils literal"><span class="pre">void*</span></tt> is useful for allocating
+memory or otherwise escaping the type system, but use it carefully.
+<tt class="docutils literal"><span class="pre">reinterpret_cast</span></tt> is considered to be an obvious enough sign of taking
+responsibility for any problems.</p>
+</div>
+<p>It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-<tt class="docutils literal"><span class="pre">__weak</span></tt> object
+may be read through an <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> lvalue.</p>
+<p>It is undefined behavior if a managed operation is performed on a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+or <tt class="docutils literal"><span class="pre">__weak</span></tt> 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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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 (<tt class="docutils literal"><span class="pre">__strong</span></tt> objects) and consistency errors
+(<tt class="docutils literal"><span class="pre">__weak</span></tt> objects).</p>
+</div>
+<p>These requirements are followed automatically in Objective-C++ when creating
+objects of retainable object owner type with <tt class="docutils literal"><span class="pre">new</span></tt> or <tt class="docutils literal"><span class="pre">new[]</span></tt> and destroying
+them with <tt class="docutils literal"><span class="pre">delete</span></tt>, <tt class="docutils literal"><span class="pre">delete[]</span></tt>, 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
+<tt class="docutils literal"><span class="pre">new[]</span></tt>‘d in ARC translation units cannot be <tt class="docutils literal"><span class="pre">delete[]</span></tt>‘d in non-ARC
+translation units and vice-versa.</p>
+</div>
+<div class="section" id="passing-to-an-out-parameter-by-writeback">
+<span id="arc-ownership-restrictions-pass-by-writeback"></span><h4><a class="toc-backref" href="#id28">Passing to an out parameter by writeback</a><a class="headerlink" href="#passing-to-an-out-parameter-by-writeback" title="Permalink to this headline">Â¶</a></h4>
+<p>If the argument passed to a parameter of type <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__autoreleasing</span> <span class="pre">*</span></tt> has type
+<tt class="docutils literal"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></tt>, where <tt class="docutils literal"><span class="pre">oq</span></tt> is an ownership qualifier, then the argument is a
+candidate for <span class="arc-term">pass-by-writeback`</span> if:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">oq</span></tt> is <tt class="docutils literal"><span class="pre">__strong</span></tt> or <tt class="docutils literal"><span class="pre">__weak</span></tt>, and</li>
+<li>it would be legal to initialize a <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__strong</span> <span class="pre">*</span></tt> with a <tt class="docutils literal"><span class="pre">U</span> <span class="pre">__strong</span> <span class="pre">*</span></tt>.</li>
+</ul>
+<p>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.</p>
+<p>The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">&var</span></tt>, where <tt class="docutils literal"><span class="pre">var</span></tt> is a scalar variable of automatic storage duration
+with retainable object pointer type</li>
+<li>a conditional expression where the second and third operands are both legal
+forms</li>
+<li>a cast whose operand is a legal form</li>
+<li>a null pointer constant</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>A pass-by-writeback is evaluated as follows:</p>
+<ol class="arabic simple">
+<li>The argument is evaluated to yield a pointer <tt class="docutils literal"><span class="pre">p</span></tt> of type <tt class="docutils literal"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></tt>.</li>
+<li>If <tt class="docutils literal"><span class="pre">p</span></tt> is a null pointer, then a null pointer is passed as the argument,
+and no further work is required for the pass-by-writeback.</li>
+<li>Otherwise, a temporary of type <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__autoreleasing</span></tt> is created and
+initialized to a null pointer.</li>
+<li>If the parameter is not an Objective-C method parameter marked <tt class="docutils literal"><span class="pre">out</span></tt>,
+then <tt class="docutils literal"><span class="pre">*p</span></tt> is read, and the result is written into the temporary with
+primitive semantics.</li>
+<li>The address of the temporary is passed as the argument to the actual call.</li>
+<li>After the call completes, the temporary is loaded with primitive
+semantics, and that value is assigned into <tt class="docutils literal"><span class="pre">*p</span></tt>.</li>
+</ol>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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 <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> rather than <tt class="docutils literal"><span class="pre">__strong</span></tt>.  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
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> on all the variables they intend to use for
+out-parameters.  This was the least bad solution.</p>
+</div>
+</div>
+<div class="section" id="ownership-qualified-fields-of-structs-and-unions">
+<span id="arc-ownership-restrictions-records"></span><h4><a class="toc-backref" href="#id29">Ownership-qualified fields of structs and unions</a><a class="headerlink" href="#ownership-qualified-fields-of-structs-and-unions" title="Permalink to this headline">Â¶</a></h4>
+<p>A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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 <tt class="docutils literal"><span class="pre">void*</span></tt> or an <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> object.</p>
+</div>
+<p>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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+</div>
+<div class="section" id="ownership-inference">
+<span id="arc-ownership-inference"></span><h3><a class="toc-backref" href="#id30">Ownership inference</a><a class="headerlink" href="#ownership-inference" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="objects">
+<span id="arc-ownership-inference-variables"></span><h4><a class="toc-backref" href="#id31">Objects</a><a class="headerlink" href="#objects" title="Permalink to this headline">Â¶</a></h4>
+<p>If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+<tt class="docutils literal"><span class="pre">__strong</span></tt> qualification.</p>
+<p>As a special case, if the object’s base type is <tt class="docutils literal"><span class="pre">Class</span></tt> (possibly
+protocol-qualified), the type is adjusted to have <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>
+qualification instead.</p>
+</div>
+<div class="section" id="indirect-parameters">
+<span id="arc-ownership-inference-indirect-parameters"></span><h4><a class="toc-backref" href="#id32">Indirect parameters</a><a class="headerlink" href="#indirect-parameters" title="Permalink to this headline">Â¶</a></h4>
+<p>If a function or method parameter has type <tt class="docutils literal"><span class="pre">T*</span></tt>, where <tt class="docutils literal"><span class="pre">T</span></tt> is an
+ownership-unqualified retainable object pointer type, then:</p>
+<ul class="simple">
+<li>if <tt class="docutils literal"><span class="pre">T</span></tt> is <tt class="docutils literal"><span class="pre">const</span></tt>-qualified or <tt class="docutils literal"><span class="pre">Class</span></tt>, then it is implicitly
+qualified with <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>;</li>
+<li>otherwise, it is implicitly qualified with <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last"><tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> exists mostly for this case, the Cocoa convention for
+out-parameters.  Since a pointer to <tt class="docutils literal"><span class="pre">const</span></tt> 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 <em>mutable</em> array, inferring
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> is the wrong thing to do; this directs some of the
+caution in the following rules about writeback.</p>
+</div>
+<p>Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.</p>
+<p>This rule does not apply in Objective-C++ if a parameter’s type is dependent in
+a template pattern and is only <em>instantiated</em> to a type which would be a
+pointer to an unqualified retainable object pointer type.  Such code is still
+ill-formed.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The convention is very unlikely to be intentional in template code.</p>
+</div>
+</div>
+<div class="section" id="template-arguments">
+<span id="arc-ownership-inference-template-arguments"></span><h4><a class="toc-backref" href="#id33">Template arguments</a><a class="headerlink" href="#template-arguments" title="Permalink to this headline">Â¶</a></h4>
+<p>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 <tt class="docutils literal"><span class="pre">__strong</span></tt> qualification.  This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last"><tt class="docutils literal"><span class="pre">__strong</span></tt> is a useful default for containers (e.g., <tt class="docutils literal"><span class="pre">std::vector<id></span></tt>),
+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.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="method-families">
+<span id="arc-method-families"></span><h2><a class="toc-backref" href="#id34">Method families</a><a class="headerlink" href="#method-families" title="Permalink to this headline">Â¶</a></h2>
+<p>An Objective-C method may fall into a <span class="arc-term">method family</span>, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.</p>
+<p>A method is in a certain method family if:</p>
+<ul class="simple">
+<li>it has a <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute placing it in that family; or if
+not that,</li>
+<li>it does not have an <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute placing it in a
+different or no family, and</li>
+<li>its selector falls into the corresponding selector family, and</li>
+<li>its signature obeys the added restrictions of the method family.</li>
+</ul>
+<p>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, <tt class="docutils literal"><span class="pre">_perform:with:</span></tt> and
+<tt class="docutils literal"><span class="pre">performWith:</span></tt> would fall into the <tt class="docutils literal"><span class="pre">perform</span></tt> family (if we recognized one),
+but <tt class="docutils literal"><span class="pre">performing:with</span></tt> would not.</p>
+<p>The families and their added restrictions are:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">alloc</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">copy</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">mutableCopy</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">new</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">init</span></tt> 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 <tt class="docutils literal"><span class="pre">init</span></tt> method whose return type is neither <tt class="docutils literal"><span class="pre">id</span></tt> 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).</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>There are a fair number of existing methods with <tt class="docutils literal"><span class="pre">init</span></tt>-like selectors
+which nonetheless don’t follow the <tt class="docutils literal"><span class="pre">init</span></tt> conventions.  Typically these
+are either accidental naming collisions or helper methods called during
+initialization.  Because of the peculiar retain/release behavior of
+<tt class="docutils literal"><span class="pre">init</span></tt> methods, it’s very important not to treat these methods as
+<tt class="docutils literal"><span class="pre">init</span></tt> 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 <tt class="docutils literal"><span class="pre">init</span></tt> family.</p>
+<p class="last">Note that a method with an <tt class="docutils literal"><span class="pre">init</span></tt>-family selector which returns a
+non-Objective-C type (e.g. <tt class="docutils literal"><span class="pre">void</span></tt>) is perfectly well-formed; it simply
+isn’t in the <tt class="docutils literal"><span class="pre">init</span></tt> family.</p>
+</div>
+</li>
+</ul>
+<p>A program is ill-formed if a method’s declarations, implementations, and
+overrides do not all have the same method family.</p>
+<div class="section" id="explicit-method-family-control">
+<span id="arc-family-attribute"></span><h3><a class="toc-backref" href="#id35">Explicit method family control</a><a class="headerlink" href="#explicit-method-family-control" title="Permalink to this headline">Â¶</a></h3>
+<p>A method may be annotated with the <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute to
+precisely control which method family it belongs to.  If a method in an
+<tt class="docutils literal"><span class="pre">@implementation</span></tt> does not have this attribute, but there is a method
+declared in the corresponding <tt class="docutils literal"><span class="pre">@interface</span></tt> that does, then the attribute is
+copied to the declaration in the <tt class="docutils literal"><span class="pre">@implementation</span></tt>.  The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+<tt class="docutils literal"><span class="pre">__has_attribute(objc_method_family)</span></tt>.</p>
+<p>The attribute is spelled
+<tt class="docutils literal"><span class="pre">__attribute__((objc_method_family(</span></tt> <em>family</em> <tt class="docutils literal"><span class="pre">)))</span></tt>.  If <em>family</em> is
+<tt class="docutils literal"><span class="pre">none</span></tt>, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type.  Otherwise, <em>family</em> must be one of
+<tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, or <tt class="docutils literal"><span class="pre">new</span></tt>, 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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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
+<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt>, this attribute allows the user to communicate
+semantic intent, which is of use both to ARC (which, e.g., treats calls to
+<tt class="docutils literal"><span class="pre">init</span></tt> specially) and the static analyzer.</p>
+</div>
+</div>
+<div class="section" id="semantics-of-method-families">
+<span id="arc-family-semantics"></span><h3><a class="toc-backref" href="#id36">Semantics of method families</a><a class="headerlink" href="#semantics-of-method-families" title="Permalink to this headline">Â¶</a></h3>
+<p>A method’s membership in a method family may imply non-standard semantics for
+its parameters and return type.</p>
+<p>Methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt> families —
+that is, methods in all the currently-defined families except <tt class="docutils literal"><span class="pre">init</span></tt> —
+implicitly <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>return a retained object</em></a> as if they were annotated with
+the <tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt> attribute.  This can be overridden by annotating
+the method with either of the <tt class="docutils literal"><span class="pre">ns_returns_autoreleased</span></tt> or
+<tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt> attributes.</p>
+<p>Properties also follow same naming rules as methods.  This means that those in
+the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt> families provide access
+to <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>retained objects</em></a>.  This
+can be overridden by annotating the property with <tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt>
+attribute.</p>
+<div class="section" id="semantics-of-init">
+<span id="arc-family-semantics-init"></span><h4><a class="toc-backref" href="#id37">Semantics of <tt class="docutils literal"><span class="pre">init</span></tt></a><a class="headerlink" href="#semantics-of-init" title="Permalink to this headline">Â¶</a></h4>
+<p>Methods in the <tt class="docutils literal"><span class="pre">init</span></tt> family implicitly <a class="reference internal" href="#arc-objects-operands-consumed"><em>consume</em></a> their <tt class="docutils literal"><span class="pre">self</span></tt> parameter and <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>return a
+retained object</em></a>.  Neither of
+these properties can be altered through attributes.</p>
+<p>A call to an <tt class="docutils literal"><span class="pre">init</span></tt> method with a receiver that is either <tt class="docutils literal"><span class="pre">self</span></tt> (possibly
+parenthesized or casted) or <tt class="docutils literal"><span class="pre">super</span></tt> is called a <span class="arc-term">delegate init
+call</span>.  It is an error for a delegate init call to be made except from an
+<tt class="docutils literal"><span class="pre">init</span></tt> method, and excluding blocks within such methods.</p>
+<p>As an exception to the <a class="reference internal" href="#arc-misc-self"><em>usual rule</em></a>, the variable <tt class="docutils literal"><span class="pre">self</span></tt>
+is mutable in an <tt class="docutils literal"><span class="pre">init</span></tt> method and has the usual semantics for a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+variable.  However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an <tt class="docutils literal"><span class="pre">init</span></tt> method attempts to use the previous value
+of <tt class="docutils literal"><span class="pre">self</span></tt> after the completion of a delegate init call.  It is conventional,
+but not required, for an <tt class="docutils literal"><span class="pre">init</span></tt> method to return <tt class="docutils literal"><span class="pre">self</span></tt>.</p>
+<p>It is undefined behavior for a program to cause two or more calls to <tt class="docutils literal"><span class="pre">init</span></tt>
+methods on the same object, except that each <tt class="docutils literal"><span class="pre">init</span></tt> method invocation may
+perform at most one delegate init call.</p>
+</div>
+<div class="section" id="related-result-types">
+<span id="arc-family-semantics-result-type"></span><h4><a class="toc-backref" href="#id38">Related result types</a><a class="headerlink" href="#related-result-types" title="Permalink to this headline">Â¶</a></h4>
+<p>Certain methods are candidates to have <span class="arc-term">related result types</span>:</p>
+<ul class="simple">
+<li>class methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt> and <tt class="docutils literal"><span class="pre">new</span></tt> method families</li>
+<li>instance methods in the <tt class="docutils literal"><span class="pre">init</span></tt> family</li>
+<li>the instance method <tt class="docutils literal"><span class="pre">self</span></tt></li>
+<li>outside of ARC, the instance methods <tt class="docutils literal"><span class="pre">retain</span></tt> and <tt class="docutils literal"><span class="pre">autorelease</span></tt></li>
+</ul>
+<p>If the formal result type of such a method is <tt class="docutils literal"><span class="pre">id</span></tt> or protocol-qualified
+<tt class="docutils literal"><span class="pre">id</span></tt>, 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:</p>
+<ul class="simple">
+<li>if it is a class method, and the receiver is a class name <tt class="docutils literal"><span class="pre">T</span></tt>, the message
+send expression has type <tt class="docutils literal"><span class="pre">T*</span></tt>; otherwise</li>
+<li>if it is an instance method, and the receiver has type <tt class="docutils literal"><span class="pre">T</span></tt>, the message
+send expression has type <tt class="docutils literal"><span class="pre">T</span></tt>; otherwise</li>
+<li>the message send expression has the normal result type of the method.</li>
+</ul>
+<p>This is a new rule of the Objective-C language and applies outside of ARC.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="optimization">
+<span id="arc-optimization"></span><h2><a class="toc-backref" href="#id39">Optimization</a><a class="headerlink" href="#optimization" title="Permalink to this headline">Â¶</a></h2>
+<p>Within this section, the word <span class="arc-term">function</span> will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.</p>
+<p>This specification describes ARC as performing specific <tt class="docutils literal"><span class="pre">retain</span></tt> and
+<tt class="docutils literal"><span class="pre">release</span></tt> 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 <span class="arc-term">formal local retain history</span> of the
+object pointer.  The corresponding actual sequence executed is the
+<cite>dynamic local retain history</cite>.</p>
+<p>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 <a class="reference internal" href="#arc-objects-retains"><em>restrictions</em></a> on
+the implementation of <tt class="docutils literal"><span class="pre">retain</span></tt> and <tt class="docutils literal"><span class="pre">release</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Specifically, ARC is sometimes permitted to optimize <tt class="docutils literal"><span class="pre">release</span></tt>
+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 <tt class="docutils literal"><span class="pre">retain</span></tt>/<tt class="docutils literal"><span class="pre">release</span></tt> pairs.  For
+example, consider the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">x</span> <span class="o">=</span> <span class="n">_ivar</span><span class="p">;</span>
+<span class="p">[</span><span class="n">x</span> <span class="n">foo</span><span class="p">];</span>
+</pre></div>
+</div>
+<p class="last">If we were not permitted in any event to shorten the lifetime of the
+object in <tt class="docutils literal"><span class="pre">x</span></tt>, then we would not be able to eliminate this retain
+and release unless we could prove that the message send could not
+modify <tt class="docutils literal"><span class="pre">_ivar</span></tt> (or deallocate <tt class="docutils literal"><span class="pre">self</span></tt>).  Since message sends are
+opaque to the optimizer, this is not possible, and so ARC’s hands
+would be almost completely tied.</p>
+</div>
+<p>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.</p>
+<p>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).</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>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 <tt class="docutils literal"><span class="pre">__strong</span></tt> 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.</p>
+<div class="section" id="object-liveness">
+<span id="arc-optimization-liveness"></span><h3><a class="toc-backref" href="#id40">Object liveness</a><a class="headerlink" href="#object-liveness" title="Permalink to this headline">Â¶</a></h3>
+<p>ARC may not allow a retainable object <tt class="docutils literal"><span class="pre">X</span></tt> to be deallocated at a
+time <tt class="docutils literal"><span class="pre">T</span></tt> in a computation history if:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is the value stored in a <tt class="docutils literal"><span class="pre">__strong</span></tt> object <tt class="docutils literal"><span class="pre">S</span></tt> with
+<a class="reference internal" href="#arc-optimization-precise"><em>precise lifetime semantics</em></a>, or</li>
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is the value stored in a <tt class="docutils literal"><span class="pre">__strong</span></tt> object <tt class="docutils literal"><span class="pre">S</span></tt> with
+imprecise lifetime semantics and, at some point after <tt class="docutils literal"><span class="pre">T</span></tt> but
+before the next store to <tt class="docutils literal"><span class="pre">S</span></tt>, the computation history features a
+load from <tt class="docutils literal"><span class="pre">S</span></tt> and in some way depends on the value loaded, or</li>
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is a value described as being released at the end of the
+current full-expression and, at some point after <tt class="docutils literal"><span class="pre">T</span></tt> but before
+the end of the full-expression, the computation history depends
+on that value.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The intent of the second rule is to say that objects held in normal
+<tt class="docutils literal"><span class="pre">__strong</span></tt> 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.</p>
+<p class="last">The intent of the third rule is to say that return values may be
+released after they’ve been used.</p>
+</div>
+<p>A computation history depends on a pointer value <tt class="docutils literal"><span class="pre">P</span></tt> if it:</p>
+<ul class="simple">
+<li>performs a pointer comparison with <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>loads from <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>stores to <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>depends on a pointer value <tt class="docutils literal"><span class="pre">Q</span></tt> derived via pointer arithmetic
+from <tt class="docutils literal"><span class="pre">P</span></tt> (including an instance-variable or field access), or</li>
+<li>depends on a pointer value <tt class="docutils literal"><span class="pre">Q</span></tt> loaded from <tt class="docutils literal"><span class="pre">P</span></tt>.</li>
+</ul>
+<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 <tt class="docutils literal"><span class="pre">P</span></tt>.  Furthermore, this
+dependency is not carried by values that are stored to objects.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>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.</p>
+<p>Dependency propagates to values loaded from a pointer because those
+values might be invalidated by deallocating the object.  For
+example, given the code <tt class="docutils literal"><span class="pre">__strong</span> <span class="pre">id</span> <span class="pre">x</span> <span class="pre">=</span> <span class="pre">p->ivar;</span></tt>, ARC must not
+move the release of <tt class="docutils literal"><span class="pre">p</span></tt> to between the load of <tt class="docutils literal"><span class="pre">p->ivar</span></tt> and the
+retain of that value for storing into <tt class="docutils literal"><span class="pre">x</span></tt>.</p>
+<p>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.</p>
+<p class="last">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.</p>
+</div>
+</div>
+<div class="section" id="no-object-lifetime-extension">
+<span id="arc-optimization-object-lifetime"></span><h3><a class="toc-backref" href="#id41">No object lifetime extension</a><a class="headerlink" href="#no-object-lifetime-extension" title="Permalink to this headline">Â¶</a></h3>
+<p>If, in the formal computation history of the program, an object <tt class="docutils literal"><span class="pre">X</span></tt>
+has been deallocated by the time of an observable side-effect, then
+ARC must cause <tt class="docutils literal"><span class="pre">X</span></tt> 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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>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.</p>
+<p class="last">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.</p>
+</div>
+</div>
+<div class="section" id="precise-lifetime-semantics">
+<span id="arc-optimization-precise"></span><h3><a class="toc-backref" href="#id42">Precise lifetime semantics</a><a class="headerlink" href="#precise-lifetime-semantics" title="Permalink to this headline">Â¶</a></h3>
+<p>In general, ARC maintains an invariant that a retainable object pointer held in
+a <tt class="docutils literal"><span class="pre">__strong</span></tt> object will be retained for the full formal lifetime of the
+object.  Objects subject to this invariant have <span class="arc-term">precise lifetime
+semantics</span>.</p>
+<p>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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>A local variable of retainable object owner type and automatic storage duration
+may be annotated with the <tt class="docutils literal"><span class="pre">objc_precise_lifetime</span></tt> attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+</div>
+<div class="section" id="miscellaneous">
+<span id="arc-misc"></span><h2><a class="toc-backref" href="#id43">Miscellaneous</a><a class="headerlink" href="#miscellaneous" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="special-methods">
+<span id="arc-misc-special-methods"></span><h3><a class="toc-backref" href="#id44">Special methods</a><a class="headerlink" href="#special-methods" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="memory-management-methods">
+<span id="arc-misc-special-methods-retain"></span><h4><a class="toc-backref" href="#id45">Memory management methods</a><a class="headerlink" href="#memory-management-methods" title="Permalink to this headline">Â¶</a></h4>
+<p>A program is ill-formed if it contains a method definition, message send, or
+<tt class="docutils literal"><span class="pre">@selector</span></tt> expression for any of the following selectors:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">autorelease</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">release</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">retain</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">retainCount</span></tt></li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p><tt class="docutils literal"><span class="pre">retainCount</span></tt> is banned because ARC robs it of consistent semantics.  The
+others were banned after weighing three options for how to deal with message
+sends:</p>
+<p><strong>Honoring</strong> 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.</p>
+<p><strong>Ignoring</strong> them would badly violate user expectations about their code.
+While it <em>would</em> 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.</p>
+<p><strong>Banning</strong> 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.</p>
+<p class="last">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 <a class="reference internal" href="#arc-objects-retains"><em>semantics</em></a> laid out elsewhere in this document.</p>
+</div>
+</div>
+<div class="section" id="dealloc">
+<span id="arc-misc-special-methods-dealloc"></span><h4><a class="toc-backref" href="#id46"><tt class="docutils literal"><span class="pre">dealloc</span></tt></a><a class="headerlink" href="#dealloc" title="Permalink to this headline">Â¶</a></h4>
+<p>A program is ill-formed if it contains a message send or <tt class="docutils literal"><span class="pre">@selector</span></tt>
+expression for the selector <tt class="docutils literal"><span class="pre">dealloc</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">There are no legitimate reasons to call <tt class="docutils literal"><span class="pre">dealloc</span></tt> directly.</p>
+</div>
+<p>A class may provide a method definition for an instance method named
+<tt class="docutils literal"><span class="pre">dealloc</span></tt>.  This method will be called after the final <tt class="docutils literal"><span class="pre">release</span></tt> of the
+object but before it is deallocated or any of its instance variables are
+destroyed.  The superclass’s implementation of <tt class="docutils literal"><span class="pre">dealloc</span></tt> will be called
+automatically when the method returns.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Even though ARC destroys instance variables automatically, there are still
+legitimate reasons to write a <tt class="docutils literal"><span class="pre">dealloc</span></tt> method, such as freeing
+non-retainable resources.  Failing to call <tt class="docutils literal"><span class="pre">[super</span> <span class="pre">dealloc]</span></tt> in such a
+method is nearly always a bug.  Sometimes, the object is simply trying to
+prevent itself from being destroyed, but <tt class="docutils literal"><span class="pre">dealloc</span></tt> 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
+<tt class="docutils literal"><span class="pre">free</span></tt>; for now, this can only be supported with a <tt class="docutils literal"><span class="pre">dealloc</span></tt>
+implementation outside of ARC.  Such an implementation must be very careful
+to do all the other work that <tt class="docutils literal"><span class="pre">NSObject</span></tt>‘s <tt class="docutils literal"><span class="pre">dealloc</span></tt> would, which is
+outside the scope of this document to describe.</p>
+</div>
+<p>The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the <tt class="docutils literal"><span class="pre">dealloc</span></tt> 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.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The traditional, non-ARC pattern for destroying instance variables is to
+destroy them immediately before calling <tt class="docutils literal"><span class="pre">[super</span> <span class="pre">dealloc]</span></tt>.  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
+<tt class="docutils literal"><span class="pre">dealloc</span></tt>, 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.</p>
+<p class="last">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 <tt class="docutils literal"><span class="pre">dealloc</span></tt>; a more
+holistic solution is to move semantically important side-effects out of
+<tt class="docutils literal"><span class="pre">dealloc</span></tt> and into a separate teardown phase which can rely on working with
+well-formed objects.</p>
+</div>
+</div>
+</div>
+<div class="section" id="autoreleasepool">
+<span id="arc-misc-autoreleasepool"></span><h3><a class="toc-backref" href="#id47"><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt></a><a class="headerlink" href="#autoreleasepool" title="Permalink to this headline">Â¶</a></h3>
+<p>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 <tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt> followed by a <em>compound-statement</em>, 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 <tt class="docutils literal"><span class="pre">return</span></tt> or
+<tt class="docutils literal"><span class="pre">break</span></tt>), 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.</p>
+<p><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt> may be used in non-ARC translation units, with equivalent
+semantics.</p>
+<p>A program is ill-formed if it refers to the <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> class.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+<div class="section" id="self">
+<span id="arc-misc-self"></span><h3><a class="toc-backref" href="#id48"><tt class="docutils literal"><span class="pre">self</span></tt></a><a class="headerlink" href="#self" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">self</span></tt> 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.</p>
+<p>To make this safe, for Objective-C instance methods <tt class="docutils literal"><span class="pre">self</span></tt> is implicitly
+<tt class="docutils literal"><span class="pre">const</span></tt> unless the method is in the <a class="reference internal" href="#arc-family-semantics-init"><em>init family</em></a>.  Further, <tt class="docutils literal"><span class="pre">self</span></tt> is <strong>always</strong> implicitly
+<tt class="docutils literal"><span class="pre">const</span></tt> within a class method.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The cost of retaining <tt class="docutils literal"><span class="pre">self</span></tt> 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 <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>), we
+chose to make this optimizing assumption and shift some amount of risk to the
+user.</p>
+</div>
+</div>
+<div class="section" id="fast-enumeration-iteration-variables">
+<span id="arc-misc-enumeration"></span><h3><a class="toc-backref" href="#id49">Fast enumeration iteration variables</a><a class="headerlink" href="#fast-enumeration-iteration-variables" title="Permalink to this headline">Â¶</a></h3>
+<p>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 <tt class="docutils literal"><span class="pre">const</span> <span class="pre">__strong</span></tt> and objects encountered during the
+enumeration are not actually retained.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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 <tt class="docutils literal"><span class="pre">__strong</span></tt>, which will make the variable
+mutable again and cause the loop to retain the objects it encounters.</p>
+</div>
+</div>
+<div class="section" id="blocks">
+<span id="arc-misc-blocks"></span><h3><a class="toc-backref" href="#id50">Blocks</a><a class="headerlink" href="#blocks" title="Permalink to this headline">Â¶</a></h3>
+<p>The implicit <tt class="docutils literal"><span class="pre">const</span></tt> 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.</p>
+<p>The <a class="reference internal" href="#arc-ownership-inference"><em>inference</em></a> rules apply equally to
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables, which is a shift in semantics from non-ARC, where
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables did not implicitly retain during capture.</p>
+<p><tt class="docutils literal"><span class="pre">__block</span></tt> 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.</p>
+<p>With the exception of retains done as part of initializing a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+parameter variable or reading a <tt class="docutils literal"><span class="pre">__weak</span></tt> variable, whenever these semantics
+call for retaining a value of block-pointer type, it has the effect of a
+<tt class="docutils literal"><span class="pre">Block_copy</span></tt>.  The optimizer may remove such copies when it sees that the
+result is used only as an argument to a call.</p>
+</div>
+<div class="section" id="exceptions">
+<span id="arc-misc-exceptions"></span><h3><a class="toc-backref" href="#id51">Exceptions</a><a class="headerlink" href="#exceptions" title="Permalink to this headline">Â¶</a></h3>
+<p>By default in Objective C, ARC is not exception-safe for normal releases:</p>
+<ul class="simple">
+<li>It does not end the lifetime of <tt class="docutils literal"><span class="pre">__strong</span></tt> variables when their scopes are
+abnormally terminated by an exception.</li>
+<li>It does not perform releases which would occur at the end of a
+full-expression if that full-expression throws an exception.</li>
+</ul>
+<p>A program may be compiled with the option <tt class="docutils literal"><span class="pre">-fobjc-arc-exceptions</span></tt> in order to
+enable these, or with the option <tt class="docutils literal"><span class="pre">-fno-objc-arc-exceptions</span></tt> to explicitly
+disable them, with the last such argument “winning”.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>In Objective-C++, <tt class="docutils literal"><span class="pre">-fobjc-arc-exceptions</span></tt> is enabled by default.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<p>ARC does end the lifetimes of <tt class="docutils literal"><span class="pre">__weak</span></tt> objects when an exception terminates
+their scope unless exceptions are disabled in the compiler.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The consequence of a local <tt class="docutils literal"><span class="pre">__weak</span></tt> 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.</p>
+</div>
+</div>
+<div class="section" id="interior-pointers">
+<span id="arc-misc-interior"></span><h3><a class="toc-backref" href="#id52">Interior pointers</a><a class="headerlink" href="#interior-pointers" title="Permalink to this headline">Â¶</a></h3>
+<p>An Objective-C method returning a non-retainable pointer may be annotated with
+the <tt class="docutils literal"><span class="pre">objc_returns_inner_pointer</span></tt> 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:</p>
+<ul class="simple">
+<li>the last use of the returned pointer, or any pointer derived from it, in the
+calling function or</li>
+<li>the autorelease pool is restored to a previous state.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>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.</p>
+<p class="last">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 <tt class="docutils literal"><span class="pre">strchr</span></tt>).  However, the implementation
+never need account for uses after a return from the code which calls the
+method returning an interior pointer.</p>
+</div>
+<p>As an exception, no extension is required if the receiver is loaded directly
+from a <tt class="docutils literal"><span class="pre">__strong</span></tt> object with <a class="reference internal" href="#arc-optimization-precise"><em>precise lifetime semantics</em></a>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+<div class="section" id="c-retainable-pointer-types">
+<span id="arc-misc-c-retainable"></span><h3><a class="toc-backref" href="#id53">C retainable pointer types</a><a class="headerlink" href="#c-retainable-pointer-types" title="Permalink to this headline">Â¶</a></h3>
+<p>A type is a <span class="arc-term">C retainable pointer type</span> if it is a pointer to
+(possibly qualified) <tt class="docutils literal"><span class="pre">void</span></tt> or a pointer to a (possibly qualifier) <tt class="docutils literal"><span class="pre">struct</span></tt>
+or <tt class="docutils literal"><span class="pre">class</span></tt> type.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+<div class="section" id="auditing-of-c-retainable-pointer-interfaces">
+<span id="arc-misc-c-retainable-audit"></span><h4><a class="toc-backref" href="#id54">Auditing of C retainable pointer interfaces</a><a class="headerlink" href="#auditing-of-c-retainable-pointer-interfaces" title="Permalink to this headline">Â¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
+<p>A C function may be marked with the <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> 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:</p>
+<ul class="simple">
+<li>A parameter of C retainable pointer type is assumed to not be consumed
+unless it is marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute, and</li>
+<li>A result of C retainable pointer type is assumed to not be returned retained
+unless the function is either marked <tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> or it follows
+the create/copy naming convention and is not marked
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt>.</li>
+</ul>
+<p>A function obeys the <span class="arc-term">create/copy</span> naming convention if its name
+contains as a substring:</p>
+<ul class="simple">
+<li>either “Create” or “Copy” not followed by a lowercase letter, or</li>
+<li>either “create” or “copy” not followed by a lowercase letter and
+not preceded by any letter, whether uppercase or lowercase.</li>
+</ul>
+<p>A second attribute, <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt>, 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 <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> and <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt>.</p>
+<p>A pragma is provided to facilitate the mass annotation of interfaces:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="cp">#pragma clang arc_cf_code_audited begin</span>
+<span class="p">...</span>
+<span class="cp">#pragma clang arc_cf_code_audited end</span>
+</pre></div>
+</div>
+<p>All C functions declared within the extent of this pragma are treated as if
+annotated with the <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> attribute unless they otherwise have
+the <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt> 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.</p>
+<p>It is possible to test for all the features in this section with
+<tt class="docutils literal"><span class="pre">__has_feature(arc_cf_code_audited)</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="runtime-support">
+<span id="arc-runtime"></span><h2><a class="toc-backref" href="#id55">Runtime support</a><a class="headerlink" href="#runtime-support" title="Permalink to this headline">Â¶</a></h2>
+<p>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++.</p>
+<p>Ownership qualification does not alter the storage requirements for objects,
+except that it is undefined behavior if a <tt class="docutils literal"><span class="pre">__weak</span></tt> object is inadequately
+aligned for an object of type <tt class="docutils literal"><span class="pre">id</span></tt>.  The other qualifiers may be used on
+explicitly under-aligned memory.</p>
+<p>The runtime tracks <tt class="docutils literal"><span class="pre">__weak</span></tt> objects which holds non-null values.  It is
+undefined behavior to direct modify a <tt class="docutils literal"><span class="pre">__weak</span></tt> object which is being tracked
+by the runtime except through an
+<a class="reference internal" href="#arc-runtime-objc-storeweak"><em>objc_storeWeak</em></a>,
+<a class="reference internal" href="#arc-runtime-objc-destroyweak"><em>objc_destroyWeak</em></a>, or
+<a class="reference internal" href="#arc-runtime-objc-moveweak"><em>objc_moveWeak</em></a> call.</p>
+<p>The runtime must provide a number of new entrypoints which the compiler may
+emit, which are described in the remainder of this section.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Several of these functions are semantically equivalent to a message send; we
+emit calls to C functions instead because:</p>
+<ul class="simple">
+<li>the machine code to do so is significantly smaller,</li>
+<li>it is much easier to recognize the C functions in the ARC optimizer, and</li>
+<li>a sufficient sophisticated runtime may be able to avoid the message send in
+common cases.</li>
+</ul>
+<p class="last">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.</p>
+</div>
+<div class="section" id="arc-runtime-objc-autorelease">
+<span id="id-objc-autorelease-id-value"></span><h3><a class="toc-backref" href="#id56"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-autorelease" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> 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
+<tt class="docutils literal"><span class="pre">autorelease</span></tt> message.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-autoreleasepoolpop-void-pool">
+<span id="arc-runtime-objc-autoreleasepoolpop"></span><h3><a class="toc-backref" href="#id57"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></tt></a><a class="headerlink" href="#void-objc-autoreleasepoolpop-void-pool" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">pool</span></tt> is the result of a previous call to
+<a class="reference internal" href="#arc-runtime-objc-autoreleasepoolpush"><em>objc_autoreleasePoolPush</em></a> on the
+current thread, where neither <tt class="docutils literal"><span class="pre">pool</span></tt> nor any enclosing pool have previously
+been popped.</p>
+<p>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 <tt class="docutils literal"><span class="pre">pool</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-autoreleasepoolpush-void">
+<span id="arc-runtime-objc-autoreleasepoolpush"></span><h3><a class="toc-backref" href="#id58"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></tt></a><a class="headerlink" href="#void-objc-autoreleasepoolpush-void" title="Permalink to this headline">Â¶</a></h3>
+<p>Creates a new autorelease pool that is enclosed by the current pool, makes that
+the current pool, and returns an opaque “handle” to it.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">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.</p>
+</div>
+</div>
+<div class="section" id="arc-runtime-objc-autoreleasereturnvalue">
+<span id="id-objc-autoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id59"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-autoreleasereturnvalue" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> 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
+<a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue"><em>objc_retainAutoreleasedReturnValue</em></a> for the same object in an
+enclosing call frame.  If this is not possible, the object is autoreleased as
+above.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-copyweak-id-dest-id-src">
+<span id="arc-runtime-objc-copyweak"></span><h3><a class="toc-backref" href="#id60"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a><a class="headerlink" href="#void-objc-copyweak-id-dest-id-src" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">src</span></tt> is a valid pointer which either contains a null pointer
+or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.  <tt class="docutils literal"><span class="pre">dest</span></tt> is a valid pointer
+which has not been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">dest</span></tt> is initialized to be equivalent to <tt class="docutils literal"><span class="pre">src</span></tt>, potentially registering it
+with the runtime.  Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">objc_copyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="kt">id</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">objc_release</span><span class="p">(</span><span class="n">objc_initWeak</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">src</span><span class="p">)));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">src</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-destroyweak-id-object">
+<span id="arc-runtime-objc-destroyweak"></span><h3><a class="toc-backref" href="#id61"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#void-objc-destroyweak-id-object" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">object</span></tt> is unregistered as a weak object, if it ever was.  The current value
+of <tt class="docutils literal"><span class="pre">object</span></tt> is left unspecified; otherwise, equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">objc_destroyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="nb">nil</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Does not need to be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on
+<tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-initweak">
+<span id="id-objc-initweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id62"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-initweak" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which has not been registered as
+a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.  <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is a null pointer or the object to which it points has begun
+deallocation, <tt class="docutils literal"><span class="pre">object</span></tt> is zero-initialized.  Otherwise, <tt class="docutils literal"><span class="pre">object</span></tt> is
+registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object pointing to <tt class="docutils literal"><span class="pre">value</span></tt>.  Equivalent to the
+following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_initWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="nb">nil</span><span class="p">;</span>
+  <span class="k">return</span> <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">value</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Returns the value of <tt class="docutils literal"><span class="pre">object</span></tt> after the call.</p>
+<p>Does not need to be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on
+<tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-loadweak">
+<span id="id-objc-loadweak-id-object"></span><h3><a class="toc-backref" href="#id63"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-loadweak" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p>If <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object, and the last value stored
+into <tt class="docutils literal"><span class="pre">object</span></tt> has not yet been deallocated or begun deallocation, retains and
+autoreleases that value and returns it.  Otherwise returns null.  Equivalent to
+the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_loadWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">object</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Loading weak references would be inherently prone to race conditions without
+the retain.</p>
+</div>
+</div>
+<div class="section" id="arc-runtime-objc-loadweakretained">
+<span id="id-objc-loadweakretained-id-object"></span><h3><a class="toc-backref" href="#id64"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-loadweakretained" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p>If <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object, and the last value stored
+into <tt class="docutils literal"><span class="pre">object</span></tt> has not yet been deallocated or begun deallocation, retains
+that value and returns it.  Otherwise returns null.</p>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-moveweak-id-dest-id-src">
+<span id="arc-runtime-objc-moveweak"></span><h3><a class="toc-backref" href="#id65"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a><a class="headerlink" href="#void-objc-moveweak-id-dest-id-src" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">src</span></tt> is a valid pointer which either contains a null pointer
+or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.  <tt class="docutils literal"><span class="pre">dest</span></tt> is a valid pointer
+which has not been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">dest</span></tt> is initialized to be equivalent to <tt class="docutils literal"><span class="pre">src</span></tt>, potentially registering it
+with the runtime.  <tt class="docutils literal"><span class="pre">src</span></tt> may then be left in its original state, in which
+case this call is equivalent to <a class="reference internal" href="#arc-runtime-objc-copyweak"><em>objc_copyWeak</em></a>, or it may be left as null.</p>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">src</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-release-id-value">
+<span id="arc-runtime-objc-release"></span><h3><a class="toc-backref" href="#id66"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#void-objc-release-id-value" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it performs a
+release operation exactly as if the object had been sent the <tt class="docutils literal"><span class="pre">release</span></tt>
+message.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retain">
+<span id="id-objc-retain-id-value"></span><h3><a class="toc-backref" href="#id67"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retain" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it performs a retain
+operation exactly as if the object had been sent the <tt class="docutils literal"><span class="pre">retain</span></tt> message.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautorelease">
+<span id="id-objc-retainautorelease-id-value"></span><h3><a class="toc-backref" href="#id68"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautorelease" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it performs a retain
+operation followed by an autorelease operation.  Equivalent to the following
+code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_retainAutorelease</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautoreleasereturnvalue">
+<span id="id-objc-retainautoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id69"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasereturnvalue" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it performs a retain
+operation followed by the operation described in
+<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><em>objc_autoreleaseReturnValue</em></a>.
+Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_retainAutoreleaseReturnValue</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autoreleaseReturnValue</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautoreleasedreturnvalue">
+<span id="id-objc-retainautoreleasedreturnvalue-id-value"></span><h3><a class="toc-backref" href="#id70"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasedreturnvalue" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it attempts to
+accept a hand off of a retain count from a call to
+<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><em>objc_autoreleaseReturnValue</em></a> on
+<tt class="docutils literal"><span class="pre">value</span></tt> in a recently-called function or something it calls.  If that fails,
+it performs a retain operation exactly like <a class="reference internal" href="#arc-runtime-objc-retain"><em>objc_retain</em></a>.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainblock">
+<span id="id-objc-retainblock-id-value"></span><h3><a class="toc-backref" href="#id71"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainblock" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid block object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, if the block pointed
+to by <tt class="docutils literal"><span class="pre">value</span></tt> 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 <tt class="docutils literal"><span class="pre">retain</span></tt> message.</p>
+</div>
+<div class="section" id="arc-runtime-objc-storestrong">
+<span id="id-objc-storestrong-id-object-id-value"></span><h3><a class="toc-backref" href="#id72"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-storestrong" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer to a <tt class="docutils literal"><span class="pre">__strong</span></tt> object which is
+adequately aligned for a pointer.  <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid
+object.</p>
+<p>Performs the complete sequence for assigning to a <tt class="docutils literal"><span class="pre">__strong</span></tt> object of
+non-block type <a class="footnote-reference" href="#id3" id="id2">[*]</a>.  Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_storeStrong</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">value</span> <span class="n">retain</span><span class="p">];</span>
+  <span class="kt">id</span> <span class="n">oldValue</span> <span class="o">=</span> <span class="o">*</span><span class="n">object</span><span class="p">;</span>
+  <span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="n">value</span><span class="p">;</span>
+  <span class="p">[</span><span class="n">oldValue</span> <span class="n">release</span><span class="p">];</span>
+  <span class="k">return</span> <span class="n">value</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+<table class="docutils footnote" frame="void" id="id3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[*]</a></td><td>This does not imply that a <tt class="docutils literal"><span class="pre">__strong</span></tt> object of block type is an
+invalid argument to this function. Rather it implies that an <tt class="docutils literal"><span class="pre">objc_retain</span></tt>
+and not an <tt class="docutils literal"><span class="pre">objc_retainBlock</span></tt> operation will be emitted if the argument is
+a block.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="arc-runtime-objc-storeweak">
+<span id="id-objc-storeweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id73"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-storeweak" title="Permalink to this headline">Â¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.  <tt class="docutils literal"><span class="pre">value</span></tt> is null or a
+pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is a null pointer or the object to which it points has begun
+deallocation, <tt class="docutils literal"><span class="pre">object</span></tt> is assigned null and unregistered as a <tt class="docutils literal"><span class="pre">__weak</span></tt>
+object.  Otherwise, <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object or has its
+registration updated to point to <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+<p>Returns the value of <tt class="docutils literal"><span class="pre">object</span></tt> after the call.</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="CrossCompilation.html">Cross-compilation using Clang</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/Block-ABI-Apple.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/Block-ABI-Apple.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/Block-ABI-Apple.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/Block-ABI-Apple.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,913 @@
+
+
+<!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>Block Implementation Specification — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="next" title="Objective-C Automatic Reference Counting (ARC)" href="AutomaticReferenceCounting.html" />
+    <link rel="prev" title="Language Specification for Blocks" href="BlockLanguageSpec.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Block Implementation Specification</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="block-implementation-specification">
+<h1>Block Implementation Specification<a class="headerlink" href="#block-implementation-specification" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#history" id="id1">History</a></li>
+<li><a class="reference internal" href="#high-level" id="id2">High Level</a></li>
+<li><a class="reference internal" href="#imported-variables" id="id3">Imported Variables</a><ul>
+<li><a class="reference internal" href="#imported-const-copy-variables" id="id4">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy variables</a></li>
+<li><a class="reference internal" href="#imported-const-copy-of-block-reference" id="id5">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy of <tt class="docutils literal"><span class="pre">Block</span></tt> reference</a><ul>
+<li><a class="reference internal" href="#importing-attribute-nsobject-variables" id="id6">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#imported-block-marked-variables" id="id7">Imported <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><ul>
+<li><a class="reference internal" href="#layout-of-block-marked-variables" id="id8">Layout of <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a></li>
+<li><a class="reference internal" href="#access-to-block-variables-from-within-its-lexical-scope" id="id9">Access to <tt class="docutils literal"><span class="pre">__block</span></tt> variables from within its lexical scope</a></li>
+<li><a class="reference internal" href="#importing-block-variables-into-blocks" id="id10">Importing <tt class="docutils literal"><span class="pre">__block</span></tt> variables into <tt class="docutils literal"><span class="pre">Blocks</span></tt></a></li>
+<li><a class="reference internal" href="#importing-attribute-nsobject-block-variables" id="id11">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables</a></li>
+<li><a class="reference internal" href="#block-escapes" id="id12"><tt class="docutils literal"><span class="pre">__block</span></tt> escapes</a></li>
+<li><a class="reference internal" href="#nesting" id="id13">Nesting</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-extensions-to-blocks" id="id14">Objective C Extensions to <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><ul>
+<li><a class="reference internal" href="#importing-objects" id="id15">Importing Objects</a></li>
+<li><a class="reference internal" href="#blocks-as-objects" id="id16"><tt class="docutils literal"><span class="pre">Blocks</span></tt> as Objects</a></li>
+<li><a class="reference internal" href="#weak-block-support" id="id17"><tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt> Support</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-support" id="id18">C++ Support</a></li>
+<li><a class="reference internal" href="#runtime-helper-functions" id="id19">Runtime Helper Functions</a></li>
+<li><a class="reference internal" href="#copyright" id="id20">Copyright</a></li>
+</ul>
+</div>
+<div class="section" id="history">
+<h2><a class="toc-backref" href="#id1">History</a><a class="headerlink" href="#history" title="Permalink to this headline">Â¶</a></h2>
+<ul class="simple">
+<li>2008/7/14 - created.</li>
+<li>2008/8/21 - revised, C++.</li>
+<li>2008/9/24 - add <tt class="docutils literal"><span class="pre">NULL</span></tt> <tt class="docutils literal"><span class="pre">isa</span></tt> field to <tt class="docutils literal"><span class="pre">__block</span></tt> storage.</li>
+<li>2008/10/1 - revise block layout to use a <tt class="docutils literal"><span class="pre">static</span></tt> descriptor structure.</li>
+<li>2008/10/6 - revise block layout to use an unsigned long int flags.</li>
+<li>2008/10/28 - specify use of <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> for all “Object” types in helper functions.</li>
+<li>2008/10/30 - revise new layout to have invoke function in same place.</li>
+<li>2008/10/30 - add <tt class="docutils literal"><span class="pre">__weak</span></tt> support.</li>
+<li>2010/3/16 - rev for stret return, signature field.</li>
+<li>2010/4/6 - improved wording.</li>
+<li>2013/1/6 - improved wording and converted to rst.</li>
+</ul>
+<p>This document describes the Apple ABI implementation specification of Blocks.</p>
+<p>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.</p>
+<p>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.</p>
+</div>
+<div class="section" id="high-level">
+<h2><a class="toc-backref" href="#id2">High Level</a><a class="headerlink" href="#high-level" title="Permalink to this headline">Â¶</a></h2>
+<p>The ABI of <tt class="docutils literal"><span class="pre">Blocks</span></tt> consist of their layout and the runtime functions required
+by the compiler.  A <tt class="docutils literal"><span class="pre">Block</span></tt> consists of a structure of the following form:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Block_literal_1</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span> <span class="c1">// initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">,</span> <span class="p">...);</span>
+    <span class="k">struct</span> <span class="n">Block_descriptor_1</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>         <span class="c1">// NULL</span>
+        <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>         <span class="c1">// sizeof(struct Block_literal_1)</span>
+        <span class="c1">// optional helper functions</span>
+        <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>     <span class="c1">// IFF (1<<25)</span>
+        <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>             <span class="c1">// IFF (1<<25)</span>
+        <span class="c1">// required ABI.2010.3.16</span>
+        <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">signature</span><span class="p">;</span>                         <span class="c1">// IFF (1<<30)</span>
+    <span class="p">}</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="c1">// imported variables</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The following flags bits are in use thusly for a possible ABI.2010.3.16:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+    <span class="n">BLOCK_HAS_COPY_DISPOSE</span> <span class="o">=</span>  <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">25</span><span class="p">),</span>
+    <span class="n">BLOCK_HAS_CTOR</span> <span class="o">=</span>          <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">26</span><span class="p">),</span> <span class="c1">// helpers have C++ code</span>
+    <span class="n">BLOCK_IS_GLOBAL</span> <span class="o">=</span>         <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">28</span><span class="p">),</span>
+    <span class="n">BLOCK_HAS_STRET</span> <span class="o">=</span>         <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">29</span><span class="p">),</span> <span class="c1">// IFF BLOCK_HAS_SIGNATURE</span>
+    <span class="n">BLOCK_HAS_SIGNATURE</span> <span class="o">=</span>     <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">30</span><span class="p">),</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>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:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">switch</span> <span class="p">(</span><span class="n">flags</span> <span class="o">&</span> <span class="p">(</span><span class="mi">3</span><span class="o"><<</span><span class="mi">29</span><span class="p">))</span> <span class="p">{</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">0</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>:      <span class="mf">10.6</span><span class="p">.</span><span class="n">ABI</span><span class="p">,</span> <span class="n">no</span> <span class="n">signature</span> <span class="n">field</span> <span class="n">available</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>:      <span class="mf">10.6</span><span class="p">.</span><span class="n">ABI</span><span class="p">,</span> <span class="n">no</span> <span class="n">signature</span> <span class="n">field</span> <span class="n">available</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">2</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>: <span class="n">ABI</span><span class="mf">.2010.3.16</span><span class="p">,</span> <span class="n">regular</span> <span class="n">calling</span> <span class="n">convention</span><span class="p">,</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">signature</span> <span class="n">field</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">3</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>: <span class="n">ABI</span><span class="mf">.2010.3.16</span><span class="p">,</span> <span class="n">stret</span> <span class="n">calling</span> <span class="n">convention</span><span class="p">,</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">signature</span> <span class="n">field</span><span class="p">,</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The signature field is not always populated.</p>
+<p>The following discussions are presented as 10.6.ABI otherwise.</p>
+<p><tt class="docutils literal"><span class="pre">Block</span></tt> literals may occur within functions where the structure is created in
+stack local memory.  They may also appear as initialization expressions for
+<tt class="docutils literal"><span class="pre">Block</span></tt> variables of global or <tt class="docutils literal"><span class="pre">static</span></tt> local variables.</p>
+<p>When a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression is evaluated the stack based structure is
+initialized as follows:</p>
+<ol class="arabic simple">
+<li>A <tt class="docutils literal"><span class="pre">static</span></tt> descriptor structure is declared and initialized as follows:</li>
+</ol>
+<blockquote>
+<div><p>a. The <tt class="docutils literal"><span class="pre">invoke</span></tt> function pointer is set to a function that takes the
+<tt class="docutils literal"><span class="pre">Block</span></tt> structure as its first argument and the rest of the arguments (if
+any) to the <tt class="docutils literal"><span class="pre">Block</span></tt> and executes the <tt class="docutils literal"><span class="pre">Block</span></tt> compound statement.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">size</span></tt> field is set to the size of the following <tt class="docutils literal"><span class="pre">Block</span></tt> literal
+structure.</p>
+<p>c. The <tt class="docutils literal"><span class="pre">copy_helper</span></tt> and <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> function pointers are set to
+respective helper functions if they are required by the <tt class="docutils literal"><span class="pre">Block</span></tt> literal.</p>
+</div></blockquote>
+<ol class="arabic" start="2">
+<li><p class="first">A stack (or global) <tt class="docutils literal"><span class="pre">Block</span></tt> literal data structure is created and
+initialized as follows:</p>
+<p>a. The <tt class="docutils literal"><span class="pre">isa</span></tt> field is set to the address of the external
+<tt class="docutils literal"><span class="pre">_NSConcreteStackBlock</span></tt>, which is a block of uninitialized memory supplied
+in <tt class="docutils literal"><span class="pre">libSystem</span></tt>, or <tt class="docutils literal"><span class="pre">_NSConcreteGlobalBlock</span></tt> if this is a static or file
+level <tt class="docutils literal"><span class="pre">Block</span></tt> literal.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">flags</span></tt> field is set to zero unless there are variables imported
+into the <tt class="docutils literal"><span class="pre">Block</span></tt> that need helper functions for program level
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt> and <tt class="docutils literal"><span class="pre">Block_release()</span></tt> operations, in which case the
+(1<<25) flags bit is set.</p>
+</li>
+</ol>
+<p>As an example, the <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>would cause the following to be created on a 32-bit system:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_1</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_1</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_1</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">__block_descriptor_1</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_1</span><span class="p">),</span> <span class="n">__block_invoke_1</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and where the <tt class="docutils literal"><span class="pre">Block</span></tt> literal itself appears:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+     <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+     <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+     <span class="n">__block_invoke_1</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">__block_descriptor_1</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">Block</span></tt> imports other <tt class="docutils literal"><span class="pre">Block</span></tt> references, <tt class="docutils literal"><span class="pre">const</span></tt> copies of other
+variables, and variables marked <tt class="docutils literal"><span class="pre">__block</span></tt>.  In Objective-C, variables may
+additionally be objects.</p>
+<p>When a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression is used as the initial value of a global
+or <tt class="docutils literal"><span class="pre">static</span></tt> local variable, it is initialized as follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="n">__block_literal_1</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteGlobalBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">28</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_1</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_1</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>that is, a different address is provided as the first value and a particular
+(1<<28) bit is set in the <tt class="docutils literal"><span class="pre">flags</span></tt> field, and otherwise it is the same as for
+stack based <tt class="docutils literal"><span class="pre">Block</span></tt> literals.  This is an optimization that can be used for
+any <tt class="docutils literal"><span class="pre">Block</span></tt> literal that imports no <tt class="docutils literal"><span class="pre">const</span></tt> or <tt class="docutils literal"><span class="pre">__block</span></tt> storage
+variables.</p>
+</div>
+<div class="section" id="imported-variables">
+<h2><a class="toc-backref" href="#id3">Imported Variables</a><a class="headerlink" href="#imported-variables" title="Permalink to this headline">Â¶</a></h2>
+<p>Variables of <tt class="docutils literal"><span class="pre">auto</span></tt> storage class are imported as <tt class="docutils literal"><span class="pre">const</span></tt> copies.  Variables
+of <tt class="docutils literal"><span class="pre">__block</span></tt> storage class are imported as a pointer to an enclosing data
+structure.  Global variables are simply referenced and not considered as
+imported.</p>
+<div class="section" id="imported-const-copy-variables">
+<h3><a class="toc-backref" href="#id4">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy variables</a><a class="headerlink" href="#imported-const-copy-variables" title="Permalink to this headline">Â¶</a></h3>
+<p>Automatic storage variables not marked with <tt class="docutils literal"><span class="pre">__block</span></tt> are imported as
+<tt class="docutils literal"><span class="pre">const</span></tt> copies.</p>
+<p>The simplest example is that of importing a variable of type <tt class="docutils literal"><span class="pre">int</span></tt>:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">vv</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"x is %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="n">x</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+<span class="n">vv</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>which would be compiled to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_2</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">const</span> <span class="kt">int</span> <span class="n">x</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_2</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">printf</span><span class="p">(</span><span class="s">"x is %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">_block</span><span class="o">-></span><span class="n">x</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_2</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">__block_descriptor_2</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span><span class="p">)</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="n">__block_literal_2</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_2</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_2</span><span class="p">,</span>
+      <span class="n">x</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+<p>In summary, scalars, structures, unions, and function pointers are generally
+imported as <tt class="docutils literal"><span class="pre">const</span></tt> copies with no need for helper functions.</p>
+</div>
+<div class="section" id="imported-const-copy-of-block-reference">
+<h3><a class="toc-backref" href="#id5">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy of <tt class="docutils literal"><span class="pre">Block</span></tt> reference</a><a class="headerlink" href="#imported-const-copy-of-block-reference" title="Permalink to this headline">Â¶</a></h3>
+<p>The first case where copy and dispose helper functions are required is for the
+case of when a <tt class="docutils literal"><span class="pre">Block</span></tt> itself is imported.  In this case both a
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt> function and a <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> function are needed.  The
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt> 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 <tt class="docutils literal"><span class="pre">Block</span></tt>. The
+runtime functions are all described in <a class="reference internal" href="#runtimehelperfunctions"><em>Runtime Helper Functions</em></a>.</p>
+<p>A quick example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">existingBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">vv</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">existingBlock</span><span class="p">();</span> <span class="p">}</span>
+<span class="n">vv</span><span class="p">();</span>
+
+<span class="k">struct</span> <span class="n">__block_literal_3</span> <span class="p">{</span>
+   <span class="p">...;</span> <span class="c1">// existing block</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_literal_3</span> <span class="o">*</span><span class="k">const</span> <span class="n">existingBlock</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">__block</span><span class="o">-></span><span class="n">existingBlock</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="n">__block</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">// was _Block_destroy</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_4</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_4</span> <span class="o">=</span> <span class="p">{</span>
+    <span class="mi">0</span><span class="p">,</span>
+    <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span><span class="p">),</span>
+    <span class="n">__block_copy_4</span><span class="p">,</span>
+    <span class="n">__block_dispose_4</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>and where said <tt class="docutils literal"><span class="pre">Block</span></tt> is used:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span>
+      <span class="n">__block_invoke_4</span><span class="p">,</span>
+      <span class="o">&</span> <span class="n">__block_descriptor_4</span>
+      <span class="n">existingBlock</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<div class="section" id="importing-attribute-nsobject-variables">
+<h4><a class="toc-backref" href="#id6">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables</a><a class="headerlink" href="#importing-attribute-nsobject-variables" title="Permalink to this headline">Â¶</a></h4>
+<p>GCC introduces <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> 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. <tt class="docutils literal"><span class="pre">CFStringRef</span></tt>, <tt class="docutils literal"><span class="pre">CFArrayRef</span></tt>,
+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
+<tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> runtime helper function and in the dispose helper the
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> runtime helper function should be called.</p>
+<p>For example, <tt class="docutils literal"><span class="pre">Block</span></tt> foo in the following:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Opaque</span> <span class="o">*</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">NSObject</span><span class="p">))</span> <span class="n">objectPointer</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="p">...</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">foo</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span>  <span class="n">CFPrint</span><span class="p">(</span><span class="n">objectPointer</span><span class="p">);</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>would have the following helper functions generated:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">__block_copy_foo</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">objectPointer</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span> <span class="n">objectPointer</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_foo</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">objectPointer</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="imported-block-marked-variables">
+<h3><a class="toc-backref" href="#id7">Imported <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><a class="headerlink" href="#imported-block-marked-variables" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="layout-of-block-marked-variables">
+<h4><a class="toc-backref" href="#id8">Layout of <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><a class="headerlink" href="#layout-of-block-marked-variables" title="Permalink to this headline">Â¶</a></h4>
+<p>The compiler must embed variables that are marked <tt class="docutils literal"><span class="pre">__block</span></tt> in a specialized
+structure of the form:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">Block_byref</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="n">typeof</span><span class="p">(</span><span class="n">marked_variable</span><span class="p">)</span> <span class="n">marked_variable</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Variables of certain types require helper functions for when <tt class="docutils literal"><span class="pre">Block_copy()</span></tt>
+and <tt class="docutils literal"><span class="pre">Block_release()</span></tt> are performed upon a referencing <tt class="docutils literal"><span class="pre">Block</span></tt>.  At the “C”
+level only variables that are of type <tt class="docutils literal"><span class="pre">Block</span></tt> or ones that have
+<tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> 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:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="c1">// helper functions called via Block_copy() and Block_release()</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="kt">void</span>  <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
+    <span class="n">typeof</span><span class="p">(</span><span class="n">marked_variable</span><span class="p">)</span> <span class="n">marked_variable</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The structure is initialized such that:</p>
+<blockquote>
+<div><p>a. The <tt class="docutils literal"><span class="pre">forwarding</span></tt> pointer is set to the beginning of its enclosing
+structure.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">size</span></tt> field is initialized to the total size of the enclosing
+structure.</p>
+<p>c. The <tt class="docutils literal"><span class="pre">flags</span></tt> field is set to either 0 if no helper functions are needed
+or (1<<25) if they are.</p>
+<ol class="loweralpha simple" start="4">
+<li>The helper functions are initialized (if present).</li>
+<li>The variable itself is set to its initial value.</li>
+<li>The <tt class="docutils literal"><span class="pre">isa</span></tt> field is set to <tt class="docutils literal"><span class="pre">NULL</span></tt>.</li>
+</ol>
+</div></blockquote>
+</div>
+<div class="section" id="access-to-block-variables-from-within-its-lexical-scope">
+<h4><a class="toc-backref" href="#id9">Access to <tt class="docutils literal"><span class="pre">__block</span></tt> variables from within its lexical scope</a><a class="headerlink" href="#access-to-block-variables-from-within-its-lexical-scope" title="Permalink to this headline">Â¶</a></h4>
+<p>In order to “move” the variable to the heap upon a <tt class="docutils literal"><span class="pre">copy_helper</span></tt> operation the
+compiler must rewrite access to such a variable to be indirect through the
+structures <tt class="docutils literal"><span class="pre">forwarding</span></tt> pointer.  For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__block</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="n">i</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>would be rewritten to be:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+  <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+  <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+  <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+  <span class="kt">int</span> <span class="n">captured_i</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">i</span> <span class="o">=</span> <span class="p">{</span> <span class="nb">NULL</span><span class="p">,</span> <span class="o">&</span><span class="n">i</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_i</span><span class="p">),</span> <span class="mi">10</span> <span class="p">};</span>
+
+<span class="n">i</span><span class="p">.</span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_i</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>In the case of a <tt class="docutils literal"><span class="pre">Block</span></tt> reference variable being marked <tt class="docutils literal"><span class="pre">__block</span></tt> the
+helper code generated must use the <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> routines supplied by the runtime to make the
+copies. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__block</span> <span class="kt">void</span> <span class="p">(</span><span class="n">voidBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="n">blockA</span><span class="p">;</span>
+<span class="n">voidBlock</span> <span class="o">=</span> <span class="n">blockB</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>would translate into:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">captured_voidBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_keep_helper</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0);</span>
+    <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_dispose_helper</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">param</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_destroy(param->captured_voidBlock, 0);</span>
+    <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">param</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">)}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="n">voidBlock</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">voidBlock</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">),</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="p">),</span>
+    <span class="p">.</span><span class="n">byref_keep</span><span class="o">=</span><span class="n">_block_byref_keep_helper</span><span class="p">,</span> <span class="p">.</span><span class="n">byref_dispose</span><span class="o">=</span><span class="n">_block_byref_dispose_helper</span><span class="p">,</span>
+    <span class="p">.</span><span class="n">captured_voidBlock</span><span class="o">=</span><span class="n">blockA</span> <span class="p">)};</span>
+
+<span class="n">voidBlock</span><span class="p">.</span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_voidBlock</span> <span class="o">=</span> <span class="n">blockB</span><span class="p">;</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="importing-block-variables-into-blocks">
+<h4><a class="toc-backref" href="#id10">Importing <tt class="docutils literal"><span class="pre">__block</span></tt> variables into <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><a class="headerlink" href="#importing-block-variables-into-blocks" title="Permalink to this headline">Â¶</a></h4>
+<p>A <tt class="docutils literal"><span class="pre">Block</span></tt> that uses a <tt class="docutils literal"><span class="pre">__block</span></tt> variable in its compound statement body must
+import the variable and emit <tt class="docutils literal"><span class="pre">copy_helper</span></tt> and <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> helper
+functions that, in turn, call back into the runtime to actually copy or release
+the <tt class="docutils literal"><span class="pre">byref</span></tt> data block using the functions <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>.</p>
+<p>For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__block</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
+<span class="n">functioncall</span><span class="p">(</span><span class="o">^</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="p">});</span>
+</pre></div>
+</div>
+<p>would translate to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>  <span class="c1">// set to NULL</span>
+    <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="p">);</span>
+    <span class="kt">int</span> <span class="n">captured_i</span><span class="p">;</span>
+<span class="p">};</span>
+
+
+<span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">i_holder</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">_block</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_assign_copy(&dst->captured_i, src->captured_i);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_release(src->captured_i);</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_5</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span><span class="p">)</span> <span class="n">__block_copy_5</span><span class="p">,</span> <span class="n">__block_dispose_5</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="n">i</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">i</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_i</span><span class="p">)</span> <span class="p">)};</span>
+<span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_5</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_5</span><span class="p">,</span>
+      <span class="mi">2</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="importing-attribute-nsobject-block-variables">
+<h4><a class="toc-backref" href="#id11">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables</a><a class="headerlink" href="#importing-attribute-nsobject-block-variables" title="Permalink to this headline">Â¶</a></h4>
+<p>A <tt class="docutils literal"><span class="pre">__block</span></tt> variable that is also marked <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> should
+have <tt class="docutils literal"><span class="pre">byref_keep</span></tt> and <tt class="docutils literal"><span class="pre">byref_dispose</span></tt> helper functions that use
+<tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and <tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>.</p>
+</div>
+<div class="section" id="block-escapes">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">__block</span></tt> escapes</a><a class="headerlink" href="#block-escapes" title="Permalink to this headline">Â¶</a></h4>
+<p>Because <tt class="docutils literal"><span class="pre">Blocks</span></tt> referencing <tt class="docutils literal"><span class="pre">__block</span></tt> variables may have <tt class="docutils literal"><span class="pre">Block_copy()</span></tt>
+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
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables at all escapes or terminations of their scope.  The call
+should be:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="o">&</span><span class="n">_block_byref_foo</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="nesting">
+<h4><a class="toc-backref" href="#id13">Nesting</a><a class="headerlink" href="#nesting" title="Permalink to this headline">Â¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">Blocks</span></tt> may contain <tt class="docutils literal"><span class="pre">Block</span></tt> literal expressions.  Any variables used within
+inner blocks are imported into all enclosing <tt class="docutils literal"><span class="pre">Block</span></tt> scopes even if the
+variables are not used. This includes <tt class="docutils literal"><span class="pre">const</span></tt> imports as well as <tt class="docutils literal"><span class="pre">__block</span></tt>
+variables.</p>
+</div>
+</div>
+</div>
+<div class="section" id="objective-c-extensions-to-blocks">
+<h2><a class="toc-backref" href="#id14">Objective C Extensions to <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><a class="headerlink" href="#objective-c-extensions-to-blocks" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="importing-objects">
+<h3><a class="toc-backref" href="#id15">Importing Objects</a><a class="headerlink" href="#importing-objects" title="Permalink to this headline">Â¶</a></h3>
+<p>Objects should be treated as <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables; all
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt>, <tt class="docutils literal"><span class="pre">dispose_helper</span></tt>, <tt class="docutils literal"><span class="pre">byref_keep</span></tt>, and <tt class="docutils literal"><span class="pre">byref_dispose</span></tt>
+helper functions should use <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>.  There should be no code generated that uses
+<tt class="docutils literal"><span class="pre">*-retain</span></tt> or <tt class="docutils literal"><span class="pre">*-release</span></tt> methods.</p>
+</div>
+<div class="section" id="blocks-as-objects">
+<h3><a class="toc-backref" href="#id16"><tt class="docutils literal"><span class="pre">Blocks</span></tt> as Objects</a><a class="headerlink" href="#blocks-as-objects" title="Permalink to this headline">Â¶</a></h3>
+<p>The compiler will treat <tt class="docutils literal"><span class="pre">Blocks</span></tt> 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.</p>
+</div>
+<div class="section" id="weak-block-support">
+<h3><a class="toc-backref" href="#id17"><tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt> Support</a><a class="headerlink" href="#weak-block-support" title="Permalink to this headline">Â¶</a></h3>
+<p>Objective-C (and Objective-C++) support the <tt class="docutils literal"><span class="pre">__weak</span></tt> attribute on <tt class="docutils literal"><span class="pre">__block</span></tt>
+variables.  Under normal circumstances the compiler uses the Objective-C runtime
+helper support functions <tt class="docutils literal"><span class="pre">objc_assign_weak</span></tt> and <tt class="docutils literal"><span class="pre">objc_read_weak</span></tt>.  Both
+should continue to be used for all reads and writes of <tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt>
+variables:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">objc_read_weak</span><span class="p">(</span><span class="o">&</span><span class="n">block</span><span class="o">-></span><span class="n">byref_i</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">i</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">__weak</span></tt> variable is stored in a <tt class="docutils literal"><span class="pre">_block_byref_foo</span></tt> structure and the
+<tt class="docutils literal"><span class="pre">Block</span></tt> has copy and dispose helpers for this structure that call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span> <span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In turn, the <tt class="docutils literal"><span class="pre">block_byref</span></tt> copy support helpers distinguish between whether
+the <tt class="docutils literal"><span class="pre">__block</span></tt> variable is a <tt class="docutils literal"><span class="pre">Block</span></tt> or not and should either call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for something declared as an object or:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for something declared as a <tt class="docutils literal"><span class="pre">Block</span></tt>.</p>
+<p>A full example follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__block</span> <span class="n">__weak</span> <span class="n">id</span> <span class="n">obj</span> <span class="o">=</span> <span class="o"><</span><span class="n">initialization</span> <span class="n">expression</span><span class="o">></span><span class="p">;</span>
+<span class="n">functioncall</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">obj</span> <span class="n">somemessage</span><span class="p">];</span> <span class="p">});</span>
+</pre></div>
+</div>
+<p>would translate to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>  <span class="c1">// uninitialized</span>
+    <span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="p">);</span>
+    <span class="n">id</span> <span class="n">captured_obj</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_keep</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0);</span>
+    <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_dispose</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">param</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_destroy(param->captured_obj, 0);</span>
+    <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">param</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>for the block <tt class="docutils literal"><span class="pre">byref</span></tt> part and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="o">*</span><span class="n">byref_obj</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="p">[</span><span class="n">objc_read_weak</span><span class="p">(</span><span class="o">&</span><span class="n">_block</span><span class="o">-></span><span class="n">byref_obj</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">)</span> <span class="n">somemessage</span><span class="p">];</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_release(src->byref_obj);</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_5</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span><span class="p">),</span> <span class="n">__block_copy_5</span><span class="p">,</span> <span class="n">__block_dispose_5</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and within the compound statement:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">truct</span> <span class="n">_block_byref_obj</span> <span class="n">obj</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">obj</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">),</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_obj</span><span class="p">),</span>
+                 <span class="p">.</span><span class="n">byref_keep</span><span class="o">=</span><span class="n">_block_byref_obj_keep</span><span class="p">,</span> <span class="p">.</span><span class="n">byref_dispose</span><span class="o">=</span><span class="n">_block_byref_obj_dispose</span><span class="p">,</span>
+                 <span class="p">.</span><span class="n">captured_obj</span> <span class="o">=</span> <span class="o"><</span><span class="n">initialization</span> <span class="n">expression</span><span class="o">></span> <span class="p">)};</span>
+
+<span class="n">truct</span> <span class="n">__block_literal_5</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+     <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+     <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+     <span class="n">__block_invoke_5</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">__block_descriptor_5</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">obj</span><span class="p">,</span>        <span class="c1">// a reference to the on-stack structure containing "captured_obj"</span>
+<span class="p">};</span>
+
+
+<span class="n">functioncall</span><span class="p">(</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="p">));</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="c-support">
+<h2><a class="toc-backref" href="#id18">C++ Support</a><a class="headerlink" href="#c-support" title="Permalink to this headline">Â¶</a></h2>
+<p>Within a block stack based C++ objects are copied into <tt class="docutils literal"><span class="pre">const</span></tt> 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
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt> 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 <tt class="docutils literal"><span class="pre">const</span></tt> constructed copies, and similarly
+should call the destructor in the destroy routine.</p>
+<p>As an example, suppose a C++ class <tt class="docutils literal"><span class="pre">FOO</span></tt> existed with a copy constructor.
+Within a code block a stack version of a <tt class="docutils literal"><span class="pre">FOO</span></tt> object is declared and used
+within a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">{</span>
+    <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">block</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"%d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">foo</span><span class="p">.</span><span class="n">value</span><span class="p">());</span> <span class="p">};</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The compiler would synthesize:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_10</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">const</span> <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">printf</span><span class="p">(</span><span class="s">"%d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">_block</span><span class="o">-></span><span class="n">foo</span><span class="p">.</span><span class="n">value</span><span class="p">());</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_literal_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">foo</span><span class="p">,</span> <span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_10</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_10</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span><span class="p">),</span> <span class="n">__block_copy_10</span><span class="p">,</span> <span class="n">__block_dispose_10</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and the code would be:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">{</span>
+  <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+  <span class="n">comp_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// default constructor</span>
+  <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+    <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+    <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">26</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+    <span class="n">__block_invoke_10</span><span class="p">,</span>
+    <span class="o">&</span><span class="n">__block_descriptor_10</span><span class="p">,</span>
+   <span class="p">};</span>
+   <span class="n">comp_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">foo</span><span class="p">,</span> <span class="o">&</span><span class="n">foo</span><span class="p">);</span>  <span class="c1">// const copy into stack version</span>
+   <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">&</span><span class="n">block</span> <span class="o">=</span> <span class="o">&</span><span class="n">_block_literal</span><span class="p">;</span>  <span class="c1">// assign literal to block variable</span>
+   <span class="n">block</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="n">block</span><span class="p">);</span>    <span class="c1">// invoke block</span>
+   <span class="n">comp_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span> <span class="c1">// destroy stack version of const block copy</span>
+   <span class="n">comp_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// destroy original version</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>C++ objects stored in <tt class="docutils literal"><span class="pre">__block</span></tt> storage start out on the stack in a
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> data structure as do other variables.  Such objects (if not
+<tt class="docutils literal"><span class="pre">const</span></tt> objects) must support a regular copy constructor.  The <tt class="docutils literal"><span class="pre">block_byref</span></tt>
+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 <tt class="docutils literal"><span class="pre">block_byref</span></tt> 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
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> heap data structure.  For example,</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__block</span> <span class="n">FOO</span> <span class="n">blockStorageFoo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>requires the normal constructor for the embedded <tt class="docutils literal"><span class="pre">blockStorageFoo</span></tt> object:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span> <span class="n">_block_byref_blockStorageFoo</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and at scope termination the destructor:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span> <span class="n">_block_byref_blockStorageFoo</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Note that the forwarding indirection is <em>NOT</em> used.</p>
+<p>The compiler would need to generate (if used from a block literal) the following
+copy/dispose helpers:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">_block_byref_obj_keep</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">,</span> <span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_dispose</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>for the appropriately named constructor and destructor for the class/struct
+<tt class="docutils literal"><span class="pre">FOO</span></tt>.</p>
+<p>To support member variable and function access the compiler will synthesize a
+<tt class="docutils literal"><span class="pre">const</span></tt> pointer to a block version of the <tt class="docutils literal"><span class="pre">this</span></tt> pointer.</p>
+</div>
+<div class="section" id="runtime-helper-functions">
+<span id="runtimehelperfunctions"></span><h2><a class="toc-backref" href="#id19">Runtime Helper Functions</a><a class="headerlink" href="#runtime-helper-functions" title="Permalink to this headline">Â¶</a></h2>
+<p>The runtime helper functions are described in
+<tt class="docutils literal"><span class="pre">/usr/local/include/Block_private.h</span></tt>.  To summarize their use, a <tt class="docutils literal"><span class="pre">Block</span></tt>
+requires copy/dispose helpers if it imports any block variables, <tt class="docutils literal"><span class="pre">__block</span></tt>
+storage variables, <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables, or C++ <tt class="docutils literal"><span class="pre">const</span></tt>
+copied objects with constructor/destructors.  The (1<<26) bit is set and
+functions are generated.</p>
+<p>The block copy helper function should, for each of the variables of the type
+mentioned above, call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">BLOCK_FIELD_</span><span class="o"><</span><span class="n">appropo</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>in the copy helper and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">BLOCK_FIELD_</span><span class="o"><</span><span class="n">appropo</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>in the dispose helper where <tt class="docutils literal"><span class="pre"><appropo></span></tt> is:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+    <span class="n">BLOCK_FIELD_IS_OBJECT</span>   <span class="o">=</span>  <span class="mi">3</span><span class="p">,</span>  <span class="c1">// id, NSObject, __attribute__((NSObject)), block, ...</span>
+    <span class="n">BLOCK_FIELD_IS_BLOCK</span>    <span class="o">=</span>  <span class="mi">7</span><span class="p">,</span>  <span class="c1">// a block variable</span>
+    <span class="n">BLOCK_FIELD_IS_BYREF</span>    <span class="o">=</span>  <span class="mi">8</span><span class="p">,</span>  <span class="c1">// the on stack structure holding the __block variable</span>
+
+    <span class="n">BLOCK_FIELD_IS_WEAK</span>     <span class="o">=</span> <span class="mi">16</span><span class="p">,</span>  <span class="c1">// declared __weak</span>
+
+    <span class="n">BLOCK_BYREF_CALLER</span>      <span class="o">=</span> <span class="mi">128</span><span class="p">,</span> <span class="c1">// called from byref copy/dispose helpers</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>and of course the constructors/destructors for <tt class="docutils literal"><span class="pre">const</span></tt> copied C++ objects.</p>
+<p>The <tt class="docutils literal"><span class="pre">block_byref</span></tt> data structure similarly requires copy/dispose helpers for
+block variables, <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables, or C++ <tt class="docutils literal"><span class="pre">const</span></tt>
+copied objects with constructor/destructors, and again the (1<<26) bit is set
+and functions are generated in the same manner.</p>
+<p>Under ObjC we allow <tt class="docutils literal"><span class="pre">__weak</span></tt> as an attribute on <tt class="docutils literal"><span class="pre">__block</span></tt> variables, and
+this causes the addition of <tt class="docutils literal"><span class="pre">BLOCK_FIELD_IS_WEAK</span></tt> orred onto the
+<tt class="docutils literal"><span class="pre">BLOCK_FIELD_IS_BYREF</span></tt> flag when copying the <tt class="docutils literal"><span class="pre">block_byref</span></tt> structure in the
+<tt class="docutils literal"><span class="pre">Block</span></tt> copy helper, and onto the <tt class="docutils literal"><span class="pre">BLOCK_FIELD_<appropo></span></tt> field within the
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> copy/dispose helper calls.</p>
+<p>The prototypes, and summary, of the helper functions are:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Certain field types require runtime assistance when being copied to the</span>
+<span class="cm">   heap.  The following function is used to copy fields of types: blocks,</span>
+<span class="cm">   pointers to byref structures, and objects (including</span>
+<span class="cm">   __attribute__((NSObject)) pointers.  BLOCK_FIELD_IS_WEAK is orthogonal to</span>
+<span class="cm">   the other choices which are mutually exclusive.  Only in a Block copy</span>
+<span class="cm">   helper will one see BLOCK_FIELD_IS_BYREF.</span>
+<span class="cm">*/</span>
+<span class="kt">void</span> <span class="nf">_Block_object_assign</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">destAddr</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">);</span>
+
+<span class="cm">/* Similarly a compiler generated dispose helper needs to call back for each</span>
+<span class="cm">   field of the byref data structure.  (Currently the implementation only</span>
+<span class="cm">   packs one field into the byref structure but in principle there could be</span>
+<span class="cm">   more).  The same flags used in the copy helper should be used for each</span>
+<span class="cm">   call generated to this function:</span>
+<span class="cm">*/</span>
+<span class="kt">void</span> <span class="nf">_Block_object_dispose</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="copyright">
+<h2><a class="toc-backref" href="#id20">Copyright</a><a class="headerlink" href="#copyright" title="Permalink to this headline">Â¶</a></h2>
+<p>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:</p>
+<p>The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.</p>
+<p>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.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/Block-ABI-Apple.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/Block-ABI-Apple.txt?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/Block-ABI-Apple.txt (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/Block-ABI-Apple.txt Mon Jun 16 08:19:07 2014
@@ -0,0 +1 @@
+*NOTE* This document has moved to http://clang.llvm.org/docs/Block-ABI-Apple.html.

Added: www-releases/trunk/3.4.2/tools/clang/docs/html/BlockLanguageSpec.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/BlockLanguageSpec.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/BlockLanguageSpec.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/BlockLanguageSpec.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,376 @@
+
+
+<!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>Language Specification for Blocks — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="next" title="Block Implementation Specification" href="Block-ABI-Apple.html" />
+    <link rel="prev" title="Objective-C Literals" href="ObjectiveCLiterals.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Language Specification for Blocks</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ObjectiveCLiterals.html">Objective-C Literals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Block-ABI-Apple.html">Block Implementation Specification</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="language-specification-for-blocks">
+<h1>Language Specification for Blocks<a class="headerlink" href="#language-specification-for-blocks" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#revisions" id="id1">Revisions</a></li>
+<li><a class="reference internal" href="#overview" id="id2">Overview</a></li>
+<li><a class="reference internal" href="#the-block-type" id="id3">The Block Type</a></li>
+<li><a class="reference internal" href="#block-variable-declarations" id="id4">Block Variable Declarations</a></li>
+<li><a class="reference internal" href="#block-literal-expressions" id="id5">Block Literal Expressions</a></li>
+<li><a class="reference internal" href="#the-invoke-operator" id="id6">The Invoke Operator</a></li>
+<li><a class="reference internal" href="#the-copy-and-release-operations" id="id7">The Copy and Release Operations</a></li>
+<li><a class="reference internal" href="#the-block-storage-qualifier" id="id8">The <tt class="docutils literal"><span class="pre">__block</span></tt> Storage Qualifier</a></li>
+<li><a class="reference internal" href="#control-flow" id="id9">Control Flow</a></li>
+<li><a class="reference internal" href="#objective-c-extensions" id="id10">Objective-C Extensions</a></li>
+<li><a class="reference internal" href="#c-extensions" id="id11">C++ Extensions</a></li>
+</ul>
+</div>
+<div class="section" id="revisions">
+<h2><a class="toc-backref" href="#id1">Revisions</a><a class="headerlink" href="#revisions" title="Permalink to this headline">Â¶</a></h2>
+<ul class="simple">
+<li>2008/2/25 — created</li>
+<li>2008/7/28 — revised, <tt class="docutils literal"><span class="pre">__block</span></tt> syntax</li>
+<li>2008/8/13 — revised, Block globals</li>
+<li>2008/8/21 — revised, C++ elaboration</li>
+<li>2008/11/1 — revised, <tt class="docutils literal"><span class="pre">__weak</span></tt> support</li>
+<li>2009/1/12 — revised, explicit return types</li>
+<li>2009/2/10 — revised, <tt class="docutils literal"><span class="pre">__block</span></tt> objects need retain</li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id2">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">Â¶</a></h2>
+<p>A new derived type is introduced to C and, by extension, Objective-C,
+C++, and Objective-C++</p>
+</div>
+<div class="section" id="the-block-type">
+<h2><a class="toc-backref" href="#id3">The Block Type</a><a class="headerlink" href="#the-block-type" title="Permalink to this headline">Â¶</a></h2>
+<p>Like function types, the <span class="block-term">Block type</span> 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.</p>
+<p>The abstract declarator,</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="p">)(</span><span class="kt">char</span><span class="p">,</span> <span class="kt">float</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>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.</p>
+</div>
+<div class="section" id="block-variable-declarations">
+<h2><a class="toc-backref" href="#id4">Block Variable Declarations</a><a class="headerlink" href="#block-variable-declarations" title="Permalink to this headline">Â¶</a></h2>
+<p>A <span class="block-term">variable with Block type</span> is declared using function
+pointer style notation substituting <tt class="docutils literal"><span class="pre">^</span></tt> for <tt class="docutils literal"><span class="pre">*</span></tt>. The following are
+valid Block variable declarations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">blockReturningVoidWithVoidArgument</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="n">blockReturningIntWithIntAndCharArguments</span><span class="p">)(</span><span class="kt">int</span><span class="p">,</span> <span class="kt">char</span><span class="p">);</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">arrayOfTenBlocksReturningVoidWithIntArgument</span><span class="p">[</span><span class="mi">10</span><span class="p">])(</span><span class="kt">int</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Variadic <tt class="docutils literal"><span class="pre">...</span></tt> 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.</p>
+<p>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 <tt class="docutils literal"><span class="pre">*</span></tt>, and thus a Block’s size may not be
+computed at compile time. [sizeof.c]</p>
+</div>
+<div class="section" id="block-literal-expressions">
+<h2><a class="toc-backref" href="#id5">Block Literal Expressions</a><a class="headerlink" href="#block-literal-expressions" title="Permalink to this headline">Â¶</a></h2>
+<p>A <span class="block-term">Block literal expression</span> produces a reference to a
+Block. It is introduced by the use of the <tt class="docutils literal"><span class="pre">^</span></tt> token as a unary
+operator.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">Block_literal_expression</span> <span class="o">::=</span>   <span class="o">^</span> <span class="n">block_decl</span> <span class="n">compound_statement_body</span>
+<span class="n">block_decl</span> <span class="o">::=</span>
+<span class="n">block_decl</span> <span class="o">::=</span> <span class="n">parameter_list</span>
+<span class="n">block_decl</span> <span class="o">::=</span> <span class="n">type_expression</span>
+</pre></div>
+</div>
+<p>where type expression is extended to allow <tt class="docutils literal"><span class="pre">^</span></tt> as a Block reference
+(pointer) where <tt class="docutils literal"><span class="pre">*</span></tt> is allowed as a function reference (pointer).</p>
+<p>The following Block literal:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="kt">void</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>produces a reference to a Block with no arguments with no return value.</p>
+<p>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.</p>
+<p>If the return type is omitted and the argument list is <tt class="docutils literal"><span class="pre">(</span> <span class="pre">void</span> <span class="pre">)</span></tt>,
+the <tt class="docutils literal"><span class="pre">(</span> <span class="pre">void</span> <span class="pre">)</span></tt> argument list may also be omitted.</p>
+<p>So:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">(</span> <span class="kt">void</span> <span class="p">)</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>are exactly equivalent constructs for the same expression.</p>
+<p>The type_expression extends C expression parsing to accommodate Block
+reference declarations as it accommodates function pointer
+declarations.</p>
+<p>Given:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="n">pointerToFunctionThatReturnsIntWithCharArg</span><span class="p">)(</span><span class="kt">char</span><span class="p">);</span>
+<span class="n">pointerToFunctionThatReturnsIntWithCharArg</span> <span class="n">functionPointer</span><span class="p">;</span>
+<span class="o">^</span> <span class="n">pointerToFunctionThatReturnsIntWithCharArg</span> <span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="kt">int</span> <span class="p">((</span><span class="o">*</span><span class="p">)(</span><span class="kt">float</span> <span class="n">x</span><span class="p">))(</span><span class="kt">char</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>are equivalent expressions, as is:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span><span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>[returnfunctionptr.c]</p>
+<p>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]</p>
+<p>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.</p>
+<p>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:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">foo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This matters when capturing the variable has side-effects, as it can
+in Objective-C or C++.</p>
+<p>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]</p>
+<p>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.</p>
+<p>A Block literal expression may be used as the initialization value for
+Block variables at global or local static scope.</p>
+</div>
+<div class="section" id="the-invoke-operator">
+<h2><a class="toc-backref" href="#id6">The Invoke Operator</a><a class="headerlink" href="#the-invoke-operator" title="Permalink to this headline">Â¶</a></h2>
+<p>Blocks are <span class="block-term">invoked</span> 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:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="n">x</span><span class="p">)(</span><span class="kt">char</span><span class="p">);</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">z</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="p">(</span><span class="o">*</span><span class="n">y</span><span class="p">))(</span><span class="kt">char</span><span class="p">)</span> <span class="o">=</span> <span class="o">&</span><span class="n">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>the following are all legal Block invocations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">x</span><span class="p">(</span><span class="sc">'a'</span><span class="p">);</span>
+<span class="p">(</span><span class="o">*</span><span class="n">y</span><span class="p">)(</span><span class="sc">'a'</span><span class="p">);</span>
+<span class="p">(</span><span class="nb">true</span> <span class="o">?</span> <span class="n">x</span> <span class="o">:</span> <span class="o">*</span><span class="n">y</span><span class="p">)(</span><span class="sc">'a'</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-copy-and-release-operations">
+<h2><a class="toc-backref" href="#id7">The Copy and Release Operations</a><a class="headerlink" href="#the-copy-and-release-operations" title="Permalink to this headline">Â¶</a></h2>
+<p>The compiler and runtime provide <span class="block-term">copy</span> and
+<span class="block-term">release</span> operations for Block references that create and,
+in matched use, release allocated storage for referenced Blocks.</p>
+<p>The copy operation <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> is styled as a function that takes
+an arbitrary Block reference and returns a Block reference of the same
+type. The release operation, <tt class="docutils literal"><span class="pre">Block_release()</span></tt>, 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.</p>
+</div>
+<div class="section" id="the-block-storage-qualifier">
+<h2><a class="toc-backref" href="#id8">The <tt class="docutils literal"><span class="pre">__block</span></tt> Storage Qualifier</a><a class="headerlink" href="#the-block-storage-qualifier" title="Permalink to this headline">Â¶</a></h2>
+<p>In addition to the new Block type we also introduce a new storage
+qualifier, <span class="block-term">__block</span>, for local variables. [testme: a
+__block declaration within a block literal] The <tt class="docutils literal"><span class="pre">__block</span></tt> storage
+qualifier is mutually exclusive to the existing local storage
+qualifiers auto, register, and static. [testme] Variables qualified by
+<tt class="docutils literal"><span class="pre">__block</span></tt> 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.</p>
+<p>In the case where a <tt class="docutils literal"><span class="pre">__block</span></tt> variable is a Block one must assume
+that the <tt class="docutils literal"><span class="pre">__block</span></tt> 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 <tt class="docutils literal"><span class="pre">Block_copy</span></tt> operation).  Despite this
+there is no provision to do a <tt class="docutils literal"><span class="pre">Block_copy</span></tt> or a <tt class="docutils literal"><span class="pre">Block_release</span></tt> 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.</p>
+</div>
+<div class="section" id="control-flow">
+<h2><a class="toc-backref" href="#id9">Control Flow</a><a class="headerlink" href="#control-flow" title="Permalink to this headline">Â¶</a></h2>
+<p>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 <em>normally</em> in that when
+thrown they pop stack frames until a catch clause is found.</p>
+</div>
+<div class="section" id="objective-c-extensions">
+<h2><a class="toc-backref" href="#id10">Objective-C Extensions</a><a class="headerlink" href="#objective-c-extensions" title="Permalink to this headline">Â¶</a></h2>
+<p>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.</p>
+<p>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 <tt class="docutils literal"><span class="pre">__weak</span></tt> locations
+if garbage collection is enabled.</p>
+<p>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.</p>
+<p>The <span class="block-term">Block_copy</span> 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 <tt class="docutils literal"><span class="pre">__block</span></tt> storage type are assumed to hold
+normal pointers with no provision for retain and release messages.</p>
+<p>Foundation defines (and supplies) <tt class="docutils literal"><span class="pre">-copy</span></tt> and <tt class="docutils literal"><span class="pre">-release</span></tt> methods for
+Blocks.</p>
+<p>In the Objective-C and Objective-C++ languages, we allow the
+<tt class="docutils literal"><span class="pre">__weak</span></tt> specifier for <tt class="docutils literal"><span class="pre">__block</span></tt> 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.</p>
+<p>In garbage collected environments, the <tt class="docutils literal"><span class="pre">__weak</span></tt> variable is set to
+nil when the object it references is collected, as long as the
+<tt class="docutils literal"><span class="pre">__block</span></tt> variable resides in the heap (either by default or via
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt>).  The initial Apple implementation does in fact
+start <tt class="docutils literal"><span class="pre">__block</span></tt> variables on the stack and migrate them to the heap
+only as a result of a <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> operation.</p>
+<p>It is a runtime error to attempt to assign a reference to a
+stack-based Block into any storage marked <tt class="docutils literal"><span class="pre">__weak</span></tt>, including
+<tt class="docutils literal"><span class="pre">__weak</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables.</p>
+</div>
+<div class="section" id="c-extensions">
+<h2><a class="toc-backref" href="#id11">C++ Extensions</a><a class="headerlink" href="#c-extensions" title="Permalink to this headline">Â¶</a></h2>
+<p>Block literal expressions within functions are extended to allow const
+use of C++ objects, pointers, or references held in automatic storage.</p>
+<p>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.</p>
+<p>For example, given a class Foo:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">Foo</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">&</span><span class="n">fooRef</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">*</span><span class="n">fooPtr</span> <span class="o">=</span> <span class="o">&</span><span class="n">foo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>A Block that referenced these variables would import the variables as
+const variations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">const</span> <span class="n">Foo</span> <span class="n">block_foo</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">&</span><span class="n">block_fooRef</span> <span class="o">=</span> <span class="n">fooRef</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">*</span><span class="k">const</span> <span class="n">block_fooPtr</span> <span class="o">=</span> <span class="n">fooPtr</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Captured variables are copied into the Block at the instant of
+evaluating the Block literal expression.  They are also copied when
+calling <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> 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.</p>
+<p>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.</p>
+<p>Variables declared as residing in <tt class="docutils literal"><span class="pre">__block</span></tt> 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 <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> operation. When copied
+from the stack, <tt class="docutils literal"><span class="pre">__block</span></tt> variables are copied using their normal
+qualification (i.e. without adding const).  In C++11, <tt class="docutils literal"><span class="pre">__block</span></tt>
+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.</p>
+<p>References to <tt class="docutils literal"><span class="pre">this</span></tt>, as well as references to non-static members of
+any enclosing class, are evaluated by capturing <tt class="docutils literal"><span class="pre">this</span></tt> just like a
+normal variable of C pointer type.</p>
+<p>Member variables that are Blocks may not be overloaded by the types of
+their arguments.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ObjectiveCLiterals.html">Objective-C Literals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Block-ABI-Apple.html">Block Implementation Specification</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/ClangCheck.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/ClangCheck.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/ClangCheck.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/ClangCheck.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,107 @@
+
+
+<!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>ClangCheck — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="ClangFormat" href="ClangFormat.html" />
+    <link rel="prev" title="Overview" href="ClangTools.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>ClangCheck</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ClangTools.html">Overview</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormat.html">ClangFormat</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clangcheck">
+<h1>ClangCheck<a class="headerlink" href="#clangcheck" title="Permalink to this headline">Â¶</a></h1>
+<p><cite>ClangCheck</cite> is a small wrapper around <a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> which can be used to
+do basic error checking and AST dumping.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat <span class="s"><<EOF > snippet.cc</span>
+<span class="gp">></span><span class="s"> void f() {</span>
+<span class="gp">></span><span class="s">   int a = 0</span>
+<span class="gp">></span><span class="s"> }</span>
+<span class="gp">></span><span class="s"> EOF</span>
+<span class="gp">$</span> ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+<span class="go">Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.</span>
+<span class="go">/Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of</span>
+<span class="go">      declaration</span>
+<span class="go">  int a = 0</span>
+<span class="go">           ^</span>
+<span class="go">           ;</span>
+<span class="go">(TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>></span>
+<span class="go">  (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')</span>
+<span class="go">  (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')</span>
+<span class="go">  (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')</span>
+<span class="go">  (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'</span>
+<span class="go">    (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1></span>
+<span class="go">      (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1></span>
+<span class="go">        (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'</span>
+<span class="go">          (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))</span>
+<span class="go">1 error generated.</span>
+<span class="go">Error while processing snippet.cc.</span>
+</pre></div>
+</div>
+<p>The ‘–’ at the end is important as it prevents <cite>clang-check</cite> from search for a
+compilation database. For more information on how to setup and use <cite>clang-check</cite>
+in a project, see <a class="reference internal" href="HowToSetupToolingForLLVM.html"><em>How To Setup Clang Tooling For LLVM</em></a>.</p>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ClangTools.html">Overview</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormat.html">ClangFormat</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/ClangFormat.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/ClangFormat.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/ClangFormat.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/ClangFormat.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,220 @@
+
+
+<!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>ClangFormat — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="Clang-Format Style Options" href="ClangFormatStyleOptions.html" />
+    <link rel="prev" title="ClangCheck" href="ClangCheck.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>ClangFormat</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ClangCheck.html">ClangCheck</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormatStyleOptions.html">Clang-Format Style Options</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clangformat">
+<h1>ClangFormat<a class="headerlink" href="#clangformat" title="Permalink to this headline">Â¶</a></h1>
+<p><cite>ClangFormat</cite> describes a set of tools that are built on top of
+<a class="reference internal" href="LibFormat.html"><em>LibFormat</em></a>. It can support your workflow in a variety of ways including a
+standalone tool and editor integrations.</p>
+<div class="section" id="standalone-tool">
+<h2>Standalone Tool<a class="headerlink" href="#standalone-tool" title="Permalink to this headline">Â¶</a></h2>
+<p><strong class="program">clang-format</strong> is located in <cite>clang/tools/clang-format</cite> and can be used
+to format C/C++/Obj-C code.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang-format -help
+<span class="go">OVERVIEW: A tool to format C/C++/Obj-C code.</span>
+
+<span class="go">If no arguments are specified, it formats the code from standard input</span>
+<span class="go">and writes the result to the standard output.</span>
+<span class="go">If <file>s are given, it reformats the files. If -i is specified</span>
+<span class="go">together with <file>s, the files are edited in-place. Otherwise, the</span>
+<span class="go">result is written to the standard output.</span>
+
+<span class="go">USAGE: clang-format [options] [<file> ...]</span>
+
+<span class="go">OPTIONS:</span>
+
+<span class="go">Clang-format options:</span>
+
+<span class="go">  -cursor=<uint>           - The position of the cursor when invoking</span>
+<span class="go">                             clang-format from an editor integration</span>
+<span class="go">  -dump-config             - Dump configuration options to stdout and exit.</span>
+<span class="go">                             Can be used with -style option.</span>
+<span class="go">  -i                       - Inplace edit <file>s, if specified.</span>
+<span class="go">  -length=<uint>           - Format a range of this length (in bytes).</span>
+<span class="go">                             Multiple ranges can be formatted by specifying</span>
+<span class="go">                             several -offset and -length pairs.</span>
+<span class="go">                             When only a single -offset is specified without</span>
+<span class="go">                             -length, clang-format will format up to the end</span>
+<span class="go">                             of the file.</span>
+<span class="go">                             Can only be used with one input file.</span>
+<span class="go">  -lines=<string>          - <start line>:<end line> - format a range of</span>
+<span class="go">                             lines (both 1-based).</span>
+<span class="go">                             Multiple ranges can be formatted by specifying</span>
+<span class="go">                             several -lines arguments.</span>
+<span class="go">                             Can't be used with -offset and -length.</span>
+<span class="go">                             Can only be used with one input file.</span>
+<span class="go">  -offset=<uint>           - Format a range starting at this byte offset.</span>
+<span class="go">                             Multiple ranges can be formatted by specifying</span>
+<span class="go">                             several -offset and -length pairs.</span>
+<span class="go">                             Can only be used with one input file.</span>
+<span class="go">  -output-replacements-xml - Output replacements as XML.</span>
+<span class="go">  -style=<string>          - Coding style, currently supports:</span>
+<span class="go">                               LLVM, Google, Chromium, Mozilla, WebKit.</span>
+<span class="go">                             Use -style=file to load style configuration from</span>
+<span class="go">                             .clang-format file located in one of the parent</span>
+<span class="go">                             directories of the source file (or current</span>
+<span class="go">                             directory for stdin).</span>
+<span class="go">                             Use -style="{key: value, ...}" to set specific</span>
+<span class="go">                             parameters, e.g.:</span>
+<span class="go">                               -style="{BasedOnStyle: llvm, IndentWidth: 8}"</span>
+
+<span class="go">General options:</span>
+
+<span class="go">  -help                    - Display available options (-help-hidden for more)</span>
+<span class="go">  -help-list               - Display list of available options (-help-list-hidden for more)</span>
+<span class="go">  -version                 - Display the version of this program</span>
+</pre></div>
+</div>
+<p>When the desired code formatting style is different from the available options,
+the style can be customized using the <tt class="docutils literal"><span class="pre">-style="{key:</span> <span class="pre">value,</span> <span class="pre">...}"</span></tt> option or
+by putting your style configuration in the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> or <tt class="docutils literal"><span class="pre">_clang-format</span></tt>
+file in your project’s directory and using <tt class="docutils literal"><span class="pre">clang-format</span> <span class="pre">-style=file</span></tt>.</p>
+<p>An easy way to create the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file is:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">clang-format -style=llvm -dump-config > .clang-format</span>
+</pre></div>
+</div>
+<p>Available style options are described in <a class="reference internal" href="ClangFormatStyleOptions.html"><em>Clang-Format Style Options</em></a>.</p>
+</div>
+<div class="section" id="vim-integration">
+<h2>Vim Integration<a class="headerlink" href="#vim-integration" title="Permalink to this headline">Â¶</a></h2>
+<p>There is an integration for <strong class="program">vim</strong> which lets you run the
+<strong class="program">clang-format</strong> standalone tool on your current buffer, optionally
+selecting regions to reformat. The integration has the form of a <cite>python</cite>-file
+which can be found under <cite>clang/tools/clang-format/clang-format.py</cite>.</p>
+<p>This can be integrated by adding the following to your <cite>.vimrc</cite>:</p>
+<div class="highlight-vim"><div class="highlight"><pre>map <span class="p"><</span>C<span class="p">-</span>K<span class="p">></span> :<span class="k">pyf</span> <span class="p"><</span><span class="nb">path</span><span class="p">-</span><span class="k">to</span><span class="p">-</span>this<span class="p">-</span><span class="k">file</span><span class="p">></span>/clang<span class="p">-</span>format.<span class="k">py</span><span class="p"><</span>CR<span class="p">></span>
+imap <span class="p"><</span>C<span class="p">-</span>K<span class="p">></span> <span class="p"><</span>ESC<span class="p">></span>:<span class="k">pyf</span> <span class="p"><</span><span class="nb">path</span><span class="p">-</span><span class="k">to</span><span class="p">-</span>this<span class="p">-</span><span class="k">file</span><span class="p">></span>/clang<span class="p">-</span>format.<span class="k">py</span><span class="p"><</span>CR<span class="p">></span><span class="k">i</span>
+</pre></div>
+</div>
+<p>The first line enables <strong class="program">clang-format</strong> for NORMAL and VISUAL mode, the
+second line adds support for INSERT mode. Change “C-K” to another binding if
+you need <strong class="program">clang-format</strong> on a different key (C-K stands for Ctrl+k).</p>
+<p>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.</p>
+<p>It operates on the current, potentially unsaved buffer and does not create
+or save any files. To revert a formatting, just undo.</p>
+</div>
+<div class="section" id="emacs-integration">
+<h2>Emacs Integration<a class="headerlink" href="#emacs-integration" title="Permalink to this headline">Â¶</a></h2>
+<p>Similar to the integration for <strong class="program">vim</strong>, there is an integration for
+<strong class="program">emacs</strong>. It can be found at <cite>clang/tools/clang-format/clang-format.el</cite>
+and used by adding this to your <cite>.emacs</cite>:</p>
+<div class="highlight-common-lisp"><div class="highlight"><pre><span class="p">(</span><span class="nb">load</span> <span class="s">"<path-to-clang>/tools/clang-format/clang-format.el"</span><span class="p">)</span>
+<span class="p">(</span><span class="nv">global-set-key</span> <span class="nv">[C-M-tab]</span> <span class="ss">'clang-format-region</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This binds the function <cite>clang-format-region</cite> to C-M-tab, which then formats the
+current line or selected region.</p>
+</div>
+<div class="section" id="bbedit-integration">
+<h2>BBEdit Integration<a class="headerlink" href="#bbedit-integration" title="Permalink to this headline">Â¶</a></h2>
+<p><strong class="program">clang-format</strong> 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
+<cite>clang/tools/clang-format/clang-format-bbedit.applescript</cite>; place a copy in
+<cite>~/Library/Application Support/BBEdit/Scripts</cite>, and edit the path within it to
+point to your local copy of <strong class="program">clang-format</strong>.</p>
+<p>With this integration you can select the script from the Script menu and
+<strong class="program">clang-format</strong> 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.</p>
+</div>
+<div class="section" id="visual-studio-integration">
+<h2>Visual Studio Integration<a class="headerlink" href="#visual-studio-integration" title="Permalink to this headline">Â¶</a></h2>
+<p>Download the latest Visual Studio plugin from the <a class="reference external" href="http://llvm.org/builds/">alpha build site</a>. The default key-binding is Ctrl-R,Ctrl-F.</p>
+</div>
+<div class="section" id="script-for-patch-reformatting">
+<h2>Script for patch reformatting<a class="headerlink" href="#script-for-patch-reformatting" title="Permalink to this headline">Â¶</a></h2>
+<p>The python script <cite>clang/tools/clang-format-diff.py</cite> parses the output of
+a unified diff and reformats all contained lines with <strong class="program">clang-format</strong>.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">usage: clang-format-diff.py [-h] [-p P] [-style STYLE]</span>
+
+<span class="go">Reformat changed lines in diff.</span>
+
+<span class="go">optional arguments:</span>
+<span class="go">  -h, --help    show this help message and exit</span>
+<span class="go">  -p P          strip the smallest prefix containing P slashes</span>
+<span class="go">  -style STYLE  formatting style to apply (LLVM, Google, Chromium, Mozilla,</span>
+<span class="go">                WebKit)</span>
+</pre></div>
+</div>
+<p>So to reformat all the lines in the latest <strong class="program">git</strong> commit, just do:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">git diff -U0 HEAD^ | clang-format-diff.py -p1</span>
+</pre></div>
+</div>
+<p>The <em class="xref std std-option">-U0</em> will create a diff without context lines (the script would format
+those as well).</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ClangCheck.html">ClangCheck</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormatStyleOptions.html">Clang-Format Style Options</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/ClangFormatStyleOptions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/ClangFormatStyleOptions.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/ClangFormatStyleOptions.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/ClangFormatStyleOptions.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,391 @@
+
+
+<!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-Format Style Options — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="âClangâ CFE Internals Manual" href="InternalsManual.html" />
+    <link rel="prev" title="ClangFormat" href="ClangFormat.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang-Format Style Options</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ClangFormat.html">ClangFormat</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="InternalsManual.html">“Clang” CFE Internals Manual</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-format-style-options">
+<h1>Clang-Format Style Options<a class="headerlink" href="#clang-format-style-options" title="Permalink to this headline">Â¶</a></h1>
+<p><a class="reference internal" href=""><em>Clang-Format Style Options</em></a> describes configurable formatting style options
+supported by <a class="reference internal" href="LibFormat.html"><em>LibFormat</em></a> and <a class="reference internal" href="ClangFormat.html"><em>ClangFormat</em></a>.</p>
+<p>When using <strong class="program">clang-format</strong> command line utility or
+<tt class="docutils literal"><span class="pre">clang::format::reformat(...)</span></tt> functions from code, one can either use one of
+the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a
+custom style by configuring specific style options.</p>
+<div class="section" id="configuring-style-with-clang-format">
+<h2>Configuring Style with clang-format<a class="headerlink" href="#configuring-style-with-clang-format" title="Permalink to this headline">Â¶</a></h2>
+<p><strong class="program">clang-format</strong> supports two ways to provide custom style options:
+directly specify style configuration in the <tt class="docutils literal"><span class="pre">-style=</span></tt> command line option or
+use <tt class="docutils literal"><span class="pre">-style=file</span></tt> and put style configuration in the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> or
+<tt class="docutils literal"><span class="pre">_clang-format</span></tt> file in the project directory.</p>
+<p>When using <tt class="docutils literal"><span class="pre">-style=file</span></tt>, <strong class="program">clang-format</strong> for each input file will
+try to find the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file located in the closest parent directory
+of the input file. When the standard input is used, the search is started from
+the current directory.</p>
+<p>The <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file uses YAML format:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">key1</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">value1</span>
+<span class="l-Scalar-Plain">key2</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">value2</span>
+<span class="c1"># A comment.</span>
+<span class="nn">...</span>
+</pre></div>
+</div>
+<p>An easy way to get a valid <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file containing all configuration
+options of a certain predefined style is:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">clang-format -style=llvm -dump-config > .clang-format</span>
+</pre></div>
+</div>
+<p>When specifying configuration in the <tt class="docutils literal"><span class="pre">-style=</span></tt> option, the same configuration
+is applied for all input files. The format of the configuration is:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">-style='{key1: value1, key2: value2, ...}'</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="configuring-style-in-code">
+<h2>Configuring Style in Code<a class="headerlink" href="#configuring-style-in-code" title="Permalink to this headline">Â¶</a></h2>
+<p>When using <tt class="docutils literal"><span class="pre">clang::format::reformat(...)</span></tt> functions, the format is specified
+by supplying the <a class="reference external" href="http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html">clang::format::FormatStyle</a>
+structure.</p>
+</div>
+<div class="section" id="configurable-format-style-options">
+<h2>Configurable Format Style Options<a class="headerlink" href="#configurable-format-style-options" title="Permalink to this headline">Â¶</a></h2>
+<p>This section lists the supported style options. Value type is specified for
+each option. For enumeration types possible values are specified both as a C++
+enumeration member (with a prefix, e.g. <tt class="docutils literal"><span class="pre">LS_Auto</span></tt>), and as a value usable in
+the configuration (without a prefix: <tt class="docutils literal"><span class="pre">Auto</span></tt>).</p>
+<dl class="docutils">
+<dt><strong>BasedOnStyle</strong> (<tt class="docutils literal"><span class="pre">string</span></tt>)</dt>
+<dd><p class="first">The style used for all options not specifically set in the configuration.</p>
+<p>This option is supported only in the <strong class="program">clang-format</strong> configuration
+(both within <tt class="docutils literal"><span class="pre">-style='{...}'</span></tt> and the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file).</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">LLVM</span></tt>
+A style complying with the <a class="reference external" href="http://llvm.org/docs/CodingStandards.html">LLVM coding standards</a></li>
+<li><tt class="docutils literal"><span class="pre">Google</span></tt>
+A style complying with <a class="reference external" href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml">Google’s C++ style guide</a></li>
+<li><tt class="docutils literal"><span class="pre">Chromium</span></tt>
+A style complying with <a class="reference external" href="http://www.chromium.org/developers/coding-style">Chromium’s style guide</a></li>
+<li><tt class="docutils literal"><span class="pre">Mozilla</span></tt>
+A style complying with <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style">Mozilla’s style guide</a></li>
+<li><tt class="docutils literal"><span class="pre">WebKit</span></tt>
+A style complying with <a class="reference external" href="http://www.webkit.org/coding/coding-style.html">WebKit’s style guide</a></li>
+</ul>
+</dd>
+</dl>
+<dl class="docutils">
+<dt><strong>AccessModifierOffset</strong> (<tt class="docutils literal"><span class="pre">int</span></tt>)</dt>
+<dd>The extra indent or outdent of access modifiers, e.g. <tt class="docutils literal"><span class="pre">public:</span></tt>.</dd>
+<dt><strong>AlignEscapedNewlinesLeft</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, aligns escaped newlines as far left as possible.
+Otherwise puts them into the right-most column.</dd>
+<dt><strong>AlignTrailingComments</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, aligns trailing comments.</dd>
+<dt><strong>AllowAllParametersOfDeclarationOnNextLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Allow putting all parameters of a function declaration onto
+the next line even if <tt class="docutils literal"><span class="pre">BinPackParameters</span></tt> is <tt class="docutils literal"><span class="pre">false</span></tt>.</dd>
+<dt><strong>AllowShortIfStatementsOnASingleLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(a)</span> <span class="pre">return;</span></tt> can be put on a single
+line.</dd>
+<dt><strong>AllowShortLoopsOnASingleLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, <tt class="docutils literal"><span class="pre">while</span> <span class="pre">(true)</span> <span class="pre">continue;</span></tt> can be put on a
+single line.</dd>
+<dt><strong>AlwaysBreakBeforeMultilineStrings</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, always break before multiline string literals.</dd>
+<dt><strong>AlwaysBreakTemplateDeclarations</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, always break after the <tt class="docutils literal"><span class="pre">template<...></span></tt> of a
+template declaration.</dd>
+<dt><strong>BinPackParameters</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">false</span></tt>, a function call’s or function definition’s parameters
+will either all be on the same line or will have one line each.</dd>
+<dt><strong>BreakBeforeBinaryOperators</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, binary operators will be placed after line breaks.</dd>
+<dt><strong>BreakBeforeBraces</strong> (<tt class="docutils literal"><span class="pre">BraceBreakingStyle</span></tt>)</dt>
+<dd><p class="first">The brace breaking style to use.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">BS_Attach</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Attach</span></tt>)
+Always attach braces to surrounding context.</li>
+<li><tt class="docutils literal"><span class="pre">BS_Linux</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Linux</span></tt>)
+Like <tt class="docutils literal"><span class="pre">Attach</span></tt>, but break before braces on function, namespace and
+class definitions.</li>
+<li><tt class="docutils literal"><span class="pre">BS_Stroustrup</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Stroustrup</span></tt>)
+Like <tt class="docutils literal"><span class="pre">Attach</span></tt>, but break before function definitions.</li>
+<li><tt class="docutils literal"><span class="pre">BS_Allman</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Allman</span></tt>)
+Always break before braces.</li>
+</ul>
+</dd>
+<dt><strong>BreakConstructorInitializersBeforeComma</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Always break constructor initializers before commas and align
+the commas with the colon.</dd>
+<dt><strong>ColumnLimit</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd><p class="first">The column limit.</p>
+<p class="last">A column limit of <tt class="docutils literal"><span class="pre">0</span></tt> means that there is no column limit. In this case,
+clang-format will respect the input’s line breaking decisions within
+statements.</p>
+</dd>
+<dt><strong>ConstructorInitializerAllOnOneLineOrOnePerLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If the constructor initializers don’t fit on a line, put each
+initializer on its own line.</dd>
+<dt><strong>ConstructorInitializerIndentWidth</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The number of characters to use for indentation of constructor
+initializer lists.</dd>
+<dt><strong>Cpp11BracedListStyle</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, format braced lists as best suited for C++11 braced
+lists.</p>
+<p>Important differences:
+- No spaces inside the braced list.
+- No line break before the closing brace.
+- Indentation with the continuation indent, not with the block indent.</p>
+<p class="last">Fundamentally, C++11 braced lists are formatted exactly like function
+calls would be formatted in their place. If the braced list follows a name
+(e.g. a type or variable name), clang-format formats as if the <tt class="docutils literal"><span class="pre">{}</span></tt> were
+the parentheses of a function call with that name. If there is no name,
+a zero-length name is assumed.</p>
+</dd>
+<dt><strong>DerivePointerBinding</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, analyze the formatted file for the most common binding.</dd>
+<dt><strong>ExperimentalAutoDetectBinPacking</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, clang-format detects whether function calls and
+definitions are formatted with one parameter per line.</p>
+<p>Each call can be bin-packed, one-per-line or inconclusive. If it is
+inconclusive, e.g. completely on one line, but a decision needs to be
+made, clang-format analyzes whether there are other bin-packed cases in
+the input file and act accordingly.</p>
+<p class="last">NOTE: This is an experimental flag, that might go away or be renamed. Do
+not use this in config files, etc. Use at your own risk.</p>
+</dd>
+<dt><strong>IndentCaseLabels</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">Indent case labels one level from the switch statement.</p>
+<p class="last">When <tt class="docutils literal"><span class="pre">false</span></tt>, use the same indentation level as for the switch statement.
+Switch statement body is always indented one level more than case labels.</p>
+</dd>
+<dt><strong>IndentFunctionDeclarationAfterType</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, indent when breaking function declarations which
+are not also definitions after the type.</dd>
+<dt><strong>IndentWidth</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The number of columns to use for indentation.</dd>
+<dt><strong>MaxEmptyLinesToKeep</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The maximum number of consecutive empty lines to keep.</dd>
+<dt><strong>NamespaceIndentation</strong> (<tt class="docutils literal"><span class="pre">NamespaceIndentationKind</span></tt>)</dt>
+<dd><p class="first">The indentation used for namespaces.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">NI_None</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">None</span></tt>)
+Don’t indent in namespaces.</li>
+<li><tt class="docutils literal"><span class="pre">NI_Inner</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Inner</span></tt>)
+Indent only in inner namespaces (nested in other namespaces).</li>
+<li><tt class="docutils literal"><span class="pre">NI_All</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">All</span></tt>)
+Indent in all namespaces.</li>
+</ul>
+</dd>
+<dt><strong>ObjCSpaceBeforeProtocolList</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Add a space in front of an Objective-C protocol list, i.e. use
+<tt class="docutils literal"><span class="pre">Foo</span> <span class="pre"><Protocol></span></tt> instead of <tt class="docutils literal"><span class="pre">Foo<Protocol></span></tt>.</dd>
+<dt><strong>PenaltyBreakComment</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for each line break introduced inside a comment.</dd>
+<dt><strong>PenaltyBreakFirstLessLess</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for breaking before the first <tt class="docutils literal"><span class="pre"><<</span></tt>.</dd>
+<dt><strong>PenaltyBreakString</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for each line break introduced inside a string literal.</dd>
+<dt><strong>PenaltyExcessCharacter</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for each character outside of the column limit.</dd>
+<dt><strong>PenaltyReturnTypeOnItsOwnLine</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>Penalty for putting the return type of a function onto its own
+line.</dd>
+<dt><strong>PointerBindsToType</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Set whether & and * bind to the type as opposed to the variable.</dd>
+<dt><strong>SpaceAfterControlStatementKeyword</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, spaces will be inserted between ‘for’/’if’/’while’/...
+and ‘(‘.</dd>
+<dt><strong>SpaceBeforeAssignmentOperators</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">false</span></tt>, spaces will be removed before assignment operators.</dd>
+<dt><strong>SpaceInEmptyParentheses</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">false</span></tt>, spaces may be inserted into ‘()’.</dd>
+<dt><strong>SpacesBeforeTrailingComments</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The number of spaces to before trailing line comments.</dd>
+<dt><strong>SpacesInCStyleCastParentheses</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">false</span></tt>, spaces may be inserted into C style casts.</dd>
+<dt><strong>SpacesInParentheses</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, spaces will be inserted after every ‘(‘ and before
+every ‘)’.</dd>
+<dt><strong>Standard</strong> (<tt class="docutils literal"><span class="pre">LanguageStandard</span></tt>)</dt>
+<dd><p class="first">Format compatible with this standard, e.g. use
+<tt class="docutils literal"><span class="pre">A<A<int></span> <span class="pre">></span></tt> instead of <tt class="docutils literal"><span class="pre">A<A<int>></span></tt> for LS_Cpp03.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">LS_Cpp03</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Cpp03</span></tt>)
+Use C++03-compatible syntax.</li>
+<li><tt class="docutils literal"><span class="pre">LS_Cpp11</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Cpp11</span></tt>)
+Use features of C++11 (e.g. <tt class="docutils literal"><span class="pre">A<A<int>></span></tt> instead of
+<tt class="docutils literal"><span class="pre">A<A<int></span> <span class="pre">></span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">LS_Auto</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Auto</span></tt>)
+Automatic detection based on the input.</li>
+</ul>
+</dd>
+<dt><strong>TabWidth</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The number of columns used for tab stops.</dd>
+<dt><strong>UseTab</strong> (<tt class="docutils literal"><span class="pre">UseTabStyle</span></tt>)</dt>
+<dd><p class="first">The way to use tab characters in the resulting file.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">UT_Never</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Never</span></tt>)
+Never use tab.</li>
+<li><tt class="docutils literal"><span class="pre">UT_ForIndentation</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">ForIndentation</span></tt>)
+Use tabs only for indentation.</li>
+<li><tt class="docutils literal"><span class="pre">UT_Always</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Always</span></tt>)
+Use tabs whenever we need to fill whitespace that spans at least from
+one tab stop to the next one.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="examples">
+<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">Â¶</a></h2>
+<p>A style similar to the <a class="reference external" href="https://www.kernel.org/doc/Documentation/CodingStyle">Linux Kernel style</a>:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">BasedOnStyle</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">LLVM</span>
+<span class="l-Scalar-Plain">IndentWidth</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">8</span>
+<span class="l-Scalar-Plain">UseTab</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Always</span>
+<span class="l-Scalar-Plain">BreakBeforeBraces</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Linux</span>
+<span class="l-Scalar-Plain">AllowShortIfStatementsOnASingleLine</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+<span class="l-Scalar-Plain">IndentCaseLabels</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+</pre></div>
+</div>
+<p>The result is (imagine that tabs are used for indentation here):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">test</span><span class="p">()</span>
+<span class="p">{</span>
+        <span class="k">switch</span> <span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+        <span class="k">case</span> <span class="mi">0</span>:
+        <span class="k">case</span> <span class="mi">1</span>:
+                <span class="n">do_something</span><span class="p">();</span>
+                <span class="k">break</span><span class="p">;</span>
+        <span class="k">case</span> <span class="mi">2</span>:
+                <span class="n">do_something_else</span><span class="p">();</span>
+                <span class="k">break</span><span class="p">;</span>
+        <span class="nl">default:</span>
+                <span class="k">break</span><span class="p">;</span>
+        <span class="p">}</span>
+        <span class="k">if</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span>
+                <span class="n">do_something_completely_different</span><span class="p">();</span>
+
+        <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">==</span> <span class="n">y</span><span class="p">)</span> <span class="p">{</span>
+                <span class="n">q</span><span class="p">();</span>
+        <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">></span> <span class="n">y</span><span class="p">)</span> <span class="p">{</span>
+                <span class="n">w</span><span class="p">();</span>
+        <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+                <span class="n">r</span><span class="p">();</span>
+        <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A style similar to the default Visual Studio formatting style:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">UseTab</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Never</span>
+<span class="l-Scalar-Plain">IndentWidth</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">4</span>
+<span class="l-Scalar-Plain">BreakBeforeBraces</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Allman</span>
+<span class="l-Scalar-Plain">AllowShortIfStatementsOnASingleLine</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+<span class="l-Scalar-Plain">IndentCaseLabels</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+<span class="l-Scalar-Plain">ColumnLimit</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0</span>
+</pre></div>
+</div>
+<p>The result is:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">test</span><span class="p">()</span>
+<span class="p">{</span>
+    <span class="k">switch</span> <span class="p">(</span><span class="n">suffix</span><span class="p">)</span>
+    <span class="p">{</span>
+    <span class="k">case</span> <span class="mi">0</span>:
+    <span class="k">case</span> <span class="mi">1</span>:
+        <span class="n">do_something</span><span class="p">();</span>
+        <span class="k">break</span><span class="p">;</span>
+    <span class="k">case</span> <span class="mi">2</span>:
+        <span class="n">do_something_else</span><span class="p">();</span>
+        <span class="k">break</span><span class="p">;</span>
+    <span class="nl">default:</span>
+        <span class="k">break</span><span class="p">;</span>
+    <span class="p">}</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span>
+        <span class="n">do_somthing_completely_different</span><span class="p">();</span>
+
+    <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">==</span> <span class="n">y</span><span class="p">)</span>
+    <span class="p">{</span>
+        <span class="n">q</span><span class="p">();</span>
+    <span class="p">}</span>
+    <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">></span> <span class="n">y</span><span class="p">)</span>
+    <span class="p">{</span>
+        <span class="n">w</span><span class="p">();</span>
+    <span class="p">}</span>
+    <span class="k">else</span>
+    <span class="p">{</span>
+        <span class="n">r</span><span class="p">();</span>
+    <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ClangFormat.html">ClangFormat</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="InternalsManual.html">“Clang” CFE Internals Manual</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/ClangPlugins.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/ClangPlugins.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/ClangPlugins.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/ClangPlugins.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,210 @@
+
+
+<!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 Plugins — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="How to write RecursiveASTVisitor based ASTFrontendActions." href="RAVFrontendAction.html" />
+    <link rel="prev" title="LibFormat" href="LibFormat.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang Plugins</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="LibFormat.html">LibFormat</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="RAVFrontendAction.html">How to write RecursiveASTVisitor based ASTFrontendActions.</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-plugins">
+<h1>Clang Plugins<a class="headerlink" href="#clang-plugins" title="Permalink to this headline">Â¶</a></h1>
+<p>Clang Plugins make it possible to run extra user defined actions during a
+compilation. This document will provide a basic walkthrough of how to write and
+run a Clang Plugin.</p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>Clang Plugins run FrontendActions over code. See the <a class="reference internal" href="RAVFrontendAction.html"><em>FrontendAction
+tutorial</em></a> on how to write a <tt class="docutils literal"><span class="pre">FrontendAction</span></tt> using the
+<tt class="docutils literal"><span class="pre">RecursiveASTVisitor</span></tt>. In this tutorial, we’ll demonstrate how to write a
+simple clang plugin.</p>
+</div>
+<div class="section" id="writing-a-pluginastaction">
+<h2>Writing a <tt class="docutils literal"><span class="pre">PluginASTAction</span></tt><a class="headerlink" href="#writing-a-pluginastaction" title="Permalink to this headline">Â¶</a></h2>
+<p>The main difference from writing normal <tt class="docutils literal"><span class="pre">FrontendActions</span></tt> is that you can
+handle plugin command line options. The <tt class="docutils literal"><span class="pre">PluginASTAction</span></tt> base class declares
+a <tt class="docutils literal"><span class="pre">ParseArgs</span></tt> method which you have to implement in your plugin.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="nf">ParseArgs</span><span class="p">(</span><span class="k">const</span> <span class="n">CompilerInstance</span> <span class="o">&</span><span class="n">CI</span><span class="p">,</span>
+               <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">>&</span> <span class="n">args</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">e</span> <span class="o">=</span> <span class="n">args</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">==</span> <span class="s">"-some-arg"</span><span class="p">)</span> <span class="p">{</span>
+      <span class="c1">// Handle the command line argument.</span>
+    <span class="p">}</span>
+  <span class="p">}</span>
+  <span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="registering-a-plugin">
+<h2>Registering a plugin<a class="headerlink" href="#registering-a-plugin" title="Permalink to this headline">Â¶</a></h2>
+<p>A plugin is loaded from a dynamic library at runtime by the compiler. To
+register a plugin in a library, use <tt class="docutils literal"><span class="pre">FrontendPluginRegistry::Add<></span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">FrontendPluginRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyPlugin</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="s">"my-plugin-name"</span><span class="p">,</span> <span class="s">"my plugin description"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="putting-it-all-together">
+<h2>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Permalink to this headline">Â¶</a></h2>
+<p>Let’s look at an example plugin that prints top-level function names.  This
+example is also checked into the clang repository; please also take a look at
+the latest <a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup">checked in version of PrintFunctionNames.cpp</a>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "clang/Frontend/FrontendPluginRegistry.h"</span>
+<span class="cp">#include "clang/AST/ASTConsumer.h"</span>
+<span class="cp">#include "clang/AST/AST.h"</span>
+<span class="cp">#include "clang/Frontend/CompilerInstance.h"</span>
+<span class="cp">#include "llvm/Support/raw_ostream.h"</span>
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">clang</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+
+<span class="k">class</span> <span class="nc">PrintFunctionsConsumer</span> <span class="o">:</span> <span class="k">public</span> <span class="n">ASTConsumer</span> <span class="p">{</span>
+<span class="nl">public:</span>
+  <span class="k">virtual</span> <span class="kt">bool</span> <span class="n">HandleTopLevelDecl</span><span class="p">(</span><span class="n">DeclGroupRef</span> <span class="n">DG</span><span class="p">)</span> <span class="p">{</span>
+    <span class="k">for</span> <span class="p">(</span><span class="n">DeclGroupRef</span><span class="o">::</span><span class="n">iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">DG</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">e</span> <span class="o">=</span> <span class="n">DG</span><span class="p">.</span><span class="n">end</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+      <span class="k">const</span> <span class="n">Decl</span> <span class="o">*</span><span class="n">D</span> <span class="o">=</span> <span class="o">*</span><span class="n">i</span><span class="p">;</span>
+      <span class="k">if</span> <span class="p">(</span><span class="k">const</span> <span class="n">NamedDecl</span> <span class="o">*</span><span class="n">ND</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">NamedDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span>
+        <span class="n">llvm</span><span class="o">::</span><span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"top-level-decl: </span><span class="se">\"</span><span class="s">"</span> <span class="o"><<</span> <span class="n">ND</span><span class="o">-></span><span class="n">getNameAsString</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\"\n</span><span class="s">"</span><span class="p">;</span>
+    <span class="p">}</span>
+
+    <span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">PrintFunctionNamesAction</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PluginASTAction</span> <span class="p">{</span>
+<span class="nl">protected:</span>
+  <span class="n">ASTConsumer</span> <span class="o">*</span><span class="n">CreateASTConsumer</span><span class="p">(</span><span class="n">CompilerInstance</span> <span class="o">&</span><span class="n">CI</span><span class="p">,</span> <span class="n">llvm</span><span class="o">::</span><span class="n">StringRef</span><span class="p">)</span> <span class="p">{</span>
+    <span class="k">return</span> <span class="k">new</span> <span class="n">PrintFunctionsConsumer</span><span class="p">();</span>
+  <span class="p">}</span>
+
+  <span class="kt">bool</span> <span class="n">ParseArgs</span><span class="p">(</span><span class="k">const</span> <span class="n">CompilerInstance</span> <span class="o">&</span><span class="n">CI</span><span class="p">,</span>
+                 <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">>&</span> <span class="n">args</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">e</span> <span class="o">=</span> <span class="n">args</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</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">llvm</span><span class="o">::</span><span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"PrintFunctionNames arg = "</span> <span class="o"><<</span> <span class="n">args</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+
+      <span class="c1">// Example error handling.</span>
+      <span class="k">if</span> <span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">==</span> <span class="s">"-an-error"</span><span class="p">)</span> <span class="p">{</span>
+        <span class="n">DiagnosticsEngine</span> <span class="o">&</span><span class="n">D</span> <span class="o">=</span> <span class="n">CI</span><span class="p">.</span><span class="n">getDiagnostics</span><span class="p">();</span>
+        <span class="kt">unsigned</span> <span class="n">DiagID</span> <span class="o">=</span> <span class="n">D</span><span class="p">.</span><span class="n">getCustomDiagID</span><span class="p">(</span>
+          <span class="n">DiagnosticsEngine</span><span class="o">::</span><span class="n">Error</span><span class="p">,</span> <span class="s">"invalid argument '"</span> <span class="o">+</span> <span class="n">args</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="s">"'"</span><span class="p">);</span>
+        <span class="n">D</span><span class="p">.</span><span class="n">Report</span><span class="p">(</span><span class="n">DiagID</span><span class="p">);</span>
+        <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+      <span class="p">}</span>
+    <span class="p">}</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">args</span><span class="p">.</span><span class="n">size</span><span class="p">()</span> <span class="o">&&</span> <span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="s">"help"</span><span class="p">)</span>
+      <span class="n">PrintHelp</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">errs</span><span class="p">());</span>
+
+    <span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
+  <span class="p">}</span>
+  <span class="kt">void</span> <span class="n">PrintHelp</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span><span class="o">&</span> <span class="n">ros</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">ros</span> <span class="o"><<</span> <span class="s">"Help for PrintFunctionNames plugin goes here</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+  <span class="p">}</span>
+
+<span class="p">};</span>
+
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="n">FrontendPluginRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">PrintFunctionNamesAction</span><span class="o">></span>
+<span class="n">X</span><span class="p">(</span><span class="s">"print-fns"</span><span class="p">,</span> <span class="s">"print function names"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="running-the-plugin">
+<h2>Running the plugin<a class="headerlink" href="#running-the-plugin" title="Permalink to this headline">Â¶</a></h2>
+<p>To run a plugin, the dynamic library containing the plugin registry must be
+loaded via the <em class="xref std std-option">-load</em> command line option. This will load all plugins
+that are registered, and you can select the plugins to run by specifying the
+<em class="xref std std-option">-plugin</em> option. Additional parameters for the plugins can be passed with
+<em class="xref std std-option">-plugin-arg-</em>.</p>
+<p>Note that those options must reach clang’s cc1 process. There are two
+ways to do so:</p>
+<ul class="simple">
+<li>Directly call the parsing process by using the <em class="xref std std-option">-cc1</em> option; this
+has the downside of not configuring the default header search paths, so
+you’ll need to specify the full system path configuration on the command
+line.</li>
+<li>Use clang as usual, but prefix all arguments to the cc1 process with
+<em class="xref std std-option">-Xclang</em>.</li>
+</ul>
+<p>For example, to run the <tt class="docutils literal"><span class="pre">print-function-names</span></tt> plugin over a source file in
+clang, first build the plugin, and then call clang with the plugin from the
+source tree:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">export </span><span class="nv">BD</span><span class="o">=</span>/path/to/build/directory
+<span class="gp">$</span> <span class="o">(</span><span class="nb">cd</span> <span class="nv">$BD</span> <span class="o">&&</span> make PrintFunctionNames <span class="o">)</span>
+<span class="gp">$</span> clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS <span class="se">\</span>
+<span class="go">          -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \</span>
+<span class="go">          -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \</span>
+<span class="go">          tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \</span>
+<span class="go">          -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \</span>
+<span class="go">          -plugin -Xclang print-fns</span>
+</pre></div>
+</div>
+<p>Also see the print-function-name plugin example’s
+<a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup">README</a></p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="LibFormat.html">LibFormat</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="RAVFrontendAction.html">How to write RecursiveASTVisitor based ASTFrontendActions.</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/ClangTools.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/ClangTools.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/ClangTools.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/ClangTools.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,246 @@
+
+
+<!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>Overview — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="ClangCheck" href="ClangCheck.html" />
+    <link rel="prev" title="JSON Compilation Database Format Specification" href="JSONCompilationDatabase.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Overview</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangCheck.html">ClangCheck</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="overview">
+<h1>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">Â¶</a></h1>
+<p>Clang Tools are standalone command line (and potentially GUI) tools
+designed for use by C++ developers who are already using and enjoying
+Clang as their compiler. These tools provide developer-oriented
+functionality such as fast syntax checking, automatic formatting,
+refactoring, etc.</p>
+<p>Only a couple of the most basic and fundamental tools are kept in the
+primary Clang Subversion project. The rest of the tools are kept in a
+side-project so that developers who don’t want or need to build them
+don’t. If you want to get access to the extra Clang Tools repository,
+simply check it out into the tools tree of your Clang checkout and
+follow the usual process for building and working with a combined
+LLVM/Clang checkout:</p>
+<ul class="simple">
+<li>With Subversion:<ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools/clang/tools</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/clang-tools-extra/trunk</span> <span class="pre">extra</span></tt></li>
+</ul>
+</li>
+<li>Or with Git:<ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools/clang/tools</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">http://llvm.org/git/clang-tools-extra.git</span> <span class="pre">extra</span></tt></li>
+</ul>
+</li>
+</ul>
+<p>This document describes a high-level overview of the organization of
+Clang Tools within the project as well as giving an introduction to some
+of the more important tools. However, it should be noted that this
+document is currently focused on Clang and Clang Tool developers, not on
+end users of these tools.</p>
+<div class="section" id="clang-tools-organization">
+<h2>Clang Tools Organization<a class="headerlink" href="#clang-tools-organization" title="Permalink to this headline">Â¶</a></h2>
+<p>Clang Tools are CLI or GUI programs that are intended to be directly
+used by C++ developers. That is they are <em>not</em> primarily for use by
+Clang developers, although they are hopefully useful to C++ developers
+who happen to work on Clang, and we try to actively dogfood their
+functionality. They are developed in three components: the underlying
+infrastructure for building a standalone tool based on Clang, core
+shared logic used by many different tools in the form of refactoring and
+rewriting libraries, and the tools themselves.</p>
+<p>The underlying infrastructure for Clang Tools is the
+<a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> platform. See its documentation for much
+more detailed information about how this infrastructure works. The
+common refactoring and rewriting toolkit-style library is also part of
+LibTooling organizationally.</p>
+<p>A few Clang Tools are developed along side the core Clang libraries as
+examples and test cases of fundamental functionality. However, most of
+the tools are developed in a side repository to provide easy separation
+from the core libraries. We intentionally do not support public
+libraries in the side repository, as we want to carefully review and
+find good APIs for libraries as they are lifted out of a few tools and
+into the core Clang library set.</p>
+<p>Regardless of which repository Clang Tools’ code resides in, the
+development process and practices for all Clang Tools are exactly those
+of Clang itself. They are entirely within the Clang <em>project</em>,
+regardless of the version control scheme.</p>
+</div>
+<div class="section" id="core-clang-tools">
+<h2>Core Clang Tools<a class="headerlink" href="#core-clang-tools" title="Permalink to this headline">Â¶</a></h2>
+<p>The core set of Clang tools that are within the main repository are
+tools that very specifically complement, and allow use and testing of
+<em>Clang</em> specific functionality.</p>
+<div class="section" id="clang-check">
+<h3><tt class="docutils literal"><span class="pre">clang-check</span></tt><a class="headerlink" href="#clang-check" title="Permalink to this headline">Â¶</a></h3>
+<p><a class="reference internal" href="ClangCheck.html"><em>ClangCheck</em></a> combines the LibTooling framework for running a
+Clang tool with the basic Clang diagnostics by syntax checking specific files
+in a fast, command line interface. It can also accept flags to re-display the
+diagnostics in different formats with different flags, suitable for use driving
+an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
+fixit-hints offered by clang. See <a class="reference internal" href="HowToSetupToolingForLLVM.html"><em>How To Setup Clang Tooling For LLVM</em></a> for
+instructions on how to setup and used <cite>clang-check</cite>.</p>
+<div class="section" id="clang-format">
+<h4><tt class="docutils literal"><span class="pre">clang-format</span></tt><a class="headerlink" href="#clang-format" title="Permalink to this headline">Â¶</a></h4>
+<p>Clang-format is both a <a class="reference internal" href="LibFormat.html"><em>library</em></a> and a <a class="reference internal" href="ClangFormat.html"><em>stand-alone tool</em></a> with the goal of automatically reformatting C++ sources files
+according to configurable style guides.  To do so, clang-format uses Clang’s
+<tt class="docutils literal"><span class="pre">Lexer</span></tt> to transform an input file into a token stream and then changes all
+the whitespace around those tokens.  The goal is for clang-format to serve both
+as a user tool (ideally with powerful IDE integrations) and as part of other
+refactoring tools, e.g. to do a reformatting of all the lines changed during a
+renaming.</p>
+</div>
+<div class="section" id="cpp11-migrate">
+<h4><tt class="docutils literal"><span class="pre">cpp11-migrate</span></tt><a class="headerlink" href="#cpp11-migrate" title="Permalink to this headline">Â¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">cpp11-migrate</span></tt> migrates C++ code to use C++11 features where appropriate.
+Currently it can:</p>
+<ul class="simple">
+<li>convert loops to range-based for loops;</li>
+<li>convert null pointer constants (like <tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">0</span></tt>) to C++11 <tt class="docutils literal"><span class="pre">nullptr</span></tt>;</li>
+<li>replace the type specifier in variable declarations with the <tt class="docutils literal"><span class="pre">auto</span></tt> type specifier;</li>
+<li>add the <tt class="docutils literal"><span class="pre">override</span></tt> specifier to applicable member functions.</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="section" id="extra-clang-tools">
+<h2>Extra Clang Tools<a class="headerlink" href="#extra-clang-tools" title="Permalink to this headline">Â¶</a></h2>
+<p>As various categories of Clang Tools are added to the extra repository,
+they’ll be tracked here. The focus of this documentation is on the scope
+and features of the tools for other tool developers; each tool should
+provide its own user-focused documentation.</p>
+</div>
+<div class="section" id="ideas-for-new-tools">
+<h2>Ideas for new Tools<a class="headerlink" href="#ideas-for-new-tools" title="Permalink to this headline">Â¶</a></h2>
+<ul>
+<li><p class="first">C++ cast conversion tool.  Will convert C-style casts (<tt class="docutils literal"><span class="pre">(type)</span> <span class="pre">value</span></tt>) to
+appropriate C++ cast (<tt class="docutils literal"><span class="pre">static_cast</span></tt>, <tt class="docutils literal"><span class="pre">const_cast</span></tt> or
+<tt class="docutils literal"><span class="pre">reinterpret_cast</span></tt>).</p>
+</li>
+<li><p class="first">Non-member <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> conversion tool.  Will convert
+<tt class="docutils literal"><span class="pre">foo.begin()</span></tt> into <tt class="docutils literal"><span class="pre">begin(foo)</span></tt> and similarly for <tt class="docutils literal"><span class="pre">end()</span></tt>, where
+<tt class="docutils literal"><span class="pre">foo</span></tt> is a standard container.  We could also detect similar patterns for
+arrays.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">make_shared</span></tt> / <tt class="docutils literal"><span class="pre">make_unique</span></tt> conversion.  Part of this transformation
+can be incorporated into the <tt class="docutils literal"><span class="pre">auto</span></tt> transformation.  Will convert</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="n">sp</span><span class="p">(</span><span class="k">new</span> <span class="n">Foo</span><span class="p">);</span>
+<span class="n">std</span><span class="o">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="n">up</span><span class="p">(</span><span class="k">new</span> <span class="n">Foo</span><span class="p">);</span>
+
+<span class="n">func</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span><span class="p">(</span><span class="k">new</span> <span class="n">Foo</span><span class="p">),</span> <span class="n">bar</span><span class="p">());</span>
+</pre></div>
+</div>
+<p>into:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">auto</span> <span class="n">sp</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">make_shared</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span><span class="p">();</span>
+<span class="k">auto</span> <span class="n">up</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">make_unique</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span><span class="p">();</span> <span class="c1">// In C++14 mode.</span>
+
+<span class="c1">// This also affects correctness.  For the cases where bar() throws,</span>
+<span class="c1">// make_shared() is safe and the original code may leak.</span>
+<span class="n">func</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_shared</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span><span class="p">(),</span> <span class="n">bar</span><span class="p">());</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">tr1</span></tt> removal tool.  Will migrate source code from using TR1 library
+features to C++11 library.  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <tr1/unordered_map></span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span>
+<span class="p">{</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">tr1</span><span class="o">::</span><span class="n">unordered_map</span> <span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">></span> <span class="n">ma</span><span class="p">;</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">ma</span><span class="p">.</span><span class="n">size</span> <span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</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>should be rewritten to:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <unordered_map></span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span>
+<span class="p">{</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">unordered_map</span> <span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">></span> <span class="n">ma</span><span class="p">;</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">ma</span><span class="p">.</span><span class="n">size</span> <span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</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>
+</li>
+<li><p class="first">A tool to remove <tt class="docutils literal"><span class="pre">auto</span></tt>.  Will convert <tt class="docutils literal"><span class="pre">auto</span></tt> to an explicit type or add
+comments with deduced types.  The motivation is that there are developers
+that don’t want to use <tt class="docutils literal"><span class="pre">auto</span></tt> because they are afraid that they might lose
+control over their code.</p>
+</li>
+<li><p class="first">C++14: less verbose operator function objects (<a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm">N3421</a>).
+For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">sort</span><span class="p">(</span><span class="n">v</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">v</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">greater</span><span class="o"><</span><span class="n">ValueType</span><span class="o">></span><span class="p">());</span>
+</pre></div>
+</div>
+<p>should be rewritten to:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">sort</span><span class="p">(</span><span class="n">v</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">v</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">greater</span><span class="o"><></span><span class="p">());</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangCheck.html">ClangCheck</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/CrossCompilation.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/CrossCompilation.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/CrossCompilation.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/CrossCompilation.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,263 @@
+
+
+<!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>Cross-compilation using Clang — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="AddressSanitizer" href="AddressSanitizer.html" />
+    <link rel="prev" title="Objective-C Automatic Reference Counting (ARC)" href="AutomaticReferenceCounting.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Cross-compilation using Clang</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AddressSanitizer.html">AddressSanitizer</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="cross-compilation-using-clang">
+<h1>Cross-compilation using Clang<a class="headerlink" href="#cross-compilation-using-clang" title="Permalink to this headline">Â¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>This document will guide you in choosing the right Clang options
+for cross-compiling your code to a different architecture. It assumes you
+already know how to compile the code in question for the host architecture,
+and that you know how to choose additional include and library paths.</p>
+<p>However, this document is <em>not</em> a “how to” and won’t help you setting your
+build system or Makefiles, nor choosing the right CMake options, etc.
+Also, it does not cover all the possible options, nor does it contain
+specific examples for specific architectures. For a concrete example, the
+<a class="reference external" href="http://llvm.org/docs/HowToCrossCompileLLVM.html">instructions for cross-compiling LLVM itself</a> may be of interest.</p>
+<p>After reading this document, you should be familiar with the main issues
+related to cross-compilation, and what main compiler options Clang provides
+for performing cross-compilation.</p>
+</div>
+<div class="section" id="cross-compilation-issues">
+<h2>Cross compilation issues<a class="headerlink" href="#cross-compilation-issues" title="Permalink to this headline">Â¶</a></h2>
+<p>In GCC world, every host/target combination has its own set of binaries,
+headers, libraries, etc. So, it’s usually simple to download a package
+with all files in, unzip to a directory and point the build system to
+that compiler, that will know about its location and find all it needs to
+when compiling your code.</p>
+<p>On the other hand, Clang/LLVM is natively a cross-compiler, meaning that
+one set of programs can compile to all targets by setting the <tt class="docutils literal"><span class="pre">-target</span></tt>
+option. That makes it a lot easier for programers wishing to compile to
+different platforms and architectures, and for compiler developers that
+only have to maintain one build system, and for OS distributions, that
+need only one set of main packages.</p>
+<p>But, as is true to any cross-compiler, and given the complexity of
+different architectures, OS’s and options, it’s not always easy finding
+the headers, libraries or binutils to generate target specific code.
+So you’ll need special options to help Clang understand what target
+you’re compiling to, where your tools are, etc.</p>
+<p>Another problem is that compilers come with standard libraries only (like
+<tt class="docutils literal"><span class="pre">compiler-rt</span></tt>, <tt class="docutils literal"><span class="pre">libcxx</span></tt>, <tt class="docutils literal"><span class="pre">libgcc</span></tt>, <tt class="docutils literal"><span class="pre">libm</span></tt>, etc), so you’ll have to
+find and make available to the build system, every other library required
+to build your software, that is specific to your target. It’s not enough to
+have your host’s libraries installed.</p>
+<p>Finally, not all toolchains are the same, and consequently, not every Clang
+option will work magically. Some options, like <tt class="docutils literal"><span class="pre">--sysroot</span></tt> (which
+effectively changes the logical root for headers and libraries), assume
+all your binaries and libraries are in the same directory, which may not
+true when your cross-compiler was installed by the distribution’s package
+management. So, for each specific case, you may use more than one
+option, and in most cases, you’ll end up setting include paths (<tt class="docutils literal"><span class="pre">-I</span></tt>) and
+library paths (<tt class="docutils literal"><span class="pre">-L</span></tt>) manually.</p>
+<dl class="docutils">
+<dt>To sum up, different toolchains can:</dt>
+<dd><ul class="first last simple">
+<li>be host/target specific or more flexible</li>
+<li>be in a single directory, or spread out across your system</li>
+<li>have different sets of libraries and headers by default</li>
+<li>need special options, which your build system won’t be able to figure
+out by itself</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="general-cross-compilation-options-in-clang">
+<h2>General Cross-Compilation Options in Clang<a class="headerlink" href="#general-cross-compilation-options-in-clang" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="target-triple">
+<h3>Target Triple<a class="headerlink" href="#target-triple" title="Permalink to this headline">Â¶</a></h3>
+<p>The basic option is to define the target architecture. For that, use
+<tt class="docutils literal"><span class="pre">-target</span> <span class="pre"><triple></span></tt>. If you don’t specify the target, CPU names won’t
+match (since Clang assumes the host triple), and the compilation will
+go ahead, creating code for the host platform, which will break later
+on when assembling or linking.</p>
+<dl class="docutils">
+<dt>The triple has the general format <tt class="docutils literal"><span class="pre"><arch><sub>-<vendor>-<sys>-<abi></span></tt>, where:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">arch</span></tt> = <tt class="docutils literal"><span class="pre">x86</span></tt>, <tt class="docutils literal"><span class="pre">arm</span></tt>, <tt class="docutils literal"><span class="pre">thumb</span></tt>, <tt class="docutils literal"><span class="pre">mips</span></tt>, etc.</li>
+<li><tt class="docutils literal"><span class="pre">sub</span></tt> = for ex. on ARM: <tt class="docutils literal"><span class="pre">v5</span></tt>, <tt class="docutils literal"><span class="pre">v6m</span></tt>, <tt class="docutils literal"><span class="pre">v7a</span></tt>, <tt class="docutils literal"><span class="pre">v7m</span></tt>, etc.</li>
+<li><tt class="docutils literal"><span class="pre">vendor</span></tt> = <tt class="docutils literal"><span class="pre">pc</span></tt>, <tt class="docutils literal"><span class="pre">apple</span></tt>, <tt class="docutils literal"><span class="pre">nvidia</span></tt>, <tt class="docutils literal"><span class="pre">ibm</span></tt>, etc.</li>
+<li><tt class="docutils literal"><span class="pre">sys</span></tt> = <tt class="docutils literal"><span class="pre">none</span></tt>, <tt class="docutils literal"><span class="pre">linux</span></tt>, <tt class="docutils literal"><span class="pre">win32</span></tt>, <tt class="docutils literal"><span class="pre">darwin</span></tt>, <tt class="docutils literal"><span class="pre">cuda</span></tt>, etc.</li>
+<li><tt class="docutils literal"><span class="pre">abi</span></tt> = <tt class="docutils literal"><span class="pre">eabi</span></tt>, <tt class="docutils literal"><span class="pre">gnu</span></tt>, <tt class="docutils literal"><span class="pre">android</span></tt>, <tt class="docutils literal"><span class="pre">macho</span></tt>, <tt class="docutils literal"><span class="pre">elf</span></tt>, etc.</li>
+</ul>
+</dd>
+</dl>
+<p>The sub-architecture options are available for their own architectures,
+of course, so “x86v7a” doesn’t make sense. The vendor needs to be
+specified only if there’s a relevant change, for instance between PC
+and Apple. Most of the time it can be omitted (and Unknown)
+will be assumed, which sets the defaults for the specified architecture.
+The system name is generally the OS (linux, darwin), but could be special
+like the bare-metal “none”.</p>
+<p>When a parameter is not important, they can be omitted, or you can
+choose <tt class="docutils literal"><span class="pre">unknown</span></tt> and the defaults will be used. If you choose a parameter
+that Clang doesn’t know, like <tt class="docutils literal"><span class="pre">blerg</span></tt>, it’ll ignore and assume
+<tt class="docutils literal"><span class="pre">unknown</span></tt>, which is not always desired, so be careful.</p>
+<p>Finally, the ABI option is something that will pick default CPU/FPU,
+define the specific behaviour of your code (PCS, extensions),
+and also choose the correct library calls, etc.</p>
+</div>
+<div class="section" id="cpu-fpu-abi">
+<h3>CPU, FPU, ABI<a class="headerlink" href="#cpu-fpu-abi" title="Permalink to this headline">Â¶</a></h3>
+<p>Once your target is specified, it’s time to pick the hardware you’ll
+be compiling to. For every architecture, a default set of CPU/FPU/ABI
+will be chosen, so you’ll almost always have to change it via flags.</p>
+<dl class="docutils">
+<dt>Typical flags include:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">-mcpu=<cpu-name></span></tt>, like x86-64, swift, cortex-a15</li>
+<li><tt class="docutils literal"><span class="pre">-fpu=<fpu-name></span></tt>, like SSE3, NEON, controlling the FP unit available</li>
+<li><tt class="docutils literal"><span class="pre">-mfloat-abi=<fabi></span></tt>, like soft, hard, controlling which registers
+to use for floating-point</li>
+</ul>
+</dd>
+</dl>
+<p>The default is normally the common denominator, so that Clang doesn’t
+generate code that breaks. But that also means you won’t get the best
+code for your specific hardware, which may mean orders of magnitude
+slower than you expect.</p>
+<p>For example, if your target is <tt class="docutils literal"><span class="pre">arm-none-eabi</span></tt>, the default CPU will
+be <tt class="docutils literal"><span class="pre">arm7tdmi</span></tt> using soft float, which is extremely slow on modern cores,
+whereas if your triple is <tt class="docutils literal"><span class="pre">armv7a-none-eabi</span></tt>, it’ll be Cortex-A8 with
+NEON, but still using soft-float, which is much better, but still not
+great.</p>
+</div>
+<div class="section" id="toolchain-options">
+<h3>Toolchain Options<a class="headerlink" href="#toolchain-options" title="Permalink to this headline">Â¶</a></h3>
+<p>There are three main options to control access to your cross-compiler:
+<tt class="docutils literal"><span class="pre">--sysroot</span></tt>, <tt class="docutils literal"><span class="pre">-I</span></tt>, and <tt class="docutils literal"><span class="pre">-L</span></tt>. The two last ones are well known,
+but they’re particularly important for additional libraries
+and headers that are specific to your target.</p>
+<p>There are two main ways to have a cross-compiler:</p>
+<ol class="arabic">
+<li><p class="first">When you have extracted your cross-compiler from a zip file into
+a directory, you have to use <tt class="docutils literal"><span class="pre">--sysroot=<path></span></tt>. The path is the
+root directory where you have unpacked your file, and Clang will
+look for the directories <tt class="docutils literal"><span class="pre">bin</span></tt>, <tt class="docutils literal"><span class="pre">lib</span></tt>, <tt class="docutils literal"><span class="pre">include</span></tt> in there.</p>
+<p>In this case, your setup should be pretty much done (if no
+additional headers or libraries are needed), as Clang will find
+all binaries it needs (assembler, linker, etc) in there.</p>
+</li>
+<li><p class="first">When you have installed via a package manager (modern Linux
+distributions have cross-compiler packages available), make
+sure the target triple you set is <em>also</em> the prefix of your
+cross-compiler toolchain.</p>
+<p>In this case, Clang will find the other binaries (assembler,
+linker), but not always where the target headers and libraries
+are. People add system-specific clues to Clang often, but as
+things change, it’s more likely that it won’t find than the
+other way around.</p>
+<p>So, here, you’ll be a lot safer if you specify the include/library
+directories manually (via <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-L</span></tt>).</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="section" id="target-specific-libraries">
+<h2>Target-Specific Libraries<a class="headerlink" href="#target-specific-libraries" title="Permalink to this headline">Â¶</a></h2>
+<p>All libraries that you compile as part of your build will be
+cross-compiled to your target, and your build system will probably
+find them in the right place. But all dependencies that are
+normally checked against (like <tt class="docutils literal"><span class="pre">libxml</span></tt> or <tt class="docutils literal"><span class="pre">libz</span></tt> etc) will match
+against the host platform, not the target.</p>
+<p>So, if the build system is not aware that you want to cross-compile
+your code, it will get every dependency wrong, and your compilation
+will fail during build time, not configure time.</p>
+<p>Also, finding the libraries for your target are not as easy
+as for your host machine. There aren’t many cross-libraries available
+as packages to most OS’s, so you’ll have to either cross-compile them
+from source, or download the package for your target platform,
+extract the libraries and headers, put them in specific directories
+and add <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-L</span></tt> pointing to them.</p>
+<p>Also, some libraries have different dependencies on different targets,
+so configuration tools to find dependencies in the host can get the
+list wrong for the target platform. This means that the configuration
+of your build can get things wrong when setting their own library
+paths, and you’ll have to augment it via additional flags (configure,
+Make, CMake, etc).</p>
+<div class="section" id="multilibs">
+<h3>Multilibs<a class="headerlink" href="#multilibs" title="Permalink to this headline">Â¶</a></h3>
+<p>When you want to cross-compile to more than one configuration, for
+example hard-float-ARM and soft-float-ARM, you’ll have to have multiple
+copies of your libraries and (possibly) headers.</p>
+<p>Some Linux distributions have support for Multilib, which handle that
+for you in an easier way, but if you’re not careful and, for instance,
+forget to specify <tt class="docutils literal"><span class="pre">-ccc-gcc-name</span> <span class="pre">armv7l-linux-gnueabihf-gcc</span></tt> (which
+uses hard-float), Clang will pick the <tt class="docutils literal"><span class="pre">armv7l-linux-gnueabi-ld</span></tt>
+(which uses soft-float) and linker errors will happen.</p>
+<p>The same is true if you’re compiling for different ABIs, like <tt class="docutils literal"><span class="pre">gnueabi</span></tt>
+and <tt class="docutils literal"><span class="pre">androideabi</span></tt>, and might even link and run, but produce run-time
+errors, which are much harder to track down and fix.</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AddressSanitizer.html">AddressSanitizer</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/DataFlowSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/DataFlowSanitizer.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/DataFlowSanitizer.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/DataFlowSanitizer.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,225 @@
+
+
+<!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>DataFlowSanitizer — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="DataFlowSanitizer Design Document" href="DataFlowSanitizerDesign.html" />
+    <link rel="prev" title="MemorySanitizer" href="MemorySanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>DataFlowSanitizer</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="MemorySanitizer.html">MemorySanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DataFlowSanitizerDesign.html">DataFlowSanitizer Design Document</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="dataflowsanitizer">
+<h1>DataFlowSanitizer<a class="headerlink" href="#dataflowsanitizer" title="Permalink to this headline">Â¶</a></h1>
+<div class="toctree-wrapper compound">
+</div>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#usage" id="id2">Usage</a><ul>
+<li><a class="reference internal" href="#abi-list" id="id3">ABI List</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#example" id="id4">Example</a></li>
+<li><a class="reference internal" href="#current-status" id="id5">Current status</a></li>
+<li><a class="reference internal" href="#design" id="id6">Design</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>DataFlowSanitizer is a generalised dynamic data flow analysis.</p>
+<p>Unlike other Sanitizer tools, this tool is not designed to detect a
+specific class of bugs on its own.  Instead, it provides a generic
+dynamic data flow analysis framework to be used by clients to help
+detect application-specific issues within their own code.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id2">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">Â¶</a></h2>
+<p>With no program changes, applying DataFlowSanitizer to a program
+will not alter its behavior.  To use DataFlowSanitizer, the program
+uses API functions to apply tags to data to cause it to be tracked, and to
+check the tag of a specific data item.  DataFlowSanitizer manages
+the propagation of tags through the program according to its data flow.</p>
+<p>The APIs are defined in the header file <tt class="docutils literal"><span class="pre">sanitizer/dfsan_interface.h</span></tt>.
+For further information about each function, please refer to the header
+file.</p>
+<div class="section" id="abi-list">
+<h3><a class="toc-backref" href="#id3">ABI List</a><a class="headerlink" href="#abi-list" title="Permalink to this headline">Â¶</a></h3>
+<p>DataFlowSanitizer uses a list of functions known as an ABI list to decide
+whether a call to a specific function should use the operating system’s native
+ABI or whether it should use a variant of this ABI that also propagates labels
+through function parameters and return values.  The ABI list file also controls
+how labels are propagated in the former case.  DataFlowSanitizer comes with a
+default ABI list which is intended to eventually cover the glibc library on
+Linux but it may become necessary for users to extend the ABI list in cases
+where a particular library or function cannot be instrumented (e.g. because
+it is implemented in assembly or another language which DataFlowSanitizer does
+not support) or a function is called from a library or function which cannot
+be instrumented.</p>
+<p>DataFlowSanitizer’s ABI list file is a <a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>.
+The pass treats every function in the <tt class="docutils literal"><span class="pre">uninstrumented</span></tt> category in the
+ABI list file as conforming to the native ABI.  Unless the ABI list contains
+additional categories for those functions, a call to one of those functions
+will produce a warning message, as the labelling behavior of the function
+is unknown.  The other supported categories are <tt class="docutils literal"><span class="pre">discard</span></tt>, <tt class="docutils literal"><span class="pre">functional</span></tt>
+and <tt class="docutils literal"><span class="pre">custom</span></tt>.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">discard</span></tt> – To the extent that this function writes to (user-accessible)
+memory, it also updates labels in shadow memory (this condition is trivially
+satisfied for functions which do not write to user-accessible memory).  Its
+return value is unlabelled.</li>
+<li><tt class="docutils literal"><span class="pre">functional</span></tt> – Like <tt class="docutils literal"><span class="pre">discard</span></tt>, except that the label of its return value
+is the union of the label of its arguments.</li>
+<li><tt class="docutils literal"><span class="pre">custom</span></tt> – Instead of calling the function, a custom wrapper <tt class="docutils literal"><span class="pre">__dfsw_F</span></tt>
+is called, where <tt class="docutils literal"><span class="pre">F</span></tt> is the name of the function.  This function may wrap
+the original function or provide its own implementation.  This category is
+generally used for uninstrumentable functions which write to user-accessible
+memory or which have more complex label propagation behavior.  The signature
+of <tt class="docutils literal"><span class="pre">__dfsw_F</span></tt> is based on that of <tt class="docutils literal"><span class="pre">F</span></tt> with each argument having a
+label of type <tt class="docutils literal"><span class="pre">dfsan_label</span></tt> appended to the argument list.  If <tt class="docutils literal"><span class="pre">F</span></tt>
+is of non-void return type a final argument of type <tt class="docutils literal"><span class="pre">dfsan_label</span> <span class="pre">*</span></tt>
+is appended to which the custom function can store the label for the
+return value.  For example:</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__dfsw_f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">dfsan_label</span> <span class="n">x_label</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="o">*</span><span class="nf">memcpy</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">n</span><span class="p">);</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">__dfsw_memcpy</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">n</span><span class="p">,</span>
+                    <span class="n">dfsan_label</span> <span class="n">dest_label</span><span class="p">,</span> <span class="n">dfsan_label</span> <span class="n">src_label</span><span class="p">,</span>
+                    <span class="n">dfsan_label</span> <span class="n">n_label</span><span class="p">,</span> <span class="n">dfsan_label</span> <span class="o">*</span><span class="n">ret_label</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>If a function defined in the translation unit being compiled belongs to the
+<tt class="docutils literal"><span class="pre">uninstrumented</span></tt> category, it will be compiled so as to conform to the
+native ABI.  Its arguments will be assumed to be unlabelled, but it will
+propagate labels in shadow memory.</p>
+<p>For example:</p>
+<div class="highlight-none"><div class="highlight"><pre># main is called by the C runtime using the native ABI.
+fun:main=uninstrumented
+fun:main=discard
+
+# malloc only writes to its internal data structures, not user-accessible memory.
+fun:malloc=uninstrumented
+fun:malloc=discard
+
+# tolower is a pure function.
+fun:tolower=uninstrumented
+fun:tolower=functional
+
+# memcpy needs to copy the shadow from the source to the destination region.
+# This is done in a custom function.
+fun:memcpy=uninstrumented
+fun:memcpy=custom
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="example">
+<h2><a class="toc-backref" href="#id4">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">Â¶</a></h2>
+<p>The following program demonstrates label propagation by checking that
+the correct labels are propagated.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <sanitizer/dfsan_interface.h></span>
+<span class="cp">#include <assert.h></span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="n">dfsan_label</span> <span class="n">i_label</span> <span class="o">=</span> <span class="n">dfsan_create_label</span><span class="p">(</span><span class="s">"i"</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+  <span class="n">dfsan_set_label</span><span class="p">(</span><span class="n">i_label</span><span class="p">,</span> <span class="o">&</span><span class="n">i</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">i</span><span class="p">));</span>
+
+  <span class="kt">int</span> <span class="n">j</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
+  <span class="n">dfsan_label</span> <span class="n">j_label</span> <span class="o">=</span> <span class="n">dfsan_create_label</span><span class="p">(</span><span class="s">"j"</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+  <span class="n">dfsan_set_label</span><span class="p">(</span><span class="n">j_label</span><span class="p">,</span> <span class="o">&</span><span class="n">j</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">j</span><span class="p">));</span>
+
+  <span class="kt">int</span> <span class="n">k</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span>
+  <span class="n">dfsan_label</span> <span class="n">k_label</span> <span class="o">=</span> <span class="n">dfsan_create_label</span><span class="p">(</span><span class="s">"k"</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+  <span class="n">dfsan_set_label</span><span class="p">(</span><span class="n">k_label</span><span class="p">,</span> <span class="o">&</span><span class="n">k</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">k</span><span class="p">));</span>
+
+  <span class="n">dfsan_label</span> <span class="n">ij_label</span> <span class="o">=</span> <span class="n">dfsan_get_label</span><span class="p">(</span><span class="n">i</span> <span class="o">+</span> <span class="n">j</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ij_label</span><span class="p">,</span> <span class="n">i_label</span><span class="p">));</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ij_label</span><span class="p">,</span> <span class="n">j_label</span><span class="p">));</span>
+  <span class="n">assert</span><span class="p">(</span><span class="o">!</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ij_label</span><span class="p">,</span> <span class="n">k_label</span><span class="p">));</span>
+
+  <span class="n">dfsan_label</span> <span class="n">ijk_label</span> <span class="o">=</span> <span class="n">dfsan_get_label</span><span class="p">(</span><span class="n">i</span> <span class="o">+</span> <span class="n">j</span> <span class="o">+</span> <span class="n">k</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ijk_label</span><span class="p">,</span> <span class="n">i_label</span><span class="p">));</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ijk_label</span><span class="p">,</span> <span class="n">j_label</span><span class="p">));</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ijk_label</span><span class="p">,</span> <span class="n">k_label</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>
+</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>
+<p>DataFlowSanitizer is a work in progress, currently under development for
+x86_64 Linux.</p>
+</div>
+<div class="section" id="design">
+<h2><a class="toc-backref" href="#id6">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">Â¶</a></h2>
+<p>Please refer to the <a class="reference internal" href="DataFlowSanitizerDesign.html"><em>design document</em></a>.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="MemorySanitizer.html">MemorySanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DataFlowSanitizerDesign.html">DataFlowSanitizer Design Document</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/DataFlowSanitizerDesign.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/DataFlowSanitizerDesign.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/DataFlowSanitizerDesign.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/DataFlowSanitizerDesign.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,295 @@
+
+
+<!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>DataFlowSanitizer Design Document — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="up" title="DataFlowSanitizer" href="DataFlowSanitizer.html" />
+    <link rel="next" title="LeakSanitizer" href="LeakSanitizer.html" />
+    <link rel="prev" title="DataFlowSanitizer" href="DataFlowSanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>DataFlowSanitizer Design Document</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="DataFlowSanitizer.html">DataFlowSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LeakSanitizer.html">LeakSanitizer</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="dataflowsanitizer-design-document">
+<h1>DataFlowSanitizer Design Document<a class="headerlink" href="#dataflowsanitizer-design-document" title="Permalink to this headline">Â¶</a></h1>
+<p>This document sets out the design for DataFlowSanitizer, a general
+dynamic data flow analysis.  Unlike other Sanitizer tools, this tool is
+not designed to detect a specific class of bugs on its own. Instead,
+it provides a generic dynamic data flow analysis framework to be used
+by clients to help detect application-specific issues within their
+own code.</p>
+<p>DataFlowSanitizer is a program instrumentation which can associate
+a number of taint labels with any data stored in any memory region
+accessible by the program. The analysis is dynamic, which means that
+it operates on a running program, and tracks how the labels propagate
+through that program. The tool shall support a large (>100) number
+of labels, such that programs which operate on large numbers of data
+items may be analysed with each data item being tracked separately.</p>
+<div class="section" id="use-cases">
+<h2>Use Cases<a class="headerlink" href="#use-cases" title="Permalink to this headline">Â¶</a></h2>
+<p>This instrumentation can be used as a tool to help monitor how data
+flows from a program’s inputs (sources) to its outputs (sinks).
+This has applications from a privacy/security perspective in that
+one can audit how a sensitive data item is used within a program and
+ensure it isn’t exiting the program anywhere it shouldn’t be.</p>
+</div>
+<div class="section" id="interface">
+<h2>Interface<a class="headerlink" href="#interface" title="Permalink to this headline">Â¶</a></h2>
+<p>A number of functions are provided which will create taint labels,
+attach labels to memory regions and extract the set of labels
+associated with a specific memory region. These functions are declared
+in the header file <tt class="docutils literal"><span class="pre">sanitizer/dfsan_interface.h</span></tt>.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="c1">/// Creates and returns a base label with the given description and user data.</span>
+<span class="n">dfsan_label</span> <span class="nf">dfsan_create_label</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">desc</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">userdata</span><span class="p">);</span>
+
+<span class="c1">/// Sets the label for each address in [addr,addr+size) to \c label.</span>
+<span class="kt">void</span> <span class="nf">dfsan_set_label</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">addr</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span>
+
+<span class="c1">/// Sets the label for each address in [addr,addr+size) to the union of the</span>
+<span class="c1">/// current label for that address and \c label.</span>
+<span class="kt">void</span> <span class="nf">dfsan_add_label</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">addr</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span>
+
+<span class="c1">/// Retrieves the label associated with the given data.</span>
+<span class="c1">///</span>
+<span class="c1">/// The type of 'data' is arbitrary.  The function accepts a value of any type,</span>
+<span class="c1">/// which can be truncated or extended (implicitly or explicitly) as necessary.</span>
+<span class="c1">/// The truncation/extension operations will preserve the label of the original</span>
+<span class="c1">/// value.</span>
+<span class="n">dfsan_label</span> <span class="nf">dfsan_get_label</span><span class="p">(</span><span class="kt">long</span> <span class="n">data</span><span class="p">);</span>
+
+<span class="c1">/// Retrieves a pointer to the dfsan_label_info struct for the given label.</span>
+<span class="k">const</span> <span class="k">struct</span> <span class="n">dfsan_label_info</span> <span class="o">*</span><span class="nf">dfsan_get_label_info</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">);</span>
+
+<span class="c1">/// Returns whether the given label label contains the label elem.</span>
+<span class="kt">int</span> <span class="nf">dfsan_has_label</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">,</span> <span class="n">dfsan_label</span> <span class="n">elem</span><span class="p">);</span>
+
+<span class="c1">/// If the given label label contains a label with the description desc, returns</span>
+<span class="c1">/// that label, else returns 0.</span>
+<span class="n">dfsan_label</span> <span class="nf">dfsan_has_label_with_desc</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">desc</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="taint-label-representation">
+<h2>Taint label representation<a class="headerlink" href="#taint-label-representation" title="Permalink to this headline">Â¶</a></h2>
+<p>As stated above, the tool must track a large number of taint
+labels. This poses an implementation challenge, as most multiple-label
+tainting systems assign one label per bit to shadow storage, and
+union taint labels using a bitwise or operation. This will not scale
+to clients which use hundreds or thousands of taint labels, as the
+label union operation becomes O(n) in the number of supported labels,
+and data associated with it will quickly dominate the live variable
+set, causing register spills and hampering performance.</p>
+<p>Instead, a low overhead approach is proposed which is best-case O(log<sub>2</sub> n) during execution. The underlying assumption is that
+the required space of label unions is sparse, which is a reasonable
+assumption to make given that we are optimizing for the case where
+applications mostly copy data from one place to another, without often
+invoking the need for an actual union operation. The representation
+of a taint label is a 16-bit integer, and new labels are allocated
+sequentially from a pool. The label identifier 0 is special, and means
+that the data item is unlabelled.</p>
+<p>When a label union operation is requested at a join point (any
+arithmetic or logical operation with two or more operands, such as
+addition), the code checks whether a union is required, whether the
+same union has been requested before, and whether one union label
+subsumes the other. If so, it returns the previously allocated union
+label. If not, it allocates a new union label from the same pool used
+for new labels.</p>
+<p>Specifically, the instrumentation pass will insert code like this
+to decide the union label <tt class="docutils literal"><span class="pre">lu</span></tt> for a pair of labels <tt class="docutils literal"><span class="pre">l1</span></tt>
+and <tt class="docutils literal"><span class="pre">l2</span></tt>:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">l1</span> <span class="o">==</span> <span class="n">l2</span><span class="p">)</span>
+  <span class="n">lu</span> <span class="o">=</span> <span class="n">l1</span><span class="p">;</span>
+<span class="k">else</span>
+  <span class="n">lu</span> <span class="o">=</span> <span class="n">__dfsan_union</span><span class="p">(</span><span class="n">l1</span><span class="p">,</span> <span class="n">l2</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The equality comparison is outlined, to provide an early exit in
+the common cases where the program is processing unlabelled data, or
+where the two data items have the same label.  <tt class="docutils literal"><span class="pre">__dfsan_union</span></tt> is
+a runtime library function which performs all other union computation.</p>
+<p>Further optimizations are possible, for example if <tt class="docutils literal"><span class="pre">l1</span></tt> is known
+at compile time to be zero (e.g. it is derived from a constant),
+<tt class="docutils literal"><span class="pre">l2</span></tt> can be used for <tt class="docutils literal"><span class="pre">lu</span></tt>, and vice versa.</p>
+</div>
+<div class="section" id="memory-layout-and-label-management">
+<h2>Memory layout and label management<a class="headerlink" href="#memory-layout-and-label-management" title="Permalink to this headline">Â¶</a></h2>
+<p>The following is the current memory layout for Linux/x86_64:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="30%" />
+<col width="30%" />
+<col width="40%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Start</th>
+<th class="head">End</th>
+<th class="head">Use</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>0x700000008000</td>
+<td>0x800000000000</td>
+<td>application memory</td>
+</tr>
+<tr class="row-odd"><td>0x200200000000</td>
+<td>0x700000008000</td>
+<td>unused</td>
+</tr>
+<tr class="row-even"><td>0x200000000000</td>
+<td>0x200200000000</td>
+<td>union table</td>
+</tr>
+<tr class="row-odd"><td>0x000000010000</td>
+<td>0x200000000000</td>
+<td>shadow memory</td>
+</tr>
+<tr class="row-even"><td>0x000000000000</td>
+<td>0x000000010000</td>
+<td>reserved by kernel</td>
+</tr>
+</tbody>
+</table>
+<p>Each byte of application memory corresponds to two bytes of shadow
+memory, which are used to store its taint label. As for LLVM SSA
+registers, we have not found it necessary to associate a label with
+each byte or bit of data, as some other tools do. Instead, labels are
+associated directly with registers.  Loads will result in a union of
+all shadow labels corresponding to bytes loaded (which most of the
+time will be short circuited by the initial comparison) and stores will
+result in a copy of the label to the shadow of all bytes stored to.</p>
+</div>
+<div class="section" id="propagating-labels-through-arguments">
+<h2>Propagating labels through arguments<a class="headerlink" href="#propagating-labels-through-arguments" title="Permalink to this headline">Â¶</a></h2>
+<p>In order to propagate labels through function arguments and return values,
+DataFlowSanitizer changes the ABI of each function in the translation unit.
+There are currently two supported ABIs:</p>
+<ul class="simple">
+<li>Args – Argument and return value labels are passed through additional
+arguments and by modifying the return type.</li>
+<li>TLS – Argument and return value labels are passed through TLS variables
+<tt class="docutils literal"><span class="pre">__dfsan_arg_tls</span></tt> and <tt class="docutils literal"><span class="pre">__dfsan_retval_tls</span></tt>.</li>
+</ul>
+<p>The main advantage of the TLS ABI is that it is more tolerant of ABI mismatches
+(TLS storage is not shared with any other form of storage, whereas extra
+arguments may be stored in registers which under the native ABI are not used
+for parameter passing and thus could contain arbitrary values).  On the other
+hand the args ABI is more efficient and allows ABI mismatches to be more easily
+identified by checking for nonzero labels in nominally unlabelled programs.</p>
+</div>
+<div class="section" id="implementing-the-abi-list">
+<h2>Implementing the ABI list<a class="headerlink" href="#implementing-the-abi-list" title="Permalink to this headline">Â¶</a></h2>
+<p>The <a class="reference external" href="DataFlowSanitizer.html#abi-list">ABI list</a> provides a list of functions
+which conform to the native ABI, each of which is callable from an instrumented
+program.  This is implemented by replacing each reference to a native ABI
+function with a reference to a function which uses the instrumented ABI.
+Such functions are automatically-generated wrappers for the native functions.
+For example, given the ABI list example provided in the user manual, the
+following wrappers will be generated under the args ABI:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">linkonce_odr</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="vg">@"dfsw$malloc"</span><span class="p">(</span><span class="k">i64</span> <span class="nv-Anonymous">%0</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%1</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv-Anonymous">%2</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@malloc</span><span class="p">(</span><span class="k">i64</span> <span class="nv-Anonymous">%0</span><span class="p">)</span>
+  <span class="nv-Anonymous">%3</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="k">undef</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%2</span><span class="p">,</span> <span class="m">0</span>
+  <span class="nv-Anonymous">%4</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%3</span><span class="p">,</span> <span class="k">i16</span> <span class="m">0</span><span class="p">,</span> <span class="m">1</span>
+  <span class="k">ret</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%4</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="k">linkonce_odr</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i16</span> <span class="p">}</span> <span class="vg">@"dfsw$tolower"</span><span class="p">(</span><span class="k">i32</span> <span class="nv-Anonymous">%0</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%1</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv-Anonymous">%2</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@tolower</span><span class="p">(</span><span class="k">i32</span> <span class="nv-Anonymous">%0</span><span class="p">)</span>
+  <span class="nv-Anonymous">%3</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i16</span> <span class="p">}</span> <span class="k">undef</span><span class="p">,</span> <span class="k">i32</span> <span class="nv-Anonymous">%2</span><span class="p">,</span> <span class="m">0</span>
+  <span class="nv-Anonymous">%4</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%3</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%1</span><span class="p">,</span> <span class="m">1</span>
+  <span class="k">ret</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%4</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="k">linkonce_odr</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="vg">@"dfsw$memcpy"</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%1</span><span class="p">,</span> <span class="k">i64</span> <span class="nv-Anonymous">%2</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%3</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%4</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%5</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%labelreturn</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i16</span>
+  <span class="nv-Anonymous">%6</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@__dfsw_memcpy</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%1</span><span class="p">,</span> <span class="k">i64</span> <span class="nv-Anonymous">%2</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%3</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%4</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%5</span><span class="p">,</span> <span class="k">i16</span><span class="p">*</span> <span class="nv">%labelreturn</span><span class="p">)</span>
+  <span class="nv-Anonymous">%7</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i16</span><span class="p">*</span> <span class="nv">%labelreturn</span>
+  <span class="nv-Anonymous">%8</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="k">undef</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%6</span><span class="p">,</span> <span class="m">0</span>
+  <span class="nv-Anonymous">%9</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%8</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%7</span><span class="p">,</span> <span class="m">1</span>
+  <span class="k">ret</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%9</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>As an optimization, direct calls to native ABI functions will call the
+native ABI function directly and the pass will compute the appropriate label
+internally.  This has the advantage of reducing the number of union operations
+required when the return value label is known to be zero (i.e. <tt class="docutils literal"><span class="pre">discard</span></tt>
+functions, or <tt class="docutils literal"><span class="pre">functional</span></tt> functions with known unlabelled arguments).</p>
+</div>
+<div class="section" id="checking-abi-consistency">
+<h2>Checking ABI Consistency<a class="headerlink" href="#checking-abi-consistency" title="Permalink to this headline">Â¶</a></h2>
+<p>DFSan changes the ABI of each function in the module.  This makes it possible
+for a function with the native ABI to be called with the instrumented ABI,
+or vice versa, thus possibly invoking undefined behavior.  A simple way
+of statically detecting instances of this problem is to prepend the prefix
+“dfs$” to the name of each instrumented-ABI function.</p>
+<p>This will not catch every such problem; in particular function pointers passed
+across the instrumented-native barrier cannot be used on the other side.
+These problems could potentially be caught dynamically.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="DataFlowSanitizer.html">DataFlowSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LeakSanitizer.html">LeakSanitizer</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/DriverInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/DriverInternals.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/DriverInternals.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/DriverInternals.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,456 @@
+
+
+<!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>Driver Design & Internals — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="Pretokenized Headers (PTH)" href="PTHInternals.html" />
+    <link rel="prev" title="âClangâ CFE Internals Manual" href="InternalsManual.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Driver Design & Internals</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="InternalsManual.html">“Clang” CFE Internals Manual</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="driver-design-internals">
+<h1>Driver Design & Internals<a class="headerlink" href="#driver-design-internals" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
+<li><a class="reference internal" href="#features-and-goals" id="id3">Features and Goals</a><ul>
+<li><a class="reference internal" href="#gcc-compatibility" id="id4">GCC Compatibility</a></li>
+<li><a class="reference internal" href="#flexible" id="id5">Flexible</a></li>
+<li><a class="reference internal" href="#low-overhead" id="id6">Low Overhead</a></li>
+<li><a class="reference internal" href="#simple" id="id7">Simple</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#internal-design-and-implementation" id="id8">Internal Design and Implementation</a><ul>
+<li><a class="reference internal" href="#internals-introduction" id="id9">Internals Introduction</a></li>
+<li><a class="reference internal" href="#design-overview" id="id10">Design Overview</a></li>
+<li><a class="reference internal" href="#driver-stages" id="id11">Driver Stages</a></li>
+<li><a class="reference internal" href="#additional-notes" id="id12">Additional Notes</a><ul>
+<li><a class="reference internal" href="#the-compilation-object" id="id13">The Compilation Object</a></li>
+<li><a class="reference internal" href="#unified-parsing-pipelining" id="id14">Unified Parsing & Pipelining</a></li>
+<li><a class="reference internal" href="#toolchain-argument-translation" id="id15">ToolChain Argument Translation</a></li>
+<li><a class="reference internal" href="#unused-argument-warnings" id="id16">Unused Argument Warnings</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#relation-to-gcc-driver-concepts" id="id17">Relation to GCC Driver Concepts</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>This document describes the Clang driver. The purpose of this document
+is to describe both the motivation and design goals for the driver, as
+well as details of the internal implementation.</p>
+</div>
+<div class="section" id="features-and-goals">
+<h2><a class="toc-backref" href="#id3">Features and Goals</a><a class="headerlink" href="#features-and-goals" title="Permalink to this headline">Â¶</a></h2>
+<p>The Clang driver is intended to be a production quality compiler driver
+providing access to the Clang compiler and tools, with a command line
+interface which is compatible with the gcc driver.</p>
+<p>Although the driver is part of and driven by the Clang project, it is
+logically a separate tool which shares many of the same goals as Clang:</p>
+<div class="contents local topic" id="features">
+<p class="topic-title first">Features</p>
+<ul class="simple">
+<li><a class="reference internal" href="#gcc-compatibility" id="id18">GCC Compatibility</a></li>
+<li><a class="reference internal" href="#flexible" id="id19">Flexible</a></li>
+<li><a class="reference internal" href="#low-overhead" id="id20">Low Overhead</a></li>
+<li><a class="reference internal" href="#simple" id="id21">Simple</a></li>
+</ul>
+</div>
+<div class="section" id="gcc-compatibility">
+<h3><a class="toc-backref" href="#id18">GCC Compatibility</a><a class="headerlink" href="#gcc-compatibility" title="Permalink to this headline">Â¶</a></h3>
+<p>The number one goal of the driver is to ease the adoption of Clang by
+allowing users to drop Clang into a build system which was designed to
+call GCC. Although this makes the driver much more complicated than
+might otherwise be necessary, we decided that being very compatible with
+the gcc command line interface was worth it in order to allow users to
+quickly test clang on their projects.</p>
+</div>
+<div class="section" id="flexible">
+<h3><a class="toc-backref" href="#id19">Flexible</a><a class="headerlink" href="#flexible" title="Permalink to this headline">Â¶</a></h3>
+<p>The driver was designed to be flexible and easily accommodate new uses
+as we grow the clang and LLVM infrastructure. As one example, the driver
+can easily support the introduction of tools which have an integrated
+assembler; something we hope to add to LLVM in the future.</p>
+<p>Similarly, most of the driver functionality is kept in a library which
+can be used to build other tools which want to implement or accept a gcc
+like interface.</p>
+</div>
+<div class="section" id="low-overhead">
+<h3><a class="toc-backref" href="#id20">Low Overhead</a><a class="headerlink" href="#low-overhead" title="Permalink to this headline">Â¶</a></h3>
+<p>The driver should have as little overhead as possible. In practice, we
+found that the gcc driver by itself incurred a small but meaningful
+overhead when compiling many small files. The driver doesn’t do much
+work compared to a compilation, but we have tried to keep it as
+efficient as possible by following a few simple principles:</p>
+<ul class="simple">
+<li>Avoid memory allocation and string copying when possible.</li>
+<li>Don’t parse arguments more than once.</li>
+<li>Provide a few simple interfaces for efficiently searching arguments.</li>
+</ul>
+</div>
+<div class="section" id="simple">
+<h3><a class="toc-backref" href="#id21">Simple</a><a class="headerlink" href="#simple" title="Permalink to this headline">Â¶</a></h3>
+<p>Finally, the driver was designed to be “as simple as possible”, given
+the other goals. Notably, trying to be completely compatible with the
+gcc driver adds a significant amount of complexity. However, the design
+of the driver attempts to mitigate this complexity by dividing the
+process into a number of independent stages instead of a single
+monolithic task.</p>
+</div>
+</div>
+<div class="section" id="internal-design-and-implementation">
+<h2><a class="toc-backref" href="#id8">Internal Design and Implementation</a><a class="headerlink" href="#internal-design-and-implementation" title="Permalink to this headline">Â¶</a></h2>
+<div class="contents local topic" id="id1">
+<ul class="simple">
+<li><a class="reference internal" href="#internals-introduction" id="id22">Internals Introduction</a></li>
+<li><a class="reference internal" href="#design-overview" id="id23">Design Overview</a></li>
+<li><a class="reference internal" href="#driver-stages" id="id24">Driver Stages</a></li>
+<li><a class="reference internal" href="#additional-notes" id="id25">Additional Notes</a></li>
+<li><a class="reference internal" href="#relation-to-gcc-driver-concepts" id="id26">Relation to GCC Driver Concepts</a></li>
+</ul>
+</div>
+<div class="section" id="internals-introduction">
+<h3><a class="toc-backref" href="#id22">Internals Introduction</a><a class="headerlink" href="#internals-introduction" title="Permalink to this headline">Â¶</a></h3>
+<p>In order to satisfy the stated goals, the driver was designed to
+completely subsume the functionality of the gcc executable; that is, the
+driver should not need to delegate to gcc to perform subtasks. On
+Darwin, this implies that the Clang driver also subsumes the gcc
+driver-driver, which is used to implement support for building universal
+images (binaries and object files). This also implies that the driver
+should be able to call the language specific compilers (e.g. cc1)
+directly, which means that it must have enough information to forward
+command line arguments to child processes correctly.</p>
+</div>
+<div class="section" id="design-overview">
+<h3><a class="toc-backref" href="#id23">Design Overview</a><a class="headerlink" href="#design-overview" title="Permalink to this headline">Â¶</a></h3>
+<p>The diagram below shows the significant components of the driver
+architecture and how they relate to one another. The orange components
+represent concrete data structures built by the driver, the green
+components indicate conceptually distinct stages which manipulate these
+data structures, and the blue components are important helper classes.</p>
+<img alt="Driver Architecture Diagram" class="align-center" src="_images/DriverArchitecture.png" />
+</div>
+<div class="section" id="driver-stages">
+<h3><a class="toc-backref" href="#id24">Driver Stages</a><a class="headerlink" href="#driver-stages" title="Permalink to this headline">Â¶</a></h3>
+<p>The driver functionality is conceptually divided into five stages:</p>
+<ol class="arabic">
+<li><p class="first"><strong>Parse: Option Parsing</strong></p>
+<p>The command line argument strings are decomposed into arguments
+(<tt class="docutils literal"><span class="pre">Arg</span></tt> instances). The driver expects to understand all available
+options, although there is some facility for just passing certain
+classes of options through (like <tt class="docutils literal"><span class="pre">-Wl,</span></tt>).</p>
+<p>Each argument corresponds to exactly one abstract <tt class="docutils literal"><span class="pre">Option</span></tt>
+definition, which describes how the option is parsed along with some
+additional metadata. The Arg instances themselves are lightweight and
+merely contain enough information for clients to determine which
+option they correspond to and their values (if they have additional
+parameters).</p>
+<p>For example, a command line like “-Ifoo -I foo” would parse to two
+Arg instances (a JoinedArg and a SeparateArg instance), but each
+would refer to the same Option.</p>
+<p>Options are lazily created in order to avoid populating all Option
+classes when the driver is loaded. Most of the driver code only needs
+to deal with options by their unique ID (e.g., <tt class="docutils literal"><span class="pre">options::OPT_I</span></tt>),</p>
+<p>Arg instances themselves do not generally store the values of
+parameters. In many cases, this would simply result in creating
+unnecessary string copies. Instead, Arg instances are always embedded
+inside an ArgList structure, which contains the original vector of
+argument strings. Each Arg itself only needs to contain an index into
+this vector instead of storing its values directly.</p>
+<p>The clang driver can dump the results of this stage using the
+<tt class="docutils literal"><span class="pre">-ccc-print-options</span></tt> flag (which must precede any actual command
+line arguments). For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -ccc-print-options -Xarch_i386 -fomit-frame-pointer -Wa,-fast -Ifoo -I foo t.c
+<span class="go">Option 0 - Name: "-Xarch_", Values: {"i386", "-fomit-frame-pointer"}</span>
+<span class="go">Option 1 - Name: "-Wa,", Values: {"-fast"}</span>
+<span class="go">Option 2 - Name: "-I", Values: {"foo"}</span>
+<span class="go">Option 3 - Name: "-I", Values: {"foo"}</span>
+<span class="go">Option 4 - Name: "<input>", Values: {"t.c"}</span>
+</pre></div>
+</div>
+<p>After this stage is complete the command line should be broken down
+into well defined option objects with their appropriate parameters.
+Subsequent stages should rarely, if ever, need to do any string
+processing.</p>
+</li>
+<li><p class="first"><strong>Pipeline: Compilation Job Construction</strong></p>
+<p>Once the arguments are parsed, the tree of subprocess jobs needed for
+the desired compilation sequence are constructed. This involves
+determining the input files and their types, what work is to be done
+on them (preprocess, compile, assemble, link, etc.), and constructing
+a list of Action instances for each task. The result is a list of one
+or more top-level actions, each of which generally corresponds to a
+single output (for example, an object or linked executable).</p>
+<p>The majority of Actions correspond to actual tasks, however there are
+two special Actions. The first is InputAction, which simply serves to
+adapt an input argument for use as an input to other Actions. The
+second is BindArchAction, which conceptually alters the architecture
+to be used for all of its input Actions.</p>
+<p>The clang driver can dump the results of this stage using the
+<tt class="docutils literal"><span class="pre">-ccc-print-phases</span></tt> flag. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -ccc-print-phases -x c t.c -x assembler t.s
+<span class="go">0: input, "t.c", c</span>
+<span class="go">1: preprocessor, {0}, cpp-output</span>
+<span class="go">2: compiler, {1}, assembler</span>
+<span class="go">3: assembler, {2}, object</span>
+<span class="go">4: input, "t.s", assembler</span>
+<span class="go">5: assembler, {4}, object</span>
+<span class="go">6: linker, {3, 5}, image</span>
+</pre></div>
+</div>
+<p>Here the driver is constructing seven distinct actions, four to
+compile the “t.c” input into an object file, two to assemble the
+“t.s” input, and one to link them together.</p>
+<p>A rather different compilation pipeline is shown here; in this
+example there are two top level actions to compile the input files
+into two separate object files, where each object file is built using
+<tt class="docutils literal"><span class="pre">lipo</span></tt> to merge results built for two separate architectures.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -ccc-print-phases -c -arch i386 -arch x86_64 t0.c t1.c
+<span class="go">0: input, "t0.c", c</span>
+<span class="go">1: preprocessor, {0}, cpp-output</span>
+<span class="go">2: compiler, {1}, assembler</span>
+<span class="go">3: assembler, {2}, object</span>
+<span class="go">4: bind-arch, "i386", {3}, object</span>
+<span class="go">5: bind-arch, "x86_64", {3}, object</span>
+<span class="go">6: lipo, {4, 5}, object</span>
+<span class="go">7: input, "t1.c", c</span>
+<span class="go">8: preprocessor, {7}, cpp-output</span>
+<span class="go">9: compiler, {8}, assembler</span>
+<span class="go">10: assembler, {9}, object</span>
+<span class="go">11: bind-arch, "i386", {10}, object</span>
+<span class="go">12: bind-arch, "x86_64", {10}, object</span>
+<span class="go">13: lipo, {11, 12}, object</span>
+</pre></div>
+</div>
+<p>After this stage is complete the compilation process is divided into
+a simple set of actions which need to be performed to produce
+intermediate or final outputs (in some cases, like <tt class="docutils literal"><span class="pre">-fsyntax-only</span></tt>,
+there is no “real” final output). Phases are well known compilation
+steps, such as “preprocess”, “compile”, “assemble”, “link”, etc.</p>
+</li>
+<li><p class="first"><strong>Bind: Tool & Filename Selection</strong></p>
+<p>This stage (in conjunction with the Translate stage) turns the tree
+of Actions into a list of actual subprocess to run. Conceptually, the
+driver performs a top down matching to assign Action(s) to Tools. The
+ToolChain is responsible for selecting the tool to perform a
+particular action; once selected the driver interacts with the tool
+to see if it can match additional actions (for example, by having an
+integrated preprocessor).</p>
+<p>Once Tools have been selected for all actions, the driver determines
+how the tools should be connected (for example, using an inprocess
+module, pipes, temporary files, or user provided filenames). If an
+output file is required, the driver also computes the appropriate
+file name (the suffix and file location depend on the input types and
+options such as <tt class="docutils literal"><span class="pre">-save-temps</span></tt>).</p>
+<p>The driver interacts with a ToolChain to perform the Tool bindings.
+Each ToolChain contains information about all the tools needed for
+compilation for a particular architecture, platform, and operating
+system. A single driver invocation may query multiple ToolChains
+during one compilation in order to interact with tools for separate
+architectures.</p>
+<p>The results of this stage are not computed directly, but the driver
+can print the results via the <tt class="docutils literal"><span class="pre">-ccc-print-bindings</span></tt> option. For
+example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -ccc-print-bindings -arch i386 -arch ppc t0.c
+<span class="gp">#</span> <span class="s2">"i386-apple-darwin9"</span> - <span class="s2">"clang"</span>, inputs: <span class="o">[</span><span class="s2">"t0.c"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-Sn4RKF.s"</span>
+<span class="gp">#</span> <span class="s2">"i386-apple-darwin9"</span> - <span class="s2">"darwin::Assemble"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-Sn4RKF.s"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-gvSnbS.o"</span>
+<span class="gp">#</span> <span class="s2">"i386-apple-darwin9"</span> - <span class="s2">"darwin::Link"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-gvSnbS.o"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-jgHQxi.out"</span>
+<span class="gp">#</span> <span class="s2">"ppc-apple-darwin9"</span> - <span class="s2">"gcc::Compile"</span>, inputs: <span class="o">[</span><span class="s2">"t0.c"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-Q0bTox.s"</span>
+<span class="gp">#</span> <span class="s2">"ppc-apple-darwin9"</span> - <span class="s2">"gcc::Assemble"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-Q0bTox.s"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-WCdicw.o"</span>
+<span class="gp">#</span> <span class="s2">"ppc-apple-darwin9"</span> - <span class="s2">"gcc::Link"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-WCdicw.o"</span><span class="o">]</span>, output: <span class="s2">"/tmp/cc-HHBEBh.out"</span>
+<span class="gp">#</span> <span class="s2">"i386-apple-darwin9"</span> - <span class="s2">"darwin::Lipo"</span>, inputs: <span class="o">[</span><span class="s2">"/tmp/cc-jgHQxi.out"</span>, <span class="s2">"/tmp/cc-HHBEBh.out"</span><span class="o">]</span>, output: <span class="s2">"a.out"</span>
+</pre></div>
+</div>
+<p>This shows the tool chain, tool, inputs and outputs which have been
+bound for this compilation sequence. Here clang is being used to
+compile t0.c on the i386 architecture and darwin specific versions of
+the tools are being used to assemble and link the result, but generic
+gcc versions of the tools are being used on PowerPC.</p>
+</li>
+<li><p class="first"><strong>Translate: Tool Specific Argument Translation</strong></p>
+<p>Once a Tool has been selected to perform a particular Action, the
+Tool must construct concrete Jobs which will be executed during
+compilation. The main work is in translating from the gcc style
+command line options to whatever options the subprocess expects.</p>
+<p>Some tools, such as the assembler, only interact with a handful of
+arguments and just determine the path of the executable to call and
+pass on their input and output arguments. Others, like the compiler
+or the linker, may translate a large number of arguments in addition.</p>
+<p>The ArgList class provides a number of simple helper methods to
+assist with translating arguments; for example, to pass on only the
+last of arguments corresponding to some option, or all arguments for
+an option.</p>
+<p>The result of this stage is a list of Jobs (executable paths and
+argument strings) to execute.</p>
+</li>
+<li><p class="first"><strong>Execute</strong></p>
+<p>Finally, the compilation pipeline is executed. This is mostly
+straightforward, although there is some interaction with options like
+<tt class="docutils literal"><span class="pre">-pipe</span></tt>, <tt class="docutils literal"><span class="pre">-pass-exit-codes</span></tt> and <tt class="docutils literal"><span class="pre">-time</span></tt>.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="additional-notes">
+<h3><a class="toc-backref" href="#id25">Additional Notes</a><a class="headerlink" href="#additional-notes" title="Permalink to this headline">Â¶</a></h3>
+<div class="section" id="the-compilation-object">
+<h4><a class="toc-backref" href="#id13">The Compilation Object</a><a class="headerlink" href="#the-compilation-object" title="Permalink to this headline">Â¶</a></h4>
+<p>The driver constructs a Compilation object for each set of command line
+arguments. The Driver itself is intended to be invariant during
+construction of a Compilation; an IDE should be able to construct a
+single long lived driver instance to use for an entire build, for
+example.</p>
+<p>The Compilation object holds information that is particular to each
+compilation sequence. For example, the list of used temporary files
+(which must be removed once compilation is finished) and result files
+(which should be removed if compilation fails).</p>
+</div>
+<div class="section" id="unified-parsing-pipelining">
+<h4><a class="toc-backref" href="#id14">Unified Parsing & Pipelining</a><a class="headerlink" href="#unified-parsing-pipelining" title="Permalink to this headline">Â¶</a></h4>
+<p>Parsing and pipelining both occur without reference to a Compilation
+instance. This is by design; the driver expects that both of these
+phases are platform neutral, with a few very well defined exceptions
+such as whether the platform uses a driver driver.</p>
+</div>
+<div class="section" id="toolchain-argument-translation">
+<h4><a class="toc-backref" href="#id15">ToolChain Argument Translation</a><a class="headerlink" href="#toolchain-argument-translation" title="Permalink to this headline">Â¶</a></h4>
+<p>In order to match gcc very closely, the clang driver currently allows
+tool chains to perform their own translation of the argument list (into
+a new ArgList data structure). Although this allows the clang driver to
+match gcc easily, it also makes the driver operation much harder to
+understand (since the Tools stop seeing some arguments the user
+provided, and see new ones instead).</p>
+<p>For example, on Darwin <tt class="docutils literal"><span class="pre">-gfull</span></tt> gets translated into two separate
+arguments, <tt class="docutils literal"><span class="pre">-g</span></tt> and <tt class="docutils literal"><span class="pre">-fno-eliminate-unused-debug-symbols</span></tt>. Trying to
+write Tool logic to do something with <tt class="docutils literal"><span class="pre">-gfull</span></tt> will not work, because
+Tool argument translation is done after the arguments have been
+translated.</p>
+<p>A long term goal is to remove this tool chain specific translation, and
+instead force each tool to change its own logic to do the right thing on
+the untranslated original arguments.</p>
+</div>
+<div class="section" id="unused-argument-warnings">
+<h4><a class="toc-backref" href="#id16">Unused Argument Warnings</a><a class="headerlink" href="#unused-argument-warnings" title="Permalink to this headline">Â¶</a></h4>
+<p>The driver operates by parsing all arguments but giving Tools the
+opportunity to choose which arguments to pass on. One downside of this
+infrastructure is that if the user misspells some option, or is confused
+about which options to use, some command line arguments the user really
+cared about may go unused. This problem is particularly important when
+using clang as a compiler, since the clang compiler does not support
+anywhere near all the options that gcc does, and we want to make sure
+users know which ones are being used.</p>
+<p>To support this, the driver maintains a bit associated with each
+argument of whether it has been used (at all) during the compilation.
+This bit usually doesn’t need to be set by hand, as the key ArgList
+accessors will set it automatically.</p>
+<p>When a compilation is successful (there are no errors), the driver
+checks the bit and emits an “unused argument” warning for any arguments
+which were never accessed. This is conservative (the argument may not
+have been used to do what the user wanted) but still catches the most
+obvious cases.</p>
+</div>
+</div>
+<div class="section" id="relation-to-gcc-driver-concepts">
+<h3><a class="toc-backref" href="#id26">Relation to GCC Driver Concepts</a><a class="headerlink" href="#relation-to-gcc-driver-concepts" title="Permalink to this headline">Â¶</a></h3>
+<p>For those familiar with the gcc driver, this section provides a brief
+overview of how things from the gcc driver map to the clang driver.</p>
+<ul>
+<li><p class="first"><strong>Driver Driver</strong></p>
+<p>The driver driver is fully integrated into the clang driver. The
+driver simply constructs additional Actions to bind the architecture
+during the <em>Pipeline</em> phase. The tool chain specific argument
+translation is responsible for handling <tt class="docutils literal"><span class="pre">-Xarch_</span></tt>.</p>
+<p>The one caveat is that this approach requires <tt class="docutils literal"><span class="pre">-Xarch_</span></tt> not be used
+to alter the compilation itself (for example, one cannot provide
+<tt class="docutils literal"><span class="pre">-S</span></tt> as an <tt class="docutils literal"><span class="pre">-Xarch_</span></tt> argument). The driver attempts to reject
+such invocations, and overall there isn’t a good reason to abuse
+<tt class="docutils literal"><span class="pre">-Xarch_</span></tt> to that end in practice.</p>
+<p>The upside is that the clang driver is more efficient and does little
+extra work to support universal builds. It also provides better error
+reporting and UI consistency.</p>
+</li>
+<li><p class="first"><strong>Specs</strong></p>
+<p>The clang driver has no direct correspondent for “specs”. The
+majority of the functionality that is embedded in specs is in the
+Tool specific argument translation routines. The parts of specs which
+control the compilation pipeline are generally part of the <em>Pipeline</em>
+stage.</p>
+</li>
+<li><p class="first"><strong>Toolchains</strong></p>
+<p>The gcc driver has no direct understanding of tool chains. Each gcc
+binary roughly corresponds to the information which is embedded
+inside a single ToolChain.</p>
+<p>The clang driver is intended to be portable and support complex
+compilation environments. All platform and tool chain specific code
+should be protected behind either abstract or well defined interfaces
+(such as whether the platform supports use as a driver driver).</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="InternalsManual.html">“Clang” CFE Internals Manual</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/ExternalClangExamples.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/ExternalClangExamples.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/ExternalClangExamples.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/ExternalClangExamples.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,140 @@
+
+
+<!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>External Clang Examples — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="Introduction to the Clang AST" href="IntroductionToTheClangAST.html" />
+    <link rel="prev" title="Choosing the Right Interface for Your Application" href="Tooling.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>External Clang Examples</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="Tooling.html">Choosing the Right Interface for Your Application</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="external-clang-examples">
+<h1>External Clang Examples<a class="headerlink" href="#external-clang-examples" title="Permalink to this headline">Â¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>This page provides some examples of the kinds of things that people have
+done with Clang that might serve as useful guides (or starting points) from
+which to develop your own tools. They may be helpful even for something as
+banal (but necessary) as how to set up your build to integrate Clang.</p>
+<p>Clang’s library-based design is deliberately aimed at facilitating use by
+external projects, and we are always interested in improving Clang to
+better serve our external users. Some typical categories of applications
+where Clang is used are:</p>
+<ul class="simple">
+<li>Static analysis.</li>
+<li>Documentation/cross-reference generation.</li>
+</ul>
+<p>If you know of (or wrote!) a tool or project using Clang, please send an
+email to Clang’s <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">development discussion mailing list</a> to have it added.
+(or if you are already a Clang contributor, feel free to directly commit
+additions). Since the primary purpose of this page is to provide examples
+that can help developers, generally they must have code available.</p>
+</div>
+<div class="section" id="list-of-projects-and-tools">
+<h2>List of projects and tools<a class="headerlink" href="#list-of-projects-and-tools" title="Permalink to this headline">Â¶</a></h2>
+<dl class="docutils">
+<dt><a class="reference external" href="https://github.com/Andersbakken/rtags/">https://github.com/Andersbakken/rtags/</a></dt>
+<dd>“RTags is a client/server application that indexes c/c++ code and keeps
+a persistent in-memory database of references, symbolnames, completions
+etc.”</dd>
+<dt><a class="reference external" href="http://rprichard.github.com/sourceweb/">http://rprichard.github.com/sourceweb/</a></dt>
+<dd>“A C/C++ source code indexer and navigator”</dd>
+<dt><a class="reference external" href="https://github.com/etaoins/qconnectlint">https://github.com/etaoins/qconnectlint</a></dt>
+<dd>“qconnectlint is a Clang tool for statically verifying the consistency
+of signal and slot connections made with Qt’s <tt class="docutils literal"><span class="pre">QObject::connect</span></tt>.”</dd>
+<dt><a class="reference external" href="https://github.com/woboq/woboq_codebrowser">https://github.com/woboq/woboq_codebrowser</a></dt>
+<dd>“The Woboq Code Browser is a web-based code browser for C/C++ projects.
+Check out <a class="reference external" href="http://code.woboq.org/">http://code.woboq.org/</a> for an example!”</dd>
+<dt><a class="reference external" href="https://github.com/mozilla/dxr">https://github.com/mozilla/dxr</a></dt>
+<dd>“DXR is a source code cross-reference tool that uses static analysis
+data collected by instrumented compilers.”</dd>
+<dt><a class="reference external" href="https://github.com/eschulte/clang-mutate">https://github.com/eschulte/clang-mutate</a></dt>
+<dd>“This tool performs a number of operations on C-language source files.”</dd>
+<dt><a class="reference external" href="https://github.com/gmarpons/Crisp">https://github.com/gmarpons/Crisp</a></dt>
+<dd>“A coding rule validation add-on for LLVM/clang. Crisp rules are written
+in Prolog. A high-level declarative DSL to easily write new rules is under
+development. It will be called CRISP, an acronym for <em>Coding Rules in
+Sugared Prolog</em>.”</dd>
+<dt><a class="reference external" href="https://github.com/drothlis/clang-ctags">https://github.com/drothlis/clang-ctags</a></dt>
+<dd>“Generate tag file for C++ source code.”</dd>
+<dt><a class="reference external" href="https://github.com/exclipy/clang_indexer">https://github.com/exclipy/clang_indexer</a></dt>
+<dd>“This is an indexer for C and C++ based on the libclang library.”</dd>
+<dt><a class="reference external" href="https://github.com/holtgrewe/linty">https://github.com/holtgrewe/linty</a></dt>
+<dd>“Linty - C/C++ Style Checking with Python & libclang.”</dd>
+<dt><a class="reference external" href="https://github.com/axw/cmonster">https://github.com/axw/cmonster</a></dt>
+<dd>“cmonster is a Python wrapper for the Clang C++ parser.”</dd>
+<dt><a class="reference external" href="https://github.com/rizsotto/Constantine">https://github.com/rizsotto/Constantine</a></dt>
+<dd>“Constantine is a toy project to learn how to write clang plugin.
+Implements pseudo const analysis. Generates warnings about variables,
+which were declared without const qualifier.”</dd>
+<dt><a class="reference external" href="https://github.com/jessevdk/cldoc">https://github.com/jessevdk/cldoc</a></dt>
+<dd>“cldoc is a Clang based documentation generator for C and C++.
+cldoc tries to solve the issue of writing C/C++ software documentation
+with a modern, non-intrusive and robust approach.”</dd>
+</dl>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="Tooling.html">Choosing the Right Interface for Your Application</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="IntroductionToTheClangAST.html">Introduction to the Clang AST</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/FAQ.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/FAQ.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/FAQ.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/FAQ.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,131 @@
+
+
+<!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>Frequently Asked Questions (FAQ) — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="Choosing the Right Interface for Your Application" href="Tooling.html" />
+    <link rel="prev" title="Modules" href="Modules.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Frequently Asked Questions (FAQ)</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="Modules.html">Modules</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Tooling.html">Choosing the Right Interface for Your Application</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="frequently-asked-questions-faq">
+<h1>Frequently Asked Questions (FAQ)<a class="headerlink" href="#frequently-asked-questions-faq" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#driver" id="id1">Driver</a><ul>
+<li><a class="reference internal" href="#i-run-clang-cc1-and-get-weird-errors-about-missing-headers" id="id2">I run <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span> <span class="pre">...</span></tt> and get weird errors about missing headers</a></li>
+<li><a class="reference internal" href="#i-get-errors-about-some-headers-being-missing-stddef-h-stdarg-h" id="id3">I get errors about some headers being missing (<tt class="docutils literal"><span class="pre">stddef.h</span></tt>, <tt class="docutils literal"><span class="pre">stdarg.h</span></tt>)</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="driver">
+<h2><a class="toc-backref" href="#id1">Driver</a><a class="headerlink" href="#driver" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="i-run-clang-cc1-and-get-weird-errors-about-missing-headers">
+<h3><a class="toc-backref" href="#id2">I run <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span> <span class="pre">...</span></tt> and get weird errors about missing headers</a><a class="headerlink" href="#i-run-clang-cc1-and-get-weird-errors-about-missing-headers" title="Permalink to this headline">Â¶</a></h3>
+<p>Given this source file:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">printf</span><span class="p">(</span><span class="s">"Hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If you run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 hello.c
+<span class="go">hello.c:1:10: fatal error: 'stdio.h' file not found</span>
+<span class="gp">#</span>include <stdio.h>
+<span class="go">         ^</span>
+<span class="go">1 error generated.</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> is the frontend, <tt class="docutils literal"><span class="pre">clang</span></tt> is the <a class="reference internal" href="DriverInternals.html"><em>driver</em></a>.  The driver invokes the frontend with options appropriate
+for your system.  To see these options, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -### -c hello.c
+</pre></div>
+</div>
+<p>Some clang command line options are driver-only options, some are frontend-only
+options.  Frontend-only options are intended to be used only by clang developers.
+Users should not run <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> directly, because <tt class="docutils literal"><span class="pre">-cc1</span></tt> options are not
+guaranteed to be stable.</p>
+<p>If you want to use a frontend-only option (“a <tt class="docutils literal"><span class="pre">-cc1</span></tt> option”), for example
+<tt class="docutils literal"><span class="pre">-ast-dump</span></tt>, then you need to take the <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> line generated by the
+driver and add the option you need.  Alternatively, you can run
+<tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-Xclang</span> <span class="pre"><option></span> <span class="pre">...</span></tt> to force the driver pass <tt class="docutils literal"><span class="pre"><option></span></tt> to
+<tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>.</p>
+</div>
+<div class="section" id="i-get-errors-about-some-headers-being-missing-stddef-h-stdarg-h">
+<h3><a class="toc-backref" href="#id3">I get errors about some headers being missing (<tt class="docutils literal"><span class="pre">stddef.h</span></tt>, <tt class="docutils literal"><span class="pre">stdarg.h</span></tt>)</a><a class="headerlink" href="#i-get-errors-about-some-headers-being-missing-stddef-h-stdarg-h" title="Permalink to this headline">Â¶</a></h3>
+<p>Some header files (<tt class="docutils literal"><span class="pre">stddef.h</span></tt>, <tt class="docutils literal"><span class="pre">stdarg.h</span></tt>, and others) are shipped with
+Clang — these are called builtin includes.  Clang searches for them in a
+directory relative to the location of the <tt class="docutils literal"><span class="pre">clang</span></tt> binary.  If you moved the
+<tt class="docutils literal"><span class="pre">clang</span></tt> binary, you need to move the builtin headers, too.</p>
+<p>More information can be found in the <a class="reference internal" href="LibTooling.html#libtooling-builtin-includes"><em>Builtin includes</em></a>
+section.</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="Modules.html">Modules</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Tooling.html">Choosing the Right Interface for Your Application</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/HowToSetupToolingForLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/HowToSetupToolingForLLVM.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/HowToSetupToolingForLLVM.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/HowToSetupToolingForLLVM.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,240 @@
+
+
+<!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 Setup Clang Tooling For LLVM — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="JSON Compilation Database Format Specification" href="JSONCompilationDatabase.html" />
+    <link rel="prev" title="Matching the Clang AST" href="LibASTMatchers.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>How To Setup Clang Tooling For LLVM</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="LibASTMatchers.html">Matching the Clang AST</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="how-to-setup-clang-tooling-for-llvm">
+<h1>How To Setup Clang Tooling For LLVM<a class="headerlink" href="#how-to-setup-clang-tooling-for-llvm" title="Permalink to this headline">Â¶</a></h1>
+<p>Clang Tooling provides infrastructure to write tools that need syntactic
+and semantic information about a program. This term also relates to a set
+of specific tools using this infrastructure (e.g. <tt class="docutils literal"><span class="pre">clang-check</span></tt>). This
+document provides information on how to set up and use Clang Tooling for
+the LLVM source code.</p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>Clang Tooling needs a compilation database to figure out specific build
+options for each file. Currently it can create a compilation database
+from the <tt class="docutils literal"><span class="pre">compilation_commands.json</span></tt> file, generated by CMake. When
+invoking clang tools, you can either specify a path to a build directory
+using a command line parameter <tt class="docutils literal"><span class="pre">-p</span></tt> or let Clang Tooling find this
+file in your source tree. In either case you need to configure your
+build using CMake to use clang tools.</p>
+</div>
+<div class="section" id="setup-clang-tooling-using-cmake-and-make">
+<h2>Setup Clang Tooling Using CMake and Make<a class="headerlink" href="#setup-clang-tooling-using-cmake-and-make" title="Permalink to this headline">Â¶</a></h2>
+<p>If you intend to use make to build LLVM, you should have CMake 2.8.6 or
+later installed (can be found <a class="reference external" href="http://cmake.org">here</a>).</p>
+<p>First, you need to generate Makefiles for LLVM with CMake. You need to
+make a build directory and run CMake from it:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> mkdir your/build/directory
+<span class="gp">$</span> <span class="nb">cd </span>your/build/directory
+<span class="gp">$</span> cmake -DCMAKE_EXPORT_COMPILE_COMMANDS<span class="o">=</span>ON path/to/llvm/sources
+</pre></div>
+</div>
+<p>If you want to use clang instead of GCC, you can add
+<tt class="docutils literal"><span class="pre">-DCMAKE_C_COMPILER=/path/to/clang</span> <span class="pre">-DCMAKE_CXX_COMPILER=/path/to/clang++</span></tt>.
+You can also use <tt class="docutils literal"><span class="pre">ccmake</span></tt>, which provides a curses interface to configure
+CMake variables for lazy people.</p>
+<p>As a result, the new <tt class="docutils literal"><span class="pre">compile_commands.json</span></tt> file should appear in the
+current directory. You should link it to the LLVM source tree so that
+Clang Tooling is able to use it:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> ln -s <span class="nv">$PWD</span>/compile_commands.json path/to/llvm/source/
+</pre></div>
+</div>
+<p>Now you are ready to build and test LLVM using make:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> make check-all
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-clang-tools">
+<h2>Using Clang Tools<a class="headerlink" href="#using-clang-tools" title="Permalink to this headline">Â¶</a></h2>
+<p>After you completed the previous steps, you are ready to run clang tools. If
+you have a recent clang installed, you should have <tt class="docutils literal"><span class="pre">clang-check</span></tt> in
+<tt class="docutils literal"><span class="pre">$PATH</span></tt>. Try to run it on any <tt class="docutils literal"><span class="pre">.cpp</span></tt> file inside the LLVM source tree:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp
+</pre></div>
+</div>
+<p>If you’re using vim, it’s convenient to have clang-check integrated. Put
+this into your <tt class="docutils literal"><span class="pre">.vimrc</span></tt>:</p>
+<div class="highlight-python"><pre>function! ClangCheckImpl(cmd)
+  if &autowrite | wall | endif
+  echo "Running " . a:cmd . " ..."
+  let l:output = system(a:cmd)
+  cexpr l:output
+  cwindow
+  let w:quickfix_title = a:cmd
+  if v:shell_error != 0
+    cc
+  endif
+  let g:clang_check_last_cmd = a:cmd
+endfunction
+
+function! ClangCheck()
+  let l:filename = expand('%')
+  if l:filename =~ '\.\(cpp\|cxx\|cc\|c\)$'
+    call ClangCheckImpl("clang-check " . l:filename)
+  elseif exists("g:clang_check_last_cmd")
+    call ClangCheckImpl(g:clang_check_last_cmd)
+  else
+    echo "Can't detect file's compilation arguments and no previous clang-check invocation!"
+  endif
+endfunction
+
+nmap <silent> <F5> :call ClangCheck()<CR><CR></pre>
+</div>
+<p>When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In
+case the current file has a different extension (for example, .h), F5
+will re-run the last clang-check invocation made from this vim instance
+(if any). The output will go into the error window, which is opened
+automatically when clang-check finds errors, and can be re-opened with
+<tt class="docutils literal"><span class="pre">:cope</span></tt>.</p>
+<p>Other <tt class="docutils literal"><span class="pre">clang-check</span></tt> options that can be useful when working with clang
+AST:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-ast-print</span></tt> — Build ASTs and then pretty-print them.</li>
+<li><tt class="docutils literal"><span class="pre">-ast-dump</span></tt> — Build ASTs and then debug dump them.</li>
+<li><tt class="docutils literal"><span class="pre">-ast-dump-filter=<string></span></tt> — Use with <tt class="docutils literal"><span class="pre">-ast-dump</span></tt> or <tt class="docutils literal"><span class="pre">-ast-print</span></tt> to
+dump/print only AST declaration nodes having a certain substring in a
+qualified name. Use <tt class="docutils literal"><span class="pre">-ast-list</span></tt> to list all filterable declaration node
+names.</li>
+<li><tt class="docutils literal"><span class="pre">-ast-list</span></tt> — Build ASTs and print the list of declaration node qualified
+names.</li>
+</ul>
+<p>Examples:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer
+<span class="go">Processing: tools/clang/tools/clang-check/ClangCheck.cpp.</span>
+<span class="go">Dumping ::ActionFactory::newASTConsumer:</span>
+<span class="go">clang::ASTConsumer *newASTConsumer() (CompoundStmt 0x44da290 </home/alexfh/local/llvm/tools/clang/tools/clang-check/ClangCheck.cpp:64:40, line:72:3></span>
+<span class="go">  (IfStmt 0x44d97c8 <line:65:5, line:66:45></span>
+<span class="go">    <<<NULL>>></span>
+<span class="go">      (ImplicitCastExpr 0x44d96d0 <line:65:9> '_Bool':'_Bool' <UserDefinedConversion></span>
+<span class="go">...</span>
+<span class="gp">$</span> clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer
+<span class="go">Processing: tools/clang/tools/clang-check/ClangCheck.cpp.</span>
+<span class="go">Printing <anonymous namespace>::ActionFactory::newASTConsumer:</span>
+<span class="go">clang::ASTConsumer *newASTConsumer() {</span>
+<span class="go">    if (this->ASTList.operator _Bool())</span>
+<span class="go">        return clang::CreateASTDeclNodeLister();</span>
+<span class="go">    if (this->ASTDump.operator _Bool())</span>
+<span class="go">        return clang::CreateASTDumper(this->ASTDumpFilter);</span>
+<span class="go">    if (this->ASTPrint.operator _Bool())</span>
+<span class="go">        return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter);</span>
+<span class="go">    return new clang::ASTConsumer();</span>
+<span class="go">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="experimental-using-ninja-build-system">
+<h2>(Experimental) Using Ninja Build System<a class="headerlink" href="#experimental-using-ninja-build-system" title="Permalink to this headline">Â¶</a></h2>
+<p>Optionally you can use the <a class="reference external" href="https://github.com/martine/ninja">Ninja</a>
+build system instead of make. It is aimed at making your builds faster.
+Currently this step will require building Ninja from sources.</p>
+<p>To take advantage of using Clang Tools along with Ninja build you need
+at least CMake 2.8.9.</p>
+<p>Clone the Ninja git repository and build Ninja from sources:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> git clone git://github.com/martine/ninja.git
+<span class="gp">$</span> <span class="nb">cd </span>ninja/
+<span class="gp">$</span> ./bootstrap.py
+</pre></div>
+</div>
+<p>This will result in a single binary <tt class="docutils literal"><span class="pre">ninja</span></tt> in the current directory.
+It doesn’t require installation and can just be copied to any location
+inside <tt class="docutils literal"><span class="pre">$PATH</span></tt>, say <tt class="docutils literal"><span class="pre">/usr/local/bin/</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> sudo cp ninja /usr/local/bin/
+<span class="gp">$</span> sudo chmod a+rx /usr/local/bin/ninja
+</pre></div>
+</div>
+<p>After doing all of this, you’ll need to generate Ninja build files for
+LLVM with CMake. You need to make a build directory and run CMake from
+it:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> mkdir your/build/directory
+<span class="gp">$</span> <span class="nb">cd </span>your/build/directory
+<span class="gp">$</span> cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS<span class="o">=</span>ON path/to/llvm/sources
+</pre></div>
+</div>
+<p>If you want to use clang instead of GCC, you can add
+<tt class="docutils literal"><span class="pre">-DCMAKE_C_COMPILER=/path/to/clang</span> <span class="pre">-DCMAKE_CXX_COMPILER=/path/to/clang++</span></tt>.
+You can also use <tt class="docutils literal"><span class="pre">ccmake</span></tt>, which provides a curses interface to configure
+CMake variables in an interactive manner.</p>
+<p>As a result, the new <tt class="docutils literal"><span class="pre">compile_commands.json</span></tt> file should appear in the
+current directory. You should link it to the LLVM source tree so that
+Clang Tooling is able to use it:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> ln -s <span class="nv">$PWD</span>/compile_commands.json path/to/llvm/source/
+</pre></div>
+</div>
+<p>Now you are ready to build and test LLVM using Ninja:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> ninja check-all
+</pre></div>
+</div>
+<p>Other target names can be used in the same way as with make.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="LibASTMatchers.html">Matching the Clang AST</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/InternalsManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/InternalsManual.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/InternalsManual.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/InternalsManual.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,1746 @@
+
+
+<!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â CFE Internals Manual — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="Driver Design & Internals" href="DriverInternals.html" />
+    <link rel="prev" title="Clang-Format Style Options" href="ClangFormatStyleOptions.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>âClangâ CFE Internals Manual</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ClangFormatStyleOptions.html">Clang-Format Style Options</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DriverInternals.html">Driver Design & Internals</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-cfe-internals-manual">
+<h1>“Clang” CFE Internals Manual<a class="headerlink" href="#clang-cfe-internals-manual" title="Permalink to this headline">Â¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#llvm-support-library" id="id2">LLVM Support Library</a></li>
+<li><a class="reference internal" href="#the-clang-basic-library" id="id3">The Clang “Basic” Library</a><ul>
+<li><a class="reference internal" href="#the-diagnostics-subsystem" id="id4">The Diagnostics Subsystem</a><ul>
+<li><a class="reference internal" href="#the-diagnostic-kinds-td-files" id="id5">The <tt class="docutils literal"><span class="pre">Diagnostic*Kinds.td</span></tt> files</a></li>
+<li><a class="reference internal" href="#the-format-string" id="id6">The Format String</a></li>
+<li><a class="reference internal" href="#formatting-a-diagnostic-argument" id="id7">Formatting a Diagnostic Argument</a></li>
+<li><a class="reference internal" href="#producing-the-diagnostic" id="id8">Producing the Diagnostic</a></li>
+<li><a class="reference internal" href="#fix-it-hints" id="id9">Fix-It Hints</a></li>
+<li><a class="reference internal" href="#the-diagnosticclient-interface" id="id10">The <tt class="docutils literal"><span class="pre">DiagnosticClient</span></tt> Interface</a></li>
+<li><a class="reference internal" href="#adding-translations-to-clang" id="id11">Adding Translations to Clang</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-sourcelocation-and-sourcemanager-classes" id="id12">The <tt class="docutils literal"><span class="pre">SourceLocation</span></tt> and <tt class="docutils literal"><span class="pre">SourceManager</span></tt> classes</a></li>
+<li><a class="reference internal" href="#sourcerange-and-charsourcerange" id="id13"><tt class="docutils literal"><span class="pre">SourceRange</span></tt> and <tt class="docutils literal"><span class="pre">CharSourceRange</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-driver-library" id="id14">The Driver Library</a></li>
+<li><a class="reference internal" href="#precompiled-headers" id="id15">Precompiled Headers</a></li>
+<li><a class="reference internal" href="#the-frontend-library" id="id16">The Frontend Library</a></li>
+<li><a class="reference internal" href="#the-lexer-and-preprocessor-library" id="id17">The Lexer and Preprocessor Library</a><ul>
+<li><a class="reference internal" href="#the-token-class" id="id18">The Token class</a></li>
+<li><a class="reference internal" href="#annotation-tokens" id="id19">Annotation Tokens</a></li>
+<li><a class="reference internal" href="#the-lexer-class" id="id20">The <tt class="docutils literal"><span class="pre">Lexer</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-tokenlexer-class" id="id21">The <tt class="docutils literal"><span class="pre">TokenLexer</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-multipleincludeopt-class" id="id22">The <tt class="docutils literal"><span class="pre">MultipleIncludeOpt</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-parser-library" id="id23">The Parser Library</a></li>
+<li><a class="reference internal" href="#the-ast-library" id="id24">The AST Library</a><ul>
+<li><a class="reference internal" href="#the-type-class-and-its-subclasses" id="id25">The <tt class="docutils literal"><span class="pre">Type</span></tt> class and its subclasses</a><ul>
+<li><a class="reference internal" href="#canonical-types" id="id26">Canonical Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-qualtype-class" id="id27">The <tt class="docutils literal"><span class="pre">QualType</span></tt> class</a></li>
+<li><a class="reference internal" href="#declaration-names" id="id28">Declaration names</a></li>
+<li><a class="reference internal" href="#declaration-contexts" id="id29">Declaration contexts</a><ul>
+<li><a class="reference internal" href="#redeclarations-and-overloads" id="id30">Redeclarations and Overloads</a></li>
+<li><a class="reference internal" href="#lexical-and-semantic-contexts" id="id31">Lexical and Semantic Contexts</a></li>
+<li><a class="reference internal" href="#transparent-declaration-contexts" id="id32">Transparent Declaration Contexts</a></li>
+<li><a class="reference internal" href="#multiply-defined-declaration-contexts" id="id33">Multiply-Defined Declaration Contexts</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-cfg-class" id="id34">The <tt class="docutils literal"><span class="pre">CFG</span></tt> class</a><ul>
+<li><a class="reference internal" href="#basic-blocks" id="id35">Basic Blocks</a></li>
+<li><a class="reference internal" href="#entry-and-exit-blocks" id="id36">Entry and Exit Blocks</a></li>
+<li><a class="reference internal" href="#conditional-control-flow" id="id37">Conditional Control-Flow</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#constant-folding-in-the-clang-ast" id="id38">Constant Folding in the Clang AST</a><ul>
+<li><a class="reference internal" href="#implementation-approach" id="id39">Implementation Approach</a></li>
+<li><a class="reference internal" href="#extensions" id="id40">Extensions</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-change-clang" id="id41">How to change Clang</a><ul>
+<li><a class="reference internal" href="#how-to-add-an-attribute" id="id42">How to add an attribute</a><ul>
+<li><a class="reference internal" href="#include-clang-basic-attr-td" id="id43"><tt class="docutils literal"><span class="pre">include/clang/Basic/Attr.td</span></tt></a></li>
+<li><a class="reference internal" href="#boilerplate" id="id44">Boilerplate</a></li>
+<li><a class="reference internal" href="#the-meat-of-your-attribute" id="id45">The meat of your attribute</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-add-an-expression-or-statement" id="id46">How to add an expression or statement</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>This document describes some of the more important APIs and internal design
+decisions made in the Clang C front-end.  The purpose of this document is to
+both capture some of this high level information and also describe some of the
+design decisions behind it.  This is meant for people interested in hacking on
+Clang, not for end-users.  The description below is categorized by libraries,
+and does not describe any of the clients of the libraries.</p>
+</div>
+<div class="section" id="llvm-support-library">
+<h2><a class="toc-backref" href="#id2">LLVM Support Library</a><a class="headerlink" href="#llvm-support-library" title="Permalink to this headline">Â¶</a></h2>
+<p>The LLVM <tt class="docutils literal"><span class="pre">libSupport</span></tt> library provides many underlying libraries and
+<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html">data-structures</a>, including
+command line option processing, various containers and a system abstraction
+layer, which is used for file system access.</p>
+</div>
+<div class="section" id="the-clang-basic-library">
+<h2><a class="toc-backref" href="#id3">The Clang “Basic” Library</a><a class="headerlink" href="#the-clang-basic-library" title="Permalink to this headline">Â¶</a></h2>
+<p>This library certainly needs a better name.  The “basic” library contains a
+number of low-level utilities for tracking and manipulating source buffers,
+locations within the source buffers, diagnostics, tokens, target abstraction,
+and information about the subset of the language being compiled for.</p>
+<p>Part of this infrastructure is specific to C (such as the <tt class="docutils literal"><span class="pre">TargetInfo</span></tt>
+class), other parts could be reused for other non-C-based languages
+(<tt class="docutils literal"><span class="pre">SourceLocation</span></tt>, <tt class="docutils literal"><span class="pre">SourceManager</span></tt>, <tt class="docutils literal"><span class="pre">Diagnostics</span></tt>, <tt class="docutils literal"><span class="pre">FileManager</span></tt>).
+When and if there is future demand we can figure out if it makes sense to
+introduce a new library, move the general classes somewhere else, or introduce
+some other solution.</p>
+<p>We describe the roles of these classes in order of their dependencies.</p>
+<div class="section" id="the-diagnostics-subsystem">
+<h3><a class="toc-backref" href="#id4">The Diagnostics Subsystem</a><a class="headerlink" href="#the-diagnostics-subsystem" title="Permalink to this headline">Â¶</a></h3>
+<p>The Clang Diagnostics subsystem is an important part of how the compiler
+communicates with the human.  Diagnostics are the warnings and errors produced
+when the code is incorrect or dubious.  In Clang, each diagnostic produced has
+(at the minimum) a unique ID, an English translation associated with it, a
+<a class="reference internal" href="#sourcelocation"><em>SourceLocation</em></a> to “put the caret”, and a severity
+(e.g., <tt class="docutils literal"><span class="pre">WARNING</span></tt> or <tt class="docutils literal"><span class="pre">ERROR</span></tt>).  They can also optionally include a number of
+arguments to the dianostic (which fill in “%0“‘s in the string) as well as a
+number of source ranges that related to the diagnostic.</p>
+<p>In this section, we’ll be giving examples produced by the Clang command line
+driver, but diagnostics can be <a class="reference internal" href="#diagnosticclient"><em>rendered in many different ways</em></a> depending on how the <tt class="docutils literal"><span class="pre">DiagnosticClient</span></tt> interface is
+implemented.  A representative example of a diagnostic is:</p>
+<div class="highlight-c++"><pre>t.c:38:15: error: invalid operands to binary expression ('int *' and '_Complex float')
+P = (P-42) + Gamma*4;
+    ~~~~~~ ^ ~~~~~~~</pre>
+</div>
+<p>In this example, you can see the English translation, the severity (error), you
+can see the source location (the caret (“<tt class="docutils literal"><span class="pre">^</span></tt>”) and file/line/column info),
+the source ranges “<tt class="docutils literal"><span class="pre">~~~~</span></tt>”, arguments to the diagnostic (“<tt class="docutils literal"><span class="pre">int*</span></tt>” and
+“<tt class="docutils literal"><span class="pre">_Complex</span> <span class="pre">float</span></tt>”).  You’ll have to believe me that there is a unique ID
+backing the diagnostic :).</p>
+<p>Getting all of this to happen has several steps and involves many moving
+pieces, this section describes them and talks about best practices when adding
+a new diagnostic.</p>
+<div class="section" id="the-diagnostic-kinds-td-files">
+<h4><a class="toc-backref" href="#id5">The <tt class="docutils literal"><span class="pre">Diagnostic*Kinds.td</span></tt> files</a><a class="headerlink" href="#the-diagnostic-kinds-td-files" title="Permalink to this headline">Â¶</a></h4>
+<p>Diagnostics are created by adding an entry to one of the
+<tt class="docutils literal"><span class="pre">clang/Basic/Diagnostic*Kinds.td</span></tt> files, depending on what library will be
+using it.  From this file, <strong class="program">tblgen</strong> generates the unique ID of the
+diagnostic, the severity of the diagnostic and the English translation + format
+string.</p>
+<p>There is little sanity with the naming of the unique ID’s right now.  Some
+start with <tt class="docutils literal"><span class="pre">err_</span></tt>, <tt class="docutils literal"><span class="pre">warn_</span></tt>, <tt class="docutils literal"><span class="pre">ext_</span></tt> to encode the severity into the name.
+Since the enum is referenced in the C++ code that produces the diagnostic, it
+is somewhat useful for it to be reasonably short.</p>
+<p>The severity of the diagnostic comes from the set {<tt class="docutils literal"><span class="pre">NOTE</span></tt>, <tt class="docutils literal"><span class="pre">WARNING</span></tt>,
+<tt class="docutils literal"><span class="pre">EXTENSION</span></tt>, <tt class="docutils literal"><span class="pre">EXTWARN</span></tt>, <tt class="docutils literal"><span class="pre">ERROR</span></tt>}.  The <tt class="docutils literal"><span class="pre">ERROR</span></tt> severity is used for
+diagnostics indicating the program is never acceptable under any circumstances.
+When an error is emitted, the AST for the input code may not be fully built.
+The <tt class="docutils literal"><span class="pre">EXTENSION</span></tt> and <tt class="docutils literal"><span class="pre">EXTWARN</span></tt> severities are used for extensions to the
+language that Clang accepts.  This means that Clang fully understands and can
+represent them in the AST, but we produce diagnostics to tell the user their
+code is non-portable.  The difference is that the former are ignored by
+default, and the later warn by default.  The <tt class="docutils literal"><span class="pre">WARNING</span></tt> severity is used for
+constructs that are valid in the currently selected source language but that
+are dubious in some way.  The <tt class="docutils literal"><span class="pre">NOTE</span></tt> level is used to staple more information
+onto previous diagnostics.</p>
+<p>These <em>severities</em> are mapped into a smaller set (the <tt class="docutils literal"><span class="pre">Diagnostic::Level</span></tt>
+enum, {<tt class="docutils literal"><span class="pre">Ignored</span></tt>, <tt class="docutils literal"><span class="pre">Note</span></tt>, <tt class="docutils literal"><span class="pre">Warning</span></tt>, <tt class="docutils literal"><span class="pre">Error</span></tt>, <tt class="docutils literal"><span class="pre">Fatal</span></tt>}) of output
+<em>levels</em> by the diagnostics subsystem based on various configuration options.
+Clang internally supports a fully fine grained mapping mechanism that allows
+you to map almost any diagnostic to the output level that you want.  The only
+diagnostics that cannot be mapped are <tt class="docutils literal"><span class="pre">NOTE</span></tt>s, which always follow the
+severity of the previously emitted diagnostic and <tt class="docutils literal"><span class="pre">ERROR</span></tt>s, which can only
+be mapped to <tt class="docutils literal"><span class="pre">Fatal</span></tt> (it is not possible to turn an error into a warning, for
+example).</p>
+<p>Diagnostic mappings are used in many ways.  For example, if the user specifies
+<tt class="docutils literal"><span class="pre">-pedantic</span></tt>, <tt class="docutils literal"><span class="pre">EXTENSION</span></tt> maps to <tt class="docutils literal"><span class="pre">Warning</span></tt>, if they specify
+<tt class="docutils literal"><span class="pre">-pedantic-errors</span></tt>, it turns into <tt class="docutils literal"><span class="pre">Error</span></tt>.  This is used to implement
+options like <tt class="docutils literal"><span class="pre">-Wunused_macros</span></tt>, <tt class="docutils literal"><span class="pre">-Wundef</span></tt> etc.</p>
+<p>Mapping to <tt class="docutils literal"><span class="pre">Fatal</span></tt> should only be used for diagnostics that are considered so
+severe that error recovery won’t be able to recover sensibly from them (thus
+spewing a ton of bogus errors).  One example of this class of error are failure
+to <tt class="docutils literal"><span class="pre">#include</span></tt> a file.</p>
+</div>
+<div class="section" id="the-format-string">
+<h4><a class="toc-backref" href="#id6">The Format String</a><a class="headerlink" href="#the-format-string" title="Permalink to this headline">Â¶</a></h4>
+<p>The format string for the diagnostic is very simple, but it has some power.  It
+takes the form of a string in English with markers that indicate where and how
+arguments to the diagnostic are inserted and formatted.  For example, here are
+some simple format strings:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="s">"binary integer literals are an extension"</span>
+<span class="s">"format string contains '</span><span class="se">\\</span><span class="s">0' within the string body"</span>
+<span class="s">"more '%%' conversions than data arguments"</span>
+<span class="s">"invalid operands to binary expression (%0 and %1)"</span>
+<span class="s">"overloaded '%0' must be a %select{unary|binary|unary or binary}2 operator"</span>
+     <span class="s">" (has %1 parameter%s1)"</span>
+</pre></div>
+</div>
+<p>These examples show some important points of format strings.  You can use any
+plain ASCII character in the diagnostic string except “<tt class="docutils literal"><span class="pre">%</span></tt>” without a
+problem, but these are C strings, so you have to use and be aware of all the C
+escape sequences (as in the second example).  If you want to produce a “<tt class="docutils literal"><span class="pre">%</span></tt>”
+in the output, use the “<tt class="docutils literal"><span class="pre">%%</span></tt>” escape sequence, like the third diagnostic.
+Finally, Clang uses the “<tt class="docutils literal"><span class="pre">%...[digit]</span></tt>” sequences to specify where and how
+arguments to the diagnostic are formatted.</p>
+<p>Arguments to the diagnostic are numbered according to how they are specified by
+the C++ code that <a class="reference internal" href="#internals-producing-diag"><em>produces them</em></a>, and are
+referenced by <tt class="docutils literal"><span class="pre">%0</span></tt> .. <tt class="docutils literal"><span class="pre">%9</span></tt>.  If you have more than 10 arguments to your
+diagnostic, you are doing something wrong :).  Unlike <tt class="docutils literal"><span class="pre">printf</span></tt>, there is no
+requirement that arguments to the diagnostic end up in the output in the same
+order as they are specified, you could have a format string with “<tt class="docutils literal"><span class="pre">%1</span> <span class="pre">%0</span></tt>”
+that swaps them, for example.  The text in between the percent and digit are
+formatting instructions.  If there are no instructions, the argument is just
+turned into a string and substituted in.</p>
+<p>Here are some “best practices” for writing the English format string:</p>
+<ul class="simple">
+<li>Keep the string short.  It should ideally fit in the 80 column limit of the
+<tt class="docutils literal"><span class="pre">DiagnosticKinds.td</span></tt> file.  This avoids the diagnostic wrapping when
+printed, and forces you to think about the important point you are conveying
+with the diagnostic.</li>
+<li>Take advantage of location information.  The user will be able to see the
+line and location of the caret, so you don’t need to tell them that the
+problem is with the 4th argument to the function: just point to it.</li>
+<li>Do not capitalize the diagnostic string, and do not end it with a period.</li>
+<li>If you need to quote something in the diagnostic string, use single quotes.</li>
+</ul>
+<p>Diagnostics should never take random English strings as arguments: you
+shouldn’t use “<tt class="docutils literal"><span class="pre">you</span> <span class="pre">have</span> <span class="pre">a</span> <span class="pre">problem</span> <span class="pre">with</span> <span class="pre">%0</span></tt>” and pass in things like “<tt class="docutils literal"><span class="pre">your</span>
+<span class="pre">argument</span></tt>” or “<tt class="docutils literal"><span class="pre">your</span> <span class="pre">return</span> <span class="pre">value</span></tt>” as arguments.  Doing this prevents
+<a class="reference internal" href="#internals-diag-translation"><em>translating</em></a> the Clang diagnostics to other
+languages (because they’ll get random English words in their otherwise
+localized diagnostic).  The exceptions to this are C/C++ language keywords
+(e.g., <tt class="docutils literal"><span class="pre">auto</span></tt>, <tt class="docutils literal"><span class="pre">const</span></tt>, <tt class="docutils literal"><span class="pre">mutable</span></tt>, etc) and C/C++ operators (<tt class="docutils literal"><span class="pre">/=</span></tt>).
+Note that things like “pointer” and “reference” are not keywords.  On the other
+hand, you <em>can</em> include anything that comes from the user’s source code,
+including variable names, types, labels, etc.  The “<tt class="docutils literal"><span class="pre">select</span></tt>” format can be
+used to achieve this sort of thing in a localizable way, see below.</p>
+</div>
+<div class="section" id="formatting-a-diagnostic-argument">
+<h4><a class="toc-backref" href="#id7">Formatting a Diagnostic Argument</a><a class="headerlink" href="#formatting-a-diagnostic-argument" title="Permalink to this headline">Â¶</a></h4>
+<p>Arguments to diagnostics are fully typed internally, and come from a couple
+different classes: integers, types, names, and random strings.  Depending on
+the class of the argument, it can be optionally formatted in different ways.
+This gives the <tt class="docutils literal"><span class="pre">DiagnosticClient</span></tt> information about what the argument means
+without requiring it to use a specific presentation (consider this MVC for
+Clang :).</p>
+<p>Here are the different diagnostic argument formats currently supported by
+Clang:</p>
+<p><strong>“s” format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><tt class="docutils literal"><span class="pre">"requires</span> <span class="pre">%1</span> <span class="pre">parameter%s1"</span></tt></dd>
+<dt>Class:</dt>
+<dd>Integers</dd>
+<dt>Description:</dt>
+<dd>This is a simple formatter for integers that is useful when producing English
+diagnostics.  When the integer is 1, it prints as nothing.  When the integer
+is not 1, it prints as “<tt class="docutils literal"><span class="pre">s</span></tt>”.  This allows some simple grammatical forms to
+be to be handled correctly, and eliminates the need to use gross things like
+<tt class="docutils literal"><span class="pre">"requires</span> <span class="pre">%1</span> <span class="pre">parameter(s)"</span></tt>.</dd>
+</dl>
+<p><strong>“select” format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><tt class="docutils literal"><span class="pre">"must</span> <span class="pre">be</span> <span class="pre">a</span> <span class="pre">%select{unary|binary|unary</span> <span class="pre">or</span> <span class="pre">binary}2</span> <span class="pre">operator"</span></tt></dd>
+<dt>Class:</dt>
+<dd>Integers</dd>
+<dt>Description:</dt>
+<dd>This format specifier is used to merge multiple related diagnostics together
+into one common one, without requiring the difference to be specified as an
+English string argument.  Instead of specifying the string, the diagnostic
+gets an integer argument and the format string selects the numbered option.
+In this case, the “<tt class="docutils literal"><span class="pre">%2</span></tt>” value must be an integer in the range [0..2].  If
+it is 0, it prints “unary”, if it is 1 it prints “binary” if it is 2, it
+prints “unary or binary”.  This allows other language translations to
+substitute reasonable words (or entire phrases) based on the semantics of the
+diagnostic instead of having to do things textually.  The selected string
+does undergo formatting.</dd>
+</dl>
+<p><strong>“plural” format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><tt class="docutils literal"><span class="pre">"you</span> <span class="pre">have</span> <span class="pre">%1</span> <span class="pre">%plural{1:mouse|:mice}1</span> <span class="pre">connected</span> <span class="pre">to</span> <span class="pre">your</span> <span class="pre">computer"</span></tt></dd>
+<dt>Class:</dt>
+<dd>Integers</dd>
+<dt>Description:</dt>
+<dd><p class="first">This is a formatter for complex plural forms.  It is designed to handle even
+the requirements of languages with very complex plural forms, as many Baltic
+languages have.  The argument consists of a series of expression/form pairs,
+separated by ”:”, where the first form whose expression evaluates to true is
+the result of the modifier.</p>
+<p>An expression can be empty, in which case it is always true.  See the example
+at the top.  Otherwise, it is a series of one or more numeric conditions,
+separated by ”,”.  If any condition matches, the expression matches.  Each
+numeric condition can take one of three forms.</p>
+<ul class="simple">
+<li>number: A simple decimal number matches if the argument is the same as the
+number.  Example: <tt class="docutils literal"><span class="pre">"%plural{1:mouse|:mice}4"</span></tt></li>
+<li>range: A range in square brackets matches if the argument is within the
+range.  Then range is inclusive on both ends.  Example:
+<tt class="docutils literal"><span class="pre">"%plural{0:none|1:one|[2,5]:some|:many}2"</span></tt></li>
+<li>modulo: A modulo operator is followed by a number, and equals sign and
+either a number or a range.  The tests are the same as for plain numbers
+and ranges, but the argument is taken modulo the number first.  Example:
+<tt class="docutils literal"><span class="pre">"%plural{%100=0:even</span> <span class="pre">hundred|%100=[1,50]:lower</span> <span class="pre">half|:everything</span> <span class="pre">else}1"</span></tt></li>
+</ul>
+<p class="last">The parser is very unforgiving.  A syntax error, even whitespace, will abort,
+as will a failure to match the argument against any expression.</p>
+</dd>
+</dl>
+<p><strong>“ordinal” format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><tt class="docutils literal"><span class="pre">"ambiguity</span> <span class="pre">in</span> <span class="pre">%ordinal0</span> <span class="pre">argument"</span></tt></dd>
+<dt>Class:</dt>
+<dd>Integers</dd>
+<dt>Description:</dt>
+<dd>This is a formatter which represents the argument number as an ordinal: the
+value <tt class="docutils literal"><span class="pre">1</span></tt> becomes <tt class="docutils literal"><span class="pre">1st</span></tt>, <tt class="docutils literal"><span class="pre">3</span></tt> becomes <tt class="docutils literal"><span class="pre">3rd</span></tt>, and so on.  Values less
+than <tt class="docutils literal"><span class="pre">1</span></tt> are not supported.  This formatter is currently hard-coded to use
+English ordinals.</dd>
+</dl>
+<p><strong>“objcclass” format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><tt class="docutils literal"><span class="pre">"method</span> <span class="pre">%objcclass0</span> <span class="pre">not</span> <span class="pre">found"</span></tt></dd>
+<dt>Class:</dt>
+<dd><tt class="docutils literal"><span class="pre">DeclarationName</span></tt></dd>
+<dt>Description:</dt>
+<dd>This is a simple formatter that indicates the <tt class="docutils literal"><span class="pre">DeclarationName</span></tt> corresponds
+to an Objective-C class method selector.  As such, it prints the selector
+with a leading “<tt class="docutils literal"><span class="pre">+</span></tt>”.</dd>
+</dl>
+<p><strong>“objcinstance” format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><tt class="docutils literal"><span class="pre">"method</span> <span class="pre">%objcinstance0</span> <span class="pre">not</span> <span class="pre">found"</span></tt></dd>
+<dt>Class:</dt>
+<dd><tt class="docutils literal"><span class="pre">DeclarationName</span></tt></dd>
+<dt>Description:</dt>
+<dd>This is a simple formatter that indicates the <tt class="docutils literal"><span class="pre">DeclarationName</span></tt> corresponds
+to an Objective-C instance method selector.  As such, it prints the selector
+with a leading “<tt class="docutils literal"><span class="pre">-</span></tt>”.</dd>
+</dl>
+<p><strong>“q” format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><tt class="docutils literal"><span class="pre">"candidate</span> <span class="pre">found</span> <span class="pre">by</span> <span class="pre">name</span> <span class="pre">lookup</span> <span class="pre">is</span> <span class="pre">%q0"</span></tt></dd>
+<dt>Class:</dt>
+<dd><tt class="docutils literal"><span class="pre">NamedDecl</span> <span class="pre">*</span></tt></dd>
+<dt>Description:</dt>
+<dd>This formatter indicates that the fully-qualified name of the declaration
+should be printed, e.g., “<tt class="docutils literal"><span class="pre">std::vector</span></tt>” rather than “<tt class="docutils literal"><span class="pre">vector</span></tt>”.</dd>
+</dl>
+<p><strong>“diff” format</strong></p>
+<dl class="docutils">
+<dt>Example:</dt>
+<dd><tt class="docutils literal"><span class="pre">"no</span> <span class="pre">known</span> <span class="pre">conversion</span> <span class="pre">%diff{from</span> <span class="pre">$</span> <span class="pre">to</span> <span class="pre">$|from</span> <span class="pre">argument</span> <span class="pre">type</span> <span class="pre">to</span> <span class="pre">parameter</span> <span class="pre">type}1,2"</span></tt></dd>
+<dt>Class:</dt>
+<dd><tt class="docutils literal"><span class="pre">QualType</span></tt></dd>
+<dt>Description:</dt>
+<dd>This formatter takes two <tt class="docutils literal"><span class="pre">QualType</span></tt>s and attempts to print a template
+difference between the two.  If tree printing is off, the text inside the
+braces before the pipe is printed, with the formatted text replacing the $.
+If tree printing is on, the text after the pipe is printed and a type tree is
+printed after the diagnostic message.</dd>
+</dl>
+<p>It is really easy to add format specifiers to the Clang diagnostics system, but
+they should be discussed before they are added.  If you are creating a lot of
+repetitive diagnostics and/or have an idea for a useful formatter, please bring
+it up on the cfe-dev mailing list.</p>
+</div>
+<div class="section" id="producing-the-diagnostic">
+<span id="internals-producing-diag"></span><h4><a class="toc-backref" href="#id8">Producing the Diagnostic</a><a class="headerlink" href="#producing-the-diagnostic" title="Permalink to this headline">Â¶</a></h4>
+<p>Now that you’ve created the diagnostic in the <tt class="docutils literal"><span class="pre">Diagnostic*Kinds.td</span></tt> file, you
+need to write the code that detects the condition in question and emits the new
+diagnostic.  Various components of Clang (e.g., the preprocessor, <tt class="docutils literal"><span class="pre">Sema</span></tt>,
+etc.) provide a helper function named “<tt class="docutils literal"><span class="pre">Diag</span></tt>”.  It creates a diagnostic and
+accepts the arguments, ranges, and other information that goes along with it.</p>
+<p>For example, the binary expression error comes from code like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">various</span> <span class="n">things</span> <span class="n">that</span> <span class="n">are</span> <span class="n">bad</span><span class="p">)</span>
+  <span class="n">Diag</span><span class="p">(</span><span class="n">Loc</span><span class="p">,</span> <span class="n">diag</span><span class="o">::</span><span class="n">err_typecheck_invalid_operands</span><span class="p">)</span>
+    <span class="o"><<</span> <span class="n">lex</span><span class="o">-></span><span class="n">getType</span><span class="p">()</span> <span class="o"><<</span> <span class="n">rex</span><span class="o">-></span><span class="n">getType</span><span class="p">()</span>
+    <span class="o"><<</span> <span class="n">lex</span><span class="o">-></span><span class="n">getSourceRange</span><span class="p">()</span> <span class="o"><<</span> <span class="n">rex</span><span class="o">-></span><span class="n">getSourceRange</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>This shows that use of the <tt class="docutils literal"><span class="pre">Diag</span></tt> method: it takes a location (a
+<a class="reference internal" href="#sourcelocation"><em>SourceLocation</em></a> object) and a diagnostic enum value
+(which matches the name from <tt class="docutils literal"><span class="pre">Diagnostic*Kinds.td</span></tt>).  If the diagnostic takes
+arguments, they are specified with the <tt class="docutils literal"><span class="pre"><<</span></tt> operator: the first argument
+becomes <tt class="docutils literal"><span class="pre">%0</span></tt>, the second becomes <tt class="docutils literal"><span class="pre">%1</span></tt>, etc.  The diagnostic interface
+allows you to specify arguments of many different types, including <tt class="docutils literal"><span class="pre">int</span></tt> and
+<tt class="docutils literal"><span class="pre">unsigned</span></tt> for integer arguments, <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt> and <tt class="docutils literal"><span class="pre">std::string</span></tt> for
+string arguments, <tt class="docutils literal"><span class="pre">DeclarationName</span></tt> and <tt class="docutils literal"><span class="pre">const</span> <span class="pre">IdentifierInfo</span> <span class="pre">*</span></tt> for names,
+<tt class="docutils literal"><span class="pre">QualType</span></tt> for types, etc.  <tt class="docutils literal"><span class="pre">SourceRange</span></tt>s are also specified with the
+<tt class="docutils literal"><span class="pre"><<</span></tt> operator, but do not have a specific ordering requirement.</p>
+<p>As you can see, adding and producing a diagnostic is pretty straightforward.
+The hard part is deciding exactly what you need to say to help the user,
+picking a suitable wording, and providing the information needed to format it
+correctly.  The good news is that the call site that issues a diagnostic should
+be completely independent of how the diagnostic is formatted and in what
+language it is rendered.</p>
+</div>
+<div class="section" id="fix-it-hints">
+<h4><a class="toc-backref" href="#id9">Fix-It Hints</a><a class="headerlink" href="#fix-it-hints" title="Permalink to this headline">Â¶</a></h4>
+<p>In some cases, the front end emits diagnostics when it is clear that some small
+change to the source code would fix the problem.  For example, a missing
+semicolon at the end of a statement or a use of deprecated syntax that is
+easily rewritten into a more modern form.  Clang tries very hard to emit the
+diagnostic and recover gracefully in these and other cases.</p>
+<p>However, for these cases where the fix is obvious, the diagnostic can be
+annotated with a hint (referred to as a “fix-it hint”) that describes how to
+change the code referenced by the diagnostic to fix the problem.  For example,
+it might add the missing semicolon at the end of the statement or rewrite the
+use of a deprecated construct into something more palatable.  Here is one such
+example from the C++ front end, where we warn about the right-shift operator
+changing meaning from C++98 to C++11:</p>
+<div class="highlight-c++"><pre>test.cpp:3:7: warning: use of right-shift operator ('>>') in template argument
+                       will require parentheses in C++11
+A<100 >> 2> *a;
+      ^
+  (       )</pre>
+</div>
+<p>Here, the fix-it hint is suggesting that parentheses be added, and showing
+exactly where those parentheses would be inserted into the source code.  The
+fix-it hints themselves describe what changes to make to the source code in an
+abstract manner, which the text diagnostic printer renders as a line of
+“insertions” below the caret line.  <a class="reference internal" href="#diagnosticclient"><em>Other diagnostic clients</em></a> might choose to render the code differently (e.g., as
+markup inline) or even give the user the ability to automatically fix the
+problem.</p>
+<p>Fix-it hints on errors and warnings need to obey these rules:</p>
+<ul class="simple">
+<li>Since they are automatically applied if <tt class="docutils literal"><span class="pre">-Xclang</span> <span class="pre">-fixit</span></tt> is passed to the
+driver, they should only be used when it’s very likely they match the user’s
+intent.</li>
+<li>Clang must recover from errors as if the fix-it had been applied.</li>
+</ul>
+<p>If a fix-it can’t obey these rules, put the fix-it on a note.  Fix-its on notes
+are not applied automatically.</p>
+<p>All fix-it hints are described by the <tt class="docutils literal"><span class="pre">FixItHint</span></tt> class, instances of which
+should be attached to the diagnostic using the <tt class="docutils literal"><span class="pre"><<</span></tt> operator in the same way
+that highlighted source ranges and arguments are passed to the diagnostic.
+Fix-it hints can be created with one of three constructors:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">FixItHint::CreateInsertion(Loc,</span> <span class="pre">Code)</span></tt></p>
+<blockquote>
+<div><p>Specifies that the given <tt class="docutils literal"><span class="pre">Code</span></tt> (a string) should be inserted before the
+source location <tt class="docutils literal"><span class="pre">Loc</span></tt>.</p>
+</div></blockquote>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">FixItHint::CreateRemoval(Range)</span></tt></p>
+<blockquote>
+<div><p>Specifies that the code in the given source <tt class="docutils literal"><span class="pre">Range</span></tt> should be removed.</p>
+</div></blockquote>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">FixItHint::CreateReplacement(Range,</span> <span class="pre">Code)</span></tt></p>
+<blockquote>
+<div><p>Specifies that the code in the given source <tt class="docutils literal"><span class="pre">Range</span></tt> should be removed,
+and replaced with the given <tt class="docutils literal"><span class="pre">Code</span></tt> string.</p>
+</div></blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="the-diagnosticclient-interface">
+<span id="diagnosticclient"></span><h4><a class="toc-backref" href="#id10">The <tt class="docutils literal"><span class="pre">DiagnosticClient</span></tt> Interface</a><a class="headerlink" href="#the-diagnosticclient-interface" title="Permalink to this headline">Â¶</a></h4>
+<p>Once code generates a diagnostic with all of the arguments and the rest of the
+relevant information, Clang needs to know what to do with it.  As previously
+mentioned, the diagnostic machinery goes through some filtering to map a
+severity onto a diagnostic level, then (assuming the diagnostic is not mapped
+to “<tt class="docutils literal"><span class="pre">Ignore</span></tt>”) it invokes an object that implements the <tt class="docutils literal"><span class="pre">DiagnosticClient</span></tt>
+interface with the information.</p>
+<p>It is possible to implement this interface in many different ways.  For
+example, the normal Clang <tt class="docutils literal"><span class="pre">DiagnosticClient</span></tt> (named
+<tt class="docutils literal"><span class="pre">TextDiagnosticPrinter</span></tt>) turns the arguments into strings (according to the
+various formatting rules), prints out the file/line/column information and the
+string, then prints out the line of code, the source ranges, and the caret.
+However, this behavior isn’t required.</p>
+<p>Another implementation of the <tt class="docutils literal"><span class="pre">DiagnosticClient</span></tt> interface is the
+<tt class="docutils literal"><span class="pre">TextDiagnosticBuffer</span></tt> class, which is used when Clang is in <tt class="docutils literal"><span class="pre">-verify</span></tt>
+mode.  Instead of formatting and printing out the diagnostics, this
+implementation just captures and remembers the diagnostics as they fly by.
+Then <tt class="docutils literal"><span class="pre">-verify</span></tt> compares the list of produced diagnostics to the list of
+expected ones.  If they disagree, it prints out its own output.  Full
+documentation for the <tt class="docutils literal"><span class="pre">-verify</span></tt> mode can be found in the Clang API
+documentation for <a class="reference external" href="/doxygen/classclang_1_1VerifyDiagnosticConsumer.html#details">VerifyDiagnosticConsumer</a>.</p>
+<p>There are many other possible implementations of this interface, and this is
+why we prefer diagnostics to pass down rich structured information in
+arguments.  For example, an HTML output might want declaration names be
+linkified to where they come from in the source.  Another example is that a GUI
+might let you click on typedefs to expand them.  This application would want to
+pass significantly more information about types through to the GUI than a
+simple flat string.  The interface allows this to happen.</p>
+</div>
+<div class="section" id="adding-translations-to-clang">
+<span id="internals-diag-translation"></span><h4><a class="toc-backref" href="#id11">Adding Translations to Clang</a><a class="headerlink" href="#adding-translations-to-clang" title="Permalink to this headline">Â¶</a></h4>
+<p>Not possible yet! Diagnostic strings should be written in UTF-8, the client can
+translate to the relevant code page if needed.  Each translation completely
+replaces the format string for the diagnostic.</p>
+</div>
+</div>
+<div class="section" id="the-sourcelocation-and-sourcemanager-classes">
+<span id="sourcemanager"></span><span id="sourcelocation"></span><h3><a class="toc-backref" href="#id12">The <tt class="docutils literal"><span class="pre">SourceLocation</span></tt> and <tt class="docutils literal"><span class="pre">SourceManager</span></tt> classes</a><a class="headerlink" href="#the-sourcelocation-and-sourcemanager-classes" title="Permalink to this headline">Â¶</a></h3>
+<p>Strangely enough, the <tt class="docutils literal"><span class="pre">SourceLocation</span></tt> class represents a location within the
+source code of the program.  Important design points include:</p>
+<ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">sizeof(SourceLocation)</span></tt> must be extremely small, as these are embedded
+into many AST nodes and are passed around often.  Currently it is 32 bits.</li>
+<li><tt class="docutils literal"><span class="pre">SourceLocation</span></tt> must be a simple value object that can be efficiently
+copied.</li>
+<li>We should be able to represent a source location for any byte of any input
+file.  This includes in the middle of tokens, in whitespace, in trigraphs,
+etc.</li>
+<li>A <tt class="docutils literal"><span class="pre">SourceLocation</span></tt> must encode the current <tt class="docutils literal"><span class="pre">#include</span></tt> stack that was
+active when the location was processed.  For example, if the location
+corresponds to a token, it should contain the set of <tt class="docutils literal"><span class="pre">#include</span></tt>s active
+when the token was lexed.  This allows us to print the <tt class="docutils literal"><span class="pre">#include</span></tt> stack
+for a diagnostic.</li>
+<li><tt class="docutils literal"><span class="pre">SourceLocation</span></tt> must be able to describe macro expansions, capturing both
+the ultimate instantiation point and the source of the original character
+data.</li>
+</ol>
+<p>In practice, the <tt class="docutils literal"><span class="pre">SourceLocation</span></tt> works together with the <tt class="docutils literal"><span class="pre">SourceManager</span></tt>
+class to encode two pieces of information about a location: its spelling
+location and its instantiation location.  For most tokens, these will be the
+same.  However, for a macro expansion (or tokens that came from a <tt class="docutils literal"><span class="pre">_Pragma</span></tt>
+directive) these will describe the location of the characters corresponding to
+the token and the location where the token was used (i.e., the macro
+instantiation point or the location of the <tt class="docutils literal"><span class="pre">_Pragma</span></tt> itself).</p>
+<p>The Clang front-end inherently depends on the location of a token being tracked
+correctly.  If it is ever incorrect, the front-end may get confused and die.
+The reason for this is that the notion of the “spelling” of a <tt class="docutils literal"><span class="pre">Token</span></tt> in
+Clang depends on being able to find the original input characters for the
+token.  This concept maps directly to the “spelling location” for the token.</p>
+</div>
+<div class="section" id="sourcerange-and-charsourcerange">
+<h3><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">SourceRange</span></tt> and <tt class="docutils literal"><span class="pre">CharSourceRange</span></tt></a><a class="headerlink" href="#sourcerange-and-charsourcerange" title="Permalink to this headline">Â¶</a></h3>
+<p>Clang represents most source ranges by [first, last], where “first” and “last”
+each point to the beginning of their respective tokens.  For example consider
+the <tt class="docutils literal"><span class="pre">SourceRange</span></tt> of the following statement:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">x</span> <span class="o">=</span> <span class="n">foo</span> <span class="o">+</span> <span class="n">bar</span><span class="p">;</span>
+<span class="o">^</span><span class="n">first</span>    <span class="o">^</span><span class="n">last</span>
+</pre></div>
+</div>
+<p>To map from this representation to a character-based representation, the “last”
+location needs to be adjusted to point to (or past) the end of that token with
+either <tt class="docutils literal"><span class="pre">Lexer::MeasureTokenLength()</span></tt> or <tt class="docutils literal"><span class="pre">Lexer::getLocForEndOfToken()</span></tt>.  For
+the rare cases where character-level source ranges information is needed we use
+the <tt class="docutils literal"><span class="pre">CharSourceRange</span></tt> class.</p>
+</div>
+</div>
+<div class="section" id="the-driver-library">
+<h2><a class="toc-backref" href="#id14">The Driver Library</a><a class="headerlink" href="#the-driver-library" title="Permalink to this headline">Â¶</a></h2>
+<p>The clang Driver and library are documented <a class="reference internal" href="DriverInternals.html"><em>here</em></a>.</p>
+</div>
+<div class="section" id="precompiled-headers">
+<h2><a class="toc-backref" href="#id15">Precompiled Headers</a><a class="headerlink" href="#precompiled-headers" title="Permalink to this headline">Â¶</a></h2>
+<p>Clang supports two implementations of precompiled headers.  The default
+implementation, precompiled headers (<a class="reference internal" href="PCHInternals.html"><em>PCH</em></a>) uses a
+serialized representation of Clang’s internal data structures, encoded with the
+<a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM bitstream format</a>.
+Pretokenized headers (<a class="reference internal" href="PTHInternals.html"><em>PTH</em></a>), on the other hand, contain a
+serialized representation of the tokens encountered when preprocessing a header
+(and anything that header includes).</p>
+</div>
+<div class="section" id="the-frontend-library">
+<h2><a class="toc-backref" href="#id16">The Frontend Library</a><a class="headerlink" href="#the-frontend-library" title="Permalink to this headline">Â¶</a></h2>
+<p>The Frontend library contains functionality useful for building tools on top of
+the Clang libraries, for example several methods for outputting diagnostics.</p>
+</div>
+<div class="section" id="the-lexer-and-preprocessor-library">
+<h2><a class="toc-backref" href="#id17">The Lexer and Preprocessor Library</a><a class="headerlink" href="#the-lexer-and-preprocessor-library" title="Permalink to this headline">Â¶</a></h2>
+<p>The Lexer library contains several tightly-connected classes that are involved
+with the nasty process of lexing and preprocessing C source code.  The main
+interface to this library for outside clients is the large <tt class="docutils literal"><span class="pre">Preprocessor</span></tt>
+class.  It contains the various pieces of state that are required to coherently
+read tokens out of a translation unit.</p>
+<p>The core interface to the <tt class="docutils literal"><span class="pre">Preprocessor</span></tt> object (once it is set up) is the
+<tt class="docutils literal"><span class="pre">Preprocessor::Lex</span></tt> method, which returns the next <a class="reference internal" href="#token"><em>Token</em></a> from
+the preprocessor stream.  There are two types of token providers that the
+preprocessor is capable of reading from: a buffer lexer (provided by the
+<a class="reference internal" href="#lexer"><em>Lexer</em></a> class) and a buffered token stream (provided by the
+<a class="reference internal" href="#tokenlexer"><em>TokenLexer</em></a> class).</p>
+<div class="section" id="the-token-class">
+<span id="token"></span><h3><a class="toc-backref" href="#id18">The Token class</a><a class="headerlink" href="#the-token-class" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">Token</span></tt> class is used to represent a single lexed token.  Tokens are
+intended to be used by the lexer/preprocess and parser libraries, but are not
+intended to live beyond them (for example, they should not live in the ASTs).</p>
+<p>Tokens most often live on the stack (or some other location that is efficient
+to access) as the parser is running, but occasionally do get buffered up.  For
+example, macro definitions are stored as a series of tokens, and the C++
+front-end periodically needs to buffer tokens up for tentative parsing and
+various pieces of look-ahead.  As such, the size of a <tt class="docutils literal"><span class="pre">Token</span></tt> matters.  On a
+32-bit system, <tt class="docutils literal"><span class="pre">sizeof(Token)</span></tt> is currently 16 bytes.</p>
+<p>Tokens occur in two forms: <a class="reference internal" href="#annotationtoken"><em>annotation tokens</em></a> and
+normal tokens.  Normal tokens are those returned by the lexer, annotation
+tokens represent semantic information and are produced by the parser, replacing
+normal tokens in the token stream.  Normal tokens contain the following
+information:</p>
+<ul class="simple">
+<li><strong>A SourceLocation</strong> — This indicates the location of the start of the
+token.</li>
+<li><strong>A length</strong> — This stores the length of the token as stored in the
+<tt class="docutils literal"><span class="pre">SourceBuffer</span></tt>.  For tokens that include them, this length includes
+trigraphs and escaped newlines which are ignored by later phases of the
+compiler.  By pointing into the original source buffer, it is always possible
+to get the original spelling of a token completely accurately.</li>
+<li><strong>IdentifierInfo</strong> — If a token takes the form of an identifier, and if
+identifier lookup was enabled when the token was lexed (e.g., the lexer was
+not reading in “raw” mode) this contains a pointer to the unique hash value
+for the identifier.  Because the lookup happens before keyword
+identification, this field is set even for language keywords like “<tt class="docutils literal"><span class="pre">for</span></tt>”.</li>
+<li><strong>TokenKind</strong> — This indicates the kind of token as classified by the
+lexer.  This includes things like <tt class="docutils literal"><span class="pre">tok::starequal</span></tt> (for the “<tt class="docutils literal"><span class="pre">*=</span></tt>”
+operator), <tt class="docutils literal"><span class="pre">tok::ampamp</span></tt> for the “<tt class="docutils literal"><span class="pre">&&</span></tt>” token, and keyword values (e.g.,
+<tt class="docutils literal"><span class="pre">tok::kw_for</span></tt>) for identifiers that correspond to keywords.  Note that
+some tokens can be spelled multiple ways.  For example, C++ supports
+“operator keywords”, where things like “<tt class="docutils literal"><span class="pre">and</span></tt>” are treated exactly like the
+“<tt class="docutils literal"><span class="pre">&&</span></tt>” operator.  In these cases, the kind value is set to <tt class="docutils literal"><span class="pre">tok::ampamp</span></tt>,
+which is good for the parser, which doesn’t have to consider both forms.  For
+something that cares about which form is used (e.g., the preprocessor
+“stringize” operator) the spelling indicates the original form.</li>
+<li><strong>Flags</strong> — There are currently four flags tracked by the
+lexer/preprocessor system on a per-token basis:<ol class="arabic">
+<li><strong>StartOfLine</strong> — This was the first token that occurred on its input
+source line.</li>
+<li><strong>LeadingSpace</strong> — There was a space character either immediately before
+the token or transitively before the token as it was expanded through a
+macro.  The definition of this flag is very closely defined by the
+stringizing requirements of the preprocessor.</li>
+<li><strong>DisableExpand</strong> — This flag is used internally to the preprocessor to
+represent identifier tokens which have macro expansion disabled.  This
+prevents them from being considered as candidates for macro expansion ever
+in the future.</li>
+<li><strong>NeedsCleaning</strong> — This flag is set if the original spelling for the
+token includes a trigraph or escaped newline.  Since this is uncommon,
+many pieces of code can fast-path on tokens that did not need cleaning.</li>
+</ol>
+</li>
+</ul>
+<p>One interesting (and somewhat unusual) aspect of normal tokens is that they
+don’t contain any semantic information about the lexed value.  For example, if
+the token was a pp-number token, we do not represent the value of the number
+that was lexed (this is left for later pieces of code to decide).
+Additionally, the lexer library has no notion of typedef names vs variable
+names: both are returned as identifiers, and the parser is left to decide
+whether a specific identifier is a typedef or a variable (tracking this
+requires scope information among other things).  The parser can do this
+translation by replacing tokens returned by the preprocessor with “Annotation
+Tokens”.</p>
+</div>
+<div class="section" id="annotation-tokens">
+<span id="annotationtoken"></span><h3><a class="toc-backref" href="#id19">Annotation Tokens</a><a class="headerlink" href="#annotation-tokens" title="Permalink to this headline">Â¶</a></h3>
+<p>Annotation tokens are tokens that are synthesized by the parser and injected
+into the preprocessor’s token stream (replacing existing tokens) to record
+semantic information found by the parser.  For example, if “<tt class="docutils literal"><span class="pre">foo</span></tt>” is found
+to be a typedef, the “<tt class="docutils literal"><span class="pre">foo</span></tt>” <tt class="docutils literal"><span class="pre">tok::identifier</span></tt> token is replaced with an
+<tt class="docutils literal"><span class="pre">tok::annot_typename</span></tt>.  This is useful for a couple of reasons: 1) this makes
+it easy to handle qualified type names (e.g., “<tt class="docutils literal"><span class="pre">foo::bar::baz<42>::t</span></tt>”) in
+C++ as a single “token” in the parser.  2) if the parser backtracks, the
+reparse does not need to redo semantic analysis to determine whether a token
+sequence is a variable, type, template, etc.</p>
+<p>Annotation tokens are created by the parser and reinjected into the parser’s
+token stream (when backtracking is enabled).  Because they can only exist in
+tokens that the preprocessor-proper is done with, it doesn’t need to keep
+around flags like “start of line” that the preprocessor uses to do its job.
+Additionally, an annotation token may “cover” a sequence of preprocessor tokens
+(e.g., “<tt class="docutils literal"><span class="pre">a::b::c</span></tt>” is five preprocessor tokens).  As such, the valid fields
+of an annotation token are different than the fields for a normal token (but
+they are multiplexed into the normal <tt class="docutils literal"><span class="pre">Token</span></tt> fields):</p>
+<ul class="simple">
+<li><strong>SourceLocation “Location”</strong> — The <tt class="docutils literal"><span class="pre">SourceLocation</span></tt> for the annotation
+token indicates the first token replaced by the annotation token.  In the
+example above, it would be the location of the “<tt class="docutils literal"><span class="pre">a</span></tt>” identifier.</li>
+<li><strong>SourceLocation “AnnotationEndLoc”</strong> — This holds the location of the last
+token replaced with the annotation token.  In the example above, it would be
+the location of the “<tt class="docutils literal"><span class="pre">c</span></tt>” identifier.</li>
+<li><strong>void* “AnnotationValue”</strong> — This contains an opaque object that the
+parser gets from <tt class="docutils literal"><span class="pre">Sema</span></tt>.  The parser merely preserves the information for
+<tt class="docutils literal"><span class="pre">Sema</span></tt> to later interpret based on the annotation token kind.</li>
+<li><strong>TokenKind “Kind”</strong> — This indicates the kind of Annotation token this is.
+See below for the different valid kinds.</li>
+</ul>
+<p>Annotation tokens currently come in three kinds:</p>
+<ol class="arabic simple">
+<li><strong>tok::annot_typename</strong>: This annotation token represents a resolved
+typename token that is potentially qualified.  The <tt class="docutils literal"><span class="pre">AnnotationValue</span></tt> field
+contains the <tt class="docutils literal"><span class="pre">QualType</span></tt> returned by <tt class="docutils literal"><span class="pre">Sema::getTypeName()</span></tt>, possibly with
+source location information attached.</li>
+<li><strong>tok::annot_cxxscope</strong>: This annotation token represents a C++ scope
+specifier, such as “<tt class="docutils literal"><span class="pre">A::B::</span></tt>”.  This corresponds to the grammar
+productions “<em>::</em>” and “<em>:: [opt] nested-name-specifier</em>”.  The
+<tt class="docutils literal"><span class="pre">AnnotationValue</span></tt> pointer is a <tt class="docutils literal"><span class="pre">NestedNameSpecifier</span> <span class="pre">*</span></tt> returned by the
+<tt class="docutils literal"><span class="pre">Sema::ActOnCXXGlobalScopeSpecifier</span></tt> and
+<tt class="docutils literal"><span class="pre">Sema::ActOnCXXNestedNameSpecifier</span></tt> callbacks.</li>
+<li><strong>tok::annot_template_id</strong>: This annotation token represents a C++
+template-id such as “<tt class="docutils literal"><span class="pre">foo<int,</span> <span class="pre">4></span></tt>”, where “<tt class="docutils literal"><span class="pre">foo</span></tt>” is the name of a
+template.  The <tt class="docutils literal"><span class="pre">AnnotationValue</span></tt> pointer is a pointer to a <tt class="docutils literal"><span class="pre">malloc</span></tt>‘d
+<tt class="docutils literal"><span class="pre">TemplateIdAnnotation</span></tt> object.  Depending on the context, a parsed
+template-id that names a type might become a typename annotation token (if
+all we care about is the named type, e.g., because it occurs in a type
+specifier) or might remain a template-id token (if we want to retain more
+source location information or produce a new type, e.g., in a declaration of
+a class template specialization).  template-id annotation tokens that refer
+to a type can be “upgraded” to typename annotation tokens by the parser.</li>
+</ol>
+<p>As mentioned above, annotation tokens are not returned by the preprocessor,
+they are formed on demand by the parser.  This means that the parser has to be
+aware of cases where an annotation could occur and form it where appropriate.
+This is somewhat similar to how the parser handles Translation Phase 6 of C99:
+String Concatenation (see C99 5.1.1.2).  In the case of string concatenation,
+the preprocessor just returns distinct <tt class="docutils literal"><span class="pre">tok::string_literal</span></tt> and
+<tt class="docutils literal"><span class="pre">tok::wide_string_literal</span></tt> tokens and the parser eats a sequence of them
+wherever the grammar indicates that a string literal can occur.</p>
+<p>In order to do this, whenever the parser expects a <tt class="docutils literal"><span class="pre">tok::identifier</span></tt> or
+<tt class="docutils literal"><span class="pre">tok::coloncolon</span></tt>, it should call the <tt class="docutils literal"><span class="pre">TryAnnotateTypeOrScopeToken</span></tt> or
+<tt class="docutils literal"><span class="pre">TryAnnotateCXXScopeToken</span></tt> methods to form the annotation token.  These
+methods will maximally form the specified annotation tokens and replace the
+current token with them, if applicable.  If the current tokens is not valid for
+an annotation token, it will remain an identifier or “<tt class="docutils literal"><span class="pre">::</span></tt>” token.</p>
+</div>
+<div class="section" id="the-lexer-class">
+<span id="lexer"></span><h3><a class="toc-backref" href="#id20">The <tt class="docutils literal"><span class="pre">Lexer</span></tt> class</a><a class="headerlink" href="#the-lexer-class" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">Lexer</span></tt> class provides the mechanics of lexing tokens out of a source
+buffer and deciding what they mean.  The <tt class="docutils literal"><span class="pre">Lexer</span></tt> is complicated by the fact
+that it operates on raw buffers that have not had spelling eliminated (this is
+a necessity to get decent performance), but this is countered with careful
+coding as well as standard performance techniques (for example, the comment
+handling code is vectorized on X86 and PowerPC hosts).</p>
+<p>The lexer has a couple of interesting modal features:</p>
+<ul class="simple">
+<li>The lexer can operate in “raw” mode.  This mode has several features that
+make it possible to quickly lex the file (e.g., it stops identifier lookup,
+doesn’t specially handle preprocessor tokens, handles EOF differently, etc).
+This mode is used for lexing within an “<tt class="docutils literal"><span class="pre">#if</span> <span class="pre">0</span></tt>” block, for example.</li>
+<li>The lexer can capture and return comments as tokens.  This is required to
+support the <tt class="docutils literal"><span class="pre">-C</span></tt> preprocessor mode, which passes comments through, and is
+used by the diagnostic checker to identifier expect-error annotations.</li>
+<li>The lexer can be in <tt class="docutils literal"><span class="pre">ParsingFilename</span></tt> mode, which happens when
+preprocessing after reading a <tt class="docutils literal"><span class="pre">#include</span></tt> directive.  This mode changes the
+parsing of “<tt class="docutils literal"><span class="pre"><</span></tt>” to return an “angled string” instead of a bunch of tokens
+for each thing within the filename.</li>
+<li>When parsing a preprocessor directive (after “<tt class="docutils literal"><span class="pre">#</span></tt>”) the
+<tt class="docutils literal"><span class="pre">ParsingPreprocessorDirective</span></tt> mode is entered.  This changes the parser to
+return EOD at a newline.</li>
+<li>The <tt class="docutils literal"><span class="pre">Lexer</span></tt> uses a <tt class="docutils literal"><span class="pre">LangOptions</span></tt> object to know whether trigraphs are
+enabled, whether C++ or ObjC keywords are recognized, etc.</li>
+</ul>
+<p>In addition to these modes, the lexer keeps track of a couple of other features
+that are local to a lexed buffer, which change as the buffer is lexed:</p>
+<ul class="simple">
+<li>The <tt class="docutils literal"><span class="pre">Lexer</span></tt> uses <tt class="docutils literal"><span class="pre">BufferPtr</span></tt> to keep track of the current character being
+lexed.</li>
+<li>The <tt class="docutils literal"><span class="pre">Lexer</span></tt> uses <tt class="docutils literal"><span class="pre">IsAtStartOfLine</span></tt> to keep track of whether the next
+lexed token will start with its “start of line” bit set.</li>
+<li>The <tt class="docutils literal"><span class="pre">Lexer</span></tt> keeps track of the current “<tt class="docutils literal"><span class="pre">#if</span></tt>” directives that are active
+(which can be nested).</li>
+<li>The <tt class="docutils literal"><span class="pre">Lexer</span></tt> keeps track of an <a class="reference internal" href="#multipleincludeopt"><em>MultipleIncludeOpt</em></a> object, which is used to detect whether the buffer uses
+the standard “<tt class="docutils literal"><span class="pre">#ifndef</span> <span class="pre">XX</span></tt> / <tt class="docutils literal"><span class="pre">#define</span> <span class="pre">XX</span></tt>” idiom to prevent multiple
+inclusion.  If a buffer does, subsequent includes can be ignored if the
+“<tt class="docutils literal"><span class="pre">XX</span></tt>” macro is defined.</li>
+</ul>
+</div>
+<div class="section" id="the-tokenlexer-class">
+<span id="tokenlexer"></span><h3><a class="toc-backref" href="#id21">The <tt class="docutils literal"><span class="pre">TokenLexer</span></tt> class</a><a class="headerlink" href="#the-tokenlexer-class" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">TokenLexer</span></tt> class is a token provider that returns tokens from a list of
+tokens that came from somewhere else.  It typically used for two things: 1)
+returning tokens from a macro definition as it is being expanded 2) returning
+tokens from an arbitrary buffer of tokens.  The later use is used by
+<tt class="docutils literal"><span class="pre">_Pragma</span></tt> and will most likely be used to handle unbounded look-ahead for the
+C++ parser.</p>
+</div>
+<div class="section" id="the-multipleincludeopt-class">
+<span id="multipleincludeopt"></span><h3><a class="toc-backref" href="#id22">The <tt class="docutils literal"><span class="pre">MultipleIncludeOpt</span></tt> class</a><a class="headerlink" href="#the-multipleincludeopt-class" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">MultipleIncludeOpt</span></tt> class implements a really simple little state
+machine that is used to detect the standard “<tt class="docutils literal"><span class="pre">#ifndef</span> <span class="pre">XX</span></tt> / <tt class="docutils literal"><span class="pre">#define</span> <span class="pre">XX</span></tt>”
+idiom that people typically use to prevent multiple inclusion of headers.  If a
+buffer uses this idiom and is subsequently <tt class="docutils literal"><span class="pre">#include</span></tt>‘d, the preprocessor can
+simply check to see whether the guarding condition is defined or not.  If so,
+the preprocessor can completely ignore the include of the header.</p>
+</div>
+</div>
+<div class="section" id="the-parser-library">
+<h2><a class="toc-backref" href="#id23">The Parser Library</a><a class="headerlink" href="#the-parser-library" title="Permalink to this headline">Â¶</a></h2>
+</div>
+<div class="section" id="the-ast-library">
+<h2><a class="toc-backref" href="#id24">The AST Library</a><a class="headerlink" href="#the-ast-library" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="the-type-class-and-its-subclasses">
+<span id="type"></span><h3><a class="toc-backref" href="#id25">The <tt class="docutils literal"><span class="pre">Type</span></tt> class and its subclasses</a><a class="headerlink" href="#the-type-class-and-its-subclasses" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">Type</span></tt> class (and its subclasses) are an important part of the AST.
+Types are accessed through the <tt class="docutils literal"><span class="pre">ASTContext</span></tt> class, which implicitly creates
+and uniques them as they are needed.  Types have a couple of non-obvious
+features: 1) they do not capture type qualifiers like <tt class="docutils literal"><span class="pre">const</span></tt> or <tt class="docutils literal"><span class="pre">volatile</span></tt>
+(see <a class="reference internal" href="#qualtype"><em>QualType</em></a>), and 2) they implicitly capture typedef
+information.  Once created, types are immutable (unlike decls).</p>
+<p>Typedefs in C make semantic analysis a bit more complex than it would be without
+them.  The issue is that we want to capture typedef information and represent it
+in the AST perfectly, but the semantics of operations need to “see through”
+typedefs.  For example, consider this code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">func</span><span class="p">()</span> <span class="p">{</span>
+  <span class="k">typedef</span> <span class="kt">int</span> <span class="n">foo</span><span class="p">;</span>
+  <span class="n">foo</span> <span class="n">X</span><span class="p">,</span> <span class="o">*</span><span class="n">Y</span><span class="p">;</span>
+  <span class="k">typedef</span> <span class="n">foo</span> <span class="o">*</span><span class="n">bar</span><span class="p">;</span>
+  <span class="n">bar</span> <span class="n">Z</span><span class="p">;</span>
+  <span class="o">*</span><span class="n">X</span><span class="p">;</span> <span class="c1">// error</span>
+  <span class="o">**</span><span class="n">Y</span><span class="p">;</span> <span class="c1">// error</span>
+  <span class="o">**</span><span class="n">Z</span><span class="p">;</span> <span class="c1">// error</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The code above is illegal, and thus we expect there to be diagnostics emitted
+on the annotated lines.  In this example, we expect to get:</p>
+<div class="highlight-c++"><pre>test.c:6:1: error: indirection requires pointer operand ('foo' invalid)
+  *X; // error
+  ^~
+test.c:7:1: error: indirection requires pointer operand ('foo' invalid)
+  **Y; // error
+  ^~~
+test.c:8:1: error: indirection requires pointer operand ('foo' invalid)
+  **Z; // error
+  ^~~</pre>
+</div>
+<p>While this example is somewhat silly, it illustrates the point: we want to
+retain typedef information where possible, so that we can emit errors about
+“<tt class="docutils literal"><span class="pre">std::string</span></tt>” instead of “<tt class="docutils literal"><span class="pre">std::basic_string<char,</span> <span class="pre">std:...</span></tt>”.  Doing this
+requires properly keeping typedef information (for example, the type of <tt class="docutils literal"><span class="pre">X</span></tt>
+is “<tt class="docutils literal"><span class="pre">foo</span></tt>”, not “<tt class="docutils literal"><span class="pre">int</span></tt>”), and requires properly propagating it through the
+various operators (for example, the type of <tt class="docutils literal"><span class="pre">*Y</span></tt> is “<tt class="docutils literal"><span class="pre">foo</span></tt>”, not
+“<tt class="docutils literal"><span class="pre">int</span></tt>”).  In order to retain this information, the type of these expressions
+is an instance of the <tt class="docutils literal"><span class="pre">TypedefType</span></tt> class, which indicates that the type of
+these expressions is a typedef for “<tt class="docutils literal"><span class="pre">foo</span></tt>”.</p>
+<p>Representing types like this is great for diagnostics, because the
+user-specified type is always immediately available.  There are two problems
+with this: first, various semantic checks need to make judgements about the
+<em>actual structure</em> of a type, ignoring typedefs.  Second, we need an efficient
+way to query whether two types are structurally identical to each other,
+ignoring typedefs.  The solution to both of these problems is the idea of
+canonical types.</p>
+<div class="section" id="canonical-types">
+<h4><a class="toc-backref" href="#id26">Canonical Types</a><a class="headerlink" href="#canonical-types" title="Permalink to this headline">Â¶</a></h4>
+<p>Every instance of the <tt class="docutils literal"><span class="pre">Type</span></tt> class contains a canonical type pointer.  For
+simple types with no typedefs involved (e.g., “<tt class="docutils literal"><span class="pre">int</span></tt>”, “<tt class="docutils literal"><span class="pre">int*</span></tt>”,
+“<tt class="docutils literal"><span class="pre">int**</span></tt>”), the type just points to itself.  For types that have a typedef
+somewhere in their structure (e.g., “<tt class="docutils literal"><span class="pre">foo</span></tt>”, “<tt class="docutils literal"><span class="pre">foo*</span></tt>”, “<tt class="docutils literal"><span class="pre">foo**</span></tt>”,
+“<tt class="docutils literal"><span class="pre">bar</span></tt>”), the canonical type pointer points to their structurally equivalent
+type without any typedefs (e.g., “<tt class="docutils literal"><span class="pre">int</span></tt>”, “<tt class="docutils literal"><span class="pre">int*</span></tt>”, “<tt class="docutils literal"><span class="pre">int**</span></tt>”, and
+“<tt class="docutils literal"><span class="pre">int*</span></tt>” respectively).</p>
+<p>This design provides a constant time operation (dereferencing the canonical type
+pointer) that gives us access to the structure of types.  For example, we can
+trivially tell that “<tt class="docutils literal"><span class="pre">bar</span></tt>” and “<tt class="docutils literal"><span class="pre">foo*</span></tt>” are the same type by dereferencing
+their canonical type pointers and doing a pointer comparison (they both point
+to the single “<tt class="docutils literal"><span class="pre">int*</span></tt>” type).</p>
+<p>Canonical types and typedef types bring up some complexities that must be
+carefully managed.  Specifically, the <tt class="docutils literal"><span class="pre">isa</span></tt>/<tt class="docutils literal"><span class="pre">cast</span></tt>/<tt class="docutils literal"><span class="pre">dyn_cast</span></tt> operators
+generally shouldn’t be used in code that is inspecting the AST.  For example,
+when type checking the indirection operator (unary “<tt class="docutils literal"><span class="pre">*</span></tt>” on a pointer), the
+type checker must verify that the operand has a pointer type.  It would not be
+correct to check that with “<tt class="docutils literal"><span class="pre">isa<PointerType>(SubExpr->getType())</span></tt>”, because
+this predicate would fail if the subexpression had a typedef type.</p>
+<p>The solution to this problem are a set of helper methods on <tt class="docutils literal"><span class="pre">Type</span></tt>, used to
+check their properties.  In this case, it would be correct to use
+“<tt class="docutils literal"><span class="pre">SubExpr->getType()->isPointerType()</span></tt>” to do the check.  This predicate will
+return true if the <em>canonical type is a pointer</em>, which is true any time the
+type is structurally a pointer type.  The only hard part here is remembering
+not to use the <tt class="docutils literal"><span class="pre">isa</span></tt>/<tt class="docutils literal"><span class="pre">cast</span></tt>/<tt class="docutils literal"><span class="pre">dyn_cast</span></tt> operations.</p>
+<p>The second problem we face is how to get access to the pointer type once we
+know it exists.  To continue the example, the result type of the indirection
+operator is the pointee type of the subexpression.  In order to determine the
+type, we need to get the instance of <tt class="docutils literal"><span class="pre">PointerType</span></tt> that best captures the
+typedef information in the program.  If the type of the expression is literally
+a <tt class="docutils literal"><span class="pre">PointerType</span></tt>, we can return that, otherwise we have to dig through the
+typedefs to find the pointer type.  For example, if the subexpression had type
+“<tt class="docutils literal"><span class="pre">foo*</span></tt>”, we could return that type as the result.  If the subexpression had
+type “<tt class="docutils literal"><span class="pre">bar</span></tt>”, we want to return “<tt class="docutils literal"><span class="pre">foo*</span></tt>” (note that we do <em>not</em> want
+“<tt class="docutils literal"><span class="pre">int*</span></tt>”).  In order to provide all of this, <tt class="docutils literal"><span class="pre">Type</span></tt> has a
+<tt class="docutils literal"><span class="pre">getAsPointerType()</span></tt> method that checks whether the type is structurally a
+<tt class="docutils literal"><span class="pre">PointerType</span></tt> and, if so, returns the best one.  If not, it returns a null
+pointer.</p>
+<p>This structure is somewhat mystical, but after meditating on it, it will make
+sense to you :).</p>
+</div>
+</div>
+<div class="section" id="the-qualtype-class">
+<span id="qualtype"></span><h3><a class="toc-backref" href="#id27">The <tt class="docutils literal"><span class="pre">QualType</span></tt> class</a><a class="headerlink" href="#the-qualtype-class" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">QualType</span></tt> class is designed as a trivial value class that is small,
+passed by-value and is efficient to query.  The idea of <tt class="docutils literal"><span class="pre">QualType</span></tt> is that it
+stores the type qualifiers (<tt class="docutils literal"><span class="pre">const</span></tt>, <tt class="docutils literal"><span class="pre">volatile</span></tt>, <tt class="docutils literal"><span class="pre">restrict</span></tt>, plus some
+extended qualifiers required by language extensions) separately from the types
+themselves.  <tt class="docutils literal"><span class="pre">QualType</span></tt> is conceptually a pair of “<tt class="docutils literal"><span class="pre">Type*</span></tt>” and the bits
+for these type qualifiers.</p>
+<p>By storing the type qualifiers as bits in the conceptual pair, it is extremely
+efficient to get the set of qualifiers on a <tt class="docutils literal"><span class="pre">QualType</span></tt> (just return the field
+of the pair), add a type qualifier (which is a trivial constant-time operation
+that sets a bit), and remove one or more type qualifiers (just return a
+<tt class="docutils literal"><span class="pre">QualType</span></tt> with the bitfield set to empty).</p>
+<p>Further, because the bits are stored outside of the type itself, we do not need
+to create duplicates of types with different sets of qualifiers (i.e. there is
+only a single heap allocated “<tt class="docutils literal"><span class="pre">int</span></tt>” type: “<tt class="docutils literal"><span class="pre">const</span> <span class="pre">int</span></tt>” and “<tt class="docutils literal"><span class="pre">volatile</span>
+<span class="pre">const</span> <span class="pre">int</span></tt>” both point to the same heap allocated “<tt class="docutils literal"><span class="pre">int</span></tt>” type).  This
+reduces the heap size used to represent bits and also means we do not have to
+consider qualifiers when uniquing types (<a class="reference internal" href="#type"><em>Type</em></a> does not even
+contain qualifiers).</p>
+<p>In practice, the two most common type qualifiers (<tt class="docutils literal"><span class="pre">const</span></tt> and <tt class="docutils literal"><span class="pre">restrict</span></tt>)
+are stored in the low bits of the pointer to the <tt class="docutils literal"><span class="pre">Type</span></tt> object, together with
+a flag indicating whether extended qualifiers are present (which must be
+heap-allocated).  This means that <tt class="docutils literal"><span class="pre">QualType</span></tt> is exactly the same size as a
+pointer.</p>
+</div>
+<div class="section" id="declaration-names">
+<span id="declarationname"></span><h3><a class="toc-backref" href="#id28">Declaration names</a><a class="headerlink" href="#declaration-names" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">DeclarationName</span></tt> class represents the name of a declaration in Clang.
+Declarations in the C family of languages can take several different forms.
+Most declarations are named by simple identifiers, e.g., “<tt class="docutils literal"><span class="pre">f</span></tt>” and “<tt class="docutils literal"><span class="pre">x</span></tt>” in
+the function declaration <tt class="docutils literal"><span class="pre">f(int</span> <span class="pre">x)</span></tt>.  In C++, declaration names can also name
+class constructors (“<tt class="docutils literal"><span class="pre">Class</span></tt>” in <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">Class</span> <span class="pre">{</span> <span class="pre">Class();</span> <span class="pre">}</span></tt>), class
+destructors (“<tt class="docutils literal"><span class="pre">~Class</span></tt>”), overloaded operator names (“<tt class="docutils literal"><span class="pre">operator+</span></tt>”), and
+conversion functions (“<tt class="docutils literal"><span class="pre">operator</span> <span class="pre">void</span> <span class="pre">const</span> <span class="pre">*</span></tt>”).  In Objective-C,
+declaration names can refer to the names of Objective-C methods, which involve
+the method name and the parameters, collectively called a <em>selector</em>, e.g.,
+“<tt class="docutils literal"><span class="pre">setWidth:height:</span></tt>”.  Since all of these kinds of entities — variables,
+functions, Objective-C methods, C++ constructors, destructors, and operators
+— are represented as subclasses of Clang’s common <tt class="docutils literal"><span class="pre">NamedDecl</span></tt> class,
+<tt class="docutils literal"><span class="pre">DeclarationName</span></tt> is designed to efficiently represent any kind of name.</p>
+<p>Given a <tt class="docutils literal"><span class="pre">DeclarationName</span></tt> <tt class="docutils literal"><span class="pre">N</span></tt>, <tt class="docutils literal"><span class="pre">N.getNameKind()</span></tt> will produce a value
+that describes what kind of name <tt class="docutils literal"><span class="pre">N</span></tt> stores.  There are 10 options (all of
+the names are inside the <tt class="docutils literal"><span class="pre">DeclarationName</span></tt> class).</p>
+<p><tt class="docutils literal"><span class="pre">Identifier</span></tt></p>
+<blockquote>
+<div>The name is a simple identifier.  Use <tt class="docutils literal"><span class="pre">N.getAsIdentifierInfo()</span></tt> to retrieve
+the corresponding <tt class="docutils literal"><span class="pre">IdentifierInfo*</span></tt> pointing to the actual identifier.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">ObjCZeroArgSelector</span></tt>, <tt class="docutils literal"><span class="pre">ObjCOneArgSelector</span></tt>, <tt class="docutils literal"><span class="pre">ObjCMultiArgSelector</span></tt></p>
+<blockquote>
+<div>The name is an Objective-C selector, which can be retrieved as a <tt class="docutils literal"><span class="pre">Selector</span></tt>
+instance via <tt class="docutils literal"><span class="pre">N.getObjCSelector()</span></tt>.  The three possible name kinds for
+Objective-C reflect an optimization within the <tt class="docutils literal"><span class="pre">DeclarationName</span></tt> class:
+both zero- and one-argument selectors are stored as a masked
+<tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> pointer, and therefore require very little space, since
+zero- and one-argument selectors are far more common than multi-argument
+selectors (which use a different structure).</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">CXXConstructorName</span></tt></p>
+<blockquote>
+<div>The name is a C++ constructor name.  Use <tt class="docutils literal"><span class="pre">N.getCXXNameType()</span></tt> to retrieve
+the <a class="reference internal" href="#qualtype"><em>type</em></a> that this constructor is meant to construct.  The
+type is always the canonical type, since all constructors for a given type
+have the same name.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">CXXDestructorName</span></tt></p>
+<blockquote>
+<div>The name is a C++ destructor name.  Use <tt class="docutils literal"><span class="pre">N.getCXXNameType()</span></tt> to retrieve
+the <a class="reference internal" href="#qualtype"><em>type</em></a> whose destructor is being named.  This type is
+always a canonical type.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">CXXConversionFunctionName</span></tt></p>
+<blockquote>
+<div>The name is a C++ conversion function.  Conversion functions are named
+according to the type they convert to, e.g., “<tt class="docutils literal"><span class="pre">operator</span> <span class="pre">void</span> <span class="pre">const</span> <span class="pre">*</span></tt>”.
+Use <tt class="docutils literal"><span class="pre">N.getCXXNameType()</span></tt> to retrieve the type that this conversion function
+converts to.  This type is always a canonical type.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">CXXOperatorName</span></tt></p>
+<blockquote>
+<div>The name is a C++ overloaded operator name.  Overloaded operators are named
+according to their spelling, e.g., “<tt class="docutils literal"><span class="pre">operator+</span></tt>” or “<tt class="docutils literal"><span class="pre">operator</span> <span class="pre">new</span> <span class="pre">[]</span></tt>”.
+Use <tt class="docutils literal"><span class="pre">N.getCXXOverloadedOperator()</span></tt> to retrieve the overloaded operator (a
+value of type <tt class="docutils literal"><span class="pre">OverloadedOperatorKind</span></tt>).</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">CXXLiteralOperatorName</span></tt></p>
+<blockquote>
+<div>The name is a C++11 user defined literal operator.  User defined
+Literal operators are named according to the suffix they define,
+e.g., “<tt class="docutils literal"><span class="pre">_foo</span></tt>” for “<tt class="docutils literal"><span class="pre">operator</span> <span class="pre">""</span> <span class="pre">_foo</span></tt>”.  Use
+<tt class="docutils literal"><span class="pre">N.getCXXLiteralIdentifier()</span></tt> to retrieve the corresponding
+<tt class="docutils literal"><span class="pre">IdentifierInfo*</span></tt> pointing to the identifier.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">CXXUsingDirective</span></tt></p>
+<blockquote>
+<div>The name is a C++ using directive.  Using directives are not really
+NamedDecls, in that they all have the same name, but they are
+implemented as such in order to store them in DeclContext
+effectively.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">DeclarationName</span></tt>s are cheap to create, copy, and compare.  They require
+only a single pointer’s worth of storage in the common cases (identifiers,
+zero- and one-argument Objective-C selectors) and use dense, uniqued storage
+for the other kinds of names.  Two <tt class="docutils literal"><span class="pre">DeclarationName</span></tt>s can be compared for
+equality (<tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">!=</span></tt>) using a simple bitwise comparison, can be ordered
+with <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 <tt class="docutils literal"><span class="pre">>=</span></tt> (which provide a lexicographical ordering
+for normal identifiers but an unspecified ordering for other kinds of names),
+and can be placed into LLVM <tt class="docutils literal"><span class="pre">DenseMap</span></tt>s and <tt class="docutils literal"><span class="pre">DenseSet</span></tt>s.</p>
+<p><tt class="docutils literal"><span class="pre">DeclarationName</span></tt> instances can be created in different ways depending on
+what kind of name the instance will store.  Normal identifiers
+(<tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> pointers) and Objective-C selectors (<tt class="docutils literal"><span class="pre">Selector</span></tt>) can be
+implicitly converted to <tt class="docutils literal"><span class="pre">DeclarationNames</span></tt>.  Names for C++ constructors,
+destructors, conversion functions, and overloaded operators can be retrieved
+from the <tt class="docutils literal"><span class="pre">DeclarationNameTable</span></tt>, an instance of which is available as
+<tt class="docutils literal"><span class="pre">ASTContext::DeclarationNames</span></tt>.  The member functions
+<tt class="docutils literal"><span class="pre">getCXXConstructorName</span></tt>, <tt class="docutils literal"><span class="pre">getCXXDestructorName</span></tt>,
+<tt class="docutils literal"><span class="pre">getCXXConversionFunctionName</span></tt>, and <tt class="docutils literal"><span class="pre">getCXXOperatorName</span></tt>, respectively,
+return <tt class="docutils literal"><span class="pre">DeclarationName</span></tt> instances for the four kinds of C++ special function
+names.</p>
+</div>
+<div class="section" id="declaration-contexts">
+<span id="declcontext"></span><h3><a class="toc-backref" href="#id29">Declaration contexts</a><a class="headerlink" href="#declaration-contexts" title="Permalink to this headline">Â¶</a></h3>
+<p>Every declaration in a program exists within some <em>declaration context</em>, such
+as a translation unit, namespace, class, or function.  Declaration contexts in
+Clang are represented by the <tt class="docutils literal"><span class="pre">DeclContext</span></tt> class, from which the various
+declaration-context AST nodes (<tt class="docutils literal"><span class="pre">TranslationUnitDecl</span></tt>, <tt class="docutils literal"><span class="pre">NamespaceDecl</span></tt>,
+<tt class="docutils literal"><span class="pre">RecordDecl</span></tt>, <tt class="docutils literal"><span class="pre">FunctionDecl</span></tt>, etc.) will derive.  The <tt class="docutils literal"><span class="pre">DeclContext</span></tt> class
+provides several facilities common to each declaration context:</p>
+<p>Source-centric vs. Semantics-centric View of Declarations</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">DeclContext</span></tt> provides two views of the declarations stored within a
+declaration context.  The source-centric view accurately represents the
+program source code as written, including multiple declarations of entities
+where present (see the section <a class="reference internal" href="#redeclarations"><em>Redeclarations and Overloads</em></a>), while the semantics-centric view represents the program
+semantics.  The two views are kept synchronized by semantic analysis while
+the ASTs are being constructed.</div></blockquote>
+<p>Storage of declarations within that context</p>
+<blockquote>
+<div>Every declaration context can contain some number of declarations.  For
+example, a C++ class (represented by <tt class="docutils literal"><span class="pre">RecordDecl</span></tt>) contains various member
+functions, fields, nested types, and so on.  All of these declarations will
+be stored within the <tt class="docutils literal"><span class="pre">DeclContext</span></tt>, and one can iterate over the
+declarations via [<tt class="docutils literal"><span class="pre">DeclContext::decls_begin()</span></tt>,
+<tt class="docutils literal"><span class="pre">DeclContext::decls_end()</span></tt>).  This mechanism provides the source-centric
+view of declarations in the context.</div></blockquote>
+<p>Lookup of declarations within that context</p>
+<blockquote>
+<div>The <tt class="docutils literal"><span class="pre">DeclContext</span></tt> structure provides efficient name lookup for names within
+that declaration context.  For example, if <tt class="docutils literal"><span class="pre">N</span></tt> is a namespace we can look
+for the name <tt class="docutils literal"><span class="pre">N::f</span></tt> using <tt class="docutils literal"><span class="pre">DeclContext::lookup</span></tt>.  The lookup itself is
+based on a lazily-constructed array (for declaration contexts with a small
+number of declarations) or hash table (for declaration contexts with more
+declarations).  The lookup operation provides the semantics-centric view of
+the declarations in the context.</div></blockquote>
+<p>Ownership of declarations</p>
+<blockquote>
+<div>The <tt class="docutils literal"><span class="pre">DeclContext</span></tt> owns all of the declarations that were declared within
+its declaration context, and is responsible for the management of their
+memory as well as their (de-)serialization.</div></blockquote>
+<p>All declarations are stored within a declaration context, and one can query
+information about the context in which each declaration lives.  One can
+retrieve the <tt class="docutils literal"><span class="pre">DeclContext</span></tt> that contains a particular <tt class="docutils literal"><span class="pre">Decl</span></tt> using
+<tt class="docutils literal"><span class="pre">Decl::getDeclContext</span></tt>.  However, see the section
+<a class="reference internal" href="#lexicalandsemanticcontexts"><em>Lexical and Semantic Contexts</em></a> for more information about how to interpret
+this context information.</p>
+<div class="section" id="redeclarations-and-overloads">
+<span id="redeclarations"></span><h4><a class="toc-backref" href="#id30">Redeclarations and Overloads</a><a class="headerlink" href="#redeclarations-and-overloads" title="Permalink to this headline">Â¶</a></h4>
+<p>Within a translation unit, it is common for an entity to be declared several
+times.  For example, we might declare a function “<tt class="docutils literal"><span class="pre">f</span></tt>” and then later
+re-declare it as part of an inlined definition:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="kt">int</span> <span class="n">y</span><span class="p">,</span> <span class="kt">int</span> <span class="n">z</span> <span class="o">=</span> <span class="mi">1</span><span class="p">);</span>
+
+<span class="kr">inline</span> <span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="kt">int</span> <span class="n">y</span><span class="p">,</span> <span class="kt">int</span> <span class="n">z</span><span class="p">)</span> <span class="p">{</span> <span class="cm">/* ...  */</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>The representation of “<tt class="docutils literal"><span class="pre">f</span></tt>” differs in the source-centric and
+semantics-centric views of a declaration context.  In the source-centric view,
+all redeclarations will be present, in the order they occurred in the source
+code, making this view suitable for clients that wish to see the structure of
+the source code.  In the semantics-centric view, only the most recent “<tt class="docutils literal"><span class="pre">f</span></tt>”
+will be found by the lookup, since it effectively replaces the first
+declaration of “<tt class="docutils literal"><span class="pre">f</span></tt>”.</p>
+<p>In the semantics-centric view, overloading of functions is represented
+explicitly.  For example, given two declarations of a function “<tt class="docutils literal"><span class="pre">g</span></tt>” that are
+overloaded, e.g.,</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">g</span><span class="p">();</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>the <tt class="docutils literal"><span class="pre">DeclContext::lookup</span></tt> operation will return a
+<tt class="docutils literal"><span class="pre">DeclContext::lookup_result</span></tt> that contains a range of iterators over
+declarations of “<tt class="docutils literal"><span class="pre">g</span></tt>”.  Clients that perform semantic analysis on a program
+that is not concerned with the actual source code will primarily use this
+semantics-centric view.</p>
+</div>
+<div class="section" id="lexical-and-semantic-contexts">
+<span id="lexicalandsemanticcontexts"></span><h4><a class="toc-backref" href="#id31">Lexical and Semantic Contexts</a><a class="headerlink" href="#lexical-and-semantic-contexts" title="Permalink to this headline">Â¶</a></h4>
+<p>Each declaration has two potentially different declaration contexts: a
+<em>lexical</em> context, which corresponds to the source-centric view of the
+declaration context, and a <em>semantic</em> context, which corresponds to the
+semantics-centric view.  The lexical context is accessible via
+<tt class="docutils literal"><span class="pre">Decl::getLexicalDeclContext</span></tt> while the semantic context is accessible via
+<tt class="docutils literal"><span class="pre">Decl::getDeclContext</span></tt>, both of which return <tt class="docutils literal"><span class="pre">DeclContext</span></tt> pointers.  For
+most declarations, the two contexts are identical.  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">X</span> <span class="p">{</span>
+<span class="nl">public:</span>
+  <span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Here, the semantic and lexical contexts of <tt class="docutils literal"><span class="pre">X::f</span></tt> are the <tt class="docutils literal"><span class="pre">DeclContext</span></tt>
+associated with the class <tt class="docutils literal"><span class="pre">X</span></tt> (itself stored as a <tt class="docutils literal"><span class="pre">RecordDecl</span></tt> AST node).
+However, we can now define <tt class="docutils literal"><span class="pre">X::f</span></tt> out-of-line:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">X</span><span class="o">::</span><span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">17</span><span class="p">)</span> <span class="p">{</span> <span class="cm">/* ...  */</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>This definition of “<tt class="docutils literal"><span class="pre">f</span></tt>” has different lexical and semantic contexts.  The
+lexical context corresponds to the declaration context in which the actual
+declaration occurred in the source code, e.g., the translation unit containing
+<tt class="docutils literal"><span class="pre">X</span></tt>.  Thus, this declaration of <tt class="docutils literal"><span class="pre">X::f</span></tt> can be found by traversing the
+declarations provided by [<tt class="docutils literal"><span class="pre">decls_begin()</span></tt>, <tt class="docutils literal"><span class="pre">decls_end()</span></tt>) in the
+translation unit.</p>
+<p>The semantic context of <tt class="docutils literal"><span class="pre">X::f</span></tt> corresponds to the class <tt class="docutils literal"><span class="pre">X</span></tt>, since this
+member function is (semantically) a member of <tt class="docutils literal"><span class="pre">X</span></tt>.  Lookup of the name <tt class="docutils literal"><span class="pre">f</span></tt>
+into the <tt class="docutils literal"><span class="pre">DeclContext</span></tt> associated with <tt class="docutils literal"><span class="pre">X</span></tt> will then return the definition
+of <tt class="docutils literal"><span class="pre">X::f</span></tt> (including information about the default argument).</p>
+</div>
+<div class="section" id="transparent-declaration-contexts">
+<h4><a class="toc-backref" href="#id32">Transparent Declaration Contexts</a><a class="headerlink" href="#transparent-declaration-contexts" title="Permalink to this headline">Â¶</a></h4>
+<p>In C and C++, there are several contexts in which names that are logically
+declared inside another declaration will actually “leak” out into the enclosing
+scope from the perspective of name lookup.  The most obvious instance of this
+behavior is in enumeration types, e.g.,</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">Color</span> <span class="p">{</span>
+  <span class="n">Red</span><span class="p">,</span>
+  <span class="n">Green</span><span class="p">,</span>
+  <span class="n">Blue</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Here, <tt class="docutils literal"><span class="pre">Color</span></tt> is an enumeration, which is a declaration context that contains
+the enumerators <tt class="docutils literal"><span class="pre">Red</span></tt>, <tt class="docutils literal"><span class="pre">Green</span></tt>, and <tt class="docutils literal"><span class="pre">Blue</span></tt>.  Thus, traversing the list of
+declarations contained in the enumeration <tt class="docutils literal"><span class="pre">Color</span></tt> will yield <tt class="docutils literal"><span class="pre">Red</span></tt>,
+<tt class="docutils literal"><span class="pre">Green</span></tt>, and <tt class="docutils literal"><span class="pre">Blue</span></tt>.  However, outside of the scope of <tt class="docutils literal"><span class="pre">Color</span></tt> one can
+name the enumerator <tt class="docutils literal"><span class="pre">Red</span></tt> without qualifying the name, e.g.,</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Color</span> <span class="n">c</span> <span class="o">=</span> <span class="n">Red</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>There are other entities in C++ that provide similar behavior.  For example,
+linkage specifications that use curly braces:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">extern</span> <span class="s">"C"</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+  <span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="p">}</span>
+<span class="c1">// f and g are visible here</span>
+</pre></div>
+</div>
+<p>For source-level accuracy, we treat the linkage specification and enumeration
+type as a declaration context in which its enclosed declarations (“<tt class="docutils literal"><span class="pre">Red</span></tt>”,
+“<tt class="docutils literal"><span class="pre">Green</span></tt>”, and “<tt class="docutils literal"><span class="pre">Blue</span></tt>”; “<tt class="docutils literal"><span class="pre">f</span></tt>” and “<tt class="docutils literal"><span class="pre">g</span></tt>”) are declared.  However, these
+declarations are visible outside of the scope of the declaration context.</p>
+<p>These language features (and several others, described below) have roughly the
+same set of requirements: declarations are declared within a particular lexical
+context, but the declarations are also found via name lookup in scopes
+enclosing the declaration itself.  This feature is implemented via
+<em>transparent</em> declaration contexts (see
+<tt class="docutils literal"><span class="pre">DeclContext::isTransparentContext()</span></tt>), whose declarations are visible in the
+nearest enclosing non-transparent declaration context.  This means that the
+lexical context of the declaration (e.g., an enumerator) will be the
+transparent <tt class="docutils literal"><span class="pre">DeclContext</span></tt> itself, as will the semantic context, but the
+declaration will be visible in every outer context up to and including the
+first non-transparent declaration context (since transparent declaration
+contexts can be nested).</p>
+<p>The transparent <tt class="docutils literal"><span class="pre">DeclContext</span></tt>s are:</p>
+<ul>
+<li><p class="first">Enumerations (but not C++11 “scoped enumerations”):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">Color</span> <span class="p">{</span>
+  <span class="n">Red</span><span class="p">,</span>
+  <span class="n">Green</span><span class="p">,</span>
+  <span class="n">Blue</span>
+<span class="p">};</span>
+<span class="c1">// Red, Green, and Blue are in scope</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">C++ linkage specifications:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">extern</span> <span class="s">"C"</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+  <span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="p">}</span>
+<span class="c1">// f and g are in scope</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Anonymous unions and structs:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">LookupTable</span> <span class="p">{</span>
+  <span class="kt">bool</span> <span class="n">IsVector</span><span class="p">;</span>
+  <span class="k">union</span> <span class="p">{</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">Item</span><span class="o">></span> <span class="o">*</span><span class="n">Vector</span><span class="p">;</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">set</span><span class="o"><</span><span class="n">Item</span><span class="o">></span> <span class="o">*</span><span class="n">Set</span><span class="p">;</span>
+  <span class="p">};</span>
+<span class="p">};</span>
+
+<span class="n">LookupTable</span> <span class="n">LT</span><span class="p">;</span>
+<span class="n">LT</span><span class="p">.</span><span class="n">Vector</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// Okay: finds Vector inside the unnamed union</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">C++11 inline namespaces:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">mylib</span> <span class="p">{</span>
+  <span class="kr">inline</span> <span class="k">namespace</span> <span class="n">debug</span> <span class="p">{</span>
+    <span class="k">class</span> <span class="nc">X</span><span class="p">;</span>
+  <span class="p">}</span>
+<span class="p">}</span>
+<span class="n">mylib</span><span class="o">::</span><span class="n">X</span> <span class="o">*</span><span class="n">xp</span><span class="p">;</span> <span class="c1">// okay: mylib::X refers to mylib::debug::X</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="multiply-defined-declaration-contexts">
+<span id="multideclcontext"></span><h4><a class="toc-backref" href="#id33">Multiply-Defined Declaration Contexts</a><a class="headerlink" href="#multiply-defined-declaration-contexts" title="Permalink to this headline">Â¶</a></h4>
+<p>C++ namespaces have the interesting — and, so far, unique — property that
+the namespace can be defined multiple times, and the declarations provided by
+each namespace definition are effectively merged (from the semantic point of
+view).  For example, the following two code snippets are semantically
+indistinguishable:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Snippet #1:</span>
+<span class="k">namespace</span> <span class="n">N</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="n">f</span><span class="p">();</span>
+<span class="p">}</span>
+<span class="k">namespace</span> <span class="n">N</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="n">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="c1">// Snippet #2:</span>
+<span class="k">namespace</span> <span class="n">N</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="n">f</span><span class="p">();</span>
+  <span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In Clang’s representation, the source-centric view of declaration contexts will
+actually have two separate <tt class="docutils literal"><span class="pre">NamespaceDecl</span></tt> nodes in Snippet #1, each of which
+is a declaration context that contains a single declaration of “<tt class="docutils literal"><span class="pre">f</span></tt>”.
+However, the semantics-centric view provided by name lookup into the namespace
+<tt class="docutils literal"><span class="pre">N</span></tt> for “<tt class="docutils literal"><span class="pre">f</span></tt>” will return a <tt class="docutils literal"><span class="pre">DeclContext::lookup_result</span></tt> that contains a
+range of iterators over declarations of “<tt class="docutils literal"><span class="pre">f</span></tt>”.</p>
+<p><tt class="docutils literal"><span class="pre">DeclContext</span></tt> manages multiply-defined declaration contexts internally.  The
+function <tt class="docutils literal"><span class="pre">DeclContext::getPrimaryContext</span></tt> retrieves the “primary” context for
+a given <tt class="docutils literal"><span class="pre">DeclContext</span></tt> instance, which is the <tt class="docutils literal"><span class="pre">DeclContext</span></tt> responsible for
+maintaining the lookup table used for the semantics-centric view.  Given the
+primary context, one can follow the chain of <tt class="docutils literal"><span class="pre">DeclContext</span></tt> nodes that define
+additional declarations via <tt class="docutils literal"><span class="pre">DeclContext::getNextContext</span></tt>.  Note that these
+functions are used internally within the lookup and insertion methods of the
+<tt class="docutils literal"><span class="pre">DeclContext</span></tt>, so the vast majority of clients can ignore them.</p>
+</div>
+</div>
+<div class="section" id="the-cfg-class">
+<span id="cfg"></span><h3><a class="toc-backref" href="#id34">The <tt class="docutils literal"><span class="pre">CFG</span></tt> class</a><a class="headerlink" href="#the-cfg-class" title="Permalink to this headline">Â¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">CFG</span></tt> class is designed to represent a source-level control-flow graph
+for a single statement (<tt class="docutils literal"><span class="pre">Stmt*</span></tt>).  Typically instances of <tt class="docutils literal"><span class="pre">CFG</span></tt> are
+constructed for function bodies (usually an instance of <tt class="docutils literal"><span class="pre">CompoundStmt</span></tt>), but
+can also be instantiated to represent the control-flow of any class that
+subclasses <tt class="docutils literal"><span class="pre">Stmt</span></tt>, which includes simple expressions.  Control-flow graphs
+are especially useful for performing <a class="reference external" href="http://en.wikipedia.org/wiki/Data_flow_analysis#Sensitivities">flow- or path-sensitive</a> program
+analyses on a given function.</p>
+<div class="section" id="basic-blocks">
+<h4><a class="toc-backref" href="#id35">Basic Blocks</a><a class="headerlink" href="#basic-blocks" title="Permalink to this headline">Â¶</a></h4>
+<p>Concretely, an instance of <tt class="docutils literal"><span class="pre">CFG</span></tt> is a collection of basic blocks.  Each basic
+block is an instance of <tt class="docutils literal"><span class="pre">CFGBlock</span></tt>, which simply contains an ordered sequence
+of <tt class="docutils literal"><span class="pre">Stmt*</span></tt> (each referring to statements in the AST).  The ordering of
+statements within a block indicates unconditional flow of control from one
+statement to the next.  <a class="reference internal" href="#conditionalcontrolflow"><em>Conditional control-flow</em></a> is represented using edges between basic blocks.  The
+statements within a given <tt class="docutils literal"><span class="pre">CFGBlock</span></tt> can be traversed using the
+<tt class="docutils literal"><span class="pre">CFGBlock::*iterator</span></tt> interface.</p>
+<p>A <tt class="docutils literal"><span class="pre">CFG</span></tt> object owns the instances of <tt class="docutils literal"><span class="pre">CFGBlock</span></tt> within the control-flow
+graph it represents.  Each <tt class="docutils literal"><span class="pre">CFGBlock</span></tt> within a CFG is also uniquely numbered
+(accessible via <tt class="docutils literal"><span class="pre">CFGBlock::getBlockID()</span></tt>).  Currently the number is based on
+the ordering the blocks were created, but no assumptions should be made on how
+<tt class="docutils literal"><span class="pre">CFGBlocks</span></tt> are numbered other than their numbers are unique and that they
+are numbered from 0..N-1 (where N is the number of basic blocks in the CFG).</p>
+</div>
+<div class="section" id="entry-and-exit-blocks">
+<h4><a class="toc-backref" href="#id36">Entry and Exit Blocks</a><a class="headerlink" href="#entry-and-exit-blocks" title="Permalink to this headline">Â¶</a></h4>
+<p>Each instance of <tt class="docutils literal"><span class="pre">CFG</span></tt> contains two special blocks: an <em>entry</em> block
+(accessible via <tt class="docutils literal"><span class="pre">CFG::getEntry()</span></tt>), which has no incoming edges, and an
+<em>exit</em> block (accessible via <tt class="docutils literal"><span class="pre">CFG::getExit()</span></tt>), which has no outgoing edges.
+Neither block contains any statements, and they serve the role of providing a
+clear entrance and exit for a body of code such as a function body.  The
+presence of these empty blocks greatly simplifies the implementation of many
+analyses built on top of CFGs.</p>
+</div>
+<div class="section" id="conditional-control-flow">
+<span id="conditionalcontrolflow"></span><h4><a class="toc-backref" href="#id37">Conditional Control-Flow</a><a class="headerlink" href="#conditional-control-flow" title="Permalink to this headline">Â¶</a></h4>
+<p>Conditional control-flow (such as those induced by if-statements and loops) is
+represented as edges between <tt class="docutils literal"><span class="pre">CFGBlocks</span></tt>.  Because different C language
+constructs can induce control-flow, each <tt class="docutils literal"><span class="pre">CFGBlock</span></tt> also records an extra
+<tt class="docutils literal"><span class="pre">Stmt*</span></tt> that represents the <em>terminator</em> of the block.  A terminator is
+simply the statement that caused the control-flow, and is used to identify the
+nature of the conditional control-flow between blocks.  For example, in the
+case of an if-statement, the terminator refers to the <tt class="docutils literal"><span class="pre">IfStmt</span></tt> object in the
+AST that represented the given branch.</p>
+<p>To illustrate, consider the following code example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">x</span> <span class="o">=</span> <span class="n">x</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">></span> <span class="mi">2</span><span class="p">)</span>
+    <span class="n">x</span><span class="o">++</span><span class="p">;</span>
+  <span class="k">else</span> <span class="p">{</span>
+    <span class="n">x</span> <span class="o">+=</span> <span class="mi">2</span><span class="p">;</span>
+    <span class="n">x</span> <span class="o">*=</span> <span class="mi">2</span><span class="p">;</span>
+  <span class="p">}</span>
+
+  <span class="k">return</span> <span class="n">x</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>After invoking the parser+semantic analyzer on this code fragment, the AST of
+the body of <tt class="docutils literal"><span class="pre">foo</span></tt> is referenced by a single <tt class="docutils literal"><span class="pre">Stmt*</span></tt>.  We can then construct
+an instance of <tt class="docutils literal"><span class="pre">CFG</span></tt> representing the control-flow graph of this function
+body by single call to a static class method:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Stmt</span> <span class="o">*</span><span class="n">FooBody</span> <span class="o">=</span> <span class="p">...</span>
+<span class="n">CFG</span> <span class="o">*</span><span class="n">FooCFG</span> <span class="o">=</span> <span class="n">CFG</span><span class="o">::</span><span class="n">buildCFG</span><span class="p">(</span><span class="n">FooBody</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>It is the responsibility of the caller of <tt class="docutils literal"><span class="pre">CFG::buildCFG</span></tt> to <tt class="docutils literal"><span class="pre">delete</span></tt> the
+returned <tt class="docutils literal"><span class="pre">CFG*</span></tt> when the CFG is no longer needed.</p>
+<p>Along with providing an interface to iterate over its <tt class="docutils literal"><span class="pre">CFGBlocks</span></tt>, the
+<tt class="docutils literal"><span class="pre">CFG</span></tt> class also provides methods that are useful for debugging and
+visualizing CFGs.  For example, the method <tt class="docutils literal"><span class="pre">CFG::dump()</span></tt> dumps a
+pretty-printed version of the CFG to standard error.  This is especially useful
+when one is using a debugger such as gdb.  For example, here is the output of
+<tt class="docutils literal"><span class="pre">FooCFG->dump()</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">[</span> <span class="n">B5</span> <span class="p">(</span><span class="n">ENTRY</span><span class="p">)</span> <span class="p">]</span>
+   <span class="n">Predecessors</span> <span class="p">(</span><span class="mi">0</span><span class="p">)</span><span class="o">:</span>
+   <span class="n">Successors</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">:</span> <span class="n">B4</span>
+
+<span class="p">[</span> <span class="n">B4</span> <span class="p">]</span>
+   <span class="mi">1</span><span class="o">:</span> <span class="n">x</span> <span class="o">=</span> <span class="n">x</span> <span class="o">+</span> <span class="mi">1</span>
+   <span class="mi">2</span><span class="o">:</span> <span class="p">(</span><span class="n">x</span> <span class="o">></span> <span class="mi">2</span><span class="p">)</span>
+   <span class="nl">T:</span> <span class="k">if</span> <span class="p">[</span><span class="n">B4</span><span class="mf">.2</span><span class="p">]</span>
+   <span class="n">Predecessors</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">:</span> <span class="n">B5</span>
+   <span class="n">Successors</span> <span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="o">:</span> <span class="n">B3</span> <span class="n">B2</span>
+
+<span class="p">[</span> <span class="n">B3</span> <span class="p">]</span>
+   <span class="mi">1</span><span class="o">:</span> <span class="n">x</span><span class="o">++</span>
+   <span class="n">Predecessors</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">:</span> <span class="n">B4</span>
+   <span class="n">Successors</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">:</span> <span class="n">B1</span>
+
+<span class="p">[</span> <span class="n">B2</span> <span class="p">]</span>
+   <span class="mi">1</span><span class="o">:</span> <span class="n">x</span> <span class="o">+=</span> <span class="mi">2</span>
+   <span class="mi">2</span><span class="o">:</span> <span class="n">x</span> <span class="o">*=</span> <span class="mi">2</span>
+   <span class="n">Predecessors</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">:</span> <span class="n">B4</span>
+   <span class="n">Successors</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">:</span> <span class="n">B1</span>
+
+<span class="p">[</span> <span class="n">B1</span> <span class="p">]</span>
+   <span class="mi">1</span><span class="o">:</span> <span class="k">return</span> <span class="n">x</span><span class="p">;</span>
+   <span class="n">Predecessors</span> <span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="o">:</span> <span class="n">B2</span> <span class="n">B3</span>
+   <span class="n">Successors</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">:</span> <span class="n">B0</span>
+
+<span class="p">[</span> <span class="n">B0</span> <span class="p">(</span><span class="n">EXIT</span><span class="p">)</span> <span class="p">]</span>
+   <span class="n">Predecessors</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">:</span> <span class="n">B1</span>
+   <span class="n">Successors</span> <span class="p">(</span><span class="mi">0</span><span class="p">)</span><span class="o">:</span>
+</pre></div>
+</div>
+<p>For each block, the pretty-printed output displays for each block the number of
+<em>predecessor</em> blocks (blocks that have outgoing control-flow to the given
+block) and <em>successor</em> blocks (blocks that have control-flow that have incoming
+control-flow from the given block).  We can also clearly see the special entry
+and exit blocks at the beginning and end of the pretty-printed output.  For the
+entry block (block B5), the number of predecessor blocks is 0, while for the
+exit block (block B0) the number of successor blocks is 0.</p>
+<p>The most interesting block here is B4, whose outgoing control-flow represents
+the branching caused by the sole if-statement in <tt class="docutils literal"><span class="pre">foo</span></tt>.  Of particular
+interest is the second statement in the block, <tt class="docutils literal"><span class="pre">(x</span> <span class="pre">></span> <span class="pre">2)</span></tt>, and the terminator,
+printed as <tt class="docutils literal"><span class="pre">if</span> <span class="pre">[B4.2]</span></tt>.  The second statement represents the evaluation of
+the condition of the if-statement, which occurs before the actual branching of
+control-flow.  Within the <tt class="docutils literal"><span class="pre">CFGBlock</span></tt> for B4, the <tt class="docutils literal"><span class="pre">Stmt*</span></tt> for the second
+statement refers to the actual expression in the AST for <tt class="docutils literal"><span class="pre">(x</span> <span class="pre">></span> <span class="pre">2)</span></tt>.  Thus
+pointers to subclasses of <tt class="docutils literal"><span class="pre">Expr</span></tt> can appear in the list of statements in a
+block, and not just subclasses of <tt class="docutils literal"><span class="pre">Stmt</span></tt> that refer to proper C statements.</p>
+<p>The terminator of block B4 is a pointer to the <tt class="docutils literal"><span class="pre">IfStmt</span></tt> object in the AST.
+The pretty-printer outputs <tt class="docutils literal"><span class="pre">if</span> <span class="pre">[B4.2]</span></tt> because the condition expression of
+the if-statement has an actual place in the basic block, and thus the
+terminator is essentially <em>referring</em> to the expression that is the second
+statement of block B4 (i.e., B4.2).  In this manner, conditions for
+control-flow (which also includes conditions for loops and switch statements)
+are hoisted into the actual basic block.</p>
+</div>
+</div>
+<div class="section" id="constant-folding-in-the-clang-ast">
+<h3><a class="toc-backref" href="#id38">Constant Folding in the Clang AST</a><a class="headerlink" href="#constant-folding-in-the-clang-ast" title="Permalink to this headline">Â¶</a></h3>
+<p>There are several places where constants and constant folding matter a lot to
+the Clang front-end.  First, in general, we prefer the AST to retain the source
+code as close to how the user wrote it as possible.  This means that if they
+wrote “<tt class="docutils literal"><span class="pre">5+4</span></tt>”, we want to keep the addition and two constants in the AST, we
+don’t want to fold to “<tt class="docutils literal"><span class="pre">9</span></tt>”.  This means that constant folding in various
+ways turns into a tree walk that needs to handle the various cases.</p>
+<p>However, there are places in both C and C++ that require constants to be
+folded.  For example, the C standard defines what an “integer constant
+expression” (i-c-e) is with very precise and specific requirements.  The
+language then requires i-c-e’s in a lot of places (for example, the size of a
+bitfield, the value for a case statement, etc).  For these, we have to be able
+to constant fold the constants, to do semantic checks (e.g., verify bitfield
+size is non-negative and that case statements aren’t duplicated).  We aim for
+Clang to be very pedantic about this, diagnosing cases when the code does not
+use an i-c-e where one is required, but accepting the code unless running with
+<tt class="docutils literal"><span class="pre">-pedantic-errors</span></tt>.</p>
+<p>Things get a little bit more tricky when it comes to compatibility with
+real-world source code.  Specifically, GCC has historically accepted a huge
+superset of expressions as i-c-e’s, and a lot of real world code depends on
+this unfortuate accident of history (including, e.g., the glibc system
+headers).  GCC accepts anything its “fold” optimizer is capable of reducing to
+an integer constant, which means that the definition of what it accepts changes
+as its optimizer does.  One example is that GCC accepts things like “<tt class="docutils literal"><span class="pre">case</span>
+<span class="pre">X-X:</span></tt>” even when <tt class="docutils literal"><span class="pre">X</span></tt> is a variable, because it can fold this to 0.</p>
+<p>Another issue are how constants interact with the extensions we support, such
+as <tt class="docutils literal"><span class="pre">__builtin_constant_p</span></tt>, <tt class="docutils literal"><span class="pre">__builtin_inf</span></tt>, <tt class="docutils literal"><span class="pre">__extension__</span></tt> and many
+others.  C99 obviously does not specify the semantics of any of these
+extensions, and the definition of i-c-e does not include them.  However, these
+extensions are often used in real code, and we have to have a way to reason
+about them.</p>
+<p>Finally, this is not just a problem for semantic analysis.  The code generator
+and other clients have to be able to fold constants (e.g., to initialize global
+variables) and has to handle a superset of what C99 allows.  Further, these
+clients can benefit from extended information.  For example, we know that
+“<tt class="docutils literal"><span class="pre">foo()</span> <span class="pre">||</span> <span class="pre">1</span></tt>” always evaluates to <tt class="docutils literal"><span class="pre">true</span></tt>, but we can’t replace the
+expression with <tt class="docutils literal"><span class="pre">true</span></tt> because it has side effects.</p>
+<div class="section" id="implementation-approach">
+<h4><a class="toc-backref" href="#id39">Implementation Approach</a><a class="headerlink" href="#implementation-approach" title="Permalink to this headline">Â¶</a></h4>
+<p>After trying several different approaches, we’ve finally converged on a design
+(Note, at the time of this writing, not all of this has been implemented,
+consider this a design goal!).  Our basic approach is to define a single
+recursive method evaluation method (<tt class="docutils literal"><span class="pre">Expr::Evaluate</span></tt>), which is implemented
+in <tt class="docutils literal"><span class="pre">AST/ExprConstant.cpp</span></tt>.  Given an expression with “scalar” type (integer,
+fp, complex, or pointer) this method returns the following information:</p>
+<ul class="simple">
+<li>Whether the expression is an integer constant expression, a general constant
+that was folded but has no side effects, a general constant that was folded
+but that does have side effects, or an uncomputable/unfoldable value.</li>
+<li>If the expression was computable in any way, this method returns the
+<tt class="docutils literal"><span class="pre">APValue</span></tt> for the result of the expression.</li>
+<li>If the expression is not evaluatable at all, this method returns information
+on one of the problems with the expression.  This includes a
+<tt class="docutils literal"><span class="pre">SourceLocation</span></tt> for where the problem is, and a diagnostic ID that explains
+the problem.  The diagnostic should have <tt class="docutils literal"><span class="pre">ERROR</span></tt> type.</li>
+<li>If the expression is not an integer constant expression, this method returns
+information on one of the problems with the expression.  This includes a
+<tt class="docutils literal"><span class="pre">SourceLocation</span></tt> for where the problem is, and a diagnostic ID that
+explains the problem.  The diagnostic should have <tt class="docutils literal"><span class="pre">EXTENSION</span></tt> type.</li>
+</ul>
+<p>This information gives various clients the flexibility that they want, and we
+will eventually have some helper methods for various extensions.  For example,
+<tt class="docutils literal"><span class="pre">Sema</span></tt> should have a <tt class="docutils literal"><span class="pre">Sema::VerifyIntegerConstantExpression</span></tt> method, which
+calls <tt class="docutils literal"><span class="pre">Evaluate</span></tt> on the expression.  If the expression is not foldable, the
+error is emitted, and it would return <tt class="docutils literal"><span class="pre">true</span></tt>.  If the expression is not an
+i-c-e, the <tt class="docutils literal"><span class="pre">EXTENSION</span></tt> diagnostic is emitted.  Finally it would return
+<tt class="docutils literal"><span class="pre">false</span></tt> to indicate that the AST is OK.</p>
+<p>Other clients can use the information in other ways, for example, codegen can
+just use expressions that are foldable in any way.</p>
+</div>
+<div class="section" id="extensions">
+<h4><a class="toc-backref" href="#id40">Extensions</a><a class="headerlink" href="#extensions" title="Permalink to this headline">Â¶</a></h4>
+<p>This section describes how some of the various extensions Clang supports
+interacts with constant evaluation:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">__extension__</span></tt>: The expression form of this extension causes any
+evaluatable subexpression to be accepted as an integer constant expression.</li>
+<li><tt class="docutils literal"><span class="pre">__builtin_constant_p</span></tt>: This returns true (as an integer constant
+expression) if the operand evaluates to either a numeric value (that is, not
+a pointer cast to integral type) of integral, enumeration, floating or
+complex type, or if it evaluates to the address of the first character of a
+string literal (possibly cast to some other type).  As a special case, if
+<tt class="docutils literal"><span class="pre">__builtin_constant_p</span></tt> is the (potentially parenthesized) condition of a
+conditional operator expression (“<tt class="docutils literal"><span class="pre">?:</span></tt>”), only the true side of the
+conditional operator is considered, and it is evaluated with full constant
+folding.</li>
+<li><tt class="docutils literal"><span class="pre">__builtin_choose_expr</span></tt>: The condition is required to be an integer
+constant expression, but we accept any constant as an “extension of an
+extension”.  This only evaluates one operand depending on which way the
+condition evaluates.</li>
+<li><tt class="docutils literal"><span class="pre">__builtin_classify_type</span></tt>: This always returns an integer constant
+expression.</li>
+<li><tt class="docutils literal"><span class="pre">__builtin_inf,</span> <span class="pre">nan,</span> <span class="pre">...</span></tt>: These are treated just like a floating-point
+literal.</li>
+<li><tt class="docutils literal"><span class="pre">__builtin_abs,</span> <span class="pre">copysign,</span> <span class="pre">...</span></tt>: These are constant folded as general
+constant expressions.</li>
+<li><tt class="docutils literal"><span class="pre">__builtin_strlen</span></tt> and <tt class="docutils literal"><span class="pre">strlen</span></tt>: These are constant folded as integer
+constant expressions if the argument is a string literal.</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="section" id="how-to-change-clang">
+<h2><a class="toc-backref" href="#id41">How to change Clang</a><a class="headerlink" href="#how-to-change-clang" title="Permalink to this headline">Â¶</a></h2>
+<div class="section" id="how-to-add-an-attribute">
+<h3><a class="toc-backref" href="#id42">How to add an attribute</a><a class="headerlink" href="#how-to-add-an-attribute" title="Permalink to this headline">Â¶</a></h3>
+<p>To add an attribute, you’ll have to add it to the list of attributes, add it to
+the parsing phase, and look for it in the AST scan.
+<a class="reference external" href="http://llvm.org/viewvc/llvm-project?view=rev&revision=124217">r124217</a>
+has a good example of adding a warning attribute.</p>
+<p>(Beware that this hasn’t been reviewed/fixed by the people who designed the
+attributes system yet.)</p>
+<div class="section" id="include-clang-basic-attr-td">
+<h4><a class="toc-backref" href="#id43"><tt class="docutils literal"><span class="pre">include/clang/Basic/Attr.td</span></tt></a><a class="headerlink" href="#include-clang-basic-attr-td" title="Permalink to this headline">Â¶</a></h4>
+<p>First, add your attribute to the <a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/Attr.td?view=markup">include/clang/Basic/Attr.td file</a>.</p>
+<p>Each attribute gets a <tt class="docutils literal"><span class="pre">def</span></tt> inheriting from <tt class="docutils literal"><span class="pre">Attr</span></tt> or one of its
+subclasses.  <tt class="docutils literal"><span class="pre">InheritableAttr</span></tt> means that the attribute also applies to
+subsequent declarations of the same name.</p>
+<p><tt class="docutils literal"><span class="pre">Spellings</span></tt> lists the strings that can appear in <tt class="docutils literal"><span class="pre">__attribute__((here))</span></tt> or
+<tt class="docutils literal"><span class="pre">[[here]]</span></tt>.  All such strings will be synonymous.  If you want to allow the
+<tt class="docutils literal"><span class="pre">[[]]</span></tt> C++11 syntax, you have to define a list of <tt class="docutils literal"><span class="pre">Namespaces</span></tt>, which will
+let users write <tt class="docutils literal"><span class="pre">[[namespace::spelling]]</span></tt>.  Using the empty string for a
+namespace will allow users to write just the spelling with no “<tt class="docutils literal"><span class="pre">::</span></tt>”.
+Attributes which g++-4.8 accepts should also have a
+<tt class="docutils literal"><span class="pre">CXX11<"gnu",</span> <span class="pre">"spelling"></span></tt> spelling.</p>
+<p><tt class="docutils literal"><span class="pre">Subjects</span></tt> restricts what kinds of AST node to which this attribute can
+appertain (roughly, attach).</p>
+<p><tt class="docutils literal"><span class="pre">Args</span></tt> names the arguments the attribute takes, in order.  If <tt class="docutils literal"><span class="pre">Args</span></tt> is
+<tt class="docutils literal"><span class="pre">[StringArgument<"Arg1">,</span> <span class="pre">IntArgument<"Arg2">]</span></tt> then
+<tt class="docutils literal"><span class="pre">__attribute__((myattribute("Hello",</span> <span class="pre">3)))</span></tt> will be a valid use.</p>
+</div>
+<div class="section" id="boilerplate">
+<h4><a class="toc-backref" href="#id44">Boilerplate</a><a class="headerlink" href="#boilerplate" title="Permalink to this headline">Â¶</a></h4>
+<p>Write a new <tt class="docutils literal"><span class="pre">HandleYourAttr()</span></tt> function in <a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/SemaDeclAttr.cpp?view=markup">lib/Sema/SemaDeclAttr.cpp</a>,
+and add a case to the switch in <tt class="docutils literal"><span class="pre">ProcessNonInheritableDeclAttr()</span></tt> or
+<tt class="docutils literal"><span class="pre">ProcessInheritableDeclAttr()</span></tt> forwarding to it.</p>
+<p>If your attribute causes extra warnings to fire, define a <tt class="docutils literal"><span class="pre">DiagGroup</span></tt> in
+<a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticGroups.td?view=markup">include/clang/Basic/DiagnosticGroups.td</a>
+named after the attribute’s <tt class="docutils literal"><span class="pre">Spelling</span></tt> with “_”s replaced by “-“s.  If you’re
+only defining one diagnostic, you can skip <tt class="docutils literal"><span class="pre">DiagnosticGroups.td</span></tt> and use
+<tt class="docutils literal"><span class="pre">InGroup<DiagGroup<"your-attribute">></span></tt> directly in <a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticSemaKinds.td?view=markup">DiagnosticSemaKinds.td</a></p>
+</div>
+<div class="section" id="the-meat-of-your-attribute">
+<h4><a class="toc-backref" href="#id45">The meat of your attribute</a><a class="headerlink" href="#the-meat-of-your-attribute" title="Permalink to this headline">Â¶</a></h4>
+<p>Find an appropriate place in Clang to do whatever your attribute needs to do.
+Check for the attribute’s presence using <tt class="docutils literal"><span class="pre">Decl::getAttr<YourAttr>()</span></tt>.</p>
+<p>Update the <a class="reference internal" href="LanguageExtensions.html"><em>Clang Language Extensions</em></a> document to describe your new attribute.</p>
+</div>
+</div>
+<div class="section" id="how-to-add-an-expression-or-statement">
+<h3><a class="toc-backref" href="#id46">How to add an expression or statement</a><a class="headerlink" href="#how-to-add-an-expression-or-statement" title="Permalink to this headline">Â¶</a></h3>
+<p>Expressions and statements are one of the most fundamental constructs within a
+compiler, because they interact with many different parts of the AST, semantic
+analysis, and IR generation.  Therefore, adding a new expression or statement
+kind into Clang requires some care.  The following list details the various
+places in Clang where an expression or statement needs to be introduced, along
+with patterns to follow to ensure that the new expression or statement works
+well across all of the C languages.  We focus on expressions, but statements
+are similar.</p>
+<ol class="arabic simple">
+<li>Introduce parsing actions into the parser.  Recursive-descent parsing is
+mostly self-explanatory, but there are a few things that are worth keeping
+in mind:<ul>
+<li>Keep as much source location information as possible! You’ll want it later
+to produce great diagnostics and support Clang’s various features that map
+between source code and the AST.</li>
+<li>Write tests for all of the “bad” parsing cases, to make sure your recovery
+is good.  If you have matched delimiters (e.g., parentheses, square
+brackets, etc.), use <tt class="docutils literal"><span class="pre">Parser::BalancedDelimiterTracker</span></tt> to give nice
+diagnostics when things go wrong.</li>
+</ul>
+</li>
+<li>Introduce semantic analysis actions into <tt class="docutils literal"><span class="pre">Sema</span></tt>.  Semantic analysis should
+always involve two functions: an <tt class="docutils literal"><span class="pre">ActOnXXX</span></tt> function that will be called
+directly from the parser, and a <tt class="docutils literal"><span class="pre">BuildXXX</span></tt> function that performs the
+actual semantic analysis and will (eventually!) build the AST node.  It’s
+fairly common for the <tt class="docutils literal"><span class="pre">ActOnCXX</span></tt> function to do very little (often just
+some minor translation from the parser’s representation to <tt class="docutils literal"><span class="pre">Sema</span></tt>‘s
+representation of the same thing), but the separation is still important:
+C++ template instantiation, for example, should always call the <tt class="docutils literal"><span class="pre">BuildXXX</span></tt>
+variant.  Several notes on semantic analysis before we get into construction
+of the AST:<ul>
+<li>Your expression probably involves some types and some subexpressions.
+Make sure to fully check that those types, and the types of those
+subexpressions, meet your expectations.  Add implicit conversions where
+necessary to make sure that all of the types line up exactly the way you
+want them.  Write extensive tests to check that you’re getting good
+diagnostics for mistakes and that you can use various forms of
+subexpressions with your expression.</li>
+<li>When type-checking a type or subexpression, make sure to first check
+whether the type is “dependent” (<tt class="docutils literal"><span class="pre">Type::isDependentType()</span></tt>) or whether a
+subexpression is type-dependent (<tt class="docutils literal"><span class="pre">Expr::isTypeDependent()</span></tt>).  If any of
+these return <tt class="docutils literal"><span class="pre">true</span></tt>, then you’re inside a template and you can’t do much
+type-checking now.  That’s normal, and your AST node (when you get there)
+will have to deal with this case.  At this point, you can write tests that
+use your expression within templates, but don’t try to instantiate the
+templates.</li>
+<li>For each subexpression, be sure to call <tt class="docutils literal"><span class="pre">Sema::CheckPlaceholderExpr()</span></tt>
+to deal with “weird” expressions that don’t behave well as subexpressions.
+Then, determine whether you need to perform lvalue-to-rvalue conversions
+(<tt class="docutils literal"><span class="pre">Sema::DefaultLvalueConversions</span></tt>) or the usual unary conversions
+(<tt class="docutils literal"><span class="pre">Sema::UsualUnaryConversions</span></tt>), for places where the subexpression is
+producing a value you intend to use.</li>
+<li>Your <tt class="docutils literal"><span class="pre">BuildXXX</span></tt> function will probably just return <tt class="docutils literal"><span class="pre">ExprError()</span></tt> at
+this point, since you don’t have an AST.  That’s perfectly fine, and
+shouldn’t impact your testing.</li>
+</ul>
+</li>
+<li>Introduce an AST node for your new expression.  This starts with declaring
+the node in <tt class="docutils literal"><span class="pre">include/Basic/StmtNodes.td</span></tt> and creating a new class for your
+expression in the appropriate <tt class="docutils literal"><span class="pre">include/AST/Expr*.h</span></tt> header.  It’s best to
+look at the class for a similar expression to get ideas, and there are some
+specific things to watch for:<ul>
+<li>If you need to allocate memory, use the <tt class="docutils literal"><span class="pre">ASTContext</span></tt> allocator to
+allocate memory.  Never use raw <tt class="docutils literal"><span class="pre">malloc</span></tt> or <tt class="docutils literal"><span class="pre">new</span></tt>, and never hold any
+resources in an AST node, because the destructor of an AST node is never
+called.</li>
+<li>Make sure that <tt class="docutils literal"><span class="pre">getSourceRange()</span></tt> covers the exact source range of your
+expression.  This is needed for diagnostics and for IDE support.</li>
+<li>Make sure that <tt class="docutils literal"><span class="pre">children()</span></tt> visits all of the subexpressions.  This is
+important for a number of features (e.g., IDE support, C++ variadic
+templates).  If you have sub-types, you’ll also need to visit those
+sub-types in the <tt class="docutils literal"><span class="pre">RecursiveASTVisitor</span></tt>.</li>
+<li>Add printing support (<tt class="docutils literal"><span class="pre">StmtPrinter.cpp</span></tt>) and dumping support
+(<tt class="docutils literal"><span class="pre">StmtDumper.cpp</span></tt>) for your expression.</li>
+<li>Add profiling support (<tt class="docutils literal"><span class="pre">StmtProfile.cpp</span></tt>) for your AST node, noting the
+distinguishing (non-source location) characteristics of an instance of
+your expression.  Omitting this step will lead to hard-to-diagnose
+failures regarding matching of template declarations.</li>
+</ul>
+</li>
+<li>Teach semantic analysis to build your AST node.  At this point, you can wire
+up your <tt class="docutils literal"><span class="pre">Sema::BuildXXX</span></tt> function to actually create your AST.  A few
+things to check at this point:<ul>
+<li>If your expression can construct a new C++ class or return a new
+Objective-C object, be sure to update and then call
+<tt class="docutils literal"><span class="pre">Sema::MaybeBindToTemporary</span></tt> for your just-created AST node to be sure
+that the object gets properly destructed.  An easy way to test this is to
+return a C++ class with a private destructor: semantic analysis should
+flag an error here with the attempt to call the destructor.</li>
+<li>Inspect the generated AST by printing it using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span> <span class="pre">-ast-print</span></tt>,
+to make sure you’re capturing all of the important information about how
+the AST was written.</li>
+<li>Inspect the generated AST under <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span> <span class="pre">-ast-dump</span></tt> to verify that
+all of the types in the generated AST line up the way you want them.
+Remember that clients of the AST should never have to “think” to
+understand what’s going on.  For example, all implicit conversions should
+show up explicitly in the AST.</li>
+<li>Write tests that use your expression as a subexpression of other,
+well-known expressions.  Can you call a function using your expression as
+an argument?  Can you use the ternary operator?</li>
+</ul>
+</li>
+<li>Teach code generation to create IR to your AST node.  This step is the first
+(and only) that requires knowledge of LLVM IR.  There are several things to
+keep in mind:<ul>
+<li>Code generation is separated into scalar/aggregate/complex and
+lvalue/rvalue paths, depending on what kind of result your expression
+produces.  On occasion, this requires some careful factoring of code to
+avoid duplication.</li>
+<li><tt class="docutils literal"><span class="pre">CodeGenFunction</span></tt> contains functions <tt class="docutils literal"><span class="pre">ConvertType</span></tt> and
+<tt class="docutils literal"><span class="pre">ConvertTypeForMem</span></tt> that convert Clang’s types (<tt class="docutils literal"><span class="pre">clang::Type*</span></tt> or
+<tt class="docutils literal"><span class="pre">clang::QualType</span></tt>) to LLVM types.  Use the former for values, and the
+later for memory locations: test with the C++ “<tt class="docutils literal"><span class="pre">bool</span></tt>” type to check
+this.  If you find that you are having to use LLVM bitcasts to make the
+subexpressions of your expression have the type that your expression
+expects, STOP!  Go fix semantic analysis and the AST so that you don’t
+need these bitcasts.</li>
+<li>The <tt class="docutils literal"><span class="pre">CodeGenFunction</span></tt> class has a number of helper functions to make
+certain operations easy, such as generating code to produce an lvalue or
+an rvalue, or to initialize a memory location with a given value.  Prefer
+to use these functions rather than directly writing loads and stores,
+because these functions take care of some of the tricky details for you
+(e.g., for exceptions).</li>
+<li>If your expression requires some special behavior in the event of an
+exception, look at the <tt class="docutils literal"><span class="pre">push*Cleanup</span></tt> functions in <tt class="docutils literal"><span class="pre">CodeGenFunction</span></tt>
+to introduce a cleanup.  You shouldn’t have to deal with
+exception-handling directly.</li>
+<li>Testing is extremely important in IR generation.  Use <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span>
+<span class="pre">-emit-llvm</span></tt> and <a class="reference external" href="http://llvm.org/docs/CommandGuide/FileCheck.html">FileCheck</a> to verify that you’re
+generating the right IR.</li>
+</ul>
+</li>
+<li>Teach template instantiation how to cope with your AST node, which requires
+some fairly simple code:<ul>
+<li>Make sure that your expression’s constructor properly computes the flags
+for type dependence (i.e., the type your expression produces can change
+from one instantiation to the next), value dependence (i.e., the constant
+value your expression produces can change from one instantiation to the
+next), instantiation dependence (i.e., a template parameter occurs
+anywhere in your expression), and whether your expression contains a
+parameter pack (for variadic templates).  Often, computing these flags
+just means combining the results from the various types and
+subexpressions.</li>
+<li>Add <tt class="docutils literal"><span class="pre">TransformXXX</span></tt> and <tt class="docutils literal"><span class="pre">RebuildXXX</span></tt> functions to the <tt class="docutils literal"><span class="pre">TreeTransform</span></tt>
+class template in <tt class="docutils literal"><span class="pre">Sema</span></tt>.  <tt class="docutils literal"><span class="pre">TransformXXX</span></tt> should (recursively)
+transform all of the subexpressions and types within your expression,
+using <tt class="docutils literal"><span class="pre">getDerived().TransformYYY</span></tt>.  If all of the subexpressions and
+types transform without error, it will then call the <tt class="docutils literal"><span class="pre">RebuildXXX</span></tt>
+function, which will in turn call <tt class="docutils literal"><span class="pre">getSema().BuildXXX</span></tt> to perform
+semantic analysis and build your expression.</li>
+<li>To test template instantiation, take those tests you wrote to make sure
+that you were type checking with type-dependent expressions and dependent
+types (from step #2) and instantiate those templates with various types,
+some of which type-check and some that don’t, and test the error messages
+in each case.</li>
+</ul>
+</li>
+<li>There are some “extras” that make other features work better.  It’s worth
+handling these extras to give your expression complete integration into
+Clang:<ul>
+<li>Add code completion support for your expression in
+<tt class="docutils literal"><span class="pre">SemaCodeComplete.cpp</span></tt>.</li>
+<li>If your expression has types in it, or has any “interesting” features
+other than subexpressions, extend libclang’s <tt class="docutils literal"><span class="pre">CursorVisitor</span></tt> to provide
+proper visitation for your expression, enabling various IDE features such
+as syntax highlighting, cross-referencing, and so on.  The
+<tt class="docutils literal"><span class="pre">c-index-test</span></tt> helper program can be used to test these features.</li>
+</ul>
+</li>
+</ol>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ClangFormatStyleOptions.html">Clang-Format Style Options</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DriverInternals.html">Driver Design & Internals</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/IntroductionToTheClangAST.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/IntroductionToTheClangAST.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/IntroductionToTheClangAST.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/IntroductionToTheClangAST.html Mon Jun 16 08:19:07 2014
@@ -0,0 +1,182 @@
+
+
+<!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>Introduction to the Clang AST — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="LibTooling" href="LibTooling.html" />
+    <link rel="prev" title="External Clang Examples" href="ExternalClangExamples.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>Introduction to the Clang AST</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="ExternalClangExamples.html">External Clang Examples</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibTooling.html">LibTooling</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="introduction-to-the-clang-ast">
+<h1>Introduction to the Clang AST<a class="headerlink" href="#introduction-to-the-clang-ast" title="Permalink to this headline">Â¶</a></h1>
+<p>This document gives a gentle introduction to the mysteries of the Clang
+AST. It is targeted at developers who either want to contribute to
+Clang, or use tools that work based on Clang’s AST, like the AST
+matchers.</p>
+<center><iframe width="560" height="315" src="http://www.youtube.com/embed/VqCkCDFLSsc?vq=hd720" frameborder="0" allowfullscreen></iframe></center><p><a class="reference external" href="http://llvm.org/devmtg/2013-04/klimek-slides.pdf">Slides</a></p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">Â¶</a></h2>
+<p>Clang’s AST is different from ASTs produced by some other compilers in
+that it closely resembles both the written C++ code and the C++
+standard. For example, parenthesis expressions and compile time
+constants are available in an unreduced form in the AST. This makes
+Clang’s AST a good fit for refactoring tools.</p>
+<p>Documentation for all Clang AST nodes is available via the generated
+<a class="reference external" href="http://clang.llvm.org/doxygen">Doxygen</a>. The doxygen online
+documentation is also indexed by your favorite search engine, which will
+make a search for clang and the AST node’s class name usually turn up
+the doxygen of the class you’re looking for (for example, search for:
+clang ParenExpr).</p>
+</div>
+<div class="section" id="examining-the-ast">
+<h2>Examining the AST<a class="headerlink" href="#examining-the-ast" title="Permalink to this headline">Â¶</a></h2>
+<p>A good way to familarize yourself with the Clang AST is to actually look
+at it on some simple example code. Clang has a builtin AST-dump mode,
+which can be enabled with the flag <tt class="docutils literal"><span class="pre">-ast-dump</span></tt>.</p>
+<p>Let’s look at a simple example AST:</p>
+<div class="highlight-python"><pre>$ cat test.cc
+int f(int x) {
+  int result = (x / 42);
+  return result;
+}
+
+# Clang by default is a frontend for many tools; -Xclang is used to pass
+# options directly to the C++ frontend.
+$ clang -Xclang -ast-dump -fsyntax-only test.cc
+TranslationUnitDecl 0x5aea0d0 <<invalid sloc>>
+... cutting out internal declarations of clang ...
+`-FunctionDecl 0x5aeab50 <test.cc:1:1, line:4:1> f 'int (int)'
+  |-ParmVarDecl 0x5aeaa90 <line:1:7, col:11> x 'int'
+  `-CompoundStmt 0x5aead88 <col:14, line:4:1>
+    |-DeclStmt 0x5aead10 <line:2:3, col:24>
+    | `-VarDecl 0x5aeac10 <col:3, col:23> result 'int'
+    |   `-ParenExpr 0x5aeacf0 <col:16, col:23> 'int'
+    |     `-BinaryOperator 0x5aeacc8 <col:17, col:21> 'int' '/'
+    |       |-ImplicitCastExpr 0x5aeacb0 <col:17> 'int' <LValueToRValue>
+    |       | `-DeclRefExpr 0x5aeac68 <col:17> 'int' lvalue ParmVar 0x5aeaa90 'x' 'int'
+    |       `-IntegerLiteral 0x5aeac90 <col:21> 'int' 42
+    `-ReturnStmt 0x5aead68 <line:3:3, col:10>
+      `-ImplicitCastExpr 0x5aead50 <col:10> 'int' <LValueToRValue>
+        `-DeclRefExpr 0x5aead28 <col:10> 'int' lvalue Var 0x5aeac10 'result' 'int'</pre>
+</div>
+<p>The toplevel declaration in
+a translation unit is always the <a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html">translation unit
+declaration</a>.
+In this example, our first user written declaration is the <a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">function
+declaration</a>
+of “<tt class="docutils literal"><span class="pre">f</span></tt>”. The body of “<tt class="docutils literal"><span class="pre">f</span></tt>” is a <a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">compound
+statement</a>,
+whose child nodes are a <a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html">declaration
+statement</a>
+that declares our result variable, and the <a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html">return
+statement</a>.</p>
+</div>
+<div class="section" id="ast-context">
+<h2>AST Context<a class="headerlink" href="#ast-context" title="Permalink to this headline">Â¶</a></h2>
+<p>All information about the AST for a translation unit is bundled up in
+the class
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html">ASTContext</a>.
+It allows traversal of the whole translation unit starting from
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#abd909fb01ef10cfd0244832a67b1dd64">getTranslationUnitDecl</a>,
+or to access Clang’s <a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#a4f95adb9958e22fbe55212ae6482feb4">table of
+identifiers</a>
+for the parsed translation unit.</p>
+</div>
+<div class="section" id="ast-nodes">
+<h2>AST Nodes<a class="headerlink" href="#ast-nodes" title="Permalink to this headline">Â¶</a></h2>
+<p>Clang’s AST nodes are modeled on a class hierarchy that does not have a
+common ancestor. Instead, there are multiple larger hierarchies for
+basic node types like
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a> and
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>. Many
+important AST nodes derive from
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>,
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>,
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1DeclContext.html">DeclContext</a>
+or <a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>, with
+some classes deriving from both Decl and DeclContext.</p>
+<p>There are also a multitude of nodes in the AST that are not part of a
+larger hierarchy, and are only reachable from specific other nodes, like
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>.</p>
+<p>Thus, to traverse the full AST, one starts from the
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html">TranslationUnitDecl</a>
+and then recursively traverses everything that can be reached from that
+node - this information has to be encoded for each specific node type.
+This algorithm is encoded in the
+<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html">RecursiveASTVisitor</a>.
+See the <a class="reference external" href="http://clang.llvm.org/docs/RAVFrontendAction.html">RecursiveASTVisitor
+tutorial</a>.</p>
+<p>The two most basic nodes in the Clang AST are statements
+(<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>) and
+declarations
+(<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>). Note
+that expressions
+(<a class="reference external" href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>) are
+also statements in Clang’s AST.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="ExternalClangExamples.html">External Clang Examples</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibTooling.html">LibTooling</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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/3.4.2/tools/clang/docs/html/JSONCompilationDatabase.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.2/tools/clang/docs/html/JSONCompilationDatabase.html?rev=211020&view=auto
==============================================================================
--- www-releases/trunk/3.4.2/tools/clang/docs/html/JSONCompilationDatabase.html (added)
+++ www-releases/trunk/3.4.2/tools/clang/docs/html/JSONCompilationDatabase.html Mon Jun 16 08:19:07 2014
@@ -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>JSON Compilation Database Format Specification — Clang 3.4 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:     '3.4',
+        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 3.4 documentation" href="index.html" />
+    <link rel="next" title="Overview" href="ClangTools.html" />
+    <link rel="prev" title="How To Setup Clang Tooling For LLVM" href="HowToSetupToolingForLLVM.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.4 documentation</span></a></h1>
+        <h2 class="heading"><span>JSON Compilation Database Format Specification</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        Â«  <a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangTools.html">Overview</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="json-compilation-database-format-specification">
+<h1>JSON Compilation Database Format Specification<a class="headerlink" href="#json-compilation-database-format-specification" title="Permalink to this headline">Â¶</a></h1>
+<p>This document describes a format for specifying how to replay single
+compilations independently of the build system.</p>
+<div class="section" id="background">
+<h2>Background<a class="headerlink" href="#background" title="Permalink to this headline">Â¶</a></h2>
+<p>Tools based on the C++ Abstract Syntax Tree need full information how to
+parse a translation unit. Usually this information is implicitly
+available in the build system, but running tools as part of the build
+system is not necessarily the best solution:</p>
+<ul class="simple">
+<li>Build systems are inherently change driven, so running multiple tools
+over the same code base without changing the code does not fit into
+the architecture of many build systems.</li>
+<li>Figuring out whether things have changed is often an IO bound
+process; this makes it hard to build low latency end user tools based
+on the build system.</li>
+<li>Build systems are inherently sequential in the build graph, for
+example due to generated source code. While tools that run
+independently of the build still need the generated source code to
+exist, running tools multiple times over unchanging source does not
+require serialization of the runs according to the build dependency
+graph.</li>
+</ul>
+</div>
+<div class="section" id="supported-systems">
+<h2>Supported Systems<a class="headerlink" href="#supported-systems" title="Permalink to this headline">Â¶</a></h2>
+<p>Currently <a class="reference external" href="http://cmake.org">CMake</a> (since 2.8.5) supports generation
+of compilation databases for Unix Makefile builds (Ninja builds in the
+works) with the option <tt class="docutils literal"><span class="pre">CMAKE_EXPORT_COMPILE_COMMANDS</span></tt>.</p>
+<p>For projects on Linux, there is an alternative to intercept compiler
+calls with a tool called <a class="reference external" href="https://github.com/rizsotto/Bear">Bear</a>.</p>
+<p>Clang’s tooling interface supports reading compilation databases; see
+the <a class="reference internal" href="LibTooling.html"><em>LibTooling documentation</em></a>. libclang and its
+python bindings also support this (since clang 3.2); see
+<a class="reference external" href="/doxygen/group__COMPILATIONDB.html">CXCompilationDatabase.h</a>.</p>
+</div>
+<div class="section" id="format">
+<h2>Format<a class="headerlink" href="#format" title="Permalink to this headline">Â¶</a></h2>
+<p>A compilation database is a JSON file, which consist of an array of
+“command objects”, where each command object specifies one way a
+translation unit is compiled in the project.</p>
+<p>Each command object contains the translation unit’s main file, the
+working directory of the compile run and the actual compile command.</p>
+<p>Example:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span>
+  <span class="p">{</span> <span class="s">"directory"</span><span class="p">:</span> <span class="s">"/home/user/llvm/build"</span><span class="p">,</span>
+    <span class="s">"command"</span><span class="p">:</span> <span class="s">"/usr/bin/clang++ -Irelative -DSOMEDEF=</span><span class="se">\"</span><span class="s">With spaces, quotes and </span><span class="se">\\</span><span class="s">-es.</span><span class="se">\"</span><span class="s"> -c -o file.o file.cc"</span><span class="p">,</span>
+    <span class="s">"file"</span><span class="p">:</span> <span class="s">"file.cc"</span> <span class="p">},</span>
+  <span class="o">...</span>
+<span class="p">]</span>
+</pre></div>
+</div>
+<p>The contracts for each field in the command object are:</p>
+<ul class="simple">
+<li><strong>directory:</strong> The working directory of the compilation. All paths
+specified in the <strong>command</strong> or <strong>file</strong> fields must be either
+absolute or relative to this directory.</li>
+<li><strong>file:</strong> The main translation unit source processed by this
+compilation step. This is used by tools as the key into the
+compilation database. There can be multiple command objects for the
+same file, for example if the same source file is compiled with
+different configurations.</li>
+<li><strong>command:</strong> The compile command executed. After JSON unescaping,
+this must be a valid command to rerun the exact compilation step for
+the translation unit in the environment the build system uses.
+Parameters use shell quoting and shell escaping of quotes, with ‘<tt class="docutils literal"><span class="pre">"</span></tt>‘
+and ‘<tt class="docutils literal"><span class="pre">\</span></tt>‘ being the only special characters. Shell expansion is not
+supported.</li>
+</ul>
+</div>
+<div class="section" id="build-system-integration">
+<h2>Build System Integration<a class="headerlink" href="#build-system-integration" title="Permalink to this headline">Â¶</a></h2>
+<p>The convention is to name the file compile_commands.json and put it at
+the top of the build directory. Clang tools are pointed to the top of
+the build directory to detect the file and use the compilation database
+to parse C++ code in the source tree.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        Â«  <a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangTools.html">Overview</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2013, 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



