<div dir="ltr">This is great. Thanks Wilfred!<div><br></div><div>- Lang.</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Sat, Jul 2, 2016 at 10:02 AM, Wilfred Hughes via llvm-commits <span dir="ltr"><<a href="mailto:llvm-commits@lists.llvm.org" target="_blank">llvm-commits@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: wilfred<br>
Date: Sat Jul  2 12:01:59 2016<br>
New Revision: 274441<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=274441&view=rev" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project?rev=274441&view=rev</a><br>
Log:<br>
New Kaleidoscope chapter: Creating object files<br>
<br>
This new chapter describes compiling LLVM IR to object files.<br>
<br>
The new chaper is chapter 8, so later chapters have been renumbered.<br>
Since this brings us to 10 chapters total, I've also needed to rename<br>
the other chapters to use two digit numbering.<br>
<br>
Differential Revision: <a href="http://reviews.llvm.org/D18070" rel="noreferrer" target="_blank">http://reviews.llvm.org/D18070</a><br>
<br>
<br>
Added:<br>
    llvm/trunk/docs/tutorial/LangImpl01.rst<br>
    llvm/trunk/docs/tutorial/LangImpl02.rst<br>
    llvm/trunk/docs/tutorial/LangImpl03.rst<br>
    llvm/trunk/docs/tutorial/LangImpl04.rst<br>
    llvm/trunk/docs/tutorial/LangImpl05-cfg.png   (with props)<br>
    llvm/trunk/docs/tutorial/LangImpl05.rst<br>
    llvm/trunk/docs/tutorial/LangImpl06.rst<br>
    llvm/trunk/docs/tutorial/LangImpl07.rst<br>
    llvm/trunk/docs/tutorial/LangImpl08.rst<br>
    llvm/trunk/docs/tutorial/LangImpl09.rst<br>
    llvm/trunk/docs/tutorial/LangImpl10.rst<br>
    llvm/trunk/examples/Kaleidoscope/Chapter9/<br>
    llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt<br>
    llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp<br>
Removed:<br>
    llvm/trunk/docs/tutorial/LangImpl1.rst<br>
    llvm/trunk/docs/tutorial/LangImpl2.rst<br>
    llvm/trunk/docs/tutorial/LangImpl3.rst<br>
    llvm/trunk/docs/tutorial/LangImpl4.rst<br>
    llvm/trunk/docs/tutorial/LangImpl5-cfg.png<br>
    llvm/trunk/docs/tutorial/LangImpl5.rst<br>
    llvm/trunk/docs/tutorial/LangImpl6.rst<br>
    llvm/trunk/docs/tutorial/LangImpl7.rst<br>
    llvm/trunk/docs/tutorial/LangImpl8.rst<br>
    llvm/trunk/docs/tutorial/LangImpl9.rst<br>
Modified:<br>
    llvm/trunk/docs/tutorial/OCamlLangImpl5.rst<br>
    llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt<br>
    llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl01.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl01.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl01.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl01.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl01.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,293 @@<br>
+=================================================<br>
+Kaleidoscope: Tutorial Introduction and the Lexer<br>
+=================================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Tutorial Introduction<br>
+=====================<br>
+<br>
+Welcome to the "Implementing a language with LLVM" tutorial. This<br>
+tutorial runs through the implementation of a simple language, showing<br>
+how fun and easy it can be. This tutorial will get you up and started as<br>
+well as help to build a framework you can extend to other languages. The<br>
+code in this tutorial can also be used as a playground to hack on other<br>
+LLVM specific things.<br>
+<br>
+The goal of this tutorial is to progressively unveil our language,<br>
+describing how it is built up over time. This will let us cover a fairly<br>
+broad range of language design and LLVM-specific usage issues, showing<br>
+and explaining the code for it all along the way, without overwhelming<br>
+you with tons of details up front.<br>
+<br>
+It is useful to point out ahead of time that this tutorial is really<br>
+about teaching compiler techniques and LLVM specifically, *not* about<br>
+teaching modern and sane software engineering principles. In practice,<br>
+this means that we'll take a number of shortcuts to simplify the<br>
+exposition. For example, the code uses global variables<br>
+all over the place, doesn't use nice design patterns like<br>
+`visitors <<a href="http://en.wikipedia.org/wiki/Visitor_pattern" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Visitor_pattern</a>>`_, etc... but<br>
+it is very simple. If you dig in and use the code as a basis for future<br>
+projects, fixing these deficiencies shouldn't be hard.<br>
+<br>
+I've tried to put this tutorial together in a way that makes chapters<br>
+easy to skip over if you are already familiar with or are uninterested<br>
+in the various pieces. The structure of the tutorial is:<br>
+<br>
+-  `Chapter #1 <#language>`_: Introduction to the Kaleidoscope<br>
+   language, and the definition of its Lexer - This shows where we are<br>
+   going and the basic functionality that we want it to do. In order to<br>
+   make this tutorial maximally understandable and hackable, we choose<br>
+   to implement everything in C++ instead of using lexer and parser<br>
+   generators. LLVM obviously works just fine with such tools, feel free<br>
+   to use one if you prefer.<br>
+-  `Chapter #2 <LangImpl02.html>`_: Implementing a Parser and AST -<br>
+   With the lexer in place, we can talk about parsing techniques and<br>
+   basic AST construction. This tutorial describes recursive descent<br>
+   parsing and operator precedence parsing. Nothing in Chapters 1 or 2<br>
+   is LLVM-specific, the code doesn't even link in LLVM at this point.<br>
+   :)<br>
+-  `Chapter #3 <LangImpl03.html>`_: Code generation to LLVM IR - With<br>
+   the AST ready, we can show off how easy generation of LLVM IR really<br>
+   is.<br>
+-  `Chapter #4 <LangImpl04.html>`_: Adding JIT and Optimizer Support<br>
+   - Because a lot of people are interested in using LLVM as a JIT,<br>
+   we'll dive right into it and show you the 3 lines it takes to add JIT<br>
+   support. LLVM is also useful in many other ways, but this is one<br>
+   simple and "sexy" way to show off its power. :)<br>
+-  `Chapter #5 <LangImpl05.html>`_: Extending the Language: Control<br>
+   Flow - With the language up and running, we show how to extend it<br>
+   with control flow operations (if/then/else and a 'for' loop). This<br>
+   gives us a chance to talk about simple SSA construction and control<br>
+   flow.<br>
+-  `Chapter #6 <LangImpl06.html>`_: Extending the Language:<br>
+   User-defined Operators - This is a silly but fun chapter that talks<br>
+   about extending the language to let the user program define their own<br>
+   arbitrary unary and binary operators (with assignable precedence!).<br>
+   This lets us build a significant piece of the "language" as library<br>
+   routines.<br>
+-  `Chapter #7 <LangImpl07.html>`_: Extending the Language: Mutable<br>
+   Variables - This chapter talks about adding user-defined local<br>
+   variables along with an assignment operator. The interesting part<br>
+   about this is how easy and trivial it is to construct SSA form in<br>
+   LLVM: no, LLVM does *not* require your front-end to construct SSA<br>
+   form!<br>
+-  `Chapter #8 <LangImpl08.html>`_: Compiling to Object Files - This<br>
+   chapter explains how to take LLVM IR and compile it down to object<br>
+   files.<br>
+-  `Chapter #9 <LangImpl09.html>`_: Extending the Language: Debug<br>
+   Information - Having built a decent little programming language with<br>
+   control flow, functions and mutable variables, we consider what it<br>
+   takes to add debug information to standalone executables. This debug<br>
+   information will allow you to set breakpoints in Kaleidoscope<br>
+   functions, print out argument variables, and call functions - all<br>
+   from within the debugger!<br>
+-  `Chapter #10 <LangImpl10.html>`_: Conclusion and other useful LLVM<br>
+   tidbits - This chapter wraps up the series by talking about<br>
+   potential ways to extend the language, but also includes a bunch of<br>
+   pointers to info about "special topics" like adding garbage<br>
+   collection support, exceptions, debugging, support for "spaghetti<br>
+   stacks", and a bunch of other tips and tricks.<br>
+<br>
+By the end of the tutorial, we'll have written a bit less than 1000 lines<br>
+of non-comment, non-blank, lines of code. With this small amount of<br>
+code, we'll have built up a very reasonable compiler for a non-trivial<br>
+language including a hand-written lexer, parser, AST, as well as code<br>
+generation support with a JIT compiler. While other systems may have<br>
+interesting "hello world" tutorials, I think the breadth of this<br>
+tutorial is a great testament to the strengths of LLVM and why you<br>
+should consider it if you're interested in language or compiler design.<br>
+<br>
+A note about this tutorial: we expect you to extend the language and<br>
+play with it on your own. Take the code and go crazy hacking away at it,<br>
+compilers don't need to be scary creatures - it can be a lot of fun to<br>
+play with languages!<br>
+<br>
+The Basic Language<br>
+==================<br>
+<br>
+This tutorial will be illustrated with a toy language that we'll call<br>
+"`Kaleidoscope <<a href="http://en.wikipedia.org/wiki/Kaleidoscope" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Kaleidoscope</a>>`_" (derived<br>
+from "meaning beautiful, form, and view"). Kaleidoscope is a procedural<br>
+language that allows you to define functions, use conditionals, math,<br>
+etc. Over the course of the tutorial, we'll extend Kaleidoscope to<br>
+support the if/then/else construct, a for loop, user defined operators,<br>
+JIT compilation with a simple command line interface, etc.<br>
+<br>
+Because we want to keep things simple, the only datatype in Kaleidoscope<br>
+is a 64-bit floating point type (aka 'double' in C parlance). As such,<br>
+all values are implicitly double precision and the language doesn't<br>
+require type declarations. This gives the language a very nice and<br>
+simple syntax. For example, the following simple example computes<br>
+`Fibonacci numbers: <<a href="http://en.wikipedia.org/wiki/Fibonacci_number" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Fibonacci_number</a>>`_<br>
+<br>
+::<br>
+<br>
+    # Compute the x'th fibonacci number.<br>
+    def fib(x)<br>
+      if x < 3 then<br>
+        1<br>
+      else<br>
+        fib(x-1)+fib(x-2)<br>
+<br>
+    # This expression will compute the 40th number.<br>
+    fib(40)<br>
+<br>
+We also allow Kaleidoscope to call into standard library functions (the<br>
+LLVM JIT makes this completely trivial). This means that you can use the<br>
+'extern' keyword to define a function before you use it (this is also<br>
+useful for mutually recursive functions). For example:<br>
+<br>
+::<br>
+<br>
+    extern sin(arg);<br>
+    extern cos(arg);<br>
+    extern atan2(arg1 arg2);<br>
+<br>
+    atan2(sin(.4), cos(42))<br>
+<br>
+A more interesting example is included in Chapter 6 where we write a<br>
+little Kaleidoscope application that `displays a Mandelbrot<br>
+Set <LangImpl06.html#kicking-the-tires>`_ at various levels of magnification.<br>
+<br>
+Lets dive into the implementation of this language!<br>
+<br>
+The Lexer<br>
+=========<br>
+<br>
+When it comes to implementing a language, the first thing needed is the<br>
+ability to process a text file and recognize what it says. The<br>
+traditional way to do this is to use a<br>
+"`lexer <<a href="http://en.wikipedia.org/wiki/Lexical_analysis" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Lexical_analysis</a>>`_" (aka<br>
+'scanner') to break the input up into "tokens". Each token returned by<br>
+the lexer includes a token code and potentially some metadata (e.g. the<br>
+numeric value of a number). First, we define the possibilities:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    // The lexer returns tokens [0-255] if it is an unknown character, otherwise one<br>
+    // of these for known things.<br>
+    enum Token {<br>
+      tok_eof = -1,<br>
+<br>
+      // commands<br>
+      tok_def = -2,<br>
+      tok_extern = -3,<br>
+<br>
+      // primary<br>
+      tok_identifier = -4,<br>
+      tok_number = -5,<br>
+    };<br>
+<br>
+    static std::string IdentifierStr; // Filled in if tok_identifier<br>
+    static double NumVal;             // Filled in if tok_number<br>
+<br>
+Each token returned by our lexer will either be one of the Token enum<br>
+values or it will be an 'unknown' character like '+', which is returned<br>
+as its ASCII value. If the current token is an identifier, the<br>
+``IdentifierStr`` global variable holds the name of the identifier. If<br>
+the current token is a numeric literal (like 1.0), ``NumVal`` holds its<br>
+value. Note that we use global variables for simplicity, this is not the<br>
+best choice for a real language implementation :).<br>
+<br>
+The actual implementation of the lexer is a single function named<br>
+``gettok``. The ``gettok`` function is called to return the next token<br>
+from standard input. Its definition starts as:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// gettok - Return the next token from standard input.<br>
+    static int gettok() {<br>
+      static int LastChar = ' ';<br>
+<br>
+      // Skip any whitespace.<br>
+      while (isspace(LastChar))<br>
+        LastChar = getchar();<br>
+<br>
+``gettok`` works by calling the C ``getchar()`` function to read<br>
+characters one at a time from standard input. It eats them as it<br>
+recognizes them and stores the last character read, but not processed,<br>
+in LastChar. The first thing that it has to do is ignore whitespace<br>
+between tokens. This is accomplished with the loop above.<br>
+<br>
+The next thing ``gettok`` needs to do is recognize identifiers and<br>
+specific keywords like "def". Kaleidoscope does this with this simple<br>
+loop:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*<br>
+        IdentifierStr = LastChar;<br>
+        while (isalnum((LastChar = getchar())))<br>
+          IdentifierStr += LastChar;<br>
+<br>
+        if (IdentifierStr == "def")<br>
+          return tok_def;<br>
+        if (IdentifierStr == "extern")<br>
+          return tok_extern;<br>
+        return tok_identifier;<br>
+      }<br>
+<br>
+Note that this code sets the '``IdentifierStr``' global whenever it<br>
+lexes an identifier. Also, since language keywords are matched by the<br>
+same loop, we handle them here inline. Numeric values are similar:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+<br>
+        std::string NumStr;<br>
+        do {<br>
+          NumStr += LastChar;<br>
+          LastChar = getchar();<br>
+        } while (isdigit(LastChar) || LastChar == '.');<br>
+<br>
+        NumVal = strtod(NumStr.c_str(), 0);<br>
+        return tok_number;<br>
+      }<br>
+<br>
+This is all pretty straight-forward code for processing input. When<br>
+reading a numeric value from input, we use the C ``strtod`` function to<br>
+convert it to a numeric value that we store in ``NumVal``. Note that<br>
+this isn't doing sufficient error checking: it will incorrectly read<br>
+"1.23.45.67" and handle it as if you typed in "1.23". Feel free to<br>
+extend it :). Next we handle comments:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      if (LastChar == '#') {<br>
+        // Comment until end of line.<br>
+        do<br>
+          LastChar = getchar();<br>
+        while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');<br>
+<br>
+        if (LastChar != EOF)<br>
+          return gettok();<br>
+      }<br>
+<br>
+We handle comments by skipping to the end of the line and then return<br>
+the next token. Finally, if the input doesn't match one of the above<br>
+cases, it is either an operator character like '+' or the end of the<br>
+file. These are handled with this code:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Check for end of file.  Don't eat the EOF.<br>
+      if (LastChar == EOF)<br>
+        return tok_eof;<br>
+<br>
+      // Otherwise, just return the character as its ascii value.<br>
+      int ThisChar = LastChar;<br>
+      LastChar = getchar();<br>
+      return ThisChar;<br>
+    }<br>
+<br>
+With this, we have the complete lexer for the basic Kaleidoscope<br>
+language (the `full code listing <LangImpl02.html#full-code-listing>`_ for the Lexer<br>
+is available in the `next chapter <LangImpl02.html>`_ of the tutorial).<br>
+Next we'll `build a simple parser that uses this to build an Abstract<br>
+Syntax Tree <LangImpl02.html>`_. When we have that, we'll include a<br>
+driver so that you can use the lexer and parser together.<br>
+<br>
+`Next: Implementing a Parser and AST <LangImpl02.html>`_<br>
+<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl02.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl02.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl02.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl02.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl02.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,735 @@<br>
+===========================================<br>
+Kaleidoscope: Implementing a Parser and AST<br>
+===========================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Chapter 2 Introduction<br>
+======================<br>
+<br>
+Welcome to Chapter 2 of the "`Implementing a language with<br>
+LLVM <index.html>`_" tutorial. This chapter shows you how to use the<br>
+lexer, built in `Chapter 1 <LangImpl1.html>`_, to build a full<br>
+`parser <<a href="http://en.wikipedia.org/wiki/Parsing" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Parsing</a>>`_ for our Kaleidoscope<br>
+language. Once we have a parser, we'll define and build an `Abstract<br>
+Syntax Tree <<a href="http://en.wikipedia.org/wiki/Abstract_syntax_tree" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Abstract_syntax_tree</a>>`_ (AST).<br>
+<br>
+The parser we will build uses a combination of `Recursive Descent<br>
+Parsing <<a href="http://en.wikipedia.org/wiki/Recursive_descent_parser" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Recursive_descent_parser</a>>`_ and<br>
+`Operator-Precedence<br>
+Parsing <<a href="http://en.wikipedia.org/wiki/Operator-precedence_parser" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Operator-precedence_parser</a>>`_ to<br>
+parse the Kaleidoscope language (the latter for binary expressions and<br>
+the former for everything else). Before we get to parsing though, lets<br>
+talk about the output of the parser: the Abstract Syntax Tree.<br>
+<br>
+The Abstract Syntax Tree (AST)<br>
+==============================<br>
+<br>
+The AST for a program captures its behavior in such a way that it is<br>
+easy for later stages of the compiler (e.g. code generation) to<br>
+interpret. We basically want one object for each construct in the<br>
+language, and the AST should closely model the language. In<br>
+Kaleidoscope, we have expressions, a prototype, and a function object.<br>
+We'll start with expressions first:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// ExprAST - Base class for all expression nodes.<br>
+    class ExprAST {<br>
+    public:<br>
+      virtual ~ExprAST() {}<br>
+    };<br>
+<br>
+    /// NumberExprAST - Expression class for numeric literals like "1.0".<br>
+    class NumberExprAST : public ExprAST {<br>
+      double Val;<br>
+<br>
+    public:<br>
+      NumberExprAST(double Val) : Val(Val) {}<br>
+    };<br>
+<br>
+The code above shows the definition of the base ExprAST class and one<br>
+subclass which we use for numeric literals. The important thing to note<br>
+about this code is that the NumberExprAST class captures the numeric<br>
+value of the literal as an instance variable. This allows later phases<br>
+of the compiler to know what the stored numeric value is.<br>
+<br>
+Right now we only create the AST, so there are no useful accessor<br>
+methods on them. It would be very easy to add a virtual method to pretty<br>
+print the code, for example. Here are the other expression AST node<br>
+definitions that we'll use in the basic form of the Kaleidoscope<br>
+language:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// VariableExprAST - Expression class for referencing a variable, like "a".<br>
+    class VariableExprAST : public ExprAST {<br>
+      std::string Name;<br>
+<br>
+    public:<br>
+      VariableExprAST(const std::string &Name) : Name(Name) {}<br>
+    };<br>
+<br>
+    /// BinaryExprAST - Expression class for a binary operator.<br>
+    class BinaryExprAST : public ExprAST {<br>
+      char Op;<br>
+      std::unique_ptr<ExprAST> LHS, RHS;<br>
+<br>
+    public:<br>
+      BinaryExprAST(char op, std::unique_ptr<ExprAST> LHS,<br>
+                    std::unique_ptr<ExprAST> RHS)<br>
+        : Op(op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}<br>
+    };<br>
+<br>
+    /// CallExprAST - Expression class for function calls.<br>
+    class CallExprAST : public ExprAST {<br>
+      std::string Callee;<br>
+      std::vector<std::unique_ptr<ExprAST>> Args;<br>
+<br>
+    public:<br>
+      CallExprAST(const std::string &Callee,<br>
+                  std::vector<std::unique_ptr<ExprAST>> Args)<br>
+        : Callee(Callee), Args(std::move(Args)) {}<br>
+    };<br>
+<br>
+This is all (intentionally) rather straight-forward: variables capture<br>
+the variable name, binary operators capture their opcode (e.g. '+'), and<br>
+calls capture a function name as well as a list of any argument<br>
+expressions. One thing that is nice about our AST is that it captures<br>
+the language features without talking about the syntax of the language.<br>
+Note that there is no discussion about precedence of binary operators,<br>
+lexical structure, etc.<br>
+<br>
+For our basic language, these are all of the expression nodes we'll<br>
+define. Because it doesn't have conditional control flow, it isn't<br>
+Turing-complete; we'll fix that in a later installment. The two things<br>
+we need next are a way to talk about the interface to a function, and a<br>
+way to talk about functions themselves:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// PrototypeAST - This class represents the "prototype" for a function,<br>
+    /// which captures its name, and its argument names (thus implicitly the number<br>
+    /// of arguments the function takes).<br>
+    class PrototypeAST {<br>
+      std::string Name;<br>
+      std::vector<std::string> Args;<br>
+<br>
+    public:<br>
+      PrototypeAST(const std::string &name, std::vector<std::string> Args)<br>
+        : Name(name), Args(std::move(Args)) {}<br>
+    };<br>
+<br>
+    /// FunctionAST - This class represents a function definition itself.<br>
+    class FunctionAST {<br>
+      std::unique_ptr<PrototypeAST> Proto;<br>
+      std::unique_ptr<ExprAST> Body;<br>
+<br>
+    public:<br>
+      FunctionAST(std::unique_ptr<PrototypeAST> Proto,<br>
+                  std::unique_ptr<ExprAST> Body)<br>
+        : Proto(std::move(Proto)), Body(std::move(Body)) {}<br>
+    };<br>
+<br>
+In Kaleidoscope, functions are typed with just a count of their<br>
+arguments. Since all values are double precision floating point, the<br>
+type of each argument doesn't need to be stored anywhere. In a more<br>
+aggressive and realistic language, the "ExprAST" class would probably<br>
+have a type field.<br>
+<br>
+With this scaffolding, we can now talk about parsing expressions and<br>
+function bodies in Kaleidoscope.<br>
+<br>
+Parser Basics<br>
+=============<br>
+<br>
+Now that we have an AST to build, we need to define the parser code to<br>
+build it. The idea here is that we want to parse something like "x+y"<br>
+(which is returned as three tokens by the lexer) into an AST that could<br>
+be generated with calls like this:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      auto LHS = llvm::make_unique<VariableExprAST>("x");<br>
+      auto RHS = llvm::make_unique<VariableExprAST>("y");<br>
+      auto Result = std::make_unique<BinaryExprAST>('+', std::move(LHS),<br>
+                                                    std::move(RHS));<br>
+<br>
+In order to do this, we'll start by defining some basic helper routines:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current<br>
+    /// token the parser is looking at.  getNextToken reads another token from the<br>
+    /// lexer and updates CurTok with its results.<br>
+    static int CurTok;<br>
+    static int getNextToken() {<br>
+      return CurTok = gettok();<br>
+    }<br>
+<br>
+This implements a simple token buffer around the lexer. This allows us<br>
+to look one token ahead at what the lexer is returning. Every function<br>
+in our parser will assume that CurTok is the current token that needs to<br>
+be parsed.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+<br>
+    /// LogError* - These are little helper functions for error handling.<br>
+    std::unique_ptr<ExprAST> LogError(const char *Str) {<br>
+      fprintf(stderr, "LogError: %s\n", Str);<br>
+      return nullptr;<br>
+    }<br>
+    std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {<br>
+      LogError(Str);<br>
+      return nullptr;<br>
+    }<br>
+<br>
+The ``LogError`` routines are simple helper routines that our parser will<br>
+use to handle errors. The error recovery in our parser will not be the<br>
+best and is not particular user-friendly, but it will be enough for our<br>
+tutorial. These routines make it easier to handle errors in routines<br>
+that have various return types: they always return null.<br>
+<br>
+With these basic helper functions, we can implement the first piece of<br>
+our grammar: numeric literals.<br>
+<br>
+Basic Expression Parsing<br>
+========================<br>
+<br>
+We start with numeric literals, because they are the simplest to<br>
+process. For each production in our grammar, we'll define a function<br>
+which parses that production. For numeric literals, we have:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// numberexpr ::= number<br>
+    static std::unique_ptr<ExprAST> ParseNumberExpr() {<br>
+      auto Result = llvm::make_unique<NumberExprAST>(NumVal);<br>
+      getNextToken(); // consume the number<br>
+      return std::move(Result);<br>
+    }<br>
+<br>
+This routine is very simple: it expects to be called when the current<br>
+token is a ``tok_number`` token. It takes the current number value,<br>
+creates a ``NumberExprAST`` node, advances the lexer to the next token,<br>
+and finally returns.<br>
+<br>
+There are some interesting aspects to this. The most important one is<br>
+that this routine eats all of the tokens that correspond to the<br>
+production and returns the lexer buffer with the next token (which is<br>
+not part of the grammar production) ready to go. This is a fairly<br>
+standard way to go for recursive descent parsers. For a better example,<br>
+the parenthesis operator is defined like this:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// parenexpr ::= '(' expression ')'<br>
+    static std::unique_ptr<ExprAST> ParseParenExpr() {<br>
+      getNextToken(); // eat (.<br>
+      auto V = ParseExpression();<br>
+      if (!V)<br>
+        return nullptr;<br>
+<br>
+      if (CurTok != ')')<br>
+        return LogError("expected ')'");<br>
+      getNextToken(); // eat ).<br>
+      return V;<br>
+    }<br>
+<br>
+This function illustrates a number of interesting things about the<br>
+parser:<br>
+<br>
+1) It shows how we use the LogError routines. When called, this function<br>
+expects that the current token is a '(' token, but after parsing the<br>
+subexpression, it is possible that there is no ')' waiting. For example,<br>
+if the user types in "(4 x" instead of "(4)", the parser should emit an<br>
+error. Because errors can occur, the parser needs a way to indicate that<br>
+they happened: in our parser, we return null on an error.<br>
+<br>
+2) Another interesting aspect of this function is that it uses recursion<br>
+by calling ``ParseExpression`` (we will soon see that<br>
+``ParseExpression`` can call ``ParseParenExpr``). This is powerful<br>
+because it allows us to handle recursive grammars, and keeps each<br>
+production very simple. Note that parentheses do not cause construction<br>
+of AST nodes themselves. While we could do it this way, the most<br>
+important role of parentheses are to guide the parser and provide<br>
+grouping. Once the parser constructs the AST, parentheses are not<br>
+needed.<br>
+<br>
+The next simple production is for handling variable references and<br>
+function calls:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// identifierexpr<br>
+    ///   ::= identifier<br>
+    ///   ::= identifier '(' expression* ')'<br>
+    static std::unique_ptr<ExprAST> ParseIdentifierExpr() {<br>
+      std::string IdName = IdentifierStr;<br>
+<br>
+      getNextToken();  // eat identifier.<br>
+<br>
+      if (CurTok != '(') // Simple variable ref.<br>
+        return llvm::make_unique<VariableExprAST>(IdName);<br>
+<br>
+      // Call.<br>
+      getNextToken();  // eat (<br>
+      std::vector<std::unique_ptr<ExprAST>> Args;<br>
+      if (CurTok != ')') {<br>
+        while (1) {<br>
+          if (auto Arg = ParseExpression())<br>
+            Args.push_back(std::move(Arg));<br>
+          else<br>
+            return nullptr;<br>
+<br>
+          if (CurTok == ')')<br>
+            break;<br>
+<br>
+          if (CurTok != ',')<br>
+            return LogError("Expected ')' or ',' in argument list");<br>
+          getNextToken();<br>
+        }<br>
+      }<br>
+<br>
+      // Eat the ')'.<br>
+      getNextToken();<br>
+<br>
+      return llvm::make_unique<CallExprAST>(IdName, std::move(Args));<br>
+    }<br>
+<br>
+This routine follows the same style as the other routines. (It expects<br>
+to be called if the current token is a ``tok_identifier`` token). It<br>
+also has recursion and error handling. One interesting aspect of this is<br>
+that it uses *look-ahead* to determine if the current identifier is a<br>
+stand alone variable reference or if it is a function call expression.<br>
+It handles this by checking to see if the token after the identifier is<br>
+a '(' token, constructing either a ``VariableExprAST`` or<br>
+``CallExprAST`` node as appropriate.<br>
+<br>
+Now that we have all of our simple expression-parsing logic in place, we<br>
+can define a helper function to wrap it together into one entry point.<br>
+We call this class of expressions "primary" expressions, for reasons<br>
+that will become more clear `later in the<br>
+tutorial <LangImpl6.html#user-defined-unary-operators>`_. In order to parse an arbitrary<br>
+primary expression, we need to determine what sort of expression it is:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// primary<br>
+    ///   ::= identifierexpr<br>
+    ///   ::= numberexpr<br>
+    ///   ::= parenexpr<br>
+    static std::unique_ptr<ExprAST> ParsePrimary() {<br>
+      switch (CurTok) {<br>
+      default:<br>
+        return LogError("unknown token when expecting an expression");<br>
+      case tok_identifier:<br>
+        return ParseIdentifierExpr();<br>
+      case tok_number:<br>
+        return ParseNumberExpr();<br>
+      case '(':<br>
+        return ParseParenExpr();<br>
+      }<br>
+    }<br>
+<br>
+Now that you see the definition of this function, it is more obvious why<br>
+we can assume the state of CurTok in the various functions. This uses<br>
+look-ahead to determine which sort of expression is being inspected, and<br>
+then parses it with a function call.<br>
+<br>
+Now that basic expressions are handled, we need to handle binary<br>
+expressions. They are a bit more complex.<br>
+<br>
+Binary Expression Parsing<br>
+=========================<br>
+<br>
+Binary expressions are significantly harder to parse because they are<br>
+often ambiguous. For example, when given the string "x+y\*z", the parser<br>
+can choose to parse it as either "(x+y)\*z" or "x+(y\*z)". With common<br>
+definitions from mathematics, we expect the later parse, because "\*"<br>
+(multiplication) has higher *precedence* than "+" (addition).<br>
+<br>
+There are many ways to handle this, but an elegant and efficient way is<br>
+to use `Operator-Precedence<br>
+Parsing <<a href="http://en.wikipedia.org/wiki/Operator-precedence_parser" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Operator-precedence_parser</a>>`_.<br>
+This parsing technique uses the precedence of binary operators to guide<br>
+recursion. To start with, we need a table of precedences:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// BinopPrecedence - This holds the precedence for each binary operator that is<br>
+    /// defined.<br>
+    static std::map<char, int> BinopPrecedence;<br>
+<br>
+    /// GetTokPrecedence - Get the precedence of the pending binary operator token.<br>
+    static int GetTokPrecedence() {<br>
+      if (!isascii(CurTok))<br>
+        return -1;<br>
+<br>
+      // Make sure it's a declared binop.<br>
+      int TokPrec = BinopPrecedence[CurTok];<br>
+      if (TokPrec <= 0) return -1;<br>
+      return TokPrec;<br>
+    }<br>
+<br>
+    int main() {<br>
+      // Install standard binary operators.<br>
+      // 1 is lowest precedence.<br>
+      BinopPrecedence['<'] = 10;<br>
+      BinopPrecedence['+'] = 20;<br>
+      BinopPrecedence['-'] = 20;<br>
+      BinopPrecedence['*'] = 40;  // highest.<br>
+      ...<br>
+    }<br>
+<br>
+For the basic form of Kaleidoscope, we will only support 4 binary<br>
+operators (this can obviously be extended by you, our brave and intrepid<br>
+reader). The ``GetTokPrecedence`` function returns the precedence for<br>
+the current token, or -1 if the token is not a binary operator. Having a<br>
+map makes it easy to add new operators and makes it clear that the<br>
+algorithm doesn't depend on the specific operators involved, but it<br>
+would be easy enough to eliminate the map and do the comparisons in the<br>
+``GetTokPrecedence`` function. (Or just use a fixed-size array).<br>
+<br>
+With the helper above defined, we can now start parsing binary<br>
+expressions. The basic idea of operator precedence parsing is to break<br>
+down an expression with potentially ambiguous binary operators into<br>
+pieces. Consider, for example, the expression "a+b+(c+d)\*e\*f+g".<br>
+Operator precedence parsing considers this as a stream of primary<br>
+expressions separated by binary operators. As such, it will first parse<br>
+the leading primary expression "a", then it will see the pairs [+, b]<br>
+[+, (c+d)] [\*, e] [\*, f] and [+, g]. Note that because parentheses are<br>
+primary expressions, the binary expression parser doesn't need to worry<br>
+about nested subexpressions like (c+d) at all.<br>
+<br>
+To start, an expression is a primary expression potentially followed by<br>
+a sequence of [binop,primaryexpr] pairs:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// expression<br>
+    ///   ::= primary binoprhs<br>
+    ///<br>
+    static std::unique_ptr<ExprAST> ParseExpression() {<br>
+      auto LHS = ParsePrimary();<br>
+      if (!LHS)<br>
+        return nullptr;<br>
+<br>
+      return ParseBinOpRHS(0, std::move(LHS));<br>
+    }<br>
+<br>
+``ParseBinOpRHS`` is the function that parses the sequence of pairs for<br>
+us. It takes a precedence and a pointer to an expression for the part<br>
+that has been parsed so far. Note that "x" is a perfectly valid<br>
+expression: As such, "binoprhs" is allowed to be empty, in which case it<br>
+returns the expression that is passed into it. In our example above, the<br>
+code passes the expression for "a" into ``ParseBinOpRHS`` and the<br>
+current token is "+".<br>
+<br>
+The precedence value passed into ``ParseBinOpRHS`` indicates the<br>
+*minimal operator precedence* that the function is allowed to eat. For<br>
+example, if the current pair stream is [+, x] and ``ParseBinOpRHS`` is<br>
+passed in a precedence of 40, it will not consume any tokens (because<br>
+the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``<br>
+starts with:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// binoprhs<br>
+    ///   ::= ('+' primary)*<br>
+    static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,<br>
+                                                  std::unique_ptr<ExprAST> LHS) {<br>
+      // If this is a binop, find its precedence.<br>
+      while (1) {<br>
+        int TokPrec = GetTokPrecedence();<br>
+<br>
+        // If this is a binop that binds at least as tightly as the current binop,<br>
+        // consume it, otherwise we are done.<br>
+        if (TokPrec < ExprPrec)<br>
+          return LHS;<br>
+<br>
+This code gets the precedence of the current token and checks to see if<br>
+if is too low. Because we defined invalid tokens to have a precedence of<br>
+-1, this check implicitly knows that the pair-stream ends when the token<br>
+stream runs out of binary operators. If this check succeeds, we know<br>
+that the token is a binary operator and that it will be included in this<br>
+expression:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+        // Okay, we know this is a binop.<br>
+        int BinOp = CurTok;<br>
+        getNextToken();  // eat binop<br>
+<br>
+        // Parse the primary expression after the binary operator.<br>
+        auto RHS = ParsePrimary();<br>
+        if (!RHS)<br>
+          return nullptr;<br>
+<br>
+As such, this code eats (and remembers) the binary operator and then<br>
+parses the primary expression that follows. This builds up the whole<br>
+pair, the first of which is [+, b] for the running example.<br>
+<br>
+Now that we parsed the left-hand side of an expression and one pair of<br>
+the RHS sequence, we have to decide which way the expression associates.<br>
+In particular, we could have "(a+b) binop unparsed" or "a + (b binop<br>
+unparsed)". To determine this, we look ahead at "binop" to determine its<br>
+precedence and compare it to BinOp's precedence (which is '+' in this<br>
+case):<br>
+<br>
+.. code-block:: c++<br>
+<br>
+        // If BinOp binds less tightly with RHS than the operator after RHS, let<br>
+        // the pending operator take RHS as its LHS.<br>
+        int NextPrec = GetTokPrecedence();<br>
+        if (TokPrec < NextPrec) {<br>
+<br>
+If the precedence of the binop to the right of "RHS" is lower or equal<br>
+to the precedence of our current operator, then we know that the<br>
+parentheses associate as "(a+b) binop ...". In our example, the current<br>
+operator is "+" and the next operator is "+", we know that they have the<br>
+same precedence. In this case we'll create the AST node for "a+b", and<br>
+then continue parsing:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+          ... if body omitted ...<br>
+        }<br>
+<br>
+        // Merge LHS/RHS.<br>
+        LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),<br>
+                                               std::move(RHS));<br>
+      }  // loop around to the top of the while loop.<br>
+    }<br>
+<br>
+In our example above, this will turn "a+b+" into "(a+b)" and execute the<br>
+next iteration of the loop, with "+" as the current token. The code<br>
+above will eat, remember, and parse "(c+d)" as the primary expression,<br>
+which makes the current pair equal to [+, (c+d)]. It will then evaluate<br>
+the 'if' conditional above with "\*" as the binop to the right of the<br>
+primary. In this case, the precedence of "\*" is higher than the<br>
+precedence of "+" so the if condition will be entered.<br>
+<br>
+The critical question left here is "how can the if condition parse the<br>
+right hand side in full"? In particular, to build the AST correctly for<br>
+our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression<br>
+variable. The code to do this is surprisingly simple (code from the<br>
+above two blocks duplicated for context):<br>
+<br>
+.. code-block:: c++<br>
+<br>
+        // If BinOp binds less tightly with RHS than the operator after RHS, let<br>
+        // the pending operator take RHS as its LHS.<br>
+        int NextPrec = GetTokPrecedence();<br>
+        if (TokPrec < NextPrec) {<br>
+          RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));<br>
+          if (!RHS)<br>
+            return nullptr;<br>
+        }<br>
+        // Merge LHS/RHS.<br>
+        LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),<br>
+                                               std::move(RHS));<br>
+      }  // loop around to the top of the while loop.<br>
+    }<br>
+<br>
+At this point, we know that the binary operator to the RHS of our<br>
+primary has higher precedence than the binop we are currently parsing.<br>
+As such, we know that any sequence of pairs whose operators are all<br>
+higher precedence than "+" should be parsed together and returned as<br>
+"RHS". To do this, we recursively invoke the ``ParseBinOpRHS`` function<br>
+specifying "TokPrec+1" as the minimum precedence required for it to<br>
+continue. In our example above, this will cause it to return the AST<br>
+node for "(c+d)\*e\*f" as RHS, which is then set as the RHS of the '+'<br>
+expression.<br>
+<br>
+Finally, on the next iteration of the while loop, the "+g" piece is<br>
+parsed and added to the AST. With this little bit of code (14<br>
+non-trivial lines), we correctly handle fully general binary expression<br>
+parsing in a very elegant way. This was a whirlwind tour of this code,<br>
+and it is somewhat subtle. I recommend running through it with a few<br>
+tough examples to see how it works.<br>
+<br>
+This wraps up handling of expressions. At this point, we can point the<br>
+parser at an arbitrary token stream and build an expression from it,<br>
+stopping at the first token that is not part of the expression. Next up<br>
+we need to handle function definitions, etc.<br>
+<br>
+Parsing the Rest<br>
+================<br>
+<br>
+The next thing missing is handling of function prototypes. In<br>
+Kaleidoscope, these are used both for 'extern' function declarations as<br>
+well as function body definitions. The code to do this is<br>
+straight-forward and not very interesting (once you've survived<br>
+expressions):<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// prototype<br>
+    ///   ::= id '(' id* ')'<br>
+    static std::unique_ptr<PrototypeAST> ParsePrototype() {<br>
+      if (CurTok != tok_identifier)<br>
+        return LogErrorP("Expected function name in prototype");<br>
+<br>
+      std::string FnName = IdentifierStr;<br>
+      getNextToken();<br>
+<br>
+      if (CurTok != '(')<br>
+        return LogErrorP("Expected '(' in prototype");<br>
+<br>
+      // Read the list of argument names.<br>
+      std::vector<std::string> ArgNames;<br>
+      while (getNextToken() == tok_identifier)<br>
+        ArgNames.push_back(IdentifierStr);<br>
+      if (CurTok != ')')<br>
+        return LogErrorP("Expected ')' in prototype");<br>
+<br>
+      // success.<br>
+      getNextToken();  // eat ')'.<br>
+<br>
+      return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));<br>
+    }<br>
+<br>
+Given this, a function definition is very simple, just a prototype plus<br>
+an expression to implement the body:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// definition ::= 'def' prototype expression<br>
+    static std::unique_ptr<FunctionAST> ParseDefinition() {<br>
+      getNextToken();  // eat def.<br>
+      auto Proto = ParsePrototype();<br>
+      if (!Proto) return nullptr;<br>
+<br>
+      if (auto E = ParseExpression())<br>
+        return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));<br>
+      return nullptr;<br>
+    }<br>
+<br>
+In addition, we support 'extern' to declare functions like 'sin' and<br>
+'cos' as well as to support forward declaration of user functions. These<br>
+'extern's are just prototypes with no body:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// external ::= 'extern' prototype<br>
+    static std::unique_ptr<PrototypeAST> ParseExtern() {<br>
+      getNextToken();  // eat extern.<br>
+      return ParsePrototype();<br>
+    }<br>
+<br>
+Finally, we'll also let the user type in arbitrary top-level expressions<br>
+and evaluate them on the fly. We will handle this by defining anonymous<br>
+nullary (zero argument) functions for them:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// toplevelexpr ::= expression<br>
+    static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {<br>
+      if (auto E = ParseExpression()) {<br>
+        // Make an anonymous proto.<br>
+        auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());<br>
+        return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));<br>
+      }<br>
+      return nullptr;<br>
+    }<br>
+<br>
+Now that we have all the pieces, let's build a little driver that will<br>
+let us actually *execute* this code we've built!<br>
+<br>
+The Driver<br>
+==========<br>
+<br>
+The driver for this simply invokes all of the parsing pieces with a<br>
+top-level dispatch loop. There isn't much interesting here, so I'll just<br>
+include the top-level loop. See `below <#full-code-listing>`_ for full code in the<br>
+"Top-Level Parsing" section.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// top ::= definition | external | expression | ';'<br>
+    static void MainLoop() {<br>
+      while (1) {<br>
+        fprintf(stderr, "ready> ");<br>
+        switch (CurTok) {<br>
+        case tok_eof:<br>
+          return;<br>
+        case ';': // ignore top-level semicolons.<br>
+          getNextToken();<br>
+          break;<br>
+        case tok_def:<br>
+          HandleDefinition();<br>
+          break;<br>
+        case tok_extern:<br>
+          HandleExtern();<br>
+          break;<br>
+        default:<br>
+          HandleTopLevelExpression();<br>
+          break;<br>
+        }<br>
+      }<br>
+    }<br>
+<br>
+The most interesting part of this is that we ignore top-level<br>
+semicolons. Why is this, you ask? The basic reason is that if you type<br>
+"4 + 5" at the command line, the parser doesn't know whether that is the<br>
+end of what you will type or not. For example, on the next line you<br>
+could type "def foo..." in which case 4+5 is the end of a top-level<br>
+expression. Alternatively you could type "\* 6", which would continue<br>
+the expression. Having top-level semicolons allows you to type "4+5;",<br>
+and the parser will know you are done.<br>
+<br>
+Conclusions<br>
+===========<br>
+<br>
+With just under 400 lines of commented code (240 lines of non-comment,<br>
+non-blank code), we fully defined our minimal language, including a<br>
+lexer, parser, and AST builder. With this done, the executable will<br>
+validate Kaleidoscope code and tell us if it is grammatically invalid.<br>
+For example, here is a sample interaction:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    $ ./a.out<br>
+    ready> def foo(x y) x+foo(y, 4.0);<br>
+    Parsed a function definition.<br>
+    ready> def foo(x y) x+y y;<br>
+    Parsed a function definition.<br>
+    Parsed a top-level expr<br>
+    ready> def foo(x y) x+y );<br>
+    Parsed a function definition.<br>
+    Error: unknown token when expecting an expression<br>
+    ready> extern sin(a);<br>
+    ready> Parsed an extern<br>
+    ready> ^D<br>
+    $<br>
+<br>
+There is a lot of room for extension here. You can define new AST nodes,<br>
+extend the language in many ways, etc. In the `next<br>
+installment <LangImpl3.html>`_, we will describe how to generate LLVM<br>
+Intermediate Representation (IR) from the AST.<br>
+<br>
+Full Code Listing<br>
+=================<br>
+<br>
+Here is the complete code listing for this and the previous chapter.<br>
+Note that it is fully self-contained: you don't need LLVM or any<br>
+external libraries at all for this. (Besides the C and C++ standard<br>
+libraries, of course.) To build this, just compile with:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    # Compile<br>
+    clang++ -g -O3 toy.cpp<br>
+    # Run<br>
+    ./a.out<br>
+<br>
+Here is the code:<br>
+<br>
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter2/toy.cpp<br>
+   :language: c++<br>
+<br>
+`Next: Implementing Code Generation to LLVM IR <LangImpl03.html>`_<br>
+<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl03.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl03.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl03.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl03.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl03.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,567 @@<br>
+========================================<br>
+Kaleidoscope: Code generation to LLVM IR<br>
+========================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Chapter 3 Introduction<br>
+======================<br>
+<br>
+Welcome to Chapter 3 of the "`Implementing a language with<br>
+LLVM <index.html>`_" tutorial. This chapter shows you how to transform<br>
+the `Abstract Syntax Tree <LangImpl2.html>`_, built in Chapter 2, into<br>
+LLVM IR. This will teach you a little bit about how LLVM does things, as<br>
+well as demonstrate how easy it is to use. It's much more work to build<br>
+a lexer and parser than it is to generate LLVM IR code. :)<br>
+<br>
+**Please note**: the code in this chapter and later require LLVM 3.7 or<br>
+later. LLVM 3.6 and before will not work with it. Also note that you<br>
+need to use a version of this tutorial that matches your LLVM release:<br>
+If you are using an official LLVM release, use the version of the<br>
+documentation included with your release or on the `<a href="http://llvm.org" rel="noreferrer" target="_blank">llvm.org</a> releases<br>
+page <<a href="http://llvm.org/releases/" rel="noreferrer" target="_blank">http://llvm.org/releases/</a>>`_.<br>
+<br>
+Code Generation Setup<br>
+=====================<br>
+<br>
+In order to generate LLVM IR, we want some simple setup to get started.<br>
+First we define virtual code generation (codegen) methods in each AST<br>
+class:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// ExprAST - Base class for all expression nodes.<br>
+    class ExprAST {<br>
+    public:<br>
+      virtual ~ExprAST() {}<br>
+      virtual Value *codegen() = 0;<br>
+    };<br>
+<br>
+    /// NumberExprAST - Expression class for numeric literals like "1.0".<br>
+    class NumberExprAST : public ExprAST {<br>
+      double Val;<br>
+<br>
+    public:<br>
+      NumberExprAST(double Val) : Val(Val) {}<br>
+      virtual Value *codegen();<br>
+    };<br>
+    ...<br>
+<br>
+The codegen() method says to emit IR for that AST node along with all<br>
+the things it depends on, and they all return an LLVM Value object.<br>
+"Value" is the class used to represent a "`Static Single Assignment<br>
+(SSA) <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_<br>
+register" or "SSA value" in LLVM. The most distinct aspect of SSA values<br>
+is that their value is computed as the related instruction executes, and<br>
+it does not get a new value until (and if) the instruction re-executes.<br>
+In other words, there is no way to "change" an SSA value. For more<br>
+information, please read up on `Static Single<br>
+Assignment <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_<br>
+- the concepts are really quite natural once you grok them.<br>
+<br>
+Note that instead of adding virtual methods to the ExprAST class<br>
+hierarchy, it could also make sense to use a `visitor<br>
+pattern <<a href="http://en.wikipedia.org/wiki/Visitor_pattern" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Visitor_pattern</a>>`_ or some other<br>
+way to model this. Again, this tutorial won't dwell on good software<br>
+engineering practices: for our purposes, adding a virtual method is<br>
+simplest.<br>
+<br>
+The second thing we want is an "LogError" method like we used for the<br>
+parser, which will be used to report errors found during code generation<br>
+(for example, use of an undeclared parameter):<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    static LLVMContext TheContext;<br>
+    static IRBuilder<> Builder(TheContext);<br>
+    static std::unique_ptr<Module> TheModule;<br>
+    static std::map<std::string, Value *> NamedValues;<br>
+<br>
+    Value *LogErrorV(const char *Str) {<br>
+      LogError(Str);<br>
+      return nullptr;<br>
+    }<br>
+<br>
+The static variables will be used during code generation. ``TheContext``<br>
+is an opaque object that owns a lot of core LLVM data structures, such as<br>
+the type and constant value tables. We don't need to understand it in<br>
+detail, we just need a single instance to pass into APIs that require it.<br>
+<br>
+The ``Builder`` object is a helper object that makes it easy to generate<br>
+LLVM instructions. Instances of the<br>
+`IRBuilder <<a href="http://llvm.org/doxygen/IRBuilder_8h-source.html" rel="noreferrer" target="_blank">http://llvm.org/doxygen/IRBuilder_8h-source.html</a>>`_<br>
+class template keep track of the current place to insert instructions<br>
+and has methods to create new instructions.<br>
+<br>
+``TheModule`` is an LLVM construct that contains functions and global<br>
+variables. In many ways, it is the top-level structure that the LLVM IR<br>
+uses to contain code. It will own the memory for all of the IR that we<br>
+generate, which is why the codegen() method returns a raw Value\*,<br>
+rather than a unique_ptr<Value>.<br>
+<br>
+The ``NamedValues`` map keeps track of which values are defined in the<br>
+current scope and what their LLVM representation is. (In other words, it<br>
+is a symbol table for the code). In this form of Kaleidoscope, the only<br>
+things that can be referenced are function parameters. As such, function<br>
+parameters will be in this map when generating code for their function<br>
+body.<br>
+<br>
+With these basics in place, we can start talking about how to generate<br>
+code for each expression. Note that this assumes that the ``Builder``<br>
+has been set up to generate code *into* something. For now, we'll assume<br>
+that this has already been done, and we'll just use it to emit code.<br>
+<br>
+Expression Code Generation<br>
+==========================<br>
+<br>
+Generating LLVM code for expression nodes is very straightforward: less<br>
+than 45 lines of commented code for all four of our expression nodes.<br>
+First we'll do numeric literals:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *NumberExprAST::codegen() {<br>
+      return ConstantFP::get(LLVMContext, APFloat(Val));<br>
+    }<br>
+<br>
+In the LLVM IR, numeric constants are represented with the<br>
+``ConstantFP`` class, which holds the numeric value in an ``APFloat``<br>
+internally (``APFloat`` has the capability of holding floating point<br>
+constants of Arbitrary Precision). This code basically just creates<br>
+and returns a ``ConstantFP``. Note that in the LLVM IR that constants<br>
+are all uniqued together and shared. For this reason, the API uses the<br>
+"foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *VariableExprAST::codegen() {<br>
+      // Look this variable up in the function.<br>
+      Value *V = NamedValues[Name];<br>
+      if (!V)<br>
+        LogErrorV("Unknown variable name");<br>
+      return V;<br>
+    }<br>
+<br>
+References to variables are also quite simple using LLVM. In the simple<br>
+version of Kaleidoscope, we assume that the variable has already been<br>
+emitted somewhere and its value is available. In practice, the only<br>
+values that can be in the ``NamedValues`` map are function arguments.<br>
+This code simply checks to see that the specified name is in the map (if<br>
+not, an unknown variable is being referenced) and returns the value for<br>
+it. In future chapters, we'll add support for `loop induction<br>
+variables <LangImpl5.html#for-loop-expression>`_ in the symbol table, and for `local<br>
+variables <LangImpl7.html#user-defined-local-variables>`_.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *BinaryExprAST::codegen() {<br>
+      Value *L = LHS->codegen();<br>
+      Value *R = RHS->codegen();<br>
+      if (!L || !R)<br>
+        return nullptr;<br>
+<br>
+      switch (Op) {<br>
+      case '+':<br>
+        return Builder.CreateFAdd(L, R, "addtmp");<br>
+      case '-':<br>
+        return Builder.CreateFSub(L, R, "subtmp");<br>
+      case '*':<br>
+        return Builder.CreateFMul(L, R, "multmp");<br>
+      case '<':<br>
+        L = Builder.CreateFCmpULT(L, R, "cmptmp");<br>
+        // Convert bool 0/1 to double 0.0 or 1.0<br>
+        return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),<br>
+                                    "booltmp");<br>
+      default:<br>
+        return LogErrorV("invalid binary operator");<br>
+      }<br>
+    }<br>
+<br>
+Binary operators start to get more interesting. The basic idea here is<br>
+that we recursively emit code for the left-hand side of the expression,<br>
+then the right-hand side, then we compute the result of the binary<br>
+expression. In this code, we do a simple switch on the opcode to create<br>
+the right LLVM instruction.<br>
+<br>
+In the example above, the LLVM builder class is starting to show its<br>
+value. IRBuilder knows where to insert the newly created instruction,<br>
+all you have to do is specify what instruction to create (e.g. with<br>
+``CreateFAdd``), which operands to use (``L`` and ``R`` here) and<br>
+optionally provide a name for the generated instruction.<br>
+<br>
+One nice thing about LLVM is that the name is just a hint. For instance,<br>
+if the code above emits multiple "addtmp" variables, LLVM will<br>
+automatically provide each one with an increasing, unique numeric<br>
+suffix. Local value names for instructions are purely optional, but it<br>
+makes it much easier to read the IR dumps.<br>
+<br>
+`LLVM instructions <../LangRef.html#instruction-reference>`_ are constrained by strict<br>
+rules: for example, the Left and Right operators of an `add<br>
+instruction <../LangRef.html#add-instruction>`_ must have the same type, and the<br>
+result type of the add must match the operand types. Because all values<br>
+in Kaleidoscope are doubles, this makes for very simple code for add,<br>
+sub and mul.<br>
+<br>
+On the other hand, LLVM specifies that the `fcmp<br>
+instruction <../LangRef.html#fcmp-instruction>`_ always returns an 'i1' value (a<br>
+one bit integer). The problem with this is that Kaleidoscope wants the<br>
+value to be a 0.0 or 1.0 value. In order to get these semantics, we<br>
+combine the fcmp instruction with a `uitofp<br>
+instruction <../LangRef.html#uitofp-to-instruction>`_. This instruction converts its<br>
+input integer into a floating point value by treating the input as an<br>
+unsigned value. In contrast, if we used the `sitofp<br>
+instruction <../LangRef.html#sitofp-to-instruction>`_, the Kaleidoscope '<' operator<br>
+would return 0.0 and -1.0, depending on the input value.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *CallExprAST::codegen() {<br>
+      // Look up the name in the global module table.<br>
+      Function *CalleeF = TheModule->getFunction(Callee);<br>
+      if (!CalleeF)<br>
+        return LogErrorV("Unknown function referenced");<br>
+<br>
+      // If argument mismatch error.<br>
+      if (CalleeF->arg_size() != Args.size())<br>
+        return LogErrorV("Incorrect # arguments passed");<br>
+<br>
+      std::vector<Value *> ArgsV;<br>
+      for (unsigned i = 0, e = Args.size(); i != e; ++i) {<br>
+        ArgsV.push_back(Args[i]->codegen());<br>
+        if (!ArgsV.back())<br>
+          return nullptr;<br>
+      }<br>
+<br>
+      return Builder.CreateCall(CalleeF, ArgsV, "calltmp");<br>
+    }<br>
+<br>
+Code generation for function calls is quite straightforward with LLVM. The code<br>
+above initially does a function name lookup in the LLVM Module's symbol table.<br>
+Recall that the LLVM Module is the container that holds the functions we are<br>
+JIT'ing. By giving each function the same name as what the user specifies, we<br>
+can use the LLVM symbol table to resolve function names for us.<br>
+<br>
+Once we have the function to call, we recursively codegen each argument<br>
+that is to be passed in, and create an LLVM `call<br>
+instruction <../LangRef.html#call-instruction>`_. Note that LLVM uses the native C<br>
+calling conventions by default, allowing these calls to also call into<br>
+standard library functions like "sin" and "cos", with no additional<br>
+effort.<br>
+<br>
+This wraps up our handling of the four basic expressions that we have so<br>
+far in Kaleidoscope. Feel free to go in and add some more. For example,<br>
+by browsing the `LLVM language reference <../LangRef.html>`_ you'll find<br>
+several other interesting instructions that are really easy to plug into<br>
+our basic framework.<br>
+<br>
+Function Code Generation<br>
+========================<br>
+<br>
+Code generation for prototypes and functions must handle a number of<br>
+details, which make their code less beautiful than expression code<br>
+generation, but allows us to illustrate some important points. First,<br>
+lets talk about code generation for prototypes: they are used both for<br>
+function bodies and external function declarations. The code starts<br>
+with:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Function *PrototypeAST::codegen() {<br>
+      // Make the function type:  double(double,double) etc.<br>
+      std::vector<Type*> Doubles(Args.size(),<br>
+                                 Type::getDoubleTy(LLVMContext));<br>
+      FunctionType *FT =<br>
+        FunctionType::get(Type::getDoubleTy(LLVMContext), Doubles, false);<br>
+<br>
+      Function *F =<br>
+        Function::Create(FT, Function::ExternalLinkage, Name, TheModule);<br>
+<br>
+This code packs a lot of power into a few lines. Note first that this<br>
+function returns a "Function\*" instead of a "Value\*". Because a<br>
+"prototype" really talks about the external interface for a function<br>
+(not the value computed by an expression), it makes sense for it to<br>
+return the LLVM Function it corresponds to when codegen'd.<br>
+<br>
+The call to ``FunctionType::get`` creates the ``FunctionType`` that<br>
+should be used for a given Prototype. Since all function arguments in<br>
+Kaleidoscope are of type double, the first line creates a vector of "N"<br>
+LLVM double types. It then uses the ``Functiontype::get`` method to<br>
+create a function type that takes "N" doubles as arguments, returns one<br>
+double as a result, and that is not vararg (the false parameter<br>
+indicates this). Note that Types in LLVM are uniqued just like Constants<br>
+are, so you don't "new" a type, you "get" it.<br>
+<br>
+The final line above actually creates the IR Function corresponding to<br>
+the Prototype. This indicates the type, linkage and name to use, as<br>
+well as which module to insert into. "`external<br>
+linkage <../LangRef.html#linkage>`_" means that the function may be<br>
+defined outside the current module and/or that it is callable by<br>
+functions outside the module. The Name passed in is the name the user<br>
+specified: since "``TheModule``" is specified, this name is registered<br>
+in "``TheModule``"s symbol table.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  // Set names for all arguments.<br>
+  unsigned Idx = 0;<br>
+  for (auto &Arg : F->args())<br>
+    Arg.setName(Args[Idx++]);<br>
+<br>
+  return F;<br>
+<br>
+Finally, we set the name of each of the function's arguments according to the<br>
+names given in the Prototype. This step isn't strictly necessary, but keeping<br>
+the names consistent makes the IR more readable, and allows subsequent code to<br>
+refer directly to the arguments for their names, rather than having to look up<br>
+them up in the Prototype AST.<br>
+<br>
+At this point we have a function prototype with no body. This is how LLVM IR<br>
+represents function declarations. For extern statements in Kaleidoscope, this<br>
+is as far as we need to go. For function definitions however, we need to<br>
+codegen and attach a function body.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  Function *FunctionAST::codegen() {<br>
+      // First, check for an existing function from a previous 'extern' declaration.<br>
+    Function *TheFunction = TheModule->getFunction(Proto->getName());<br>
+<br>
+    if (!TheFunction)<br>
+      TheFunction = Proto->codegen();<br>
+<br>
+    if (!TheFunction)<br>
+      return nullptr;<br>
+<br>
+    if (!TheFunction->empty())<br>
+      return (Function*)LogErrorV("Function cannot be redefined.");<br>
+<br>
+<br>
+For function definitions, we start by searching TheModule's symbol table for an<br>
+existing version of this function, in case one has already been created using an<br>
+'extern' statement. If Module::getFunction returns null then no previous version<br>
+exists, so we'll codegen one from the Prototype. In either case, we want to<br>
+assert that the function is empty (i.e. has no body yet) before we start.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  // Create a new basic block to start insertion into.<br>
+  BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);<br>
+  Builder.SetInsertPoint(BB);<br>
+<br>
+  // Record the function arguments in the NamedValues map.<br>
+  NamedValues.clear();<br>
+  for (auto &Arg : TheFunction->args())<br>
+    NamedValues[Arg.getName()] = &Arg;<br>
+<br>
+Now we get to the point where the ``Builder`` is set up. The first line<br>
+creates a new `basic block <<a href="http://en.wikipedia.org/wiki/Basic_block" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Basic_block</a>>`_<br>
+(named "entry"), which is inserted into ``TheFunction``. The second line<br>
+then tells the builder that new instructions should be inserted into the<br>
+end of the new basic block. Basic blocks in LLVM are an important part<br>
+of functions that define the `Control Flow<br>
+Graph <<a href="http://en.wikipedia.org/wiki/Control_flow_graph" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Control_flow_graph</a>>`_. Since we<br>
+don't have any control flow, our functions will only contain one block<br>
+at this point. We'll fix this in `Chapter 5 <LangImpl5.html>`_ :).<br>
+<br>
+Next we add the function arguments to the NamedValues map (after first clearing<br>
+it out) so that they're accessible to ``VariableExprAST`` nodes.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      if (Value *RetVal = Body->codegen()) {<br>
+        // Finish off the function.<br>
+        Builder.CreateRet(RetVal);<br>
+<br>
+        // Validate the generated code, checking for consistency.<br>
+        verifyFunction(*TheFunction);<br>
+<br>
+        return TheFunction;<br>
+      }<br>
+<br>
+Once the insertion point has been set up and the NamedValues map populated,<br>
+we call the ``codegen()`` method for the root expression of the function. If no<br>
+error happens, this emits code to compute the expression into the entry block<br>
+and returns the value that was computed. Assuming no error, we then create an<br>
+LLVM `ret instruction <../LangRef.html#ret-instruction>`_, which completes the function.<br>
+Once the function is built, we call ``verifyFunction``, which is<br>
+provided by LLVM. This function does a variety of consistency checks on<br>
+the generated code, to determine if our compiler is doing everything<br>
+right. Using this is important: it can catch a lot of bugs. Once the<br>
+function is finished and validated, we return it.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Error reading body, remove function.<br>
+      TheFunction->eraseFromParent();<br>
+      return nullptr;<br>
+    }<br>
+<br>
+The only piece left here is handling of the error case. For simplicity,<br>
+we handle this by merely deleting the function we produced with the<br>
+``eraseFromParent`` method. This allows the user to redefine a function<br>
+that they incorrectly typed in before: if we didn't delete it, it would<br>
+live in the symbol table, with a body, preventing future redefinition.<br>
+<br>
+This code does have a bug, though: If the ``FunctionAST::codegen()`` method<br>
+finds an existing IR Function, it does not validate its signature against the<br>
+definition's own prototype. This means that an earlier 'extern' declaration will<br>
+take precedence over the function definition's signature, which can cause<br>
+codegen to fail, for instance if the function arguments are named differently.<br>
+There are a number of ways to fix this bug, see what you can come up with! Here<br>
+is a testcase:<br>
+<br>
+::<br>
+<br>
+    extern foo(a);     # ok, defines foo.<br>
+    def foo(b) b;      # Error: Unknown variable name. (decl using 'a' takes precedence).<br>
+<br>
+Driver Changes and Closing Thoughts<br>
+===================================<br>
+<br>
+For now, code generation to LLVM doesn't really get us much, except that<br>
+we can look at the pretty IR calls. The sample code inserts calls to<br>
+codegen into the "``HandleDefinition``", "``HandleExtern``" etc<br>
+functions, and then dumps out the LLVM IR. This gives a nice way to look<br>
+at the LLVM IR for simple functions. For example:<br>
+<br>
+::<br>
+<br>
+    ready> 4+5;<br>
+    Read top-level expression:<br>
+    define double @0() {<br>
+    entry:<br>
+      ret double 9.000000e+00<br>
+    }<br>
+<br>
+Note how the parser turns the top-level expression into anonymous<br>
+functions for us. This will be handy when we add `JIT<br>
+support <LangImpl4.html#adding-a-jit-compiler>`_ in the next chapter. Also note that the<br>
+code is very literally transcribed, no optimizations are being performed<br>
+except simple constant folding done by IRBuilder. We will `add<br>
+optimizations <LangImpl4.html#trivial-constant-folding>`_ explicitly in the next<br>
+chapter.<br>
+<br>
+::<br>
+<br>
+    ready> def foo(a b) a*a + 2*a*b + b*b;<br>
+    Read function definition:<br>
+    define double @foo(double %a, double %b) {<br>
+    entry:<br>
+      %multmp = fmul double %a, %a<br>
+      %multmp1 = fmul double 2.000000e+00, %a<br>
+      %multmp2 = fmul double %multmp1, %b<br>
+      %addtmp = fadd double %multmp, %multmp2<br>
+      %multmp3 = fmul double %b, %b<br>
+      %addtmp4 = fadd double %addtmp, %multmp3<br>
+      ret double %addtmp4<br>
+    }<br>
+<br>
+This shows some simple arithmetic. Notice the striking similarity to the<br>
+LLVM builder calls that we use to create the instructions.<br>
+<br>
+::<br>
+<br>
+    ready> def bar(a) foo(a, 4.0) + bar(31337);<br>
+    Read function definition:<br>
+    define double @bar(double %a) {<br>
+    entry:<br>
+      %calltmp = call double @foo(double %a, double 4.000000e+00)<br>
+      %calltmp1 = call double @bar(double 3.133700e+04)<br>
+      %addtmp = fadd double %calltmp, %calltmp1<br>
+      ret double %addtmp<br>
+    }<br>
+<br>
+This shows some function calls. Note that this function will take a long<br>
+time to execute if you call it. In the future we'll add conditional<br>
+control flow to actually make recursion useful :).<br>
+<br>
+::<br>
+<br>
+    ready> extern cos(x);<br>
+    Read extern:<br>
+    declare double @cos(double)<br>
+<br>
+    ready> cos(1.234);<br>
+    Read top-level expression:<br>
+    define double @1() {<br>
+    entry:<br>
+      %calltmp = call double @cos(double 1.234000e+00)<br>
+      ret double %calltmp<br>
+    }<br>
+<br>
+This shows an extern for the libm "cos" function, and a call to it.<br>
+<br>
+.. TODO:: Abandon Pygments' horrible `llvm` lexer. It just totally gives up<br>
+   on highlighting this due to the first line.<br>
+<br>
+::<br>
+<br>
+    ready> ^D<br>
+    ; ModuleID = 'my cool jit'<br>
+<br>
+    define double @0() {<br>
+    entry:<br>
+      %addtmp = fadd double 4.000000e+00, 5.000000e+00<br>
+      ret double %addtmp<br>
+    }<br>
+<br>
+    define double @foo(double %a, double %b) {<br>
+    entry:<br>
+      %multmp = fmul double %a, %a<br>
+      %multmp1 = fmul double 2.000000e+00, %a<br>
+      %multmp2 = fmul double %multmp1, %b<br>
+      %addtmp = fadd double %multmp, %multmp2<br>
+      %multmp3 = fmul double %b, %b<br>
+      %addtmp4 = fadd double %addtmp, %multmp3<br>
+      ret double %addtmp4<br>
+    }<br>
+<br>
+    define double @bar(double %a) {<br>
+    entry:<br>
+      %calltmp = call double @foo(double %a, double 4.000000e+00)<br>
+      %calltmp1 = call double @bar(double 3.133700e+04)<br>
+      %addtmp = fadd double %calltmp, %calltmp1<br>
+      ret double %addtmp<br>
+    }<br>
+<br>
+    declare double @cos(double)<br>
+<br>
+    define double @1() {<br>
+    entry:<br>
+      %calltmp = call double @cos(double 1.234000e+00)<br>
+      ret double %calltmp<br>
+    }<br>
+<br>
+When you quit the current demo, it dumps out the IR for the entire<br>
+module generated. Here you can see the big picture with all the<br>
+functions referencing each other.<br>
+<br>
+This wraps up the third chapter of the Kaleidoscope tutorial. Up next,<br>
+we'll describe how to `add JIT codegen and optimizer<br>
+support <LangImpl4.html>`_ to this so we can actually start running<br>
+code!<br>
+<br>
+Full Code Listing<br>
+=================<br>
+<br>
+Here is the complete code listing for our running example, enhanced with<br>
+the LLVM code generator. Because this uses the LLVM libraries, we need<br>
+to link them in. To do this, we use the<br>
+`llvm-config <<a href="http://llvm.org/cmds/llvm-config.html" rel="noreferrer" target="_blank">http://llvm.org/cmds/llvm-config.html</a>>`_ tool to inform<br>
+our makefile/command line about which options to use:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    # Compile<br>
+    clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core` -o toy<br>
+    # Run<br>
+    ./toy<br>
+<br>
+Here is the code:<br>
+<br>
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter3/toy.cpp<br>
+   :language: c++<br>
+<br>
+`Next: Adding JIT and Optimizer Support <LangImpl04.html>`_<br>
+<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl04.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl04.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl04.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl04.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl04.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,610 @@<br>
+==============================================<br>
+Kaleidoscope: Adding JIT and Optimizer Support<br>
+==============================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Chapter 4 Introduction<br>
+======================<br>
+<br>
+Welcome to Chapter 4 of the "`Implementing a language with<br>
+LLVM <index.html>`_" tutorial. Chapters 1-3 described the implementation<br>
+of a simple language and added support for generating LLVM IR. This<br>
+chapter describes two new techniques: adding optimizer support to your<br>
+language, and adding JIT compiler support. These additions will<br>
+demonstrate how to get nice, efficient code for the Kaleidoscope<br>
+language.<br>
+<br>
+Trivial Constant Folding<br>
+========================<br>
+<br>
+Our demonstration for Chapter 3 is elegant and easy to extend.<br>
+Unfortunately, it does not produce wonderful code. The IRBuilder,<br>
+however, does give us obvious optimizations when compiling simple code:<br>
+<br>
+::<br>
+<br>
+    ready> def test(x) 1+2+x;<br>
+    Read function definition:<br>
+    define double @test(double %x) {<br>
+    entry:<br>
+            %addtmp = fadd double 3.000000e+00, %x<br>
+            ret double %addtmp<br>
+    }<br>
+<br>
+This code is not a literal transcription of the AST built by parsing the<br>
+input. That would be:<br>
+<br>
+::<br>
+<br>
+    ready> def test(x) 1+2+x;<br>
+    Read function definition:<br>
+    define double @test(double %x) {<br>
+    entry:<br>
+            %addtmp = fadd double 2.000000e+00, 1.000000e+00<br>
+            %addtmp1 = fadd double %addtmp, %x<br>
+            ret double %addtmp1<br>
+    }<br>
+<br>
+Constant folding, as seen above, in particular, is a very common and<br>
+very important optimization: so much so that many language implementors<br>
+implement constant folding support in their AST representation.<br>
+<br>
+With LLVM, you don't need this support in the AST. Since all calls to<br>
+build LLVM IR go through the LLVM IR builder, the builder itself checked<br>
+to see if there was a constant folding opportunity when you call it. If<br>
+so, it just does the constant fold and return the constant instead of<br>
+creating an instruction.<br>
+<br>
+Well, that was easy :). In practice, we recommend always using<br>
+``IRBuilder`` when generating code like this. It has no "syntactic<br>
+overhead" for its use (you don't have to uglify your compiler with<br>
+constant checks everywhere) and it can dramatically reduce the amount of<br>
+LLVM IR that is generated in some cases (particular for languages with a<br>
+macro preprocessor or that use a lot of constants).<br>
+<br>
+On the other hand, the ``IRBuilder`` is limited by the fact that it does<br>
+all of its analysis inline with the code as it is built. If you take a<br>
+slightly more complex example:<br>
+<br>
+::<br>
+<br>
+    ready> def test(x) (1+2+x)*(x+(1+2));<br>
+    ready> Read function definition:<br>
+    define double @test(double %x) {<br>
+    entry:<br>
+            %addtmp = fadd double 3.000000e+00, %x<br>
+            %addtmp1 = fadd double %x, 3.000000e+00<br>
+            %multmp = fmul double %addtmp, %addtmp1<br>
+            ret double %multmp<br>
+    }<br>
+<br>
+In this case, the LHS and RHS of the multiplication are the same value.<br>
+We'd really like to see this generate "``tmp = x+3; result = tmp*tmp;``"<br>
+instead of computing "``x+3``" twice.<br>
+<br>
+Unfortunately, no amount of local analysis will be able to detect and<br>
+correct this. This requires two transformations: reassociation of<br>
+expressions (to make the add's lexically identical) and Common<br>
+Subexpression Elimination (CSE) to delete the redundant add instruction.<br>
+Fortunately, LLVM provides a broad range of optimizations that you can<br>
+use, in the form of "passes".<br>
+<br>
+LLVM Optimization Passes<br>
+========================<br>
+<br>
+LLVM provides many optimization passes, which do many different sorts of<br>
+things and have different tradeoffs. Unlike other systems, LLVM doesn't<br>
+hold to the mistaken notion that one set of optimizations is right for<br>
+all languages and for all situations. LLVM allows a compiler implementor<br>
+to make complete decisions about what optimizations to use, in which<br>
+order, and in what situation.<br>
+<br>
+As a concrete example, LLVM supports both "whole module" passes, which<br>
+look across as large of body of code as they can (often a whole file,<br>
+but if run at link time, this can be a substantial portion of the whole<br>
+program). It also supports and includes "per-function" passes which just<br>
+operate on a single function at a time, without looking at other<br>
+functions. For more information on passes and how they are run, see the<br>
+`How to Write a Pass <../WritingAnLLVMPass.html>`_ document and the<br>
+`List of LLVM Passes <../Passes.html>`_.<br>
+<br>
+For Kaleidoscope, we are currently generating functions on the fly, one<br>
+at a time, as the user types them in. We aren't shooting for the<br>
+ultimate optimization experience in this setting, but we also want to<br>
+catch the easy and quick stuff where possible. As such, we will choose<br>
+to run a few per-function optimizations as the user types the function<br>
+in. If we wanted to make a "static Kaleidoscope compiler", we would use<br>
+exactly the code we have now, except that we would defer running the<br>
+optimizer until the entire file has been parsed.<br>
+<br>
+In order to get per-function optimizations going, we need to set up a<br>
+`FunctionPassManager <../WritingAnLLVMPass.html#what-passmanager-doesr>`_ to hold<br>
+and organize the LLVM optimizations that we want to run. Once we have<br>
+that, we can add a set of optimizations to run. We'll need a new<br>
+FunctionPassManager for each module that we want to optimize, so we'll<br>
+write a function to create and initialize both the module and pass manager<br>
+for us:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    void InitializeModuleAndPassManager(void) {<br>
+      // Open a new module.<br>
+      Context LLVMContext;<br>
+      TheModule = llvm::make_unique<Module>("my cool jit", LLVMContext);<br>
+      TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());<br>
+<br>
+      // Create a new pass manager attached to it.<br>
+      TheFPM = llvm::make_unique<FunctionPassManager>(TheModule.get());<br>
+<br>
+      // Provide basic AliasAnalysis support for GVN.<br>
+      TheFPM.add(createBasicAliasAnalysisPass());<br>
+      // Do simple "peephole" optimizations and bit-twiddling optzns.<br>
+      TheFPM.add(createInstructionCombiningPass());<br>
+      // Reassociate expressions.<br>
+      TheFPM.add(createReassociatePass());<br>
+      // Eliminate Common SubExpressions.<br>
+      TheFPM.add(createGVNPass());<br>
+      // Simplify the control flow graph (deleting unreachable blocks, etc).<br>
+      TheFPM.add(createCFGSimplificationPass());<br>
+<br>
+      TheFPM.doInitialization();<br>
+    }<br>
+<br>
+This code initializes the global module ``TheModule``, and the function pass<br>
+manager ``TheFPM``, which is attached to ``TheModule``. Once the pass manager is<br>
+set up, we use a series of "add" calls to add a bunch of LLVM passes.<br>
+<br>
+In this case, we choose to add five passes: one analysis pass (alias analysis),<br>
+and four optimization passes. The passes we choose here are a pretty standard set<br>
+of "cleanup" optimizations that are useful for a wide variety of code. I won't<br>
+delve into what they do but, believe me, they are a good starting place :).<br>
+<br>
+Once the PassManager is set up, we need to make use of it. We do this by<br>
+running it after our newly created function is constructed (in<br>
+``FunctionAST::codegen()``), but before it is returned to the client:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      if (Value *RetVal = Body->codegen()) {<br>
+        // Finish off the function.<br>
+        Builder.CreateRet(RetVal);<br>
+<br>
+        // Validate the generated code, checking for consistency.<br>
+        verifyFunction(*TheFunction);<br>
+<br>
+        // Optimize the function.<br>
+        TheFPM->run(*TheFunction);<br>
+<br>
+        return TheFunction;<br>
+      }<br>
+<br>
+As you can see, this is pretty straightforward. The<br>
+``FunctionPassManager`` optimizes and updates the LLVM Function\* in<br>
+place, improving (hopefully) its body. With this in place, we can try<br>
+our test above again:<br>
+<br>
+::<br>
+<br>
+    ready> def test(x) (1+2+x)*(x+(1+2));<br>
+    ready> Read function definition:<br>
+    define double @test(double %x) {<br>
+    entry:<br>
+            %addtmp = fadd double %x, 3.000000e+00<br>
+            %multmp = fmul double %addtmp, %addtmp<br>
+            ret double %multmp<br>
+    }<br>
+<br>
+As expected, we now get our nicely optimized code, saving a floating<br>
+point add instruction from every execution of this function.<br>
+<br>
+LLVM provides a wide variety of optimizations that can be used in<br>
+certain circumstances. Some `documentation about the various<br>
+passes <../Passes.html>`_ is available, but it isn't very complete.<br>
+Another good source of ideas can come from looking at the passes that<br>
+``Clang`` runs to get started. The "``opt``" tool allows you to<br>
+experiment with passes from the command line, so you can see if they do<br>
+anything.<br>
+<br>
+Now that we have reasonable code coming out of our front-end, lets talk<br>
+about executing it!<br>
+<br>
+Adding a JIT Compiler<br>
+=====================<br>
+<br>
+Code that is available in LLVM IR can have a wide variety of tools<br>
+applied to it. For example, you can run optimizations on it (as we did<br>
+above), you can dump it out in textual or binary forms, you can compile<br>
+the code to an assembly file (.s) for some target, or you can JIT<br>
+compile it. The nice thing about the LLVM IR representation is that it<br>
+is the "common currency" between many different parts of the compiler.<br>
+<br>
+In this section, we'll add JIT compiler support to our interpreter. The<br>
+basic idea that we want for Kaleidoscope is to have the user enter<br>
+function bodies as they do now, but immediately evaluate the top-level<br>
+expressions they type in. For example, if they type in "1 + 2;", we<br>
+should evaluate and print out 3. If they define a function, they should<br>
+be able to call it from the command line.<br>
+<br>
+In order to do this, we first declare and initialize the JIT. This is<br>
+done by adding a global variable ``TheJIT``, and initializing it in<br>
+``main``:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    static std::unique_ptr<KaleidoscopeJIT> TheJIT;<br>
+    ...<br>
+    int main() {<br>
+      ..<br>
+      TheJIT = llvm::make_unique<KaleidoscopeJIT>();<br>
+<br>
+      // Run the main "interpreter loop" now.<br>
+      MainLoop();<br>
+<br>
+      return 0;<br>
+    }<br>
+<br>
+The KaleidoscopeJIT class is a simple JIT built specifically for these<br>
+tutorials. In later chapters we will look at how it works and extend it with<br>
+new features, but for now we will take it as given. Its API is very simple::<br>
+``addModule`` adds an LLVM IR module to the JIT, making its functions<br>
+available for execution; ``removeModule`` removes a module, freeing any<br>
+memory associated with the code in that module; and ``findSymbol`` allows us<br>
+to look up pointers to the compiled code.<br>
+<br>
+We can take this simple API and change our code that parses top-level expressions to<br>
+look like this:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    static void HandleTopLevelExpression() {<br>
+      // Evaluate a top-level expression into an anonymous function.<br>
+      if (auto FnAST = ParseTopLevelExpr()) {<br>
+        if (FnAST->codegen()) {<br>
+<br>
+          // JIT the module containing the anonymous expression, keeping a handle so<br>
+          // we can free it later.<br>
+          auto H = TheJIT->addModule(std::move(TheModule));<br>
+          InitializeModuleAndPassManager();<br>
+<br>
+          // Search the JIT for the __anon_expr symbol.<br>
+          auto ExprSymbol = TheJIT->findSymbol("__anon_expr");<br>
+          assert(ExprSymbol && "Function not found");<br>
+<br>
+          // Get the symbol's address and cast it to the right type (takes no<br>
+          // arguments, returns a double) so we can call it as a native function.<br>
+          double (*FP)() = (double (*)())(intptr_t)ExprSymbol.getAddress();<br>
+          fprintf(stderr, "Evaluated to %f\n", FP());<br>
+<br>
+          // Delete the anonymous expression module from the JIT.<br>
+          TheJIT->removeModule(H);<br>
+        }<br>
+<br>
+If parsing and codegen succeeed, the next step is to add the module containing<br>
+the top-level expression to the JIT. We do this by calling addModule, which<br>
+triggers code generation for all the functions in the module, and returns a<br>
+handle that can be used to remove the module from the JIT later. Once the module<br>
+has been added to the JIT it can no longer be modified, so we also open a new<br>
+module to hold subsequent code by calling ``InitializeModuleAndPassManager()``.<br>
+<br>
+Once we've added the module to the JIT we need to get a pointer to the final<br>
+generated code. We do this by calling the JIT's findSymbol method, and passing<br>
+the name of the top-level expression function: ``__anon_expr``. Since we just<br>
+added this function, we assert that findSymbol returned a result.<br>
+<br>
+Next, we get the in-memory address of the ``__anon_expr`` function by calling<br>
+``getAddress()`` on the symbol. Recall that we compile top-level expressions<br>
+into a self-contained LLVM function that takes no arguments and returns the<br>
+computed double. Because the LLVM JIT compiler matches the native platform ABI,<br>
+this means that you can just cast the result pointer to a function pointer of<br>
+that type and call it directly. This means, there is no difference between JIT<br>
+compiled code and native machine code that is statically linked into your<br>
+application.<br>
+<br>
+Finally, since we don't support re-evaluation of top-level expressions, we<br>
+remove the module from the JIT when we're done to free the associated memory.<br>
+Recall, however, that the module we created a few lines earlier (via<br>
+``InitializeModuleAndPassManager``) is still open and waiting for new code to be<br>
+added.<br>
+<br>
+With just these two changes, lets see how Kaleidoscope works now!<br>
+<br>
+::<br>
+<br>
+    ready> 4+5;<br>
+    Read top-level expression:<br>
+    define double @0() {<br>
+    entry:<br>
+      ret double 9.000000e+00<br>
+    }<br>
+<br>
+    Evaluated to 9.000000<br>
+<br>
+Well this looks like it is basically working. The dump of the function<br>
+shows the "no argument function that always returns double" that we<br>
+synthesize for each top-level expression that is typed in. This<br>
+demonstrates very basic functionality, but can we do more?<br>
+<br>
+::<br>
+<br>
+    ready> def testfunc(x y) x + y*2;<br>
+    Read function definition:<br>
+    define double @testfunc(double %x, double %y) {<br>
+    entry:<br>
+      %multmp = fmul double %y, 2.000000e+00<br>
+      %addtmp = fadd double %multmp, %x<br>
+      ret double %addtmp<br>
+    }<br>
+<br>
+    ready> testfunc(4, 10);<br>
+    Read top-level expression:<br>
+    define double @1() {<br>
+    entry:<br>
+      %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01)<br>
+      ret double %calltmp<br>
+    }<br>
+<br>
+    Evaluated to 24.000000<br>
+<br>
+    ready> testfunc(5, 10);<br>
+    ready> LLVM ERROR: Program used external function 'testfunc' which could not be resolved!<br>
+<br>
+<br>
+Function definitions and calls also work, but something went very wrong on that<br>
+last line. The call looks valid, so what happened? As you may have guessed from<br>
+the the API a Module is a unit of allocation for the JIT, and testfunc was part<br>
+of the same module that contained anonymous expression. When we removed that<br>
+module from the JIT to free the memory for the anonymous expression, we deleted<br>
+the definition of ``testfunc`` along with it. Then, when we tried to call<br>
+testfunc a second time, the JIT could no longer find it.<br>
+<br>
+The easiest way to fix this is to put the anonymous expression in a separate<br>
+module from the rest of the function definitions. The JIT will happily resolve<br>
+function calls across module boundaries, as long as each of the functions called<br>
+has a prototype, and is added to the JIT before it is called. By putting the<br>
+anonymous expression in a different module we can delete it without affecting<br>
+the rest of the functions.<br>
+<br>
+In fact, we're going to go a step further and put every function in its own<br>
+module. Doing so allows us to exploit a useful property of the KaleidoscopeJIT<br>
+that will make our environment more REPL-like: Functions can be added to the<br>
+JIT more than once (unlike a module where every function must have a unique<br>
+definition). When you look up a symbol in KaleidoscopeJIT it will always return<br>
+the most recent definition:<br>
+<br>
+::<br>
+<br>
+    ready> def foo(x) x + 1;<br>
+    Read function definition:<br>
+    define double @foo(double %x) {<br>
+    entry:<br>
+      %addtmp = fadd double %x, 1.000000e+00<br>
+      ret double %addtmp<br>
+    }<br>
+<br>
+    ready> foo(2);<br>
+    Evaluated to 3.000000<br>
+<br>
+    ready> def foo(x) x + 2;<br>
+    define double @foo(double %x) {<br>
+    entry:<br>
+      %addtmp = fadd double %x, 2.000000e+00<br>
+      ret double %addtmp<br>
+    }<br>
+<br>
+    ready> foo(2);<br>
+    Evaluated to 4.000000<br>
+<br>
+<br>
+To allow each function to live in its own module we'll need a way to<br>
+re-generate previous function declarations into each new module we open:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    static std::unique_ptr<KaleidoscopeJIT> TheJIT;<br>
+<br>
+    ...<br>
+<br>
+    Function *getFunction(std::string Name) {<br>
+      // First, see if the function has already been added to the current module.<br>
+      if (auto *F = TheModule->getFunction(Name))<br>
+        return F;<br>
+<br>
+      // If not, check whether we can codegen the declaration from some existing<br>
+      // prototype.<br>
+      auto FI = FunctionProtos.find(Name);<br>
+      if (FI != FunctionProtos.end())<br>
+        return FI->second->codegen();<br>
+<br>
+      // If no existing prototype exists, return null.<br>
+      return nullptr;<br>
+    }<br>
+<br>
+    ...<br>
+<br>
+    Value *CallExprAST::codegen() {<br>
+      // Look up the name in the global module table.<br>
+      Function *CalleeF = getFunction(Callee);<br>
+<br>
+    ...<br>
+<br>
+    Function *FunctionAST::codegen() {<br>
+      // Transfer ownership of the prototype to the FunctionProtos map, but keep a<br>
+      // reference to it for use below.<br>
+      auto &P = *Proto;<br>
+      FunctionProtos[Proto->getName()] = std::move(Proto);<br>
+      Function *TheFunction = getFunction(P.getName());<br>
+      if (!TheFunction)<br>
+        return nullptr;<br>
+<br>
+<br>
+To enable this, we'll start by adding a new global, ``FunctionProtos``, that<br>
+holds the most recent prototype for each function. We'll also add a convenience<br>
+method, ``getFunction()``, to replace calls to ``TheModule->getFunction()``.<br>
+Our convenience method searches ``TheModule`` for an existing function<br>
+declaration, falling back to generating a new declaration from FunctionProtos if<br>
+it doesn't find one. In ``CallExprAST::codegen()`` we just need to replace the<br>
+call to ``TheModule->getFunction()``. In ``FunctionAST::codegen()`` we need to<br>
+update the FunctionProtos map first, then call ``getFunction()``. With this<br>
+done, we can always obtain a function declaration in the current module for any<br>
+previously declared function.<br>
+<br>
+We also need to update HandleDefinition and HandleExtern:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    static void HandleDefinition() {<br>
+      if (auto FnAST = ParseDefinition()) {<br>
+        if (auto *FnIR = FnAST->codegen()) {<br>
+          fprintf(stderr, "Read function definition:");<br>
+          FnIR->dump();<br>
+          TheJIT->addModule(std::move(TheModule));<br>
+          InitializeModuleAndPassManager();<br>
+        }<br>
+      } else {<br>
+        // Skip token for error recovery.<br>
+         getNextToken();<br>
+      }<br>
+    }<br>
+<br>
+    static void HandleExtern() {<br>
+      if (auto ProtoAST = ParseExtern()) {<br>
+        if (auto *FnIR = ProtoAST->codegen()) {<br>
+          fprintf(stderr, "Read extern: ");<br>
+          FnIR->dump();<br>
+          FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);<br>
+        }<br>
+      } else {<br>
+        // Skip token for error recovery.<br>
+        getNextToken();<br>
+      }<br>
+    }<br>
+<br>
+In HandleDefinition, we add two lines to transfer the newly defined function to<br>
+the JIT and open a new module. In HandleExtern, we just need to add one line to<br>
+add the prototype to FunctionProtos.<br>
+<br>
+With these changes made, lets try our REPL again (I removed the dump of the<br>
+anonymous functions this time, you should get the idea by now :) :<br>
+<br>
+::<br>
+<br>
+    ready> def foo(x) x + 1;<br>
+    ready> foo(2);<br>
+    Evaluated to 3.000000<br>
+<br>
+    ready> def foo(x) x + 2;<br>
+    ready> foo(2);<br>
+    Evaluated to 4.000000<br>
+<br>
+It works!<br>
+<br>
+Even with this simple code, we get some surprisingly powerful capabilities -<br>
+check this out:<br>
+<br>
+::<br>
+<br>
+    ready> extern sin(x);<br>
+    Read extern:<br>
+    declare double @sin(double)<br>
+<br>
+    ready> extern cos(x);<br>
+    Read extern:<br>
+    declare double @cos(double)<br>
+<br>
+    ready> sin(1.0);<br>
+    Read top-level expression:<br>
+    define double @2() {<br>
+    entry:<br>
+      ret double 0x3FEAED548F090CEE<br>
+    }<br>
+<br>
+    Evaluated to 0.841471<br>
+<br>
+    ready> def foo(x) sin(x)*sin(x) + cos(x)*cos(x);<br>
+    Read function definition:<br>
+    define double @foo(double %x) {<br>
+    entry:<br>
+      %calltmp = call double @sin(double %x)<br>
+      %multmp = fmul double %calltmp, %calltmp<br>
+      %calltmp2 = call double @cos(double %x)<br>
+      %multmp4 = fmul double %calltmp2, %calltmp2<br>
+      %addtmp = fadd double %multmp, %multmp4<br>
+      ret double %addtmp<br>
+    }<br>
+<br>
+    ready> foo(4.0);<br>
+    Read top-level expression:<br>
+    define double @3() {<br>
+    entry:<br>
+      %calltmp = call double @foo(double 4.000000e+00)<br>
+      ret double %calltmp<br>
+    }<br>
+<br>
+    Evaluated to 1.000000<br>
+<br>
+Whoa, how does the JIT know about sin and cos? The answer is surprisingly<br>
+simple: The KaleidoscopeJIT has a straightforward symbol resolution rule that<br>
+it uses to find symbols that aren't available in any given module: First<br>
+it searches all the modules that have already been added to the JIT, from the<br>
+most recent to the oldest, to find the newest definition. If no definition is<br>
+found inside the JIT, it falls back to calling "``dlsym("sin")``" on the<br>
+Kaleidoscope process itself. Since "``sin``" is defined within the JIT's<br>
+address space, it simply patches up calls in the module to call the libm<br>
+version of ``sin`` directly.<br>
+<br>
+In the future we'll see how tweaking this symbol resolution rule can be used to<br>
+enable all sorts of useful features, from security (restricting the set of<br>
+symbols available to JIT'd code), to dynamic code generation based on symbol<br>
+names, and even lazy compilation.<br>
+<br>
+One immediate benefit of the symbol resolution rule is that we can now extend<br>
+the language by writing arbitrary C++ code to implement operations. For example,<br>
+if we add:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// putchard - putchar that takes a double and returns 0.<br>
+    extern "C" double putchard(double X) {<br>
+      fputc((char)X, stderr);<br>
+      return 0;<br>
+    }<br>
+<br>
+Now we can produce simple output to the console by using things like:<br>
+"``extern putchard(x); putchard(120);``", which prints a lowercase 'x'<br>
+on the console (120 is the ASCII code for 'x'). Similar code could be<br>
+used to implement file I/O, console input, and many other capabilities<br>
+in Kaleidoscope.<br>
+<br>
+This completes the JIT and optimizer chapter of the Kaleidoscope<br>
+tutorial. At this point, we can compile a non-Turing-complete<br>
+programming language, optimize and JIT compile it in a user-driven way.<br>
+Next up we'll look into `extending the language with control flow<br>
+constructs <LangImpl5.html>`_, tackling some interesting LLVM IR issues<br>
+along the way.<br>
+<br>
+Full Code Listing<br>
+=================<br>
+<br>
+Here is the complete code listing for our running example, enhanced with<br>
+the LLVM JIT and optimizer. To build this example, use:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    # Compile<br>
+    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
+    # Run<br>
+    ./toy<br>
+<br>
+If you are compiling this on Linux, make sure to add the "-rdynamic"<br>
+option as well. This makes sure that the external functions are resolved<br>
+properly at runtime.<br>
+<br>
+Here is the code:<br>
+<br>
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter4/toy.cpp<br>
+   :language: c++<br>
+<br>
+`Next: Extending the language: control flow <LangImpl05.html>`_<br>
+<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl05-cfg.png<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl05-cfg.png?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl05-cfg.png?rev=274441&view=auto</a><br>
==============================================================================<br>
Binary file - no diff available.<br>
<br>
Propchange: llvm/trunk/docs/tutorial/LangImpl05-cfg.png<br>
------------------------------------------------------------------------------<br>
    svn:mime-type = image/png<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl05.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl05.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl05.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl05.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl05.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,790 @@<br>
+==================================================<br>
+Kaleidoscope: Extending the Language: Control Flow<br>
+==================================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Chapter 5 Introduction<br>
+======================<br>
+<br>
+Welcome to Chapter 5 of the "`Implementing a language with<br>
+LLVM <index.html>`_" tutorial. Parts 1-4 described the implementation of<br>
+the simple Kaleidoscope language and included support for generating<br>
+LLVM IR, followed by optimizations and a JIT compiler. Unfortunately, as<br>
+presented, Kaleidoscope is mostly useless: it has no control flow other<br>
+than call and return. This means that you can't have conditional<br>
+branches in the code, significantly limiting its power. In this episode<br>
+of "build that compiler", we'll extend Kaleidoscope to have an<br>
+if/then/else expression plus a simple 'for' loop.<br>
+<br>
+If/Then/Else<br>
+============<br>
+<br>
+Extending Kaleidoscope to support if/then/else is quite straightforward.<br>
+It basically requires adding support for this "new" concept to the<br>
+lexer, parser, AST, and LLVM code emitter. This example is nice, because<br>
+it shows how easy it is to "grow" a language over time, incrementally<br>
+extending it as new ideas are discovered.<br>
+<br>
+Before we get going on "how" we add this extension, lets talk about<br>
+"what" we want. The basic idea is that we want to be able to write this<br>
+sort of thing:<br>
+<br>
+::<br>
+<br>
+    def fib(x)<br>
+      if x < 3 then<br>
+        1<br>
+      else<br>
+        fib(x-1)+fib(x-2);<br>
+<br>
+In Kaleidoscope, every construct is an expression: there are no<br>
+statements. As such, the if/then/else expression needs to return a value<br>
+like any other. Since we're using a mostly functional form, we'll have<br>
+it evaluate its conditional, then return the 'then' or 'else' value<br>
+based on how the condition was resolved. This is very similar to the C<br>
+"?:" expression.<br>
+<br>
+The semantics of the if/then/else expression is that it evaluates the<br>
+condition to a boolean equality value: 0.0 is considered to be false and<br>
+everything else is considered to be true. If the condition is true, the<br>
+first subexpression is evaluated and returned, if the condition is<br>
+false, the second subexpression is evaluated and returned. Since<br>
+Kaleidoscope allows side-effects, this behavior is important to nail<br>
+down.<br>
+<br>
+Now that we know what we "want", lets break this down into its<br>
+constituent pieces.<br>
+<br>
+Lexer Extensions for If/Then/Else<br>
+---------------------------------<br>
+<br>
+The lexer extensions are straightforward. First we add new enum values<br>
+for the relevant tokens:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // control<br>
+      tok_if = -6,<br>
+      tok_then = -7,<br>
+      tok_else = -8,<br>
+<br>
+Once we have that, we recognize the new keywords in the lexer. This is<br>
+pretty simple stuff:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+        ...<br>
+        if (IdentifierStr == "def")<br>
+          return tok_def;<br>
+        if (IdentifierStr == "extern")<br>
+          return tok_extern;<br>
+        if (IdentifierStr == "if")<br>
+          return tok_if;<br>
+        if (IdentifierStr == "then")<br>
+          return tok_then;<br>
+        if (IdentifierStr == "else")<br>
+          return tok_else;<br>
+        return tok_identifier;<br>
+<br>
+AST Extensions for If/Then/Else<br>
+-------------------------------<br>
+<br>
+To represent the new expression we add a new AST node for it:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// IfExprAST - Expression class for if/then/else.<br>
+    class IfExprAST : public ExprAST {<br>
+      std::unique_ptr<ExprAST> Cond, Then, Else;<br>
+<br>
+    public:<br>
+      IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,<br>
+                std::unique_ptr<ExprAST> Else)<br>
+        : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}<br>
+      virtual Value *codegen();<br>
+    };<br>
+<br>
+The AST node just has pointers to the various subexpressions.<br>
+<br>
+Parser Extensions for If/Then/Else<br>
+----------------------------------<br>
+<br>
+Now that we have the relevant tokens coming from the lexer and we have<br>
+the AST node to build, our parsing logic is relatively straightforward.<br>
+First we define a new parsing function:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// ifexpr ::= 'if' expression 'then' expression 'else' expression<br>
+    static std::unique_ptr<ExprAST> ParseIfExpr() {<br>
+      getNextToken();  // eat the if.<br>
+<br>
+      // condition.<br>
+      auto Cond = ParseExpression();<br>
+      if (!Cond)<br>
+        return nullptr;<br>
+<br>
+      if (CurTok != tok_then)<br>
+        return LogError("expected then");<br>
+      getNextToken();  // eat the then<br>
+<br>
+      auto Then = ParseExpression();<br>
+      if (!Then)<br>
+        return nullptr;<br>
+<br>
+      if (CurTok != tok_else)<br>
+        return LogError("expected else");<br>
+<br>
+      getNextToken();<br>
+<br>
+      auto Else = ParseExpression();<br>
+      if (!Else)<br>
+        return nullptr;<br>
+<br>
+      return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),<br>
+                                          std::move(Else));<br>
+    }<br>
+<br>
+Next we hook it up as a primary expression:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    static std::unique_ptr<ExprAST> ParsePrimary() {<br>
+      switch (CurTok) {<br>
+      default:<br>
+        return LogError("unknown token when expecting an expression");<br>
+      case tok_identifier:<br>
+        return ParseIdentifierExpr();<br>
+      case tok_number:<br>
+        return ParseNumberExpr();<br>
+      case '(':<br>
+        return ParseParenExpr();<br>
+      case tok_if:<br>
+        return ParseIfExpr();<br>
+      }<br>
+    }<br>
+<br>
+LLVM IR for If/Then/Else<br>
+------------------------<br>
+<br>
+Now that we have it parsing and building the AST, the final piece is<br>
+adding LLVM code generation support. This is the most interesting part<br>
+of the if/then/else example, because this is where it starts to<br>
+introduce new concepts. All of the code above has been thoroughly<br>
+described in previous chapters.<br>
+<br>
+To motivate the code we want to produce, lets take a look at a simple<br>
+example. Consider:<br>
+<br>
+::<br>
+<br>
+    extern foo();<br>
+    extern bar();<br>
+    def baz(x) if x then foo() else bar();<br>
+<br>
+If you disable optimizations, the code you'll (soon) get from<br>
+Kaleidoscope looks like this:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+    declare double @foo()<br>
+<br>
+    declare double @bar()<br>
+<br>
+    define double @baz(double %x) {<br>
+    entry:<br>
+      %ifcond = fcmp one double %x, 0.000000e+00<br>
+      br i1 %ifcond, label %then, label %else<br>
+<br>
+    then:       ; preds = %entry<br>
+      %calltmp = call double @foo()<br>
+      br label %ifcont<br>
+<br>
+    else:       ; preds = %entry<br>
+      %calltmp1 = call double @bar()<br>
+      br label %ifcont<br>
+<br>
+    ifcont:     ; preds = %else, %then<br>
+      %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]<br>
+      ret double %iftmp<br>
+    }<br>
+<br>
+To visualize the control flow graph, you can use a nifty feature of the<br>
+LLVM '`opt <<a href="http://llvm.org/cmds/opt.html" rel="noreferrer" target="_blank">http://llvm.org/cmds/opt.html</a>>`_' tool. If you put this LLVM<br>
+IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a<br>
+window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll<br>
+see this graph:<br>
+<br>
+.. figure:: LangImpl05-cfg.png<br>
+   :align: center<br>
+   :alt: Example CFG<br>
+<br>
+   Example CFG<br>
+<br>
+Another way to get this is to call "``F->viewCFG()``" or<br>
+"``F->viewCFGOnly()``" (where F is a "``Function*``") either by<br>
+inserting actual calls into the code and recompiling or by calling these<br>
+in the debugger. LLVM has many nice features for visualizing various<br>
+graphs.<br>
+<br>
+Getting back to the generated code, it is fairly simple: the entry block<br>
+evaluates the conditional expression ("x" in our case here) and compares<br>
+the result to 0.0 with the "``fcmp one``" instruction ('one' is "Ordered<br>
+and Not Equal"). Based on the result of this expression, the code jumps<br>
+to either the "then" or "else" blocks, which contain the expressions for<br>
+the true/false cases.<br>
+<br>
+Once the then/else blocks are finished executing, they both branch back<br>
+to the 'ifcont' block to execute the code that happens after the<br>
+if/then/else. In this case the only thing left to do is to return to the<br>
+caller of the function. The question then becomes: how does the code<br>
+know which expression to return?<br>
+<br>
+The answer to this question involves an important SSA operation: the<br>
+`Phi<br>
+operation <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_.<br>
+If you're not familiar with SSA, `the wikipedia<br>
+article <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_<br>
+is a good introduction and there are various other introductions to it<br>
+available on your favorite search engine. The short version is that<br>
+"execution" of the Phi operation requires "remembering" which block<br>
+control came from. The Phi operation takes on the value corresponding to<br>
+the input control block. In this case, if control comes in from the<br>
+"then" block, it gets the value of "calltmp". If control comes from the<br>
+"else" block, it gets the value of "calltmp1".<br>
+<br>
+At this point, you are probably starting to think "Oh no! This means my<br>
+simple and elegant front-end will have to start generating SSA form in<br>
+order to use LLVM!". Fortunately, this is not the case, and we strongly<br>
+advise *not* implementing an SSA construction algorithm in your<br>
+front-end unless there is an amazingly good reason to do so. In<br>
+practice, there are two sorts of values that float around in code<br>
+written for your average imperative programming language that might need<br>
+Phi nodes:<br>
+<br>
+#. Code that involves user variables: ``x = 1; x = x + 1;``<br>
+#. Values that are implicit in the structure of your AST, such as the<br>
+   Phi node in this case.<br>
+<br>
+In `Chapter 7 <LangImpl7.html>`_ of this tutorial ("mutable variables"),<br>
+we'll talk about #1 in depth. For now, just believe me that you don't<br>
+need SSA construction to handle this case. For #2, you have the choice<br>
+of using the techniques that we will describe for #1, or you can insert<br>
+Phi nodes directly, if convenient. In this case, it is really<br>
+easy to generate the Phi node, so we choose to do it directly.<br>
+<br>
+Okay, enough of the motivation and overview, lets generate code!<br>
+<br>
+Code Generation for If/Then/Else<br>
+--------------------------------<br>
+<br>
+In order to generate code for this, we implement the ``codegen`` method<br>
+for ``IfExprAST``:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *IfExprAST::codegen() {<br>
+      Value *CondV = Cond->codegen();<br>
+      if (!CondV)<br>
+        return nullptr;<br>
+<br>
+      // Convert condition to a bool by comparing equal to 0.0.<br>
+      CondV = Builder.CreateFCmpONE(<br>
+          CondV, ConstantFP::get(LLVMContext, APFloat(0.0)), "ifcond");<br>
+<br>
+This code is straightforward and similar to what we saw before. We emit<br>
+the expression for the condition, then compare that value to zero to get<br>
+a truth value as a 1-bit (bool) value.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      Function *TheFunction = Builder.GetInsertBlock()->getParent();<br>
+<br>
+      // Create blocks for the then and else cases.  Insert the 'then' block at the<br>
+      // end of the function.<br>
+      BasicBlock *ThenBB =<br>
+          BasicBlock::Create(LLVMContext, "then", TheFunction);<br>
+      BasicBlock *ElseBB = BasicBlock::Create(LLVMContext, "else");<br>
+      BasicBlock *MergeBB = BasicBlock::Create(LLVMContext, "ifcont");<br>
+<br>
+      Builder.CreateCondBr(CondV, ThenBB, ElseBB);<br>
+<br>
+This code creates the basic blocks that are related to the if/then/else<br>
+statement, and correspond directly to the blocks in the example above.<br>
+The first line gets the current Function object that is being built. It<br>
+gets this by asking the builder for the current BasicBlock, and asking<br>
+that block for its "parent" (the function it is currently embedded<br>
+into).<br>
+<br>
+Once it has that, it creates three blocks. Note that it passes<br>
+"TheFunction" into the constructor for the "then" block. This causes the<br>
+constructor to automatically insert the new block into the end of the<br>
+specified function. The other two blocks are created, but aren't yet<br>
+inserted into the function.<br>
+<br>
+Once the blocks are created, we can emit the conditional branch that<br>
+chooses between them. Note that creating new blocks does not implicitly<br>
+affect the IRBuilder, so it is still inserting into the block that the<br>
+condition went into. Also note that it is creating a branch to the<br>
+"then" block and the "else" block, even though the "else" block isn't<br>
+inserted into the function yet. This is all ok: it is the standard way<br>
+that LLVM supports forward references.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Emit then value.<br>
+      Builder.SetInsertPoint(ThenBB);<br>
+<br>
+      Value *ThenV = Then->codegen();<br>
+      if (!ThenV)<br>
+        return nullptr;<br>
+<br>
+      Builder.CreateBr(MergeBB);<br>
+      // Codegen of 'Then' can change the current block, update ThenBB for the PHI.<br>
+      ThenBB = Builder.GetInsertBlock();<br>
+<br>
+After the conditional branch is inserted, we move the builder to start<br>
+inserting into the "then" block. Strictly speaking, this call moves the<br>
+insertion point to be at the end of the specified block. However, since<br>
+the "then" block is empty, it also starts out by inserting at the<br>
+beginning of the block. :)<br>
+<br>
+Once the insertion point is set, we recursively codegen the "then"<br>
+expression from the AST. To finish off the "then" block, we create an<br>
+unconditional branch to the merge block. One interesting (and very<br>
+important) aspect of the LLVM IR is that it `requires all basic blocks<br>
+to be "terminated" <../LangRef.html#functionstructure>`_ with a `control<br>
+flow instruction <../LangRef.html#terminators>`_ such as return or<br>
+branch. This means that all control flow, *including fall throughs* must<br>
+be made explicit in the LLVM IR. If you violate this rule, the verifier<br>
+will emit an error.<br>
+<br>
+The final line here is quite subtle, but is very important. The basic<br>
+issue is that when we create the Phi node in the merge block, we need to<br>
+set up the block/value pairs that indicate how the Phi will work.<br>
+Importantly, the Phi node expects to have an entry for each predecessor<br>
+of the block in the CFG. Why then, are we getting the current block when<br>
+we just set it to ThenBB 5 lines above? The problem is that the "Then"<br>
+expression may actually itself change the block that the Builder is<br>
+emitting into if, for example, it contains a nested "if/then/else"<br>
+expression. Because calling ``codegen()`` recursively could arbitrarily change<br>
+the notion of the current block, we are required to get an up-to-date<br>
+value for code that will set up the Phi node.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Emit else block.<br>
+      TheFunction->getBasicBlockList().push_back(ElseBB);<br>
+      Builder.SetInsertPoint(ElseBB);<br>
+<br>
+      Value *ElseV = Else->codegen();<br>
+      if (!ElseV)<br>
+        return nullptr;<br>
+<br>
+      Builder.CreateBr(MergeBB);<br>
+      // codegen of 'Else' can change the current block, update ElseBB for the PHI.<br>
+      ElseBB = Builder.GetInsertBlock();<br>
+<br>
+Code generation for the 'else' block is basically identical to codegen<br>
+for the 'then' block. The only significant difference is the first line,<br>
+which adds the 'else' block to the function. Recall previously that the<br>
+'else' block was created, but not added to the function. Now that the<br>
+'then' and 'else' blocks are emitted, we can finish up with the merge<br>
+code:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Emit merge block.<br>
+      TheFunction->getBasicBlockList().push_back(MergeBB);<br>
+      Builder.SetInsertPoint(MergeBB);<br>
+      PHINode *PN =<br>
+        Builder.CreatePHI(Type::getDoubleTy(LLVMContext), 2, "iftmp");<br>
+<br>
+      PN->addIncoming(ThenV, ThenBB);<br>
+      PN->addIncoming(ElseV, ElseBB);<br>
+      return PN;<br>
+    }<br>
+<br>
+The first two lines here are now familiar: the first adds the "merge"<br>
+block to the Function object (it was previously floating, like the else<br>
+block above). The second changes the insertion point so that newly<br>
+created code will go into the "merge" block. Once that is done, we need<br>
+to create the PHI node and set up the block/value pairs for the PHI.<br>
+<br>
+Finally, the CodeGen function returns the phi node as the value computed<br>
+by the if/then/else expression. In our example above, this returned<br>
+value will feed into the code for the top-level function, which will<br>
+create the return instruction.<br>
+<br>
+Overall, we now have the ability to execute conditional code in<br>
+Kaleidoscope. With this extension, Kaleidoscope is a fairly complete<br>
+language that can calculate a wide variety of numeric functions. Next up<br>
+we'll add another useful expression that is familiar from non-functional<br>
+languages...<br>
+<br>
+'for' Loop Expression<br>
+=====================<br>
+<br>
+Now that we know how to add basic control flow constructs to the<br>
+language, we have the tools to add more powerful things. Lets add<br>
+something more aggressive, a 'for' expression:<br>
+<br>
+::<br>
+<br>
+     extern putchard(char)<br>
+     def printstar(n)<br>
+       for i = 1, i < n, 1.0 in<br>
+         putchard(42);  # ascii 42 = '*'<br>
+<br>
+     # print 100 '*' characters<br>
+     printstar(100);<br>
+<br>
+This expression defines a new variable ("i" in this case) which iterates<br>
+from a starting value, while the condition ("i < n" in this case) is<br>
+true, incrementing by an optional step value ("1.0" in this case). If<br>
+the step value is omitted, it defaults to 1.0. While the loop is true,<br>
+it executes its body expression. Because we don't have anything better<br>
+to return, we'll just define the loop as always returning 0.0. In the<br>
+future when we have mutable variables, it will get more useful.<br>
+<br>
+As before, lets talk about the changes that we need to Kaleidoscope to<br>
+support this.<br>
+<br>
+Lexer Extensions for the 'for' Loop<br>
+-----------------------------------<br>
+<br>
+The lexer extensions are the same sort of thing as for if/then/else:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      ... in enum Token ...<br>
+      // control<br>
+      tok_if = -6, tok_then = -7, tok_else = -8,<br>
+      tok_for = -9, tok_in = -10<br>
+<br>
+      ... in gettok ...<br>
+      if (IdentifierStr == "def")<br>
+        return tok_def;<br>
+      if (IdentifierStr == "extern")<br>
+        return tok_extern;<br>
+      if (IdentifierStr == "if")<br>
+        return tok_if;<br>
+      if (IdentifierStr == "then")<br>
+        return tok_then;<br>
+      if (IdentifierStr == "else")<br>
+        return tok_else;<br>
+      if (IdentifierStr == "for")<br>
+        return tok_for;<br>
+      if (IdentifierStr == "in")<br>
+        return tok_in;<br>
+      return tok_identifier;<br>
+<br>
+AST Extensions for the 'for' Loop<br>
+---------------------------------<br>
+<br>
+The AST node is just as simple. It basically boils down to capturing the<br>
+variable name and the constituent expressions in the node.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// ForExprAST - Expression class for for/in.<br>
+    class ForExprAST : public ExprAST {<br>
+      std::string VarName;<br>
+      std::unique_ptr<ExprAST> Start, End, Step, Body;<br>
+<br>
+    public:<br>
+      ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,<br>
+                 std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,<br>
+                 std::unique_ptr<ExprAST> Body)<br>
+        : VarName(VarName), Start(std::move(Start)), End(std::move(End)),<br>
+          Step(std::move(Step)), Body(std::move(Body)) {}<br>
+      virtual Value *codegen();<br>
+    };<br>
+<br>
+Parser Extensions for the 'for' Loop<br>
+------------------------------------<br>
+<br>
+The parser code is also fairly standard. The only interesting thing here<br>
+is handling of the optional step value. The parser code handles it by<br>
+checking to see if the second comma is present. If not, it sets the step<br>
+value to null in the AST node:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression<br>
+    static std::unique_ptr<ExprAST> ParseForExpr() {<br>
+      getNextToken();  // eat the for.<br>
+<br>
+      if (CurTok != tok_identifier)<br>
+        return LogError("expected identifier after for");<br>
+<br>
+      std::string IdName = IdentifierStr;<br>
+      getNextToken();  // eat identifier.<br>
+<br>
+      if (CurTok != '=')<br>
+        return LogError("expected '=' after for");<br>
+      getNextToken();  // eat '='.<br>
+<br>
+<br>
+      auto Start = ParseExpression();<br>
+      if (!Start)<br>
+        return nullptr;<br>
+      if (CurTok != ',')<br>
+        return LogError("expected ',' after for start value");<br>
+      getNextToken();<br>
+<br>
+      auto End = ParseExpression();<br>
+      if (!End)<br>
+        return nullptr;<br>
+<br>
+      // The step value is optional.<br>
+      std::unique_ptr<ExprAST> Step;<br>
+      if (CurTok == ',') {<br>
+        getNextToken();<br>
+        Step = ParseExpression();<br>
+        if (!Step)<br>
+          return nullptr;<br>
+      }<br>
+<br>
+      if (CurTok != tok_in)<br>
+        return LogError("expected 'in' after for");<br>
+      getNextToken();  // eat 'in'.<br>
+<br>
+      auto Body = ParseExpression();<br>
+      if (!Body)<br>
+        return nullptr;<br>
+<br>
+      return llvm::make_unique<ForExprAST>(IdName, std::move(Start),<br>
+                                           std::move(End), std::move(Step),<br>
+                                           std::move(Body));<br>
+    }<br>
+<br>
+LLVM IR for the 'for' Loop<br>
+--------------------------<br>
+<br>
+Now we get to the good part: the LLVM IR we want to generate for this<br>
+thing. With the simple example above, we get this LLVM IR (note that<br>
+this dump is generated with optimizations disabled for clarity):<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+    declare double @putchard(double)<br>
+<br>
+    define double @printstar(double %n) {<br>
+    entry:<br>
+      ; initial value = 1.0 (inlined into phi)<br>
+      br label %loop<br>
+<br>
+    loop:       ; preds = %loop, %entry<br>
+      %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]<br>
+      ; body<br>
+      %calltmp = call double @putchard(double 4.200000e+01)<br>
+      ; increment<br>
+      %nextvar = fadd double %i, 1.000000e+00<br>
+<br>
+      ; termination test<br>
+      %cmptmp = fcmp ult double %i, %n<br>
+      %booltmp = uitofp i1 %cmptmp to double<br>
+      %loopcond = fcmp one double %booltmp, 0.000000e+00<br>
+      br i1 %loopcond, label %loop, label %afterloop<br>
+<br>
+    afterloop:      ; preds = %loop<br>
+      ; loop always returns 0.0<br>
+      ret double 0.000000e+00<br>
+    }<br>
+<br>
+This loop contains all the same constructs we saw before: a phi node,<br>
+several expressions, and some basic blocks. Lets see how this fits<br>
+together.<br>
+<br>
+Code Generation for the 'for' Loop<br>
+----------------------------------<br>
+<br>
+The first part of codegen is very simple: we just output the start<br>
+expression for the loop value:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *ForExprAST::codegen() {<br>
+      // Emit the start code first, without 'variable' in scope.<br>
+      Value *StartVal = Start->codegen();<br>
+      if (StartVal == 0) return 0;<br>
+<br>
+With this out of the way, the next step is to set up the LLVM basic<br>
+block for the start of the loop body. In the case above, the whole loop<br>
+body is one block, but remember that the body code itself could consist<br>
+of multiple blocks (e.g. if it contains an if/then/else or a for/in<br>
+expression).<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Make the new basic block for the loop header, inserting after current<br>
+      // block.<br>
+      Function *TheFunction = Builder.GetInsertBlock()->getParent();<br>
+      BasicBlock *PreheaderBB = Builder.GetInsertBlock();<br>
+      BasicBlock *LoopBB =<br>
+          BasicBlock::Create(LLVMContext, "loop", TheFunction);<br>
+<br>
+      // Insert an explicit fall through from the current block to the LoopBB.<br>
+      Builder.CreateBr(LoopBB);<br>
+<br>
+This code is similar to what we saw for if/then/else. Because we will<br>
+need it to create the Phi node, we remember the block that falls through<br>
+into the loop. Once we have that, we create the actual block that starts<br>
+the loop and create an unconditional branch for the fall-through between<br>
+the two blocks.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Start insertion in LoopBB.<br>
+      Builder.SetInsertPoint(LoopBB);<br>
+<br>
+      // Start the PHI node with an entry for Start.<br>
+      PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(LLVMContext),<br>
+                                            2, VarName.c_str());<br>
+      Variable->addIncoming(StartVal, PreheaderBB);<br>
+<br>
+Now that the "preheader" for the loop is set up, we switch to emitting<br>
+code for the loop body. To begin with, we move the insertion point and<br>
+create the PHI node for the loop induction variable. Since we already<br>
+know the incoming value for the starting value, we add it to the Phi<br>
+node. Note that the Phi will eventually get a second value for the<br>
+backedge, but we can't set it up yet (because it doesn't exist!).<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Within the loop, the variable is defined equal to the PHI node.  If it<br>
+      // shadows an existing variable, we have to restore it, so save it now.<br>
+      Value *OldVal = NamedValues[VarName];<br>
+      NamedValues[VarName] = Variable;<br>
+<br>
+      // Emit the body of the loop.  This, like any other expr, can change the<br>
+      // current BB.  Note that we ignore the value computed by the body, but don't<br>
+      // allow an error.<br>
+      if (!Body->codegen())<br>
+        return nullptr;<br>
+<br>
+Now the code starts to get more interesting. Our 'for' loop introduces a<br>
+new variable to the symbol table. This means that our symbol table can<br>
+now contain either function arguments or loop variables. To handle this,<br>
+before we codegen the body of the loop, we add the loop variable as the<br>
+current value for its name. Note that it is possible that there is a<br>
+variable of the same name in the outer scope. It would be easy to make<br>
+this an error (emit an error and return null if there is already an<br>
+entry for VarName) but we choose to allow shadowing of variables. In<br>
+order to handle this correctly, we remember the Value that we are<br>
+potentially shadowing in ``OldVal`` (which will be null if there is no<br>
+shadowed variable).<br>
+<br>
+Once the loop variable is set into the symbol table, the code<br>
+recursively codegen's the body. This allows the body to use the loop<br>
+variable: any references to it will naturally find it in the symbol<br>
+table.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Emit the step value.<br>
+      Value *StepVal = nullptr;<br>
+      if (Step) {<br>
+        StepVal = Step->codegen();<br>
+        if (!StepVal)<br>
+          return nullptr;<br>
+      } else {<br>
+        // If not specified, use 1.0.<br>
+        StepVal = ConstantFP::get(LLVMContext, APFloat(1.0));<br>
+      }<br>
+<br>
+      Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");<br>
+<br>
+Now that the body is emitted, we compute the next value of the iteration<br>
+variable by adding the step value, or 1.0 if it isn't present.<br>
+'``NextVar``' will be the value of the loop variable on the next<br>
+iteration of the loop.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Compute the end condition.<br>
+      Value *EndCond = End->codegen();<br>
+      if (!EndCond)<br>
+        return nullptr;<br>
+<br>
+      // Convert condition to a bool by comparing equal to 0.0.<br>
+      EndCond = Builder.CreateFCmpONE(<br>
+          EndCond, ConstantFP::get(LLVMContext, APFloat(0.0)), "loopcond");<br>
+<br>
+Finally, we evaluate the exit value of the loop, to determine whether<br>
+the loop should exit. This mirrors the condition evaluation for the<br>
+if/then/else statement.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Create the "after loop" block and insert it.<br>
+      BasicBlock *LoopEndBB = Builder.GetInsertBlock();<br>
+      BasicBlock *AfterBB =<br>
+          BasicBlock::Create(LLVMContext, "afterloop", TheFunction);<br>
+<br>
+      // Insert the conditional branch into the end of LoopEndBB.<br>
+      Builder.CreateCondBr(EndCond, LoopBB, AfterBB);<br>
+<br>
+      // Any new code will be inserted in AfterBB.<br>
+      Builder.SetInsertPoint(AfterBB);<br>
+<br>
+With the code for the body of the loop complete, we just need to finish<br>
+up the control flow for it. This code remembers the end block (for the<br>
+phi node), then creates the block for the loop exit ("afterloop"). Based<br>
+on the value of the exit condition, it creates a conditional branch that<br>
+chooses between executing the loop again and exiting the loop. Any<br>
+future code is emitted in the "afterloop" block, so it sets the<br>
+insertion position to it.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Add a new entry to the PHI node for the backedge.<br>
+      Variable->addIncoming(NextVar, LoopEndBB);<br>
+<br>
+      // Restore the unshadowed variable.<br>
+      if (OldVal)<br>
+        NamedValues[VarName] = OldVal;<br>
+      else<br>
+        NamedValues.erase(VarName);<br>
+<br>
+      // for expr always returns 0.0.<br>
+      return Constant::getNullValue(Type::getDoubleTy(LLVMContext));<br>
+    }<br>
+<br>
+The final code handles various cleanups: now that we have the "NextVar"<br>
+value, we can add the incoming value to the loop PHI node. After that,<br>
+we remove the loop variable from the symbol table, so that it isn't in<br>
+scope after the for loop. Finally, code generation of the for loop<br>
+always returns 0.0, so that is what we return from<br>
+``ForExprAST::codegen()``.<br>
+<br>
+With this, we conclude the "adding control flow to Kaleidoscope" chapter<br>
+of the tutorial. In this chapter we added two control flow constructs,<br>
+and used them to motivate a couple of aspects of the LLVM IR that are<br>
+important for front-end implementors to know. In the next chapter of our<br>
+saga, we will get a bit crazier and add `user-defined<br>
+operators <LangImpl6.html>`_ to our poor innocent language.<br>
+<br>
+Full Code Listing<br>
+=================<br>
+<br>
+Here is the complete code listing for our running example, enhanced with<br>
+the if/then/else and for expressions.. To build this example, use:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    # Compile<br>
+    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
+    # Run<br>
+    ./toy<br>
+<br>
+Here is the code:<br>
+<br>
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter5/toy.cpp<br>
+   :language: c++<br>
+<br>
+`Next: Extending the language: user-defined operators <LangImpl06.html>`_<br>
+<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl06.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl06.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl06.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl06.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl06.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,768 @@<br>
+============================================================<br>
+Kaleidoscope: Extending the Language: User-defined Operators<br>
+============================================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Chapter 6 Introduction<br>
+======================<br>
+<br>
+Welcome to Chapter 6 of the "`Implementing a language with<br>
+LLVM <index.html>`_" tutorial. At this point in our tutorial, we now<br>
+have a fully functional language that is fairly minimal, but also<br>
+useful. There is still one big problem with it, however. Our language<br>
+doesn't have many useful operators (like division, logical negation, or<br>
+even any comparisons besides less-than).<br>
+<br>
+This chapter of the tutorial takes a wild digression into adding<br>
+user-defined operators to the simple and beautiful Kaleidoscope<br>
+language. This digression now gives us a simple and ugly language in<br>
+some ways, but also a powerful one at the same time. One of the great<br>
+things about creating your own language is that you get to decide what<br>
+is good or bad. In this tutorial we'll assume that it is okay to use<br>
+this as a way to show some interesting parsing techniques.<br>
+<br>
+At the end of this tutorial, we'll run through an example Kaleidoscope<br>
+application that `renders the Mandelbrot set <#kicking-the-tires>`_. This gives an<br>
+example of what you can build with Kaleidoscope and its feature set.<br>
+<br>
+User-defined Operators: the Idea<br>
+================================<br>
+<br>
+The "operator overloading" that we will add to Kaleidoscope is more<br>
+general than languages like C++. In C++, you are only allowed to<br>
+redefine existing operators: you can't programatically change the<br>
+grammar, introduce new operators, change precedence levels, etc. In this<br>
+chapter, we will add this capability to Kaleidoscope, which will let the<br>
+user round out the set of operators that are supported.<br>
+<br>
+The point of going into user-defined operators in a tutorial like this<br>
+is to show the power and flexibility of using a hand-written parser.<br>
+Thus far, the parser we have been implementing uses recursive descent<br>
+for most parts of the grammar and operator precedence parsing for the<br>
+expressions. See `Chapter 2 <LangImpl2.html>`_ for details. Without<br>
+using operator precedence parsing, it would be very difficult to allow<br>
+the programmer to introduce new operators into the grammar: the grammar<br>
+is dynamically extensible as the JIT runs.<br>
+<br>
+The two specific features we'll add are programmable unary operators<br>
+(right now, Kaleidoscope has no unary operators at all) as well as<br>
+binary operators. An example of this is:<br>
+<br>
+::<br>
+<br>
+    # Logical unary not.<br>
+    def unary!(v)<br>
+      if v then<br>
+        0<br>
+      else<br>
+        1;<br>
+<br>
+    # Define > with the same precedence as <.<br>
+    def binary> 10 (LHS RHS)<br>
+      RHS < LHS;<br>
+<br>
+    # Binary "logical or", (note that it does not "short circuit")<br>
+    def binary| 5 (LHS RHS)<br>
+      if LHS then<br>
+        1<br>
+      else if RHS then<br>
+        1<br>
+      else<br>
+        0;<br>
+<br>
+    # Define = with slightly lower precedence than relationals.<br>
+    def binary= 9 (LHS RHS)<br>
+      !(LHS < RHS | LHS > RHS);<br>
+<br>
+Many languages aspire to being able to implement their standard runtime<br>
+library in the language itself. In Kaleidoscope, we can implement<br>
+significant parts of the language in the library!<br>
+<br>
+We will break down implementation of these features into two parts:<br>
+implementing support for user-defined binary operators and adding unary<br>
+operators.<br>
+<br>
+User-defined Binary Operators<br>
+=============================<br>
+<br>
+Adding support for user-defined binary operators is pretty simple with<br>
+our current framework. We'll first add support for the unary/binary<br>
+keywords:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    enum Token {<br>
+      ...<br>
+      // operators<br>
+      tok_binary = -11,<br>
+      tok_unary = -12<br>
+    };<br>
+    ...<br>
+    static int gettok() {<br>
+    ...<br>
+        if (IdentifierStr == "for")<br>
+          return tok_for;<br>
+        if (IdentifierStr == "in")<br>
+          return tok_in;<br>
+        if (IdentifierStr == "binary")<br>
+          return tok_binary;<br>
+        if (IdentifierStr == "unary")<br>
+          return tok_unary;<br>
+        return tok_identifier;<br>
+<br>
+This just adds lexer support for the unary and binary keywords, like we<br>
+did in `previous chapters <LangImpl5.html#lexer-extensions-for-if-then-else>`_. One nice thing<br>
+about our current AST, is that we represent binary operators with full<br>
+generalisation by using their ASCII code as the opcode. For our extended<br>
+operators, we'll use this same representation, so we don't need any new<br>
+AST or parser support.<br>
+<br>
+On the other hand, we have to be able to represent the definitions of<br>
+these new operators, in the "def binary\| 5" part of the function<br>
+definition. In our grammar so far, the "name" for the function<br>
+definition is parsed as the "prototype" production and into the<br>
+``PrototypeAST`` AST node. To represent our new user-defined operators<br>
+as prototypes, we have to extend the ``PrototypeAST`` AST node like<br>
+this:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// PrototypeAST - This class represents the "prototype" for a function,<br>
+    /// which captures its argument names as well as if it is an operator.<br>
+    class PrototypeAST {<br>
+      std::string Name;<br>
+      std::vector<std::string> Args;<br>
+      bool IsOperator;<br>
+      unsigned Precedence;  // Precedence if a binary op.<br>
+<br>
+    public:<br>
+      PrototypeAST(const std::string &name, std::vector<std::string> Args,<br>
+                   bool IsOperator = false, unsigned Prec = 0)<br>
+      : Name(name), Args(std::move(Args)), IsOperator(IsOperator),<br>
+        Precedence(Prec) {}<br>
+<br>
+      bool isUnaryOp() const { return IsOperator && Args.size() == 1; }<br>
+      bool isBinaryOp() const { return IsOperator && Args.size() == 2; }<br>
+<br>
+      char getOperatorName() const {<br>
+        assert(isUnaryOp() || isBinaryOp());<br>
+        return Name[Name.size()-1];<br>
+      }<br>
+<br>
+      unsigned getBinaryPrecedence() const { return Precedence; }<br>
+<br>
+      Function *codegen();<br>
+    };<br>
+<br>
+Basically, in addition to knowing a name for the prototype, we now keep<br>
+track of whether it was an operator, and if it was, what precedence<br>
+level the operator is at. The precedence is only used for binary<br>
+operators (as you'll see below, it just doesn't apply for unary<br>
+operators). Now that we have a way to represent the prototype for a<br>
+user-defined operator, we need to parse it:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// prototype<br>
+    ///   ::= id '(' id* ')'<br>
+    ///   ::= binary LETTER number? (id, id)<br>
+    static std::unique_ptr<PrototypeAST> ParsePrototype() {<br>
+      std::string FnName;<br>
+<br>
+      unsigned Kind = 0;  // 0 = identifier, 1 = unary, 2 = binary.<br>
+      unsigned BinaryPrecedence = 30;<br>
+<br>
+      switch (CurTok) {<br>
+      default:<br>
+        return LogErrorP("Expected function name in prototype");<br>
+      case tok_identifier:<br>
+        FnName = IdentifierStr;<br>
+        Kind = 0;<br>
+        getNextToken();<br>
+        break;<br>
+      case tok_binary:<br>
+        getNextToken();<br>
+        if (!isascii(CurTok))<br>
+          return LogErrorP("Expected binary operator");<br>
+        FnName = "binary";<br>
+        FnName += (char)CurTok;<br>
+        Kind = 2;<br>
+        getNextToken();<br>
+<br>
+        // Read the precedence if present.<br>
+        if (CurTok == tok_number) {<br>
+          if (NumVal < 1 || NumVal > 100)<br>
+            return LogErrorP("Invalid precedecnce: must be 1..100");<br>
+          BinaryPrecedence = (unsigned)NumVal;<br>
+          getNextToken();<br>
+        }<br>
+        break;<br>
+      }<br>
+<br>
+      if (CurTok != '(')<br>
+        return LogErrorP("Expected '(' in prototype");<br>
+<br>
+      std::vector<std::string> ArgNames;<br>
+      while (getNextToken() == tok_identifier)<br>
+        ArgNames.push_back(IdentifierStr);<br>
+      if (CurTok != ')')<br>
+        return LogErrorP("Expected ')' in prototype");<br>
+<br>
+      // success.<br>
+      getNextToken();  // eat ')'.<br>
+<br>
+      // Verify right number of names for operator.<br>
+      if (Kind && ArgNames.size() != Kind)<br>
+        return LogErrorP("Invalid number of operands for operator");<br>
+<br>
+      return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames), Kind != 0,<br>
+                                             BinaryPrecedence);<br>
+    }<br>
+<br>
+This is all fairly straightforward parsing code, and we have already<br>
+seen a lot of similar code in the past. One interesting part about the<br>
+code above is the couple lines that set up ``FnName`` for binary<br>
+operators. This builds names like "binary@" for a newly defined "@"<br>
+operator. This then takes advantage of the fact that symbol names in the<br>
+LLVM symbol table are allowed to have any character in them, including<br>
+embedded nul characters.<br>
+<br>
+The next interesting thing to add, is codegen support for these binary<br>
+operators. Given our current structure, this is a simple addition of a<br>
+default case for our existing binary operator node:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *BinaryExprAST::codegen() {<br>
+      Value *L = LHS->codegen();<br>
+      Value *R = RHS->codegen();<br>
+      if (!L || !R)<br>
+        return nullptr;<br>
+<br>
+      switch (Op) {<br>
+      case '+':<br>
+        return Builder.CreateFAdd(L, R, "addtmp");<br>
+      case '-':<br>
+        return Builder.CreateFSub(L, R, "subtmp");<br>
+      case '*':<br>
+        return Builder.CreateFMul(L, R, "multmp");<br>
+      case '<':<br>
+        L = Builder.CreateFCmpULT(L, R, "cmptmp");<br>
+        // Convert bool 0/1 to double 0.0 or 1.0<br>
+        return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),<br>
+                                    "booltmp");<br>
+      default:<br>
+        break;<br>
+      }<br>
+<br>
+      // If it wasn't a builtin binary operator, it must be a user defined one. Emit<br>
+      // a call to it.<br>
+      Function *F = TheModule->getFunction(std::string("binary") + Op);<br>
+      assert(F && "binary operator not found!");<br>
+<br>
+      Value *Ops[2] = { L, R };<br>
+      return Builder.CreateCall(F, Ops, "binop");<br>
+    }<br>
+<br>
+As you can see above, the new code is actually really simple. It just<br>
+does a lookup for the appropriate operator in the symbol table and<br>
+generates a function call to it. Since user-defined operators are just<br>
+built as normal functions (because the "prototype" boils down to a<br>
+function with the right name) everything falls into place.<br>
+<br>
+The final piece of code we are missing, is a bit of top-level magic:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Function *FunctionAST::codegen() {<br>
+      NamedValues.clear();<br>
+<br>
+      Function *TheFunction = Proto->codegen();<br>
+      if (!TheFunction)<br>
+        return nullptr;<br>
+<br>
+      // If this is an operator, install it.<br>
+      if (Proto->isBinaryOp())<br>
+        BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();<br>
+<br>
+      // Create a new basic block to start insertion into.<br>
+      BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);<br>
+      Builder.SetInsertPoint(BB);<br>
+<br>
+      if (Value *RetVal = Body->codegen()) {<br>
+        ...<br>
+<br>
+Basically, before codegening a function, if it is a user-defined<br>
+operator, we register it in the precedence table. This allows the binary<br>
+operator parsing logic we already have in place to handle it. Since we<br>
+are working on a fully-general operator precedence parser, this is all<br>
+we need to do to "extend the grammar".<br>
+<br>
+Now we have useful user-defined binary operators. This builds a lot on<br>
+the previous framework we built for other operators. Adding unary<br>
+operators is a bit more challenging, because we don't have any framework<br>
+for it yet - lets see what it takes.<br>
+<br>
+User-defined Unary Operators<br>
+============================<br>
+<br>
+Since we don't currently support unary operators in the Kaleidoscope<br>
+language, we'll need to add everything to support them. Above, we added<br>
+simple support for the 'unary' keyword to the lexer. In addition to<br>
+that, we need an AST node:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// UnaryExprAST - Expression class for a unary operator.<br>
+    class UnaryExprAST : public ExprAST {<br>
+      char Opcode;<br>
+      std::unique_ptr<ExprAST> Operand;<br>
+<br>
+    public:<br>
+      UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)<br>
+        : Opcode(Opcode), Operand(std::move(Operand)) {}<br>
+      virtual Value *codegen();<br>
+    };<br>
+<br>
+This AST node is very simple and obvious by now. It directly mirrors the<br>
+binary operator AST node, except that it only has one child. With this,<br>
+we need to add the parsing logic. Parsing a unary operator is pretty<br>
+simple: we'll add a new function to do it:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// unary<br>
+    ///   ::= primary<br>
+    ///   ::= '!' unary<br>
+    static std::unique_ptr<ExprAST> ParseUnary() {<br>
+      // If the current token is not an operator, it must be a primary expr.<br>
+      if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')<br>
+        return ParsePrimary();<br>
+<br>
+      // If this is a unary operator, read it.<br>
+      int Opc = CurTok;<br>
+      getNextToken();<br>
+      if (auto Operand = ParseUnary())<br>
+        return llvm::unique_ptr<UnaryExprAST>(Opc, std::move(Operand));<br>
+      return nullptr;<br>
+    }<br>
+<br>
+The grammar we add is pretty straightforward here. If we see a unary<br>
+operator when parsing a primary operator, we eat the operator as a<br>
+prefix and parse the remaining piece as another unary operator. This<br>
+allows us to handle multiple unary operators (e.g. "!!x"). Note that<br>
+unary operators can't have ambiguous parses like binary operators can,<br>
+so there is no need for precedence information.<br>
+<br>
+The problem with this function, is that we need to call ParseUnary from<br>
+somewhere. To do this, we change previous callers of ParsePrimary to<br>
+call ParseUnary instead:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// binoprhs<br>
+    ///   ::= ('+' unary)*<br>
+    static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,<br>
+                                                  std::unique_ptr<ExprAST> LHS) {<br>
+      ...<br>
+        // Parse the unary expression after the binary operator.<br>
+        auto RHS = ParseUnary();<br>
+        if (!RHS)<br>
+          return nullptr;<br>
+      ...<br>
+    }<br>
+    /// expression<br>
+    ///   ::= unary binoprhs<br>
+    ///<br>
+    static std::unique_ptr<ExprAST> ParseExpression() {<br>
+      auto LHS = ParseUnary();<br>
+      if (!LHS)<br>
+        return nullptr;<br>
+<br>
+      return ParseBinOpRHS(0, std::move(LHS));<br>
+    }<br>
+<br>
+With these two simple changes, we are now able to parse unary operators<br>
+and build the AST for them. Next up, we need to add parser support for<br>
+prototypes, to parse the unary operator prototype. We extend the binary<br>
+operator code above with:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// prototype<br>
+    ///   ::= id '(' id* ')'<br>
+    ///   ::= binary LETTER number? (id, id)<br>
+    ///   ::= unary LETTER (id)<br>
+    static std::unique_ptr<PrototypeAST> ParsePrototype() {<br>
+      std::string FnName;<br>
+<br>
+      unsigned Kind = 0;  // 0 = identifier, 1 = unary, 2 = binary.<br>
+      unsigned BinaryPrecedence = 30;<br>
+<br>
+      switch (CurTok) {<br>
+      default:<br>
+        return LogErrorP("Expected function name in prototype");<br>
+      case tok_identifier:<br>
+        FnName = IdentifierStr;<br>
+        Kind = 0;<br>
+        getNextToken();<br>
+        break;<br>
+      case tok_unary:<br>
+        getNextToken();<br>
+        if (!isascii(CurTok))<br>
+          return LogErrorP("Expected unary operator");<br>
+        FnName = "unary";<br>
+        FnName += (char)CurTok;<br>
+        Kind = 1;<br>
+        getNextToken();<br>
+        break;<br>
+      case tok_binary:<br>
+        ...<br>
+<br>
+As with binary operators, we name unary operators with a name that<br>
+includes the operator character. This assists us at code generation<br>
+time. Speaking of, the final piece we need to add is codegen support for<br>
+unary operators. It looks like this:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *UnaryExprAST::codegen() {<br>
+      Value *OperandV = Operand->codegen();<br>
+      if (!OperandV)<br>
+        return nullptr;<br>
+<br>
+      Function *F = TheModule->getFunction(std::string("unary")+Opcode);<br>
+      if (!F)<br>
+        return LogErrorV("Unknown unary operator");<br>
+<br>
+      return Builder.CreateCall(F, OperandV, "unop");<br>
+    }<br>
+<br>
+This code is similar to, but simpler than, the code for binary<br>
+operators. It is simpler primarily because it doesn't need to handle any<br>
+predefined operators.<br>
+<br>
+Kicking the Tires<br>
+=================<br>
+<br>
+It is somewhat hard to believe, but with a few simple extensions we've<br>
+covered in the last chapters, we have grown a real-ish language. With<br>
+this, we can do a lot of interesting things, including I/O, math, and a<br>
+bunch of other things. For example, we can now add a nice sequencing<br>
+operator (printd is defined to print out the specified value and a<br>
+newline):<br>
+<br>
+::<br>
+<br>
+    ready> extern printd(x);<br>
+    Read extern:<br>
+    declare double @printd(double)<br>
+<br>
+    ready> def binary : 1 (x y) 0;  # Low-precedence operator that ignores operands.<br>
+    ..<br>
+    ready> printd(123) : printd(456) : printd(789);<br>
+    123.000000<br>
+    456.000000<br>
+    789.000000<br>
+    Evaluated to 0.000000<br>
+<br>
+We can also define a bunch of other "primitive" operations, such as:<br>
+<br>
+::<br>
+<br>
+    # Logical unary not.<br>
+    def unary!(v)<br>
+      if v then<br>
+        0<br>
+      else<br>
+        1;<br>
+<br>
+    # Unary negate.<br>
+    def unary-(v)<br>
+      0-v;<br>
+<br>
+    # Define > with the same precedence as <.<br>
+    def binary> 10 (LHS RHS)<br>
+      RHS < LHS;<br>
+<br>
+    # Binary logical or, which does not short circuit.<br>
+    def binary| 5 (LHS RHS)<br>
+      if LHS then<br>
+        1<br>
+      else if RHS then<br>
+        1<br>
+      else<br>
+        0;<br>
+<br>
+    # Binary logical and, which does not short circuit.<br>
+    def binary& 6 (LHS RHS)<br>
+      if !LHS then<br>
+        0<br>
+      else<br>
+        !!RHS;<br>
+<br>
+    # Define = with slightly lower precedence than relationals.<br>
+    def binary = 9 (LHS RHS)<br>
+      !(LHS < RHS | LHS > RHS);<br>
+<br>
+    # Define ':' for sequencing: as a low-precedence operator that ignores operands<br>
+    # and just returns the RHS.<br>
+    def binary : 1 (x y) y;<br>
+<br>
+Given the previous if/then/else support, we can also define interesting<br>
+functions for I/O. For example, the following prints out a character<br>
+whose "density" reflects the value passed in: the lower the value, the<br>
+denser the character:<br>
+<br>
+::<br>
+<br>
+    ready><br>
+<br>
+    extern putchard(char)<br>
+    def printdensity(d)<br>
+      if d > 8 then<br>
+        putchard(32)  # ' '<br>
+      else if d > 4 then<br>
+        putchard(46)  # '.'<br>
+      else if d > 2 then<br>
+        putchard(43)  # '+'<br>
+      else<br>
+        putchard(42); # '*'<br>
+    ...<br>
+    ready> printdensity(1): printdensity(2): printdensity(3):<br>
+           printdensity(4): printdensity(5): printdensity(9):<br>
+           putchard(10);<br>
+    **++.<br>
+    Evaluated to 0.000000<br>
+<br>
+Based on these simple primitive operations, we can start to define more<br>
+interesting things. For example, here's a little function that solves<br>
+for the number of iterations it takes a function in the complex plane to<br>
+converge:<br>
+<br>
+::<br>
+<br>
+    # Determine whether the specific location diverges.<br>
+    # Solve for z = z^2 + c in the complex plane.<br>
+    def mandelconverger(real imag iters creal cimag)<br>
+      if iters > 255 | (real*real + imag*imag > 4) then<br>
+        iters<br>
+      else<br>
+        mandelconverger(real*real - imag*imag + creal,<br>
+                        2*real*imag + cimag,<br>
+                        iters+1, creal, cimag);<br>
+<br>
+    # Return the number of iterations required for the iteration to escape<br>
+    def mandelconverge(real imag)<br>
+      mandelconverger(real, imag, 0, real, imag);<br>
+<br>
+This "``z = z2 + c``" function is a beautiful little creature that is<br>
+the basis for computation of the `Mandelbrot<br>
+Set <<a href="http://en.wikipedia.org/wiki/Mandelbrot_set" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Mandelbrot_set</a>>`_. Our<br>
+``mandelconverge`` function returns the number of iterations that it<br>
+takes for a complex orbit to escape, saturating to 255. This is not a<br>
+very useful function by itself, but if you plot its value over a<br>
+two-dimensional plane, you can see the Mandelbrot set. Given that we are<br>
+limited to using putchard here, our amazing graphical output is limited,<br>
+but we can whip together something using the density plotter above:<br>
+<br>
+::<br>
+<br>
+    # Compute and plot the mandelbrot set with the specified 2 dimensional range<br>
+    # info.<br>
+    def mandelhelp(xmin xmax xstep   ymin ymax ystep)<br>
+      for y = ymin, y < ymax, ystep in (<br>
+        (for x = xmin, x < xmax, xstep in<br>
+           printdensity(mandelconverge(x,y)))<br>
+        : putchard(10)<br>
+      )<br>
+<br>
+    # mandel - This is a convenient helper function for plotting the mandelbrot set<br>
+    # from the specified position with the specified Magnification.<br>
+    def mandel(realstart imagstart realmag imagmag)<br>
+      mandelhelp(realstart, realstart+realmag*78, realmag,<br>
+                 imagstart, imagstart+imagmag*40, imagmag);<br>
+<br>
+Given this, we can try plotting out the mandelbrot set! Lets try it out:<br>
+<br>
+::<br>
+<br>
+    ready> mandel(-2.3, -1.3, 0.05, 0.07);<br>
+    *******************************+++++++++++*************************************<br>
+    *************************+++++++++++++++++++++++*******************************<br>
+    **********************+++++++++++++++++++++++++++++****************************<br>
+    *******************+++++++++++++++++++++.. ...++++++++*************************<br>
+    *****************++++++++++++++++++++++.... ...+++++++++***********************<br>
+    ***************+++++++++++++++++++++++.....   ...+++++++++*********************<br>
+    **************+++++++++++++++++++++++....     ....+++++++++********************<br>
+    *************++++++++++++++++++++++......      .....++++++++*******************<br>
+    ************+++++++++++++++++++++.......       .......+++++++******************<br>
+    ***********+++++++++++++++++++....                ... .+++++++*****************<br>
+    **********+++++++++++++++++.......                     .+++++++****************<br>
+    *********++++++++++++++...........                    ...+++++++***************<br>
+    ********++++++++++++............                      ...++++++++**************<br>
+    ********++++++++++... ..........                        .++++++++**************<br>
+    *******+++++++++.....                                   .+++++++++*************<br>
+    *******++++++++......                                  ..+++++++++*************<br>
+    *******++++++.......                                   ..+++++++++*************<br>
+    *******+++++......                                     ..+++++++++*************<br>
+    *******.... ....                                      ...+++++++++*************<br>
+    *******.... .                                         ...+++++++++*************<br>
+    *******+++++......                                    ...+++++++++*************<br>
+    *******++++++.......                                   ..+++++++++*************<br>
+    *******++++++++......                                   .+++++++++*************<br>
+    *******+++++++++.....                                  ..+++++++++*************<br>
+    ********++++++++++... ..........                        .++++++++**************<br>
+    ********++++++++++++............                      ...++++++++**************<br>
+    *********++++++++++++++..........                     ...+++++++***************<br>
+    **********++++++++++++++++........                     .+++++++****************<br>
+    **********++++++++++++++++++++....                ... ..+++++++****************<br>
+    ***********++++++++++++++++++++++.......       .......++++++++*****************<br>
+    ************+++++++++++++++++++++++......      ......++++++++******************<br>
+    **************+++++++++++++++++++++++....      ....++++++++********************<br>
+    ***************+++++++++++++++++++++++.....   ...+++++++++*********************<br>
+    *****************++++++++++++++++++++++....  ...++++++++***********************<br>
+    *******************+++++++++++++++++++++......++++++++*************************<br>
+    *********************++++++++++++++++++++++.++++++++***************************<br>
+    *************************+++++++++++++++++++++++*******************************<br>
+    ******************************+++++++++++++************************************<br>
+    *******************************************************************************<br>
+    *******************************************************************************<br>
+    *******************************************************************************<br>
+    Evaluated to 0.000000<br>
+    ready> mandel(-2, -1, 0.02, 0.04);<br>
+    **************************+++++++++++++++++++++++++++++++++++++++++++++++++++++<br>
+    ***********************++++++++++++++++++++++++++++++++++++++++++++++++++++++++<br>
+    *********************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.<br>
+    *******************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++...<br>
+    *****************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.....<br>
+    ***************++++++++++++++++++++++++++++++++++++++++++++++++++++++++........<br>
+    **************++++++++++++++++++++++++++++++++++++++++++++++++++++++...........<br>
+    ************+++++++++++++++++++++++++++++++++++++++++++++++++++++..............<br>
+    ***********++++++++++++++++++++++++++++++++++++++++++++++++++........        .<br>
+    **********++++++++++++++++++++++++++++++++++++++++++++++.............<br>
+    ********+++++++++++++++++++++++++++++++++++++++++++..................<br>
+    *******+++++++++++++++++++++++++++++++++++++++.......................<br>
+    ******+++++++++++++++++++++++++++++++++++...........................<br>
+    *****++++++++++++++++++++++++++++++++............................<br>
+    *****++++++++++++++++++++++++++++...............................<br>
+    ****++++++++++++++++++++++++++......   .........................<br>
+    ***++++++++++++++++++++++++.........     ......    ...........<br>
+    ***++++++++++++++++++++++............<br>
+    **+++++++++++++++++++++..............<br>
+    **+++++++++++++++++++................<br>
+    *++++++++++++++++++.................<br>
+    *++++++++++++++++............ ...<br>
+    *++++++++++++++..............<br>
+    *+++....++++................<br>
+    *..........  ...........<br>
+    *<br>
+    *..........  ...........<br>
+    *+++....++++................<br>
+    *++++++++++++++..............<br>
+    *++++++++++++++++............ ...<br>
+    *++++++++++++++++++.................<br>
+    **+++++++++++++++++++................<br>
+    **+++++++++++++++++++++..............<br>
+    ***++++++++++++++++++++++............<br>
+    ***++++++++++++++++++++++++.........     ......    ...........<br>
+    ****++++++++++++++++++++++++++......   .........................<br>
+    *****++++++++++++++++++++++++++++...............................<br>
+    *****++++++++++++++++++++++++++++++++............................<br>
+    ******+++++++++++++++++++++++++++++++++++...........................<br>
+    *******+++++++++++++++++++++++++++++++++++++++.......................<br>
+    ********+++++++++++++++++++++++++++++++++++++++++++..................<br>
+    Evaluated to 0.000000<br>
+    ready> mandel(-0.9, -1.4, 0.02, 0.03);<br>
+    *******************************************************************************<br>
+    *******************************************************************************<br>
+    *******************************************************************************<br>
+    **********+++++++++++++++++++++************************************************<br>
+    *+++++++++++++++++++++++++++++++++++++++***************************************<br>
+    +++++++++++++++++++++++++++++++++++++++++++++**********************************<br>
+    ++++++++++++++++++++++++++++++++++++++++++++++++++*****************************<br>
+    ++++++++++++++++++++++++++++++++++++++++++++++++++++++*************************<br>
+    +++++++++++++++++++++++++++++++++++++++++++++++++++++++++**********************<br>
+    +++++++++++++++++++++++++++++++++.........++++++++++++++++++*******************<br>
+    +++++++++++++++++++++++++++++++....   ......+++++++++++++++++++****************<br>
+    +++++++++++++++++++++++++++++.......  ........+++++++++++++++++++**************<br>
+    ++++++++++++++++++++++++++++........   ........++++++++++++++++++++************<br>
+    +++++++++++++++++++++++++++.........     ..  ...+++++++++++++++++++++**********<br>
+    ++++++++++++++++++++++++++...........        ....++++++++++++++++++++++********<br>
+    ++++++++++++++++++++++++.............       .......++++++++++++++++++++++******<br>
+    +++++++++++++++++++++++.............        ........+++++++++++++++++++++++****<br>
+    ++++++++++++++++++++++...........           ..........++++++++++++++++++++++***<br>
+    ++++++++++++++++++++...........                .........++++++++++++++++++++++*<br>
+    ++++++++++++++++++............                  ...........++++++++++++++++++++<br>
+    ++++++++++++++++...............                 .............++++++++++++++++++<br>
+    ++++++++++++++.................                 ...............++++++++++++++++<br>
+    ++++++++++++..................                  .................++++++++++++++<br>
+    +++++++++..................                      .................+++++++++++++<br>
+    ++++++........        .                               .........  ..++++++++++++<br>
+    ++............                                         ......    ....++++++++++<br>
+    ..............                                                    ...++++++++++<br>
+    ..............                                                    ....+++++++++<br>
+    ..............                                                    .....++++++++<br>
+    .............                                                    ......++++++++<br>
+    ...........                                                     .......++++++++<br>
+    .........                                                       ........+++++++<br>
+    .........                                                       ........+++++++<br>
+    .........                                                           ....+++++++<br>
+    ........                                                             ...+++++++<br>
+    .......                                                              ...+++++++<br>
+                                                                        ....+++++++<br>
+                                                                       .....+++++++<br>
+                                                                        ....+++++++<br>
+                                                                        ....+++++++<br>
+                                                                        ....+++++++<br>
+    Evaluated to 0.000000<br>
+    ready> ^D<br>
+<br>
+At this point, you may be starting to realize that Kaleidoscope is a<br>
+real and powerful language. It may not be self-similar :), but it can be<br>
+used to plot things that are!<br>
+<br>
+With this, we conclude the "adding user-defined operators" chapter of<br>
+the tutorial. We have successfully augmented our language, adding the<br>
+ability to extend the language in the library, and we have shown how<br>
+this can be used to build a simple but interesting end-user application<br>
+in Kaleidoscope. At this point, Kaleidoscope can build a variety of<br>
+applications that are functional and can call functions with<br>
+side-effects, but it can't actually define and mutate a variable itself.<br>
+<br>
+Strikingly, variable mutation is an important feature of some languages,<br>
+and it is not at all obvious how to `add support for mutable<br>
+variables <LangImpl7.html>`_ without having to add an "SSA construction"<br>
+phase to your front-end. In the next chapter, we will describe how you<br>
+can add variable mutation without building SSA in your front-end.<br>
+<br>
+Full Code Listing<br>
+=================<br>
+<br>
+Here is the complete code listing for our running example, enhanced with<br>
+the if/then/else and for expressions.. To build this example, use:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    # Compile<br>
+    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
+    # Run<br>
+    ./toy<br>
+<br>
+On some platforms, you will need to specify -rdynamic or<br>
+-Wl,--export-dynamic when linking. This ensures that symbols defined in<br>
+the main executable are exported to the dynamic linker and so are<br>
+available for symbol resolution at run time. This is not needed if you<br>
+compile your support code into a shared library, although doing that<br>
+will cause problems on Windows.<br>
+<br>
+Here is the code:<br>
+<br>
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter6/toy.cpp<br>
+   :language: c++<br>
+<br>
+`Next: Extending the language: mutable variables / SSA<br>
+construction <LangImpl07.html>`_<br>
+<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl07.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl07.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl07.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl07.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl07.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,881 @@<br>
+=======================================================<br>
+Kaleidoscope: Extending the Language: Mutable Variables<br>
+=======================================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Chapter 7 Introduction<br>
+======================<br>
+<br>
+Welcome to Chapter 7 of the "`Implementing a language with<br>
+LLVM <index.html>`_" tutorial. In chapters 1 through 6, we've built a<br>
+very respectable, albeit simple, `functional programming<br>
+language <<a href="http://en.wikipedia.org/wiki/Functional_programming" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Functional_programming</a>>`_. In our<br>
+journey, we learned some parsing techniques, how to build and represent<br>
+an AST, how to build LLVM IR, and how to optimize the resultant code as<br>
+well as JIT compile it.<br>
+<br>
+While Kaleidoscope is interesting as a functional language, the fact<br>
+that it is functional makes it "too easy" to generate LLVM IR for it. In<br>
+particular, a functional language makes it very easy to build LLVM IR<br>
+directly in `SSA<br>
+form <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_.<br>
+Since LLVM requires that the input code be in SSA form, this is a very<br>
+nice property and it is often unclear to newcomers how to generate code<br>
+for an imperative language with mutable variables.<br>
+<br>
+The short (and happy) summary of this chapter is that there is no need<br>
+for your front-end to build SSA form: LLVM provides highly tuned and<br>
+well tested support for this, though the way it works is a bit<br>
+unexpected for some.<br>
+<br>
+Why is this a hard problem?<br>
+===========================<br>
+<br>
+To understand why mutable variables cause complexities in SSA<br>
+construction, consider this extremely simple C example:<br>
+<br>
+.. code-block:: c<br>
+<br>
+    int G, H;<br>
+    int test(_Bool Condition) {<br>
+      int X;<br>
+      if (Condition)<br>
+        X = G;<br>
+      else<br>
+        X = H;<br>
+      return X;<br>
+    }<br>
+<br>
+In this case, we have the variable "X", whose value depends on the path<br>
+executed in the program. Because there are two different possible values<br>
+for X before the return instruction, a PHI node is inserted to merge the<br>
+two values. The LLVM IR that we want for this example looks like this:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+    @G = weak global i32 0   ; type of @G is i32*<br>
+    @H = weak global i32 0   ; type of @H is i32*<br>
+<br>
+    define i32 @test(i1 %Condition) {<br>
+    entry:<br>
+      br i1 %Condition, label %cond_true, label %cond_false<br>
+<br>
+    cond_true:<br>
+      %X.0 = load i32* @G<br>
+      br label %cond_next<br>
+<br>
+    cond_false:<br>
+      %X.1 = load i32* @H<br>
+      br label %cond_next<br>
+<br>
+    cond_next:<br>
+      %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]<br>
+      ret i32 %X.2<br>
+    }<br>
+<br>
+In this example, the loads from the G and H global variables are<br>
+explicit in the LLVM IR, and they live in the then/else branches of the<br>
+if statement (cond\_true/cond\_false). In order to merge the incoming<br>
+values, the X.2 phi node in the cond\_next block selects the right value<br>
+to use based on where control flow is coming from: if control flow comes<br>
+from the cond\_false block, X.2 gets the value of X.1. Alternatively, if<br>
+control flow comes from cond\_true, it gets the value of X.0. The intent<br>
+of this chapter is not to explain the details of SSA form. For more<br>
+information, see one of the many `online<br>
+references <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_.<br>
+<br>
+The question for this article is "who places the phi nodes when lowering<br>
+assignments to mutable variables?". The issue here is that LLVM<br>
+*requires* that its IR be in SSA form: there is no "non-ssa" mode for<br>
+it. However, SSA construction requires non-trivial algorithms and data<br>
+structures, so it is inconvenient and wasteful for every front-end to<br>
+have to reproduce this logic.<br>
+<br>
+Memory in LLVM<br>
+==============<br>
+<br>
+The 'trick' here is that while LLVM does require all register values to<br>
+be in SSA form, it does not require (or permit) memory objects to be in<br>
+SSA form. In the example above, note that the loads from G and H are<br>
+direct accesses to G and H: they are not renamed or versioned. This<br>
+differs from some other compiler systems, which do try to version memory<br>
+objects. In LLVM, instead of encoding dataflow analysis of memory into<br>
+the LLVM IR, it is handled with `Analysis<br>
+Passes <../WritingAnLLVMPass.html>`_ which are computed on demand.<br>
+<br>
+With this in mind, the high-level idea is that we want to make a stack<br>
+variable (which lives in memory, because it is on the stack) for each<br>
+mutable object in a function. To take advantage of this trick, we need<br>
+to talk about how LLVM represents stack variables.<br>
+<br>
+In LLVM, all memory accesses are explicit with load/store instructions,<br>
+and it is carefully designed not to have (or need) an "address-of"<br>
+operator. Notice how the type of the @G/@H global variables is actually<br>
+"i32\*" even though the variable is defined as "i32". What this means is<br>
+that @G defines *space* for an i32 in the global data area, but its<br>
+*name* actually refers to the address for that space. Stack variables<br>
+work the same way, except that instead of being declared with global<br>
+variable definitions, they are declared with the `LLVM alloca<br>
+instruction <../LangRef.html#alloca-instruction>`_:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+    define i32 @example() {<br>
+    entry:<br>
+      %X = alloca i32           ; type of %X is i32*.<br>
+      ...<br>
+      %tmp = load i32* %X       ; load the stack value %X from the stack.<br>
+      %tmp2 = add i32 %tmp, 1   ; increment it<br>
+      store i32 %tmp2, i32* %X  ; store it back<br>
+      ...<br>
+<br>
+This code shows an example of how you can declare and manipulate a stack<br>
+variable in the LLVM IR. Stack memory allocated with the alloca<br>
+instruction is fully general: you can pass the address of the stack slot<br>
+to functions, you can store it in other variables, etc. In our example<br>
+above, we could rewrite the example to use the alloca technique to avoid<br>
+using a PHI node:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+    @G = weak global i32 0   ; type of @G is i32*<br>
+    @H = weak global i32 0   ; type of @H is i32*<br>
+<br>
+    define i32 @test(i1 %Condition) {<br>
+    entry:<br>
+      %X = alloca i32           ; type of %X is i32*.<br>
+      br i1 %Condition, label %cond_true, label %cond_false<br>
+<br>
+    cond_true:<br>
+      %X.0 = load i32* @G<br>
+      store i32 %X.0, i32* %X   ; Update X<br>
+      br label %cond_next<br>
+<br>
+    cond_false:<br>
+      %X.1 = load i32* @H<br>
+      store i32 %X.1, i32* %X   ; Update X<br>
+      br label %cond_next<br>
+<br>
+    cond_next:<br>
+      %X.2 = load i32* %X       ; Read X<br>
+      ret i32 %X.2<br>
+    }<br>
+<br>
+With this, we have discovered a way to handle arbitrary mutable<br>
+variables without the need to create Phi nodes at all:<br>
+<br>
+#. Each mutable variable becomes a stack allocation.<br>
+#. Each read of the variable becomes a load from the stack.<br>
+#. Each update of the variable becomes a store to the stack.<br>
+#. Taking the address of a variable just uses the stack address<br>
+   directly.<br>
+<br>
+While this solution has solved our immediate problem, it introduced<br>
+another one: we have now apparently introduced a lot of stack traffic<br>
+for very simple and common operations, a major performance problem.<br>
+Fortunately for us, the LLVM optimizer has a highly-tuned optimization<br>
+pass named "mem2reg" that handles this case, promoting allocas like this<br>
+into SSA registers, inserting Phi nodes as appropriate. If you run this<br>
+example through the pass, for example, you'll get:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    $ llvm-as < example.ll | opt -mem2reg | llvm-dis<br>
+    @G = weak global i32 0<br>
+    @H = weak global i32 0<br>
+<br>
+    define i32 @test(i1 %Condition) {<br>
+    entry:<br>
+      br i1 %Condition, label %cond_true, label %cond_false<br>
+<br>
+    cond_true:<br>
+      %X.0 = load i32* @G<br>
+      br label %cond_next<br>
+<br>
+    cond_false:<br>
+      %X.1 = load i32* @H<br>
+      br label %cond_next<br>
+<br>
+    cond_next:<br>
+      %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]<br>
+      ret i32 %X.01<br>
+    }<br>
+<br>
+The mem2reg pass implements the standard "iterated dominance frontier"<br>
+algorithm for constructing SSA form and has a number of optimizations<br>
+that speed up (very common) degenerate cases. The mem2reg optimization<br>
+pass is the answer to dealing with mutable variables, and we highly<br>
+recommend that you depend on it. Note that mem2reg only works on<br>
+variables in certain circumstances:<br>
+<br>
+#. mem2reg is alloca-driven: it looks for allocas and if it can handle<br>
+   them, it promotes them. It does not apply to global variables or heap<br>
+   allocations.<br>
+#. mem2reg only looks for alloca instructions in the entry block of the<br>
+   function. Being in the entry block guarantees that the alloca is only<br>
+   executed once, which makes analysis simpler.<br>
+#. mem2reg only promotes allocas whose uses are direct loads and stores.<br>
+   If the address of the stack object is passed to a function, or if any<br>
+   funny pointer arithmetic is involved, the alloca will not be<br>
+   promoted.<br>
+#. mem2reg only works on allocas of `first<br>
+   class <../LangRef.html#first-class-types>`_ values (such as pointers,<br>
+   scalars and vectors), and only if the array size of the allocation is<br>
+   1 (or missing in the .ll file). mem2reg is not capable of promoting<br>
+   structs or arrays to registers. Note that the "sroa" pass is<br>
+   more powerful and can promote structs, "unions", and arrays in many<br>
+   cases.<br>
+<br>
+All of these properties are easy to satisfy for most imperative<br>
+languages, and we'll illustrate it below with Kaleidoscope. The final<br>
+question you may be asking is: should I bother with this nonsense for my<br>
+front-end? Wouldn't it be better if I just did SSA construction<br>
+directly, avoiding use of the mem2reg optimization pass? In short, we<br>
+strongly recommend that you use this technique for building SSA form,<br>
+unless there is an extremely good reason not to. Using this technique<br>
+is:<br>
+<br>
+-  Proven and well tested: clang uses this technique<br>
+   for local mutable variables. As such, the most common clients of LLVM<br>
+   are using this to handle a bulk of their variables. You can be sure<br>
+   that bugs are found fast and fixed early.<br>
+-  Extremely Fast: mem2reg has a number of special cases that make it<br>
+   fast in common cases as well as fully general. For example, it has<br>
+   fast-paths for variables that are only used in a single block,<br>
+   variables that only have one assignment point, good heuristics to<br>
+   avoid insertion of unneeded phi nodes, etc.<br>
+-  Needed for debug info generation: `Debug information in<br>
+   LLVM <../SourceLevelDebugging.html>`_ relies on having the address of<br>
+   the variable exposed so that debug info can be attached to it. This<br>
+   technique dovetails very naturally with this style of debug info.<br>
+<br>
+If nothing else, this makes it much easier to get your front-end up and<br>
+running, and is very simple to implement. Let's extend Kaleidoscope with<br>
+mutable variables now!<br>
+<br>
+Mutable Variables in Kaleidoscope<br>
+=================================<br>
+<br>
+Now that we know the sort of problem we want to tackle, let's see what<br>
+this looks like in the context of our little Kaleidoscope language.<br>
+We're going to add two features:<br>
+<br>
+#. The ability to mutate variables with the '=' operator.<br>
+#. The ability to define new variables.<br>
+<br>
+While the first item is really what this is about, we only have<br>
+variables for incoming arguments as well as for induction variables, and<br>
+redefining those only goes so far :). Also, the ability to define new<br>
+variables is a useful thing regardless of whether you will be mutating<br>
+them. Here's a motivating example that shows how we could use these:<br>
+<br>
+::<br>
+<br>
+    # Define ':' for sequencing: as a low-precedence operator that ignores operands<br>
+    # and just returns the RHS.<br>
+    def binary : 1 (x y) y;<br>
+<br>
+    # Recursive fib, we could do this before.<br>
+    def fib(x)<br>
+      if (x < 3) then<br>
+        1<br>
+      else<br>
+        fib(x-1)+fib(x-2);<br>
+<br>
+    # Iterative fib.<br>
+    def fibi(x)<br>
+      var a = 1, b = 1, c in<br>
+      (for i = 3, i < x in<br>
+         c = a + b :<br>
+         a = b :<br>
+         b = c) :<br>
+      b;<br>
+<br>
+    # Call it.<br>
+    fibi(10);<br>
+<br>
+In order to mutate variables, we have to change our existing variables<br>
+to use the "alloca trick". Once we have that, we'll add our new<br>
+operator, then extend Kaleidoscope to support new variable definitions.<br>
+<br>
+Adjusting Existing Variables for Mutation<br>
+=========================================<br>
+<br>
+The symbol table in Kaleidoscope is managed at code generation time by<br>
+the '``NamedValues``' map. This map currently keeps track of the LLVM<br>
+"Value\*" that holds the double value for the named variable. In order<br>
+to support mutation, we need to change this slightly, so that<br>
+``NamedValues`` holds the *memory location* of the variable in question.<br>
+Note that this change is a refactoring: it changes the structure of the<br>
+code, but does not (by itself) change the behavior of the compiler. All<br>
+of these changes are isolated in the Kaleidoscope code generator.<br>
+<br>
+At this point in Kaleidoscope's development, it only supports variables<br>
+for two things: incoming arguments to functions and the induction<br>
+variable of 'for' loops. For consistency, we'll allow mutation of these<br>
+variables in addition to other user-defined variables. This means that<br>
+these will both need memory locations.<br>
+<br>
+To start our transformation of Kaleidoscope, we'll change the<br>
+NamedValues map so that it maps to AllocaInst\* instead of Value\*. Once<br>
+we do this, the C++ compiler will tell us what parts of the code we need<br>
+to update:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    static std::map<std::string, AllocaInst*> NamedValues;<br>
+<br>
+Also, since we will need to create these alloca's, we'll use a helper<br>
+function that ensures that the allocas are created in the entry block of<br>
+the function:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of<br>
+    /// the function.  This is used for mutable variables etc.<br>
+    static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,<br>
+                                              const std::string &VarName) {<br>
+      IRBuilder<> TmpB(&TheFunction->getEntryBlock(),<br>
+                     TheFunction->getEntryBlock().begin());<br>
+      return TmpB.CreateAlloca(Type::getDoubleTy(LLVMContext), 0,<br>
+                               VarName.c_str());<br>
+    }<br>
+<br>
+This funny looking code creates an IRBuilder object that is pointing at<br>
+the first instruction (.begin()) of the entry block. It then creates an<br>
+alloca with the expected name and returns it. Because all values in<br>
+Kaleidoscope are doubles, there is no need to pass in a type to use.<br>
+<br>
+With this in place, the first functionality change we want to make is to<br>
+variable references. In our new scheme, variables live on the stack, so<br>
+code generating a reference to them actually needs to produce a load<br>
+from the stack slot:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *VariableExprAST::codegen() {<br>
+      // Look this variable up in the function.<br>
+      Value *V = NamedValues[Name];<br>
+      if (!V)<br>
+        return LogErrorV("Unknown variable name");<br>
+<br>
+      // Load the value.<br>
+      return Builder.CreateLoad(V, Name.c_str());<br>
+    }<br>
+<br>
+As you can see, this is pretty straightforward. Now we need to update<br>
+the things that define the variables to set up the alloca. We'll start<br>
+with ``ForExprAST::codegen()`` (see the `full code listing <#id1>`_ for<br>
+the unabridged code):<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      Function *TheFunction = Builder.GetInsertBlock()->getParent();<br>
+<br>
+      // Create an alloca for the variable in the entry block.<br>
+      AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);<br>
+<br>
+        // Emit the start code first, without 'variable' in scope.<br>
+      Value *StartVal = Start->codegen();<br>
+      if (!StartVal)<br>
+        return nullptr;<br>
+<br>
+      // Store the value into the alloca.<br>
+      Builder.CreateStore(StartVal, Alloca);<br>
+      ...<br>
+<br>
+      // Compute the end condition.<br>
+      Value *EndCond = End->codegen();<br>
+      if (!EndCond)<br>
+        return nullptr;<br>
+<br>
+      // Reload, increment, and restore the alloca.  This handles the case where<br>
+      // the body of the loop mutates the variable.<br>
+      Value *CurVar = Builder.CreateLoad(Alloca);<br>
+      Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");<br>
+      Builder.CreateStore(NextVar, Alloca);<br>
+      ...<br>
+<br>
+This code is virtually identical to the code `before we allowed mutable<br>
+variables <LangImpl5.html#code-generation-for-the-for-loop>`_. The big difference is that we<br>
+no longer have to construct a PHI node, and we use load/store to access<br>
+the variable as needed.<br>
+<br>
+To support mutable argument variables, we need to also make allocas for<br>
+them. The code for this is also pretty simple:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// CreateArgumentAllocas - Create an alloca for each argument and register the<br>
+    /// argument in the symbol table so that references to it will succeed.<br>
+    void PrototypeAST::CreateArgumentAllocas(Function *F) {<br>
+      Function::arg_iterator AI = F->arg_begin();<br>
+      for (unsigned Idx = 0, e = Args.size(); Idx != e; ++Idx, ++AI) {<br>
+        // Create an alloca for this variable.<br>
+        AllocaInst *Alloca = CreateEntryBlockAlloca(F, Args[Idx]);<br>
+<br>
+        // Store the initial value into the alloca.<br>
+        Builder.CreateStore(AI, Alloca);<br>
+<br>
+        // Add arguments to variable symbol table.<br>
+        NamedValues[Args[Idx]] = Alloca;<br>
+      }<br>
+    }<br>
+<br>
+For each argument, we make an alloca, store the input value to the<br>
+function into the alloca, and register the alloca as the memory location<br>
+for the argument. This method gets invoked by ``FunctionAST::codegen()``<br>
+right after it sets up the entry block for the function.<br>
+<br>
+The final missing piece is adding the mem2reg pass, which allows us to<br>
+get good codegen once again:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+        // Set up the optimizer pipeline.  Start with registering info about how the<br>
+        // target lays out data structures.<br>
+        OurFPM.add(new DataLayout(*TheExecutionEngine->getDataLayout()));<br>
+        // Promote allocas to registers.<br>
+        OurFPM.add(createPromoteMemoryToRegisterPass());<br>
+        // Do simple "peephole" optimizations and bit-twiddling optzns.<br>
+        OurFPM.add(createInstructionCombiningPass());<br>
+        // Reassociate expressions.<br>
+        OurFPM.add(createReassociatePass());<br>
+<br>
+It is interesting to see what the code looks like before and after the<br>
+mem2reg optimization runs. For example, this is the before/after code<br>
+for our recursive fib function. Before the optimization:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+    define double @fib(double %x) {<br>
+    entry:<br>
+      %x1 = alloca double<br>
+      store double %x, double* %x1<br>
+      %x2 = load double* %x1<br>
+      %cmptmp = fcmp ult double %x2, 3.000000e+00<br>
+      %booltmp = uitofp i1 %cmptmp to double<br>
+      %ifcond = fcmp one double %booltmp, 0.000000e+00<br>
+      br i1 %ifcond, label %then, label %else<br>
+<br>
+    then:       ; preds = %entry<br>
+      br label %ifcont<br>
+<br>
+    else:       ; preds = %entry<br>
+      %x3 = load double* %x1<br>
+      %subtmp = fsub double %x3, 1.000000e+00<br>
+      %calltmp = call double @fib(double %subtmp)<br>
+      %x4 = load double* %x1<br>
+      %subtmp5 = fsub double %x4, 2.000000e+00<br>
+      %calltmp6 = call double @fib(double %subtmp5)<br>
+      %addtmp = fadd double %calltmp, %calltmp6<br>
+      br label %ifcont<br>
+<br>
+    ifcont:     ; preds = %else, %then<br>
+      %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]<br>
+      ret double %iftmp<br>
+    }<br>
+<br>
+Here there is only one variable (x, the input argument) but you can<br>
+still see the extremely simple-minded code generation strategy we are<br>
+using. In the entry block, an alloca is created, and the initial input<br>
+value is stored into it. Each reference to the variable does a reload<br>
+from the stack. Also, note that we didn't modify the if/then/else<br>
+expression, so it still inserts a PHI node. While we could make an<br>
+alloca for it, it is actually easier to create a PHI node for it, so we<br>
+still just make the PHI.<br>
+<br>
+Here is the code after the mem2reg pass runs:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+    define double @fib(double %x) {<br>
+    entry:<br>
+      %cmptmp = fcmp ult double %x, 3.000000e+00<br>
+      %booltmp = uitofp i1 %cmptmp to double<br>
+      %ifcond = fcmp one double %booltmp, 0.000000e+00<br>
+      br i1 %ifcond, label %then, label %else<br>
+<br>
+    then:<br>
+      br label %ifcont<br>
+<br>
+    else:<br>
+      %subtmp = fsub double %x, 1.000000e+00<br>
+      %calltmp = call double @fib(double %subtmp)<br>
+      %subtmp5 = fsub double %x, 2.000000e+00<br>
+      %calltmp6 = call double @fib(double %subtmp5)<br>
+      %addtmp = fadd double %calltmp, %calltmp6<br>
+      br label %ifcont<br>
+<br>
+    ifcont:     ; preds = %else, %then<br>
+      %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]<br>
+      ret double %iftmp<br>
+    }<br>
+<br>
+This is a trivial case for mem2reg, since there are no redefinitions of<br>
+the variable. The point of showing this is to calm your tension about<br>
+inserting such blatent inefficiencies :).<br>
+<br>
+After the rest of the optimizers run, we get:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+    define double @fib(double %x) {<br>
+    entry:<br>
+      %cmptmp = fcmp ult double %x, 3.000000e+00<br>
+      %booltmp = uitofp i1 %cmptmp to double<br>
+      %ifcond = fcmp ueq double %booltmp, 0.000000e+00<br>
+      br i1 %ifcond, label %else, label %ifcont<br>
+<br>
+    else:<br>
+      %subtmp = fsub double %x, 1.000000e+00<br>
+      %calltmp = call double @fib(double %subtmp)<br>
+      %subtmp5 = fsub double %x, 2.000000e+00<br>
+      %calltmp6 = call double @fib(double %subtmp5)<br>
+      %addtmp = fadd double %calltmp, %calltmp6<br>
+      ret double %addtmp<br>
+<br>
+    ifcont:<br>
+      ret double 1.000000e+00<br>
+    }<br>
+<br>
+Here we see that the simplifycfg pass decided to clone the return<br>
+instruction into the end of the 'else' block. This allowed it to<br>
+eliminate some branches and the PHI node.<br>
+<br>
+Now that all symbol table references are updated to use stack variables,<br>
+we'll add the assignment operator.<br>
+<br>
+New Assignment Operator<br>
+=======================<br>
+<br>
+With our current framework, adding a new assignment operator is really<br>
+simple. We will parse it just like any other binary operator, but handle<br>
+it internally (instead of allowing the user to define it). The first<br>
+step is to set a precedence:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+     int main() {<br>
+       // Install standard binary operators.<br>
+       // 1 is lowest precedence.<br>
+       BinopPrecedence['='] = 2;<br>
+       BinopPrecedence['<'] = 10;<br>
+       BinopPrecedence['+'] = 20;<br>
+       BinopPrecedence['-'] = 20;<br>
+<br>
+Now that the parser knows the precedence of the binary operator, it<br>
+takes care of all the parsing and AST generation. We just need to<br>
+implement codegen for the assignment operator. This looks like:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *BinaryExprAST::codegen() {<br>
+      // Special case '=' because we don't want to emit the LHS as an expression.<br>
+      if (Op == '=') {<br>
+        // Assignment requires the LHS to be an identifier.<br>
+        VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS.get());<br>
+        if (!LHSE)<br>
+          return LogErrorV("destination of '=' must be a variable");<br>
+<br>
+Unlike the rest of the binary operators, our assignment operator doesn't<br>
+follow the "emit LHS, emit RHS, do computation" model. As such, it is<br>
+handled as a special case before the other binary operators are handled.<br>
+The other strange thing is that it requires the LHS to be a variable. It<br>
+is invalid to have "(x+1) = expr" - only things like "x = expr" are<br>
+allowed.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+        // Codegen the RHS.<br>
+        Value *Val = RHS->codegen();<br>
+        if (!Val)<br>
+          return nullptr;<br>
+<br>
+        // Look up the name.<br>
+        Value *Variable = NamedValues[LHSE->getName()];<br>
+        if (!Variable)<br>
+          return LogErrorV("Unknown variable name");<br>
+<br>
+        Builder.CreateStore(Val, Variable);<br>
+        return Val;<br>
+      }<br>
+      ...<br>
+<br>
+Once we have the variable, codegen'ing the assignment is<br>
+straightforward: we emit the RHS of the assignment, create a store, and<br>
+return the computed value. Returning a value allows for chained<br>
+assignments like "X = (Y = Z)".<br>
+<br>
+Now that we have an assignment operator, we can mutate loop variables<br>
+and arguments. For example, we can now run code like this:<br>
+<br>
+::<br>
+<br>
+    # Function to print a double.<br>
+    extern printd(x);<br>
+<br>
+    # Define ':' for sequencing: as a low-precedence operator that ignores operands<br>
+    # and just returns the RHS.<br>
+    def binary : 1 (x y) y;<br>
+<br>
+    def test(x)<br>
+      printd(x) :<br>
+      x = 4 :<br>
+      printd(x);<br>
+<br>
+    test(123);<br>
+<br>
+When run, this example prints "123" and then "4", showing that we did<br>
+actually mutate the value! Okay, we have now officially implemented our<br>
+goal: getting this to work requires SSA construction in the general<br>
+case. However, to be really useful, we want the ability to define our<br>
+own local variables, let's add this next!<br>
+<br>
+User-defined Local Variables<br>
+============================<br>
+<br>
+Adding var/in is just like any other extension we made to<br>
+Kaleidoscope: we extend the lexer, the parser, the AST and the code<br>
+generator. The first step for adding our new 'var/in' construct is to<br>
+extend the lexer. As before, this is pretty trivial, the code looks like<br>
+this:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    enum Token {<br>
+      ...<br>
+      // var definition<br>
+      tok_var = -13<br>
+    ...<br>
+    }<br>
+    ...<br>
+    static int gettok() {<br>
+    ...<br>
+        if (IdentifierStr == "in")<br>
+          return tok_in;<br>
+        if (IdentifierStr == "binary")<br>
+          return tok_binary;<br>
+        if (IdentifierStr == "unary")<br>
+          return tok_unary;<br>
+        if (IdentifierStr == "var")<br>
+          return tok_var;<br>
+        return tok_identifier;<br>
+    ...<br>
+<br>
+The next step is to define the AST node that we will construct. For<br>
+var/in, it looks like this:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// VarExprAST - Expression class for var/in<br>
+    class VarExprAST : public ExprAST {<br>
+      std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;<br>
+      std::unique_ptr<ExprAST> Body;<br>
+<br>
+    public:<br>
+      VarExprAST(std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,<br>
+                 std::unique_ptr<ExprAST> body)<br>
+      : VarNames(std::move(VarNames)), Body(std::move(Body)) {}<br>
+<br>
+      virtual Value *codegen();<br>
+    };<br>
+<br>
+var/in allows a list of names to be defined all at once, and each name<br>
+can optionally have an initializer value. As such, we capture this<br>
+information in the VarNames vector. Also, var/in has a body, this body<br>
+is allowed to access the variables defined by the var/in.<br>
+<br>
+With this in place, we can define the parser pieces. The first thing we<br>
+do is add it as a primary expression:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// primary<br>
+    ///   ::= identifierexpr<br>
+    ///   ::= numberexpr<br>
+    ///   ::= parenexpr<br>
+    ///   ::= ifexpr<br>
+    ///   ::= forexpr<br>
+    ///   ::= varexpr<br>
+    static std::unique_ptr<ExprAST> ParsePrimary() {<br>
+      switch (CurTok) {<br>
+      default:<br>
+        return LogError("unknown token when expecting an expression");<br>
+      case tok_identifier:<br>
+        return ParseIdentifierExpr();<br>
+      case tok_number:<br>
+        return ParseNumberExpr();<br>
+      case '(':<br>
+        return ParseParenExpr();<br>
+      case tok_if:<br>
+        return ParseIfExpr();<br>
+      case tok_for:<br>
+        return ParseForExpr();<br>
+      case tok_var:<br>
+        return ParseVarExpr();<br>
+      }<br>
+    }<br>
+<br>
+Next we define ParseVarExpr:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    /// varexpr ::= 'var' identifier ('=' expression)?<br>
+    //                    (',' identifier ('=' expression)?)* 'in' expression<br>
+    static std::unique_ptr<ExprAST> ParseVarExpr() {<br>
+      getNextToken();  // eat the var.<br>
+<br>
+      std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;<br>
+<br>
+      // At least one variable name is required.<br>
+      if (CurTok != tok_identifier)<br>
+        return LogError("expected identifier after var");<br>
+<br>
+The first part of this code parses the list of identifier/expr pairs<br>
+into the local ``VarNames`` vector.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      while (1) {<br>
+        std::string Name = IdentifierStr;<br>
+        getNextToken();  // eat identifier.<br>
+<br>
+        // Read the optional initializer.<br>
+        std::unique_ptr<ExprAST> Init;<br>
+        if (CurTok == '=') {<br>
+          getNextToken(); // eat the '='.<br>
+<br>
+          Init = ParseExpression();<br>
+          if (!Init) return nullptr;<br>
+        }<br>
+<br>
+        VarNames.push_back(std::make_pair(Name, std::move(Init)));<br>
+<br>
+        // End of var list, exit loop.<br>
+        if (CurTok != ',') break;<br>
+        getNextToken(); // eat the ','.<br>
+<br>
+        if (CurTok != tok_identifier)<br>
+          return LogError("expected identifier list after var");<br>
+      }<br>
+<br>
+Once all the variables are parsed, we then parse the body and create the<br>
+AST node:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // At this point, we have to have 'in'.<br>
+      if (CurTok != tok_in)<br>
+        return LogError("expected 'in' keyword after 'var'");<br>
+      getNextToken();  // eat 'in'.<br>
+<br>
+      auto Body = ParseExpression();<br>
+      if (!Body)<br>
+        return nullptr;<br>
+<br>
+      return llvm::make_unique<VarExprAST>(std::move(VarNames),<br>
+                                           std::move(Body));<br>
+    }<br>
+<br>
+Now that we can parse and represent the code, we need to support<br>
+emission of LLVM IR for it. This code starts out with:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    Value *VarExprAST::codegen() {<br>
+      std::vector<AllocaInst *> OldBindings;<br>
+<br>
+      Function *TheFunction = Builder.GetInsertBlock()->getParent();<br>
+<br>
+      // Register all variables and emit their initializer.<br>
+      for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {<br>
+        const std::string &VarName = VarNames[i].first;<br>
+        ExprAST *Init = VarNames[i].second.get();<br>
+<br>
+Basically it loops over all the variables, installing them one at a<br>
+time. For each variable we put into the symbol table, we remember the<br>
+previous value that we replace in OldBindings.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+        // Emit the initializer before adding the variable to scope, this prevents<br>
+        // the initializer from referencing the variable itself, and permits stuff<br>
+        // like this:<br>
+        //  var a = 1 in<br>
+        //    var a = a in ...   # refers to outer 'a'.<br>
+        Value *InitVal;<br>
+        if (Init) {<br>
+          InitVal = Init->codegen();<br>
+          if (!InitVal)<br>
+            return nullptr;<br>
+        } else { // If not specified, use 0.0.<br>
+          InitVal = ConstantFP::get(LLVMContext, APFloat(0.0));<br>
+        }<br>
+<br>
+        AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);<br>
+        Builder.CreateStore(InitVal, Alloca);<br>
+<br>
+        // Remember the old variable binding so that we can restore the binding when<br>
+        // we unrecurse.<br>
+        OldBindings.push_back(NamedValues[VarName]);<br>
+<br>
+        // Remember this binding.<br>
+        NamedValues[VarName] = Alloca;<br>
+      }<br>
+<br>
+There are more comments here than code. The basic idea is that we emit<br>
+the initializer, create the alloca, then update the symbol table to<br>
+point to it. Once all the variables are installed in the symbol table,<br>
+we evaluate the body of the var/in expression:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Codegen the body, now that all vars are in scope.<br>
+      Value *BodyVal = Body->codegen();<br>
+      if (!BodyVal)<br>
+        return nullptr;<br>
+<br>
+Finally, before returning, we restore the previous variable bindings:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+      // Pop all our variables from scope.<br>
+      for (unsigned i = 0, e = VarNames.size(); i != e; ++i)<br>
+        NamedValues[VarNames[i].first] = OldBindings[i];<br>
+<br>
+      // Return the body computation.<br>
+      return BodyVal;<br>
+    }<br>
+<br>
+The end result of all of this is that we get properly scoped variable<br>
+definitions, and we even (trivially) allow mutation of them :).<br>
+<br>
+With this, we completed what we set out to do. Our nice iterative fib<br>
+example from the intro compiles and runs just fine. The mem2reg pass<br>
+optimizes all of our stack variables into SSA registers, inserting PHI<br>
+nodes where needed, and our front-end remains simple: no "iterated<br>
+dominance frontier" computation anywhere in sight.<br>
+<br>
+Full Code Listing<br>
+=================<br>
+<br>
+Here is the complete code listing for our running example, enhanced with<br>
+mutable variables and var/in support. To build this example, use:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    # Compile<br>
+    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
+    # Run<br>
+    ./toy<br>
+<br>
+Here is the code:<br>
+<br>
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter7/toy.cpp<br>
+   :language: c++<br>
+<br>
+`Next: Compiling to Object Code <LangImpl08.html>`_<br>
+<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl08.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl08.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl08.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl08.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl08.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,218 @@<br>
+========================================<br>
+ Kaleidoscope: Compiling to Object Code<br>
+========================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Chapter 8 Introduction<br>
+======================<br>
+<br>
+Welcome to Chapter 8 of the "`Implementing a language with LLVM<br>
+<index.html>`_" tutorial. This chapter describes how to compile our<br>
+language down to object files.<br>
+<br>
+Choosing a target<br>
+=================<br>
+<br>
+LLVM has native support for cross-compilation. You can compile to the<br>
+architecture of your current machine, or just as easily compile for<br>
+other architectures. In this tutorial, we'll target the current<br>
+machine.<br>
+<br>
+To specify the architecture that you want to target, we use a string<br>
+called a "target triple". This takes the form<br>
+``<arch><sub>-<vendor>-<sys>-<abi>`` (see the `cross compilation docs<br>
+<<a href="http://clang.llvm.org/docs/CrossCompilation.html#target-triple" rel="noreferrer" target="_blank">http://clang.llvm.org/docs/CrossCompilation.html#target-triple</a>>`_).<br>
+<br>
+As an example, we can see what clang thinks is our current target<br>
+triple:<br>
+<br>
+::<br>
+<br>
+    $ clang --version | grep Target<br>
+    Target: x86_64-unknown-linux-gnu<br>
+<br>
+Running this command may show something different on your machine as<br>
+you might be using a different architecture or operating system to me.<br>
+<br>
+Fortunately, we don't need to hard-code a target triple to target the<br>
+current machine. LLVM provides ``sys::getDefaultTargetTriple``, which<br>
+returns the target triple of the current machine.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    auto TargetTriple = sys::getDefaultTargetTriple();<br>
+<br>
+LLVM doesn't require us to to link in all the target<br>
+functionality. For example, if we're just using the JIT, we don't need<br>
+the assembly printers. Similarly, if we're only targetting certain<br>
+architectures, we can only link in the functionality for those<br>
+architectures.<br>
+<br>
+For this example, we'll initialize all the targets for emitting object<br>
+code.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    InitializeAllTargetInfos();<br>
+    InitializeAllTargets();<br>
+    InitializeAllTargetMCs();<br>
+    InitializeAllAsmParsers();<br>
+    InitializeAllAsmPrinters();<br>
+<br>
+We can now use our target triple to get a ``Target``:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  std::string Error;<br>
+  auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);<br>
+<br>
+  // Print an error and exit if we couldn't find the requested target.<br>
+  // This generally occurs if we've forgotten to initialise the<br>
+  // TargetRegistry or we have a bogus target triple.<br>
+  if (!Target) {<br>
+    errs() << Error;<br>
+    return 1;<br>
+  }<br>
+<br>
+Target Machine<br>
+==============<br>
+<br>
+We will also need a ``TargetMachine``. This class provides a complete<br>
+machine description of the machine we're targetting. If we want to<br>
+target a specific feature (such as SSE) or a specific CPU (such as<br>
+Intel's Sandylake), we do so now.<br>
+<br>
+To see which features and CPUs that LLVM knows about, we can use<br>
+``llc``. For example, let's look at x86:<br>
+<br>
+::<br>
+<br>
+    $ llvm-as < /dev/null | llc -march=x86 -mattr=help<br>
+    Available CPUs for this target:<br>
+<br>
+      amdfam10      - Select the amdfam10 processor.<br>
+      athlon        - Select the athlon processor.<br>
+      athlon-4      - Select the athlon-4 processor.<br>
+      ...<br>
+<br>
+    Available features for this target:<br>
+<br>
+      16bit-mode            - 16-bit mode (i8086).<br>
+      32bit-mode            - 32-bit mode (80386).<br>
+      3dnow                 - Enable 3DNow! instructions.<br>
+      3dnowa                - Enable 3DNow! Athlon instructions.<br>
+      ...<br>
+<br>
+For our example, we'll use the generic CPU without any additional<br>
+features, options or relocation model.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  auto CPU = "generic";<br>
+  auto Features = "";<br>
+<br>
+  TargetOptions opt;<br>
+  auto RM = Optional<Reloc::Model>();<br>
+  auto TargetMachine = Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);<br>
+<br>
+<br>
+Configuring the Module<br>
+======================<br>
+<br>
+We're now ready to configure our module, to specify the target and<br>
+data layout. This isn't strictly necessary, but the `frontend<br>
+performance guide <../Frontend/PerformanceTips.html>`_ recommends<br>
+this. Optimizations benefit from knowing about the target and data<br>
+layout.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  TheModule->setDataLayout(TargetMachine->createDataLayout());<br>
+  TheModule->setTargetTriple(TargetTriple);<br>
+<br>
+Emit Object Code<br>
+================<br>
+<br>
+We're ready to emit object code! Let's define where we want to write<br>
+our file to:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  auto Filename = "output.o";<br>
+  std::error_code EC;<br>
+  raw_fd_ostream dest(Filename, EC, sys::fs::F_None);<br>
+<br>
+  if (EC) {<br>
+    errs() << "Could not open file: " << EC.message();<br>
+    return 1;<br>
+  }<br>
+<br>
+Finally, we define a pass that emits object code, then we run that<br>
+pass:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  legacy::PassManager pass;<br>
+  auto FileType = TargetMachine::CGFT_ObjectFile;<br>
+<br>
+  if (TargetMachine->addPassesToEmitFile(pass, dest, FileType)) {<br>
+    errs() << "TargetMachine can't emit a file of this type";<br>
+    return 1;<br>
+  }<br>
+<br>
+  pass.run(*TheModule);<br>
+  dest.flush();<br>
+<br>
+Putting It All Together<br>
+=======================<br>
+<br>
+Does it work? Let's give it a try. We need to compile our code, but<br>
+note that the arguments to ``llvm-config`` are different to the previous chapters.<br>
+<br>
+::<br>
+<br>
+    $ clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs all` -o toy<br>
+<br>
+Let's run it, and define a simple ``average`` function. Press Ctrl-D<br>
+when you're done.<br>
+<br>
+::<br>
+<br>
+    $ ./toy<br>
+    ready> def average(x y) (x + y) * 0.5;<br>
+    ^D<br>
+    Wrote output.o<br>
+<br>
+We have an object file! To test it, let's write a simple program and<br>
+link it with our output. Here's the source code:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+    #include <iostream><br>
+<br>
+    extern "C" {<br>
+        double average(double, double);<br>
+    }<br>
+<br>
+    int main() {<br>
+        std::cout << "average of 3.0 and 4.0: " << average(3.0, 4.0) << std::endl;<br>
+    }<br>
+<br>
+We link our program to output.o and check the result is what we<br>
+expected:<br>
+<br>
+::<br>
+<br>
+    $ clang++ main.cpp output.o -o main<br>
+    $ ./main<br>
+    average of 3.0 and 4.0: 3.5<br>
+<br>
+Full Code Listing<br>
+=================<br>
+<br>
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter8/toy.cpp<br>
+   :language: c++<br>
+<br>
+`Next: Adding Debug Information <LangImpl09.html>`_<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl09.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl09.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl09.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl09.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl09.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,462 @@<br>
+======================================<br>
+Kaleidoscope: Adding Debug Information<br>
+======================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Chapter 9 Introduction<br>
+======================<br>
+<br>
+Welcome to Chapter 9 of the "`Implementing a language with<br>
+LLVM <index.html>`_" tutorial. In chapters 1 through 8, we've built a<br>
+decent little programming language with functions and variables.<br>
+What happens if something goes wrong though, how do you debug your<br>
+program?<br>
+<br>
+Source level debugging uses formatted data that helps a debugger<br>
+translate from binary and the state of the machine back to the<br>
+source that the programmer wrote. In LLVM we generally use a format<br>
+called `DWARF <<a href="http://dwarfstd.org" rel="noreferrer" target="_blank">http://dwarfstd.org</a>>`_. DWARF is a compact encoding<br>
+that represents types, source locations, and variable locations.<br>
+<br>
+The short summary of this chapter is that we'll go through the<br>
+various things you have to add to a programming language to<br>
+support debug info, and how you translate that into DWARF.<br>
+<br>
+Caveat: For now we can't debug via the JIT, so we'll need to compile<br>
+our program down to something small and standalone. As part of this<br>
+we'll make a few modifications to the running of the language and<br>
+how programs are compiled. This means that we'll have a source file<br>
+with a simple program written in Kaleidoscope rather than the<br>
+interactive JIT. It does involve a limitation that we can only<br>
+have one "top level" command at a time to reduce the number of<br>
+changes necessary.<br>
+<br>
+Here's the sample program we'll be compiling:<br>
+<br>
+.. code-block:: python<br>
+<br>
+   def fib(x)<br>
+     if x < 3 then<br>
+       1<br>
+     else<br>
+       fib(x-1)+fib(x-2);<br>
+<br>
+   fib(10)<br>
+<br>
+<br>
+Why is this a hard problem?<br>
+===========================<br>
+<br>
+Debug information is a hard problem for a few different reasons - mostly<br>
+centered around optimized code. First, optimization makes keeping source<br>
+locations more difficult. In LLVM IR we keep the original source location<br>
+for each IR level instruction on the instruction. Optimization passes<br>
+should keep the source locations for newly created instructions, but merged<br>
+instructions only get to keep a single location - this can cause jumping<br>
+around when stepping through optimized programs. Secondly, optimization<br>
+can move variables in ways that are either optimized out, shared in memory<br>
+with other variables, or difficult to track. For the purposes of this<br>
+tutorial we're going to avoid optimization (as you'll see with one of the<br>
+next sets of patches).<br>
+<br>
+Ahead-of-Time Compilation Mode<br>
+==============================<br>
+<br>
+To highlight only the aspects of adding debug information to a source<br>
+language without needing to worry about the complexities of JIT debugging<br>
+we're going to make a few changes to Kaleidoscope to support compiling<br>
+the IR emitted by the front end into a simple standalone program that<br>
+you can execute, debug, and see results.<br>
+<br>
+First we make our anonymous function that contains our top level<br>
+statement be our "main":<br>
+<br>
+.. code-block:: udiff<br>
+<br>
+  -    auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());<br>
+  +    auto Proto = llvm::make_unique<PrototypeAST>("main", std::vector<std::string>());<br>
+<br>
+just with the simple change of giving it a name.<br>
+<br>
+Then we're going to remove the command line code wherever it exists:<br>
+<br>
+.. code-block:: udiff<br>
+<br>
+  @@ -1129,7 +1129,6 @@ static void HandleTopLevelExpression() {<br>
+   /// top ::= definition | external | expression | ';'<br>
+   static void MainLoop() {<br>
+     while (1) {<br>
+  -    fprintf(stderr, "ready> ");<br>
+       switch (CurTok) {<br>
+       case tok_eof:<br>
+         return;<br>
+  @@ -1184,7 +1183,6 @@ int main() {<br>
+     BinopPrecedence['*'] = 40; // highest.<br>
+<br>
+     // Prime the first token.<br>
+  -  fprintf(stderr, "ready> ");<br>
+     getNextToken();<br>
+<br>
+Lastly we're going to disable all of the optimization passes and the JIT so<br>
+that the only thing that happens after we're done parsing and generating<br>
+code is that the llvm IR goes to standard error:<br>
+<br>
+.. code-block:: udiff<br>
+<br>
+  @@ -1108,17 +1108,8 @@ static void HandleExtern() {<br>
+   static void HandleTopLevelExpression() {<br>
+     // Evaluate a top-level expression into an anonymous function.<br>
+     if (auto FnAST = ParseTopLevelExpr()) {<br>
+  -    if (auto *FnIR = FnAST->codegen()) {<br>
+  -      // We're just doing this to make sure it executes.<br>
+  -      TheExecutionEngine->finalizeObject();<br>
+  -      // JIT the function, returning a function pointer.<br>
+  -      void *FPtr = TheExecutionEngine->getPointerToFunction(FnIR);<br>
+  -<br>
+  -      // Cast it to the right type (takes no arguments, returns a double) so we<br>
+  -      // can call it as a native function.<br>
+  -      double (*FP)() = (double (*)())(intptr_t)FPtr;<br>
+  -      // Ignore the return value for this.<br>
+  -      (void)FP;<br>
+  +    if (!F->codegen()) {<br>
+  +      fprintf(stderr, "Error generating code for top level expr");<br>
+       }<br>
+     } else {<br>
+       // Skip token for error recovery.<br>
+  @@ -1439,11 +1459,11 @@ int main() {<br>
+     // target lays out data structures.<br>
+     TheModule->setDataLayout(TheExecutionEngine->getDataLayout());<br>
+     OurFPM.add(new DataLayoutPass());<br>
+  +#if 0<br>
+     OurFPM.add(createBasicAliasAnalysisPass());<br>
+     // Promote allocas to registers.<br>
+     OurFPM.add(createPromoteMemoryToRegisterPass());<br>
+  @@ -1218,7 +1210,7 @@ int main() {<br>
+     OurFPM.add(createGVNPass());<br>
+     // Simplify the control flow graph (deleting unreachable blocks, etc).<br>
+     OurFPM.add(createCFGSimplificationPass());<br>
+  -<br>
+  +  #endif<br>
+     OurFPM.doInitialization();<br>
+<br>
+     // Set the global so the code gen can use this.<br>
+<br>
+This relatively small set of changes get us to the point that we can compile<br>
+our piece of Kaleidoscope language down to an executable program via this<br>
+command line:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+  Kaleidoscope-Ch9 < fib.ks | & clang -x ir -<br>
+<br>
+which gives an a.out/a.exe in the current working directory.<br>
+<br>
+Compile Unit<br>
+============<br>
+<br>
+The top level container for a section of code in DWARF is a compile unit.<br>
+This contains the type and function data for an individual translation unit<br>
+(read: one file of source code). So the first thing we need to do is<br>
+construct one for our fib.ks file.<br>
+<br>
+DWARF Emission Setup<br>
+====================<br>
+<br>
+Similar to the ``IRBuilder`` class we have a<br>
+`DIBuilder <<a href="http://llvm.org/doxygen/classllvm_1_1DIBuilder.html" rel="noreferrer" target="_blank">http://llvm.org/doxygen/classllvm_1_1DIBuilder.html</a>>`_ class<br>
+that helps in constructing debug metadata for an llvm IR file. It<br>
+corresponds 1:1 similarly to ``IRBuilder`` and llvm IR, but with nicer names.<br>
+Using it does require that you be more familiar with DWARF terminology than<br>
+you needed to be with ``IRBuilder`` and ``Instruction`` names, but if you<br>
+read through the general documentation on the<br>
+`Metadata Format <<a href="http://llvm.org/docs/SourceLevelDebugging.html" rel="noreferrer" target="_blank">http://llvm.org/docs/SourceLevelDebugging.html</a>>`_ it<br>
+should be a little more clear. We'll be using this class to construct all<br>
+of our IR level descriptions. Construction for it takes a module so we<br>
+need to construct it shortly after we construct our module. We've left it<br>
+as a global static variable to make it a bit easier to use.<br>
+<br>
+Next we're going to create a small container to cache some of our frequent<br>
+data. The first will be our compile unit, but we'll also write a bit of<br>
+code for our one type since we won't have to worry about multiple typed<br>
+expressions:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  static DIBuilder *DBuilder;<br>
+<br>
+  struct DebugInfo {<br>
+    DICompileUnit *TheCU;<br>
+    DIType *DblTy;<br>
+<br>
+    DIType *getDoubleTy();<br>
+  } KSDbgInfo;<br>
+<br>
+  DIType *DebugInfo::getDoubleTy() {<br>
+    if (DblTy.isValid())<br>
+      return DblTy;<br>
+<br>
+    DblTy = DBuilder->createBasicType("double", 64, 64, dwarf::DW_ATE_float);<br>
+    return DblTy;<br>
+  }<br>
+<br>
+And then later on in ``main`` when we're constructing our module:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  DBuilder = new DIBuilder(*TheModule);<br>
+<br>
+  KSDbgInfo.TheCU = DBuilder->createCompileUnit(<br>
+      dwarf::DW_LANG_C, "fib.ks", ".", "Kaleidoscope Compiler", 0, "", 0);<br>
+<br>
+There are a couple of things to note here. First, while we're producing a<br>
+compile unit for a language called Kaleidoscope we used the language<br>
+constant for C. This is because a debugger wouldn't necessarily understand<br>
+the calling conventions or default ABI for a language it doesn't recognize<br>
+and we follow the C ABI in our llvm code generation so it's the closest<br>
+thing to accurate. This ensures we can actually call functions from the<br>
+debugger and have them execute. Secondly, you'll see the "fib.ks" in the<br>
+call to ``createCompileUnit``. This is a default hard coded value since<br>
+we're using shell redirection to put our source into the Kaleidoscope<br>
+compiler. In a usual front end you'd have an input file name and it would<br>
+go there.<br>
+<br>
+One last thing as part of emitting debug information via DIBuilder is that<br>
+we need to "finalize" the debug information. The reasons are part of the<br>
+underlying API for DIBuilder, but make sure you do this near the end of<br>
+main:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  DBuilder->finalize();<br>
+<br>
+before you dump out the module.<br>
+<br>
+Functions<br>
+=========<br>
+<br>
+Now that we have our ``Compile Unit`` and our source locations, we can add<br>
+function definitions to the debug info. So in ``PrototypeAST::codegen()`` we<br>
+add a few lines of code to describe a context for our subprogram, in this<br>
+case the "File", and the actual definition of the function itself.<br>
+<br>
+So the context:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(),<br>
+                                      KSDbgInfo.TheCU.getDirectory());<br>
+<br>
+giving us an DIFile and asking the ``Compile Unit`` we created above for the<br>
+directory and filename where we are currently. Then, for now, we use some<br>
+source locations of 0 (since our AST doesn't currently have source location<br>
+information) and construct our function definition:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  DIScope *FContext = Unit;<br>
+  unsigned LineNo = 0;<br>
+  unsigned ScopeLine = 0;<br>
+  DISubprogram *SP = DBuilder->createFunction(<br>
+      FContext, Name, StringRef(), Unit, LineNo,<br>
+      CreateFunctionType(Args.size(), Unit), false /* internal linkage */,<br>
+      true /* definition */, ScopeLine, DINode::FlagPrototyped, false);<br>
+  F->setSubprogram(SP);<br>
+<br>
+and we now have an DISubprogram that contains a reference to all of our<br>
+metadata for the function.<br>
+<br>
+Source Locations<br>
+================<br>
+<br>
+The most important thing for debug information is accurate source location -<br>
+this makes it possible to map your source code back. We have a problem though,<br>
+Kaleidoscope really doesn't have any source location information in the lexer<br>
+or parser so we'll need to add it.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+   struct SourceLocation {<br>
+     int Line;<br>
+     int Col;<br>
+   };<br>
+   static SourceLocation CurLoc;<br>
+   static SourceLocation LexLoc = {1, 0};<br>
+<br>
+   static int advance() {<br>
+     int LastChar = getchar();<br>
+<br>
+     if (LastChar == '\n' || LastChar == '\r') {<br>
+       LexLoc.Line++;<br>
+       LexLoc.Col = 0;<br>
+     } else<br>
+       LexLoc.Col++;<br>
+     return LastChar;<br>
+   }<br>
+<br>
+In this set of code we've added some functionality on how to keep track of the<br>
+line and column of the "source file". As we lex every token we set our current<br>
+current "lexical location" to the assorted line and column for the beginning<br>
+of the token. We do this by overriding all of the previous calls to<br>
+``getchar()`` with our new ``advance()`` that keeps track of the information<br>
+and then we have added to all of our AST classes a source location:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+   class ExprAST {<br>
+     SourceLocation Loc;<br>
+<br>
+     public:<br>
+       ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}<br>
+       virtual ~ExprAST() {}<br>
+       virtual Value* codegen() = 0;<br>
+       int getLine() const { return Loc.Line; }<br>
+       int getCol() const { return Loc.Col; }<br>
+       virtual raw_ostream &dump(raw_ostream &out, int ind) {<br>
+         return out << ':' << getLine() << ':' << getCol() << '\n';<br>
+       }<br>
+<br>
+that we pass down through when we create a new expression:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+   LHS = llvm::make_unique<BinaryExprAST>(BinLoc, BinOp, std::move(LHS),<br>
+                                          std::move(RHS));<br>
+<br>
+giving us locations for each of our expressions and variables.<br>
+<br>
+From this we can make sure to tell ``DIBuilder`` when we're at a new source<br>
+location so it can use that when we generate the rest of our code and make<br>
+sure that each instruction has source location information. We do this<br>
+by constructing another small function:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  void DebugInfo::emitLocation(ExprAST *AST) {<br>
+    DIScope *Scope;<br>
+    if (LexicalBlocks.empty())<br>
+      Scope = TheCU;<br>
+    else<br>
+      Scope = LexicalBlocks.back();<br>
+    Builder.SetCurrentDebugLocation(<br>
+        DebugLoc::get(AST->getLine(), AST->getCol(), Scope));<br>
+  }<br>
+<br>
+that both tells the main ``IRBuilder`` where we are, but also what scope<br>
+we're in. Since we've just created a function above we can either be in<br>
+the main file scope (like when we created our function), or now we can be<br>
+in the function scope we just created. To represent this we create a stack<br>
+of scopes:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+   std::vector<DIScope *> LexicalBlocks;<br>
+   std::map<const PrototypeAST *, DIScope *> FnScopeMap;<br>
+<br>
+and keep a map of each function to the scope that it represents (an<br>
+DISubprogram is also an DIScope).<br>
+<br>
+Then we make sure to:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+   KSDbgInfo.emitLocation(this);<br>
+<br>
+emit the location every time we start to generate code for a new AST, and<br>
+also:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  KSDbgInfo.FnScopeMap[this] = SP;<br>
+<br>
+store the scope (function) when we create it and use it:<br>
+<br>
+  KSDbgInfo.LexicalBlocks.push_back(&KSDbgInfo.FnScopeMap[Proto]);<br>
+<br>
+when we start generating the code for each function.<br>
+<br>
+also, don't forget to pop the scope back off of your scope stack at the<br>
+end of the code generation for the function:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  // Pop off the lexical block for the function since we added it<br>
+  // unconditionally.<br>
+  KSDbgInfo.LexicalBlocks.pop_back();<br>
+<br>
+Variables<br>
+=========<br>
+<br>
+Now that we have functions, we need to be able to print out the variables<br>
+we have in scope. Let's get our function arguments set up so we can get<br>
+decent backtraces and see how our functions are being called. It isn't<br>
+a lot of code, and we generally handle it when we're creating the<br>
+argument allocas in ``PrototypeAST::CreateArgumentAllocas``.<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  DIScope *Scope = KSDbgInfo.LexicalBlocks.back();<br>
+  DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(),<br>
+                                      KSDbgInfo.TheCU.getDirectory());<br>
+  DILocalVariable D = DBuilder->createParameterVariable(<br>
+      Scope, Args[Idx], Idx + 1, Unit, Line, KSDbgInfo.getDoubleTy(), true);<br>
+<br>
+  DBuilder->insertDeclare(Alloca, D, DBuilder->createExpression(),<br>
+                          DebugLoc::get(Line, 0, Scope),<br>
+                          Builder.GetInsertBlock());<br>
+<br>
+Here we're doing a few things. First, we're grabbing our current scope<br>
+for the variable so we can say what range of code our variable is valid<br>
+through. Second, we're creating the variable, giving it the scope,<br>
+the name, source location, type, and since it's an argument, the argument<br>
+index. Third, we create an ``lvm.dbg.declare`` call to indicate at the IR<br>
+level that we've got a variable in an alloca (and it gives a starting<br>
+location for the variable), and setting a source location for the<br>
+beginning of the scope on the declare.<br>
+<br>
+One interesting thing to note at this point is that various debuggers have<br>
+assumptions based on how code and debug information was generated for them<br>
+in the past. In this case we need to do a little bit of a hack to avoid<br>
+generating line information for the function prologue so that the debugger<br>
+knows to skip over those instructions when setting a breakpoint. So in<br>
+``FunctionAST::CodeGen`` we add a couple of lines:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  // Unset the location for the prologue emission (leading instructions with no<br>
+  // location in a function are considered part of the prologue and the debugger<br>
+  // will run past them when breaking on a function)<br>
+  KSDbgInfo.emitLocation(nullptr);<br>
+<br>
+and then emit a new location when we actually start generating code for the<br>
+body of the function:<br>
+<br>
+.. code-block:: c++<br>
+<br>
+  KSDbgInfo.emitLocation(Body);<br>
+<br>
+With this we have enough debug information to set breakpoints in functions,<br>
+print out argument variables, and call functions. Not too bad for just a<br>
+few simple lines of code!<br>
+<br>
+Full Code Listing<br>
+=================<br>
+<br>
+Here is the complete code listing for our running example, enhanced with<br>
+debug information. To build this example, use:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+    # Compile<br>
+    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
+    # Run<br>
+    ./toy<br>
+<br>
+Here is the code:<br>
+<br>
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter9/toy.cpp<br>
+   :language: c++<br>
+<br>
+`Next: Conclusion and other useful LLVM tidbits <LangImpl10.html>`_<br>
+<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl1.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl1.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl1.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl1.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl1.rst (removed)<br>
@@ -1,290 +0,0 @@<br>
-=================================================<br>
-Kaleidoscope: Tutorial Introduction and the Lexer<br>
-=================================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Tutorial Introduction<br>
-=====================<br>
-<br>
-Welcome to the "Implementing a language with LLVM" tutorial. This<br>
-tutorial runs through the implementation of a simple language, showing<br>
-how fun and easy it can be. This tutorial will get you up and started as<br>
-well as help to build a framework you can extend to other languages. The<br>
-code in this tutorial can also be used as a playground to hack on other<br>
-LLVM specific things.<br>
-<br>
-The goal of this tutorial is to progressively unveil our language,<br>
-describing how it is built up over time. This will let us cover a fairly<br>
-broad range of language design and LLVM-specific usage issues, showing<br>
-and explaining the code for it all along the way, without overwhelming<br>
-you with tons of details up front.<br>
-<br>
-It is useful to point out ahead of time that this tutorial is really<br>
-about teaching compiler techniques and LLVM specifically, *not* about<br>
-teaching modern and sane software engineering principles. In practice,<br>
-this means that we'll take a number of shortcuts to simplify the<br>
-exposition. For example, the code uses global variables<br>
-all over the place, doesn't use nice design patterns like<br>
-`visitors <<a href="http://en.wikipedia.org/wiki/Visitor_pattern" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Visitor_pattern</a>>`_, etc... but<br>
-it is very simple. If you dig in and use the code as a basis for future<br>
-projects, fixing these deficiencies shouldn't be hard.<br>
-<br>
-I've tried to put this tutorial together in a way that makes chapters<br>
-easy to skip over if you are already familiar with or are uninterested<br>
-in the various pieces. The structure of the tutorial is:<br>
-<br>
--  `Chapter #1 <#language>`_: Introduction to the Kaleidoscope<br>
-   language, and the definition of its Lexer - This shows where we are<br>
-   going and the basic functionality that we want it to do. In order to<br>
-   make this tutorial maximally understandable and hackable, we choose<br>
-   to implement everything in C++ instead of using lexer and parser<br>
-   generators. LLVM obviously works just fine with such tools, feel free<br>
-   to use one if you prefer.<br>
--  `Chapter #2 <LangImpl2.html>`_: Implementing a Parser and AST -<br>
-   With the lexer in place, we can talk about parsing techniques and<br>
-   basic AST construction. This tutorial describes recursive descent<br>
-   parsing and operator precedence parsing. Nothing in Chapters 1 or 2<br>
-   is LLVM-specific, the code doesn't even link in LLVM at this point.<br>
-   :)<br>
--  `Chapter #3 <LangImpl3.html>`_: Code generation to LLVM IR - With<br>
-   the AST ready, we can show off how easy generation of LLVM IR really<br>
-   is.<br>
--  `Chapter #4 <LangImpl4.html>`_: Adding JIT and Optimizer Support<br>
-   - Because a lot of people are interested in using LLVM as a JIT,<br>
-   we'll dive right into it and show you the 3 lines it takes to add JIT<br>
-   support. LLVM is also useful in many other ways, but this is one<br>
-   simple and "sexy" way to show off its power. :)<br>
--  `Chapter #5 <LangImpl5.html>`_: Extending the Language: Control<br>
-   Flow - With the language up and running, we show how to extend it<br>
-   with control flow operations (if/then/else and a 'for' loop). This<br>
-   gives us a chance to talk about simple SSA construction and control<br>
-   flow.<br>
--  `Chapter #6 <LangImpl6.html>`_: Extending the Language:<br>
-   User-defined Operators - This is a silly but fun chapter that talks<br>
-   about extending the language to let the user program define their own<br>
-   arbitrary unary and binary operators (with assignable precedence!).<br>
-   This lets us build a significant piece of the "language" as library<br>
-   routines.<br>
--  `Chapter #7 <LangImpl7.html>`_: Extending the Language: Mutable<br>
-   Variables - This chapter talks about adding user-defined local<br>
-   variables along with an assignment operator. The interesting part<br>
-   about this is how easy and trivial it is to construct SSA form in<br>
-   LLVM: no, LLVM does *not* require your front-end to construct SSA<br>
-   form!<br>
--  `Chapter #8 <LangImpl8.html>`_: Extending the Language: Debug<br>
-   Information - Having built a decent little programming language with<br>
-   control flow, functions and mutable variables, we consider what it<br>
-   takes to add debug information to standalone executables. This debug<br>
-   information will allow you to set breakpoints in Kaleidoscope<br>
-   functions, print out argument variables, and call functions - all<br>
-   from within the debugger!<br>
--  `Chapter #9 <LangImpl9.html>`_: Conclusion and other useful LLVM<br>
-   tidbits - This chapter wraps up the series by talking about<br>
-   potential ways to extend the language, but also includes a bunch of<br>
-   pointers to info about "special topics" like adding garbage<br>
-   collection support, exceptions, debugging, support for "spaghetti<br>
-   stacks", and a bunch of other tips and tricks.<br>
-<br>
-By the end of the tutorial, we'll have written a bit less than 1000 lines<br>
-of non-comment, non-blank, lines of code. With this small amount of<br>
-code, we'll have built up a very reasonable compiler for a non-trivial<br>
-language including a hand-written lexer, parser, AST, as well as code<br>
-generation support with a JIT compiler. While other systems may have<br>
-interesting "hello world" tutorials, I think the breadth of this<br>
-tutorial is a great testament to the strengths of LLVM and why you<br>
-should consider it if you're interested in language or compiler design.<br>
-<br>
-A note about this tutorial: we expect you to extend the language and<br>
-play with it on your own. Take the code and go crazy hacking away at it,<br>
-compilers don't need to be scary creatures - it can be a lot of fun to<br>
-play with languages!<br>
-<br>
-The Basic Language<br>
-==================<br>
-<br>
-This tutorial will be illustrated with a toy language that we'll call<br>
-"`Kaleidoscope <<a href="http://en.wikipedia.org/wiki/Kaleidoscope" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Kaleidoscope</a>>`_" (derived<br>
-from "meaning beautiful, form, and view"). Kaleidoscope is a procedural<br>
-language that allows you to define functions, use conditionals, math,<br>
-etc. Over the course of the tutorial, we'll extend Kaleidoscope to<br>
-support the if/then/else construct, a for loop, user defined operators,<br>
-JIT compilation with a simple command line interface, etc.<br>
-<br>
-Because we want to keep things simple, the only datatype in Kaleidoscope<br>
-is a 64-bit floating point type (aka 'double' in C parlance). As such,<br>
-all values are implicitly double precision and the language doesn't<br>
-require type declarations. This gives the language a very nice and<br>
-simple syntax. For example, the following simple example computes<br>
-`Fibonacci numbers: <<a href="http://en.wikipedia.org/wiki/Fibonacci_number" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Fibonacci_number</a>>`_<br>
-<br>
-::<br>
-<br>
-    # Compute the x'th fibonacci number.<br>
-    def fib(x)<br>
-      if x < 3 then<br>
-        1<br>
-      else<br>
-        fib(x-1)+fib(x-2)<br>
-<br>
-    # This expression will compute the 40th number.<br>
-    fib(40)<br>
-<br>
-We also allow Kaleidoscope to call into standard library functions (the<br>
-LLVM JIT makes this completely trivial). This means that you can use the<br>
-'extern' keyword to define a function before you use it (this is also<br>
-useful for mutually recursive functions). For example:<br>
-<br>
-::<br>
-<br>
-    extern sin(arg);<br>
-    extern cos(arg);<br>
-    extern atan2(arg1 arg2);<br>
-<br>
-    atan2(sin(.4), cos(42))<br>
-<br>
-A more interesting example is included in Chapter 6 where we write a<br>
-little Kaleidoscope application that `displays a Mandelbrot<br>
-Set <LangImpl6.html#kicking-the-tires>`_ at various levels of magnification.<br>
-<br>
-Lets dive into the implementation of this language!<br>
-<br>
-The Lexer<br>
-=========<br>
-<br>
-When it comes to implementing a language, the first thing needed is the<br>
-ability to process a text file and recognize what it says. The<br>
-traditional way to do this is to use a<br>
-"`lexer <<a href="http://en.wikipedia.org/wiki/Lexical_analysis" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Lexical_analysis</a>>`_" (aka<br>
-'scanner') to break the input up into "tokens". Each token returned by<br>
-the lexer includes a token code and potentially some metadata (e.g. the<br>
-numeric value of a number). First, we define the possibilities:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    // The lexer returns tokens [0-255] if it is an unknown character, otherwise one<br>
-    // of these for known things.<br>
-    enum Token {<br>
-      tok_eof = -1,<br>
-<br>
-      // commands<br>
-      tok_def = -2,<br>
-      tok_extern = -3,<br>
-<br>
-      // primary<br>
-      tok_identifier = -4,<br>
-      tok_number = -5,<br>
-    };<br>
-<br>
-    static std::string IdentifierStr; // Filled in if tok_identifier<br>
-    static double NumVal;             // Filled in if tok_number<br>
-<br>
-Each token returned by our lexer will either be one of the Token enum<br>
-values or it will be an 'unknown' character like '+', which is returned<br>
-as its ASCII value. If the current token is an identifier, the<br>
-``IdentifierStr`` global variable holds the name of the identifier. If<br>
-the current token is a numeric literal (like 1.0), ``NumVal`` holds its<br>
-value. Note that we use global variables for simplicity, this is not the<br>
-best choice for a real language implementation :).<br>
-<br>
-The actual implementation of the lexer is a single function named<br>
-``gettok``. The ``gettok`` function is called to return the next token<br>
-from standard input. Its definition starts as:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// gettok - Return the next token from standard input.<br>
-    static int gettok() {<br>
-      static int LastChar = ' ';<br>
-<br>
-      // Skip any whitespace.<br>
-      while (isspace(LastChar))<br>
-        LastChar = getchar();<br>
-<br>
-``gettok`` works by calling the C ``getchar()`` function to read<br>
-characters one at a time from standard input. It eats them as it<br>
-recognizes them and stores the last character read, but not processed,<br>
-in LastChar. The first thing that it has to do is ignore whitespace<br>
-between tokens. This is accomplished with the loop above.<br>
-<br>
-The next thing ``gettok`` needs to do is recognize identifiers and<br>
-specific keywords like "def". Kaleidoscope does this with this simple<br>
-loop:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*<br>
-        IdentifierStr = LastChar;<br>
-        while (isalnum((LastChar = getchar())))<br>
-          IdentifierStr += LastChar;<br>
-<br>
-        if (IdentifierStr == "def")<br>
-          return tok_def;<br>
-        if (IdentifierStr == "extern")<br>
-          return tok_extern;<br>
-        return tok_identifier;<br>
-      }<br>
-<br>
-Note that this code sets the '``IdentifierStr``' global whenever it<br>
-lexes an identifier. Also, since language keywords are matched by the<br>
-same loop, we handle them here inline. Numeric values are similar:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+<br>
-        std::string NumStr;<br>
-        do {<br>
-          NumStr += LastChar;<br>
-          LastChar = getchar();<br>
-        } while (isdigit(LastChar) || LastChar == '.');<br>
-<br>
-        NumVal = strtod(NumStr.c_str(), 0);<br>
-        return tok_number;<br>
-      }<br>
-<br>
-This is all pretty straight-forward code for processing input. When<br>
-reading a numeric value from input, we use the C ``strtod`` function to<br>
-convert it to a numeric value that we store in ``NumVal``. Note that<br>
-this isn't doing sufficient error checking: it will incorrectly read<br>
-"1.23.45.67" and handle it as if you typed in "1.23". Feel free to<br>
-extend it :). Next we handle comments:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      if (LastChar == '#') {<br>
-        // Comment until end of line.<br>
-        do<br>
-          LastChar = getchar();<br>
-        while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');<br>
-<br>
-        if (LastChar != EOF)<br>
-          return gettok();<br>
-      }<br>
-<br>
-We handle comments by skipping to the end of the line and then return<br>
-the next token. Finally, if the input doesn't match one of the above<br>
-cases, it is either an operator character like '+' or the end of the<br>
-file. These are handled with this code:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Check for end of file.  Don't eat the EOF.<br>
-      if (LastChar == EOF)<br>
-        return tok_eof;<br>
-<br>
-      // Otherwise, just return the character as its ascii value.<br>
-      int ThisChar = LastChar;<br>
-      LastChar = getchar();<br>
-      return ThisChar;<br>
-    }<br>
-<br>
-With this, we have the complete lexer for the basic Kaleidoscope<br>
-language (the `full code listing <LangImpl2.html#full-code-listing>`_ for the Lexer<br>
-is available in the `next chapter <LangImpl2.html>`_ of the tutorial).<br>
-Next we'll `build a simple parser that uses this to build an Abstract<br>
-Syntax Tree <LangImpl2.html>`_. When we have that, we'll include a<br>
-driver so that you can use the lexer and parser together.<br>
-<br>
-`Next: Implementing a Parser and AST <LangImpl2.html>`_<br>
-<br>
<br>
Added: llvm/trunk/docs/tutorial/LangImpl10.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl10.rst?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl10.rst?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl10.rst (added)<br>
+++ llvm/trunk/docs/tutorial/LangImpl10.rst Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,259 @@<br>
+======================================================<br>
+Kaleidoscope: Conclusion and other useful LLVM tidbits<br>
+======================================================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Tutorial Conclusion<br>
+===================<br>
+<br>
+Welcome to the final chapter of the "`Implementing a language with<br>
+LLVM <index.html>`_" tutorial. In the course of this tutorial, we have<br>
+grown our little Kaleidoscope language from being a useless toy, to<br>
+being a semi-interesting (but probably still useless) toy. :)<br>
+<br>
+It is interesting to see how far we've come, and how little code it has<br>
+taken. We built the entire lexer, parser, AST, code generator, an<br>
+interactive run-loop (with a JIT!), and emitted debug information in<br>
+standalone executables - all in under 1000 lines of (non-comment/non-blank)<br>
+code.<br>
+<br>
+Our little language supports a couple of interesting features: it<br>
+supports user defined binary and unary operators, it uses JIT<br>
+compilation for immediate evaluation, and it supports a few control flow<br>
+constructs with SSA construction.<br>
+<br>
+Part of the idea of this tutorial was to show you how easy and fun it<br>
+can be to define, build, and play with languages. Building a compiler<br>
+need not be a scary or mystical process! Now that you've seen some of<br>
+the basics, I strongly encourage you to take the code and hack on it.<br>
+For example, try adding:<br>
+<br>
+-  **global variables** - While global variables have questional value<br>
+   in modern software engineering, they are often useful when putting<br>
+   together quick little hacks like the Kaleidoscope compiler itself.<br>
+   Fortunately, our current setup makes it very easy to add global<br>
+   variables: just have value lookup check to see if an unresolved<br>
+   variable is in the global variable symbol table before rejecting it.<br>
+   To create a new global variable, make an instance of the LLVM<br>
+   ``GlobalVariable`` class.<br>
+-  **typed variables** - Kaleidoscope currently only supports variables<br>
+   of type double. This gives the language a very nice elegance, because<br>
+   only supporting one type means that you never have to specify types.<br>
+   Different languages have different ways of handling this. The easiest<br>
+   way is to require the user to specify types for every variable<br>
+   definition, and record the type of the variable in the symbol table<br>
+   along with its Value\*.<br>
+-  **arrays, structs, vectors, etc** - Once you add types, you can start<br>
+   extending the type system in all sorts of interesting ways. Simple<br>
+   arrays are very easy and are quite useful for many different<br>
+   applications. Adding them is mostly an exercise in learning how the<br>
+   LLVM `getelementptr <../LangRef.html#getelementptr-instruction>`_ instruction<br>
+   works: it is so nifty/unconventional, it `has its own<br>
+   FAQ <../GetElementPtr.html>`_!<br>
+-  **standard runtime** - Our current language allows the user to access<br>
+   arbitrary external functions, and we use it for things like "printd"<br>
+   and "putchard". As you extend the language to add higher-level<br>
+   constructs, often these constructs make the most sense if they are<br>
+   lowered to calls into a language-supplied runtime. For example, if<br>
+   you add hash tables to the language, it would probably make sense to<br>
+   add the routines to a runtime, instead of inlining them all the way.<br>
+-  **memory management** - Currently we can only access the stack in<br>
+   Kaleidoscope. It would also be useful to be able to allocate heap<br>
+   memory, either with calls to the standard libc malloc/free interface<br>
+   or with a garbage collector. If you would like to use garbage<br>
+   collection, note that LLVM fully supports `Accurate Garbage<br>
+   Collection <../GarbageCollection.html>`_ including algorithms that<br>
+   move objects and need to scan/update the stack.<br>
+-  **exception handling support** - LLVM supports generation of `zero<br>
+   cost exceptions <../ExceptionHandling.html>`_ which interoperate with<br>
+   code compiled in other languages. You could also generate code by<br>
+   implicitly making every function return an error value and checking<br>
+   it. You could also make explicit use of setjmp/longjmp. There are<br>
+   many different ways to go here.<br>
+-  **object orientation, generics, database access, complex numbers,<br>
+   geometric programming, ...** - Really, there is no end of crazy<br>
+   features that you can add to the language.<br>
+-  **unusual domains** - We've been talking about applying LLVM to a<br>
+   domain that many people are interested in: building a compiler for a<br>
+   specific language. However, there are many other domains that can use<br>
+   compiler technology that are not typically considered. For example,<br>
+   LLVM has been used to implement OpenGL graphics acceleration,<br>
+   translate C++ code to ActionScript, and many other cute and clever<br>
+   things. Maybe you will be the first to JIT compile a regular<br>
+   expression interpreter into native code with LLVM?<br>
+<br>
+Have fun - try doing something crazy and unusual. Building a language<br>
+like everyone else always has, is much less fun than trying something a<br>
+little crazy or off the wall and seeing how it turns out. If you get<br>
+stuck or want to talk about it, feel free to email the `llvm-dev mailing<br>
+list <<a href="http://lists.llvm.org/mailman/listinfo/llvm-dev" rel="noreferrer" target="_blank">http://lists.llvm.org/mailman/listinfo/llvm-dev</a>>`_: it has lots<br>
+of people who are interested in languages and are often willing to help<br>
+out.<br>
+<br>
+Before we end this tutorial, I want to talk about some "tips and tricks"<br>
+for generating LLVM IR. These are some of the more subtle things that<br>
+may not be obvious, but are very useful if you want to take advantage of<br>
+LLVM's capabilities.<br>
+<br>
+Properties of the LLVM IR<br>
+=========================<br>
+<br>
+We have a couple of common questions about code in the LLVM IR form -<br>
+let's just get these out of the way right now, shall we?<br>
+<br>
+Target Independence<br>
+-------------------<br>
+<br>
+Kaleidoscope is an example of a "portable language": any program written<br>
+in Kaleidoscope will work the same way on any target that it runs on.<br>
+Many other languages have this property, e.g. lisp, java, haskell,<br>
+javascript, python, etc (note that while these languages are portable,<br>
+not all their libraries are).<br>
+<br>
+One nice aspect of LLVM is that it is often capable of preserving target<br>
+independence in the IR: you can take the LLVM IR for a<br>
+Kaleidoscope-compiled program and run it on any target that LLVM<br>
+supports, even emitting C code and compiling that on targets that LLVM<br>
+doesn't support natively. You can trivially tell that the Kaleidoscope<br>
+compiler generates target-independent code because it never queries for<br>
+any target-specific information when generating code.<br>
+<br>
+The fact that LLVM provides a compact, target-independent,<br>
+representation for code gets a lot of people excited. Unfortunately,<br>
+these people are usually thinking about C or a language from the C<br>
+family when they are asking questions about language portability. I say<br>
+"unfortunately", because there is really no way to make (fully general)<br>
+C code portable, other than shipping the source code around (and of<br>
+course, C source code is not actually portable in general either - ever<br>
+port a really old application from 32- to 64-bits?).<br>
+<br>
+The problem with C (again, in its full generality) is that it is heavily<br>
+laden with target specific assumptions. As one simple example, the<br>
+preprocessor often destructively removes target-independence from the<br>
+code when it processes the input text:<br>
+<br>
+.. code-block:: c<br>
+<br>
+    #ifdef __i386__<br>
+      int X = 1;<br>
+    #else<br>
+      int X = 42;<br>
+    #endif<br>
+<br>
+While it is possible to engineer more and more complex solutions to<br>
+problems like this, it cannot be solved in full generality in a way that<br>
+is better than shipping the actual source code.<br>
+<br>
+That said, there are interesting subsets of C that can be made portable.<br>
+If you are willing to fix primitive types to a fixed size (say int =<br>
+32-bits, and long = 64-bits), don't care about ABI compatibility with<br>
+existing binaries, and are willing to give up some other minor features,<br>
+you can have portable code. This can make sense for specialized domains<br>
+such as an in-kernel language.<br>
+<br>
+Safety Guarantees<br>
+-----------------<br>
+<br>
+Many of the languages above are also "safe" languages: it is impossible<br>
+for a program written in Java to corrupt its address space and crash the<br>
+process (assuming the JVM has no bugs). Safety is an interesting<br>
+property that requires a combination of language design, runtime<br>
+support, and often operating system support.<br>
+<br>
+It is certainly possible to implement a safe language in LLVM, but LLVM<br>
+IR does not itself guarantee safety. The LLVM IR allows unsafe pointer<br>
+casts, use after free bugs, buffer over-runs, and a variety of other<br>
+problems. Safety needs to be implemented as a layer on top of LLVM and,<br>
+conveniently, several groups have investigated this. Ask on the `llvm-dev<br>
+mailing list <<a href="http://lists.llvm.org/mailman/listinfo/llvm-dev" rel="noreferrer" target="_blank">http://lists.llvm.org/mailman/listinfo/llvm-dev</a>>`_ if<br>
+you are interested in more details.<br>
+<br>
+Language-Specific Optimizations<br>
+-------------------------------<br>
+<br>
+One thing about LLVM that turns off many people is that it does not<br>
+solve all the world's problems in one system (sorry 'world hunger',<br>
+someone else will have to solve you some other day). One specific<br>
+complaint is that people perceive LLVM as being incapable of performing<br>
+high-level language-specific optimization: LLVM "loses too much<br>
+information".<br>
+<br>
+Unfortunately, this is really not the place to give you a full and<br>
+unified version of "Chris Lattner's theory of compiler design". Instead,<br>
+I'll make a few observations:<br>
+<br>
+First, you're right that LLVM does lose information. For example, as of<br>
+this writing, there is no way to distinguish in the LLVM IR whether an<br>
+SSA-value came from a C "int" or a C "long" on an ILP32 machine (other<br>
+than debug info). Both get compiled down to an 'i32' value and the<br>
+information about what it came from is lost. The more general issue<br>
+here, is that the LLVM type system uses "structural equivalence" instead<br>
+of "name equivalence". Another place this surprises people is if you<br>
+have two types in a high-level language that have the same structure<br>
+(e.g. two different structs that have a single int field): these types<br>
+will compile down into a single LLVM type and it will be impossible to<br>
+tell what it came from.<br>
+<br>
+Second, while LLVM does lose information, LLVM is not a fixed target: we<br>
+continue to enhance and improve it in many different ways. In addition<br>
+to adding new features (LLVM did not always support exceptions or debug<br>
+info), we also extend the IR to capture important information for<br>
+optimization (e.g. whether an argument is sign or zero extended,<br>
+information about pointers aliasing, etc). Many of the enhancements are<br>
+user-driven: people want LLVM to include some specific feature, so they<br>
+go ahead and extend it.<br>
+<br>
+Third, it is *possible and easy* to add language-specific optimizations,<br>
+and you have a number of choices in how to do it. As one trivial<br>
+example, it is easy to add language-specific optimization passes that<br>
+"know" things about code compiled for a language. In the case of the C<br>
+family, there is an optimization pass that "knows" about the standard C<br>
+library functions. If you call "exit(0)" in main(), it knows that it is<br>
+safe to optimize that into "return 0;" because C specifies what the<br>
+'exit' function does.<br>
+<br>
+In addition to simple library knowledge, it is possible to embed a<br>
+variety of other language-specific information into the LLVM IR. If you<br>
+have a specific need and run into a wall, please bring the topic up on<br>
+the llvm-dev list. At the very worst, you can always treat LLVM as if it<br>
+were a "dumb code generator" and implement the high-level optimizations<br>
+you desire in your front-end, on the language-specific AST.<br>
+<br>
+Tips and Tricks<br>
+===============<br>
+<br>
+There is a variety of useful tips and tricks that you come to know after<br>
+working on/with LLVM that aren't obvious at first glance. Instead of<br>
+letting everyone rediscover them, this section talks about some of these<br>
+issues.<br>
+<br>
+Implementing portable offsetof/sizeof<br>
+-------------------------------------<br>
+<br>
+One interesting thing that comes up, if you are trying to keep the code<br>
+generated by your compiler "target independent", is that you often need<br>
+to know the size of some LLVM type or the offset of some field in an<br>
+llvm structure. For example, you might need to pass the size of a type<br>
+into a function that allocates memory.<br>
+<br>
+Unfortunately, this can vary widely across targets: for example the<br>
+width of a pointer is trivially target-specific. However, there is a<br>
+`clever way to use the getelementptr<br>
+instruction <<a href="http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt" rel="noreferrer" target="_blank">http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt</a>>`_<br>
+that allows you to compute this in a portable way.<br>
+<br>
+Garbage Collected Stack Frames<br>
+------------------------------<br>
+<br>
+Some languages want to explicitly manage their stack frames, often so<br>
+that they are garbage collected or to allow easy implementation of<br>
+closures. There are often better ways to implement these features than<br>
+explicit stack frames, but `LLVM does support<br>
+them, <<a href="http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt" rel="noreferrer" target="_blank">http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt</a>>`_<br>
+if you want. It requires your front-end to convert the code into<br>
+`Continuation Passing<br>
+Style <<a href="http://en.wikipedia.org/wiki/Continuation-passing_style" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Continuation-passing_style</a>>`_ and<br>
+the use of tail calls (which LLVM also supports).<br>
+<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl2.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl2.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl2.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl2.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl2.rst (removed)<br>
@@ -1,735 +0,0 @@<br>
-===========================================<br>
-Kaleidoscope: Implementing a Parser and AST<br>
-===========================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Chapter 2 Introduction<br>
-======================<br>
-<br>
-Welcome to Chapter 2 of the "`Implementing a language with<br>
-LLVM <index.html>`_" tutorial. This chapter shows you how to use the<br>
-lexer, built in `Chapter 1 <LangImpl1.html>`_, to build a full<br>
-`parser <<a href="http://en.wikipedia.org/wiki/Parsing" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Parsing</a>>`_ for our Kaleidoscope<br>
-language. Once we have a parser, we'll define and build an `Abstract<br>
-Syntax Tree <<a href="http://en.wikipedia.org/wiki/Abstract_syntax_tree" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Abstract_syntax_tree</a>>`_ (AST).<br>
-<br>
-The parser we will build uses a combination of `Recursive Descent<br>
-Parsing <<a href="http://en.wikipedia.org/wiki/Recursive_descent_parser" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Recursive_descent_parser</a>>`_ and<br>
-`Operator-Precedence<br>
-Parsing <<a href="http://en.wikipedia.org/wiki/Operator-precedence_parser" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Operator-precedence_parser</a>>`_ to<br>
-parse the Kaleidoscope language (the latter for binary expressions and<br>
-the former for everything else). Before we get to parsing though, lets<br>
-talk about the output of the parser: the Abstract Syntax Tree.<br>
-<br>
-The Abstract Syntax Tree (AST)<br>
-==============================<br>
-<br>
-The AST for a program captures its behavior in such a way that it is<br>
-easy for later stages of the compiler (e.g. code generation) to<br>
-interpret. We basically want one object for each construct in the<br>
-language, and the AST should closely model the language. In<br>
-Kaleidoscope, we have expressions, a prototype, and a function object.<br>
-We'll start with expressions first:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// ExprAST - Base class for all expression nodes.<br>
-    class ExprAST {<br>
-    public:<br>
-      virtual ~ExprAST() {}<br>
-    };<br>
-<br>
-    /// NumberExprAST - Expression class for numeric literals like "1.0".<br>
-    class NumberExprAST : public ExprAST {<br>
-      double Val;<br>
-<br>
-    public:<br>
-      NumberExprAST(double Val) : Val(Val) {}<br>
-    };<br>
-<br>
-The code above shows the definition of the base ExprAST class and one<br>
-subclass which we use for numeric literals. The important thing to note<br>
-about this code is that the NumberExprAST class captures the numeric<br>
-value of the literal as an instance variable. This allows later phases<br>
-of the compiler to know what the stored numeric value is.<br>
-<br>
-Right now we only create the AST, so there are no useful accessor<br>
-methods on them. It would be very easy to add a virtual method to pretty<br>
-print the code, for example. Here are the other expression AST node<br>
-definitions that we'll use in the basic form of the Kaleidoscope<br>
-language:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// VariableExprAST - Expression class for referencing a variable, like "a".<br>
-    class VariableExprAST : public ExprAST {<br>
-      std::string Name;<br>
-<br>
-    public:<br>
-      VariableExprAST(const std::string &Name) : Name(Name) {}<br>
-    };<br>
-<br>
-    /// BinaryExprAST - Expression class for a binary operator.<br>
-    class BinaryExprAST : public ExprAST {<br>
-      char Op;<br>
-      std::unique_ptr<ExprAST> LHS, RHS;<br>
-<br>
-    public:<br>
-      BinaryExprAST(char op, std::unique_ptr<ExprAST> LHS,<br>
-                    std::unique_ptr<ExprAST> RHS)<br>
-        : Op(op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}<br>
-    };<br>
-<br>
-    /// CallExprAST - Expression class for function calls.<br>
-    class CallExprAST : public ExprAST {<br>
-      std::string Callee;<br>
-      std::vector<std::unique_ptr<ExprAST>> Args;<br>
-<br>
-    public:<br>
-      CallExprAST(const std::string &Callee,<br>
-                  std::vector<std::unique_ptr<ExprAST>> Args)<br>
-        : Callee(Callee), Args(std::move(Args)) {}<br>
-    };<br>
-<br>
-This is all (intentionally) rather straight-forward: variables capture<br>
-the variable name, binary operators capture their opcode (e.g. '+'), and<br>
-calls capture a function name as well as a list of any argument<br>
-expressions. One thing that is nice about our AST is that it captures<br>
-the language features without talking about the syntax of the language.<br>
-Note that there is no discussion about precedence of binary operators,<br>
-lexical structure, etc.<br>
-<br>
-For our basic language, these are all of the expression nodes we'll<br>
-define. Because it doesn't have conditional control flow, it isn't<br>
-Turing-complete; we'll fix that in a later installment. The two things<br>
-we need next are a way to talk about the interface to a function, and a<br>
-way to talk about functions themselves:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// PrototypeAST - This class represents the "prototype" for a function,<br>
-    /// which captures its name, and its argument names (thus implicitly the number<br>
-    /// of arguments the function takes).<br>
-    class PrototypeAST {<br>
-      std::string Name;<br>
-      std::vector<std::string> Args;<br>
-<br>
-    public:<br>
-      PrototypeAST(const std::string &name, std::vector<std::string> Args)<br>
-        : Name(name), Args(std::move(Args)) {}<br>
-    };<br>
-<br>
-    /// FunctionAST - This class represents a function definition itself.<br>
-    class FunctionAST {<br>
-      std::unique_ptr<PrototypeAST> Proto;<br>
-      std::unique_ptr<ExprAST> Body;<br>
-<br>
-    public:<br>
-      FunctionAST(std::unique_ptr<PrototypeAST> Proto,<br>
-                  std::unique_ptr<ExprAST> Body)<br>
-        : Proto(std::move(Proto)), Body(std::move(Body)) {}<br>
-    };<br>
-<br>
-In Kaleidoscope, functions are typed with just a count of their<br>
-arguments. Since all values are double precision floating point, the<br>
-type of each argument doesn't need to be stored anywhere. In a more<br>
-aggressive and realistic language, the "ExprAST" class would probably<br>
-have a type field.<br>
-<br>
-With this scaffolding, we can now talk about parsing expressions and<br>
-function bodies in Kaleidoscope.<br>
-<br>
-Parser Basics<br>
-=============<br>
-<br>
-Now that we have an AST to build, we need to define the parser code to<br>
-build it. The idea here is that we want to parse something like "x+y"<br>
-(which is returned as three tokens by the lexer) into an AST that could<br>
-be generated with calls like this:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      auto LHS = llvm::make_unique<VariableExprAST>("x");<br>
-      auto RHS = llvm::make_unique<VariableExprAST>("y");<br>
-      auto Result = std::make_unique<BinaryExprAST>('+', std::move(LHS),<br>
-                                                    std::move(RHS));<br>
-<br>
-In order to do this, we'll start by defining some basic helper routines:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current<br>
-    /// token the parser is looking at.  getNextToken reads another token from the<br>
-    /// lexer and updates CurTok with its results.<br>
-    static int CurTok;<br>
-    static int getNextToken() {<br>
-      return CurTok = gettok();<br>
-    }<br>
-<br>
-This implements a simple token buffer around the lexer. This allows us<br>
-to look one token ahead at what the lexer is returning. Every function<br>
-in our parser will assume that CurTok is the current token that needs to<br>
-be parsed.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-<br>
-    /// LogError* - These are little helper functions for error handling.<br>
-    std::unique_ptr<ExprAST> LogError(const char *Str) {<br>
-      fprintf(stderr, "LogError: %s\n", Str);<br>
-      return nullptr;<br>
-    }<br>
-    std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {<br>
-      LogError(Str);<br>
-      return nullptr;<br>
-    }<br>
-<br>
-The ``LogError`` routines are simple helper routines that our parser will<br>
-use to handle errors. The error recovery in our parser will not be the<br>
-best and is not particular user-friendly, but it will be enough for our<br>
-tutorial. These routines make it easier to handle errors in routines<br>
-that have various return types: they always return null.<br>
-<br>
-With these basic helper functions, we can implement the first piece of<br>
-our grammar: numeric literals.<br>
-<br>
-Basic Expression Parsing<br>
-========================<br>
-<br>
-We start with numeric literals, because they are the simplest to<br>
-process. For each production in our grammar, we'll define a function<br>
-which parses that production. For numeric literals, we have:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// numberexpr ::= number<br>
-    static std::unique_ptr<ExprAST> ParseNumberExpr() {<br>
-      auto Result = llvm::make_unique<NumberExprAST>(NumVal);<br>
-      getNextToken(); // consume the number<br>
-      return std::move(Result);<br>
-    }<br>
-<br>
-This routine is very simple: it expects to be called when the current<br>
-token is a ``tok_number`` token. It takes the current number value,<br>
-creates a ``NumberExprAST`` node, advances the lexer to the next token,<br>
-and finally returns.<br>
-<br>
-There are some interesting aspects to this. The most important one is<br>
-that this routine eats all of the tokens that correspond to the<br>
-production and returns the lexer buffer with the next token (which is<br>
-not part of the grammar production) ready to go. This is a fairly<br>
-standard way to go for recursive descent parsers. For a better example,<br>
-the parenthesis operator is defined like this:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// parenexpr ::= '(' expression ')'<br>
-    static std::unique_ptr<ExprAST> ParseParenExpr() {<br>
-      getNextToken(); // eat (.<br>
-      auto V = ParseExpression();<br>
-      if (!V)<br>
-        return nullptr;<br>
-<br>
-      if (CurTok != ')')<br>
-        return LogError("expected ')'");<br>
-      getNextToken(); // eat ).<br>
-      return V;<br>
-    }<br>
-<br>
-This function illustrates a number of interesting things about the<br>
-parser:<br>
-<br>
-1) It shows how we use the LogError routines. When called, this function<br>
-expects that the current token is a '(' token, but after parsing the<br>
-subexpression, it is possible that there is no ')' waiting. For example,<br>
-if the user types in "(4 x" instead of "(4)", the parser should emit an<br>
-error. Because errors can occur, the parser needs a way to indicate that<br>
-they happened: in our parser, we return null on an error.<br>
-<br>
-2) Another interesting aspect of this function is that it uses recursion<br>
-by calling ``ParseExpression`` (we will soon see that<br>
-``ParseExpression`` can call ``ParseParenExpr``). This is powerful<br>
-because it allows us to handle recursive grammars, and keeps each<br>
-production very simple. Note that parentheses do not cause construction<br>
-of AST nodes themselves. While we could do it this way, the most<br>
-important role of parentheses are to guide the parser and provide<br>
-grouping. Once the parser constructs the AST, parentheses are not<br>
-needed.<br>
-<br>
-The next simple production is for handling variable references and<br>
-function calls:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// identifierexpr<br>
-    ///   ::= identifier<br>
-    ///   ::= identifier '(' expression* ')'<br>
-    static std::unique_ptr<ExprAST> ParseIdentifierExpr() {<br>
-      std::string IdName = IdentifierStr;<br>
-<br>
-      getNextToken();  // eat identifier.<br>
-<br>
-      if (CurTok != '(') // Simple variable ref.<br>
-        return llvm::make_unique<VariableExprAST>(IdName);<br>
-<br>
-      // Call.<br>
-      getNextToken();  // eat (<br>
-      std::vector<std::unique_ptr<ExprAST>> Args;<br>
-      if (CurTok != ')') {<br>
-        while (1) {<br>
-          if (auto Arg = ParseExpression())<br>
-            Args.push_back(std::move(Arg));<br>
-          else<br>
-            return nullptr;<br>
-<br>
-          if (CurTok == ')')<br>
-            break;<br>
-<br>
-          if (CurTok != ',')<br>
-            return LogError("Expected ')' or ',' in argument list");<br>
-          getNextToken();<br>
-        }<br>
-      }<br>
-<br>
-      // Eat the ')'.<br>
-      getNextToken();<br>
-<br>
-      return llvm::make_unique<CallExprAST>(IdName, std::move(Args));<br>
-    }<br>
-<br>
-This routine follows the same style as the other routines. (It expects<br>
-to be called if the current token is a ``tok_identifier`` token). It<br>
-also has recursion and error handling. One interesting aspect of this is<br>
-that it uses *look-ahead* to determine if the current identifier is a<br>
-stand alone variable reference or if it is a function call expression.<br>
-It handles this by checking to see if the token after the identifier is<br>
-a '(' token, constructing either a ``VariableExprAST`` or<br>
-``CallExprAST`` node as appropriate.<br>
-<br>
-Now that we have all of our simple expression-parsing logic in place, we<br>
-can define a helper function to wrap it together into one entry point.<br>
-We call this class of expressions "primary" expressions, for reasons<br>
-that will become more clear `later in the<br>
-tutorial <LangImpl6.html#user-defined-unary-operators>`_. In order to parse an arbitrary<br>
-primary expression, we need to determine what sort of expression it is:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// primary<br>
-    ///   ::= identifierexpr<br>
-    ///   ::= numberexpr<br>
-    ///   ::= parenexpr<br>
-    static std::unique_ptr<ExprAST> ParsePrimary() {<br>
-      switch (CurTok) {<br>
-      default:<br>
-        return LogError("unknown token when expecting an expression");<br>
-      case tok_identifier:<br>
-        return ParseIdentifierExpr();<br>
-      case tok_number:<br>
-        return ParseNumberExpr();<br>
-      case '(':<br>
-        return ParseParenExpr();<br>
-      }<br>
-    }<br>
-<br>
-Now that you see the definition of this function, it is more obvious why<br>
-we can assume the state of CurTok in the various functions. This uses<br>
-look-ahead to determine which sort of expression is being inspected, and<br>
-then parses it with a function call.<br>
-<br>
-Now that basic expressions are handled, we need to handle binary<br>
-expressions. They are a bit more complex.<br>
-<br>
-Binary Expression Parsing<br>
-=========================<br>
-<br>
-Binary expressions are significantly harder to parse because they are<br>
-often ambiguous. For example, when given the string "x+y\*z", the parser<br>
-can choose to parse it as either "(x+y)\*z" or "x+(y\*z)". With common<br>
-definitions from mathematics, we expect the later parse, because "\*"<br>
-(multiplication) has higher *precedence* than "+" (addition).<br>
-<br>
-There are many ways to handle this, but an elegant and efficient way is<br>
-to use `Operator-Precedence<br>
-Parsing <<a href="http://en.wikipedia.org/wiki/Operator-precedence_parser" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Operator-precedence_parser</a>>`_.<br>
-This parsing technique uses the precedence of binary operators to guide<br>
-recursion. To start with, we need a table of precedences:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// BinopPrecedence - This holds the precedence for each binary operator that is<br>
-    /// defined.<br>
-    static std::map<char, int> BinopPrecedence;<br>
-<br>
-    /// GetTokPrecedence - Get the precedence of the pending binary operator token.<br>
-    static int GetTokPrecedence() {<br>
-      if (!isascii(CurTok))<br>
-        return -1;<br>
-<br>
-      // Make sure it's a declared binop.<br>
-      int TokPrec = BinopPrecedence[CurTok];<br>
-      if (TokPrec <= 0) return -1;<br>
-      return TokPrec;<br>
-    }<br>
-<br>
-    int main() {<br>
-      // Install standard binary operators.<br>
-      // 1 is lowest precedence.<br>
-      BinopPrecedence['<'] = 10;<br>
-      BinopPrecedence['+'] = 20;<br>
-      BinopPrecedence['-'] = 20;<br>
-      BinopPrecedence['*'] = 40;  // highest.<br>
-      ...<br>
-    }<br>
-<br>
-For the basic form of Kaleidoscope, we will only support 4 binary<br>
-operators (this can obviously be extended by you, our brave and intrepid<br>
-reader). The ``GetTokPrecedence`` function returns the precedence for<br>
-the current token, or -1 if the token is not a binary operator. Having a<br>
-map makes it easy to add new operators and makes it clear that the<br>
-algorithm doesn't depend on the specific operators involved, but it<br>
-would be easy enough to eliminate the map and do the comparisons in the<br>
-``GetTokPrecedence`` function. (Or just use a fixed-size array).<br>
-<br>
-With the helper above defined, we can now start parsing binary<br>
-expressions. The basic idea of operator precedence parsing is to break<br>
-down an expression with potentially ambiguous binary operators into<br>
-pieces. Consider, for example, the expression "a+b+(c+d)\*e\*f+g".<br>
-Operator precedence parsing considers this as a stream of primary<br>
-expressions separated by binary operators. As such, it will first parse<br>
-the leading primary expression "a", then it will see the pairs [+, b]<br>
-[+, (c+d)] [\*, e] [\*, f] and [+, g]. Note that because parentheses are<br>
-primary expressions, the binary expression parser doesn't need to worry<br>
-about nested subexpressions like (c+d) at all.<br>
-<br>
-To start, an expression is a primary expression potentially followed by<br>
-a sequence of [binop,primaryexpr] pairs:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// expression<br>
-    ///   ::= primary binoprhs<br>
-    ///<br>
-    static std::unique_ptr<ExprAST> ParseExpression() {<br>
-      auto LHS = ParsePrimary();<br>
-      if (!LHS)<br>
-        return nullptr;<br>
-<br>
-      return ParseBinOpRHS(0, std::move(LHS));<br>
-    }<br>
-<br>
-``ParseBinOpRHS`` is the function that parses the sequence of pairs for<br>
-us. It takes a precedence and a pointer to an expression for the part<br>
-that has been parsed so far. Note that "x" is a perfectly valid<br>
-expression: As such, "binoprhs" is allowed to be empty, in which case it<br>
-returns the expression that is passed into it. In our example above, the<br>
-code passes the expression for "a" into ``ParseBinOpRHS`` and the<br>
-current token is "+".<br>
-<br>
-The precedence value passed into ``ParseBinOpRHS`` indicates the<br>
-*minimal operator precedence* that the function is allowed to eat. For<br>
-example, if the current pair stream is [+, x] and ``ParseBinOpRHS`` is<br>
-passed in a precedence of 40, it will not consume any tokens (because<br>
-the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``<br>
-starts with:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// binoprhs<br>
-    ///   ::= ('+' primary)*<br>
-    static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,<br>
-                                                  std::unique_ptr<ExprAST> LHS) {<br>
-      // If this is a binop, find its precedence.<br>
-      while (1) {<br>
-        int TokPrec = GetTokPrecedence();<br>
-<br>
-        // If this is a binop that binds at least as tightly as the current binop,<br>
-        // consume it, otherwise we are done.<br>
-        if (TokPrec < ExprPrec)<br>
-          return LHS;<br>
-<br>
-This code gets the precedence of the current token and checks to see if<br>
-if is too low. Because we defined invalid tokens to have a precedence of<br>
--1, this check implicitly knows that the pair-stream ends when the token<br>
-stream runs out of binary operators. If this check succeeds, we know<br>
-that the token is a binary operator and that it will be included in this<br>
-expression:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-        // Okay, we know this is a binop.<br>
-        int BinOp = CurTok;<br>
-        getNextToken();  // eat binop<br>
-<br>
-        // Parse the primary expression after the binary operator.<br>
-        auto RHS = ParsePrimary();<br>
-        if (!RHS)<br>
-          return nullptr;<br>
-<br>
-As such, this code eats (and remembers) the binary operator and then<br>
-parses the primary expression that follows. This builds up the whole<br>
-pair, the first of which is [+, b] for the running example.<br>
-<br>
-Now that we parsed the left-hand side of an expression and one pair of<br>
-the RHS sequence, we have to decide which way the expression associates.<br>
-In particular, we could have "(a+b) binop unparsed" or "a + (b binop<br>
-unparsed)". To determine this, we look ahead at "binop" to determine its<br>
-precedence and compare it to BinOp's precedence (which is '+' in this<br>
-case):<br>
-<br>
-.. code-block:: c++<br>
-<br>
-        // If BinOp binds less tightly with RHS than the operator after RHS, let<br>
-        // the pending operator take RHS as its LHS.<br>
-        int NextPrec = GetTokPrecedence();<br>
-        if (TokPrec < NextPrec) {<br>
-<br>
-If the precedence of the binop to the right of "RHS" is lower or equal<br>
-to the precedence of our current operator, then we know that the<br>
-parentheses associate as "(a+b) binop ...". In our example, the current<br>
-operator is "+" and the next operator is "+", we know that they have the<br>
-same precedence. In this case we'll create the AST node for "a+b", and<br>
-then continue parsing:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-          ... if body omitted ...<br>
-        }<br>
-<br>
-        // Merge LHS/RHS.<br>
-        LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),<br>
-                                               std::move(RHS));<br>
-      }  // loop around to the top of the while loop.<br>
-    }<br>
-<br>
-In our example above, this will turn "a+b+" into "(a+b)" and execute the<br>
-next iteration of the loop, with "+" as the current token. The code<br>
-above will eat, remember, and parse "(c+d)" as the primary expression,<br>
-which makes the current pair equal to [+, (c+d)]. It will then evaluate<br>
-the 'if' conditional above with "\*" as the binop to the right of the<br>
-primary. In this case, the precedence of "\*" is higher than the<br>
-precedence of "+" so the if condition will be entered.<br>
-<br>
-The critical question left here is "how can the if condition parse the<br>
-right hand side in full"? In particular, to build the AST correctly for<br>
-our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression<br>
-variable. The code to do this is surprisingly simple (code from the<br>
-above two blocks duplicated for context):<br>
-<br>
-.. code-block:: c++<br>
-<br>
-        // If BinOp binds less tightly with RHS than the operator after RHS, let<br>
-        // the pending operator take RHS as its LHS.<br>
-        int NextPrec = GetTokPrecedence();<br>
-        if (TokPrec < NextPrec) {<br>
-          RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));<br>
-          if (!RHS)<br>
-            return nullptr;<br>
-        }<br>
-        // Merge LHS/RHS.<br>
-        LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),<br>
-                                               std::move(RHS));<br>
-      }  // loop around to the top of the while loop.<br>
-    }<br>
-<br>
-At this point, we know that the binary operator to the RHS of our<br>
-primary has higher precedence than the binop we are currently parsing.<br>
-As such, we know that any sequence of pairs whose operators are all<br>
-higher precedence than "+" should be parsed together and returned as<br>
-"RHS". To do this, we recursively invoke the ``ParseBinOpRHS`` function<br>
-specifying "TokPrec+1" as the minimum precedence required for it to<br>
-continue. In our example above, this will cause it to return the AST<br>
-node for "(c+d)\*e\*f" as RHS, which is then set as the RHS of the '+'<br>
-expression.<br>
-<br>
-Finally, on the next iteration of the while loop, the "+g" piece is<br>
-parsed and added to the AST. With this little bit of code (14<br>
-non-trivial lines), we correctly handle fully general binary expression<br>
-parsing in a very elegant way. This was a whirlwind tour of this code,<br>
-and it is somewhat subtle. I recommend running through it with a few<br>
-tough examples to see how it works.<br>
-<br>
-This wraps up handling of expressions. At this point, we can point the<br>
-parser at an arbitrary token stream and build an expression from it,<br>
-stopping at the first token that is not part of the expression. Next up<br>
-we need to handle function definitions, etc.<br>
-<br>
-Parsing the Rest<br>
-================<br>
-<br>
-The next thing missing is handling of function prototypes. In<br>
-Kaleidoscope, these are used both for 'extern' function declarations as<br>
-well as function body definitions. The code to do this is<br>
-straight-forward and not very interesting (once you've survived<br>
-expressions):<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// prototype<br>
-    ///   ::= id '(' id* ')'<br>
-    static std::unique_ptr<PrototypeAST> ParsePrototype() {<br>
-      if (CurTok != tok_identifier)<br>
-        return LogErrorP("Expected function name in prototype");<br>
-<br>
-      std::string FnName = IdentifierStr;<br>
-      getNextToken();<br>
-<br>
-      if (CurTok != '(')<br>
-        return LogErrorP("Expected '(' in prototype");<br>
-<br>
-      // Read the list of argument names.<br>
-      std::vector<std::string> ArgNames;<br>
-      while (getNextToken() == tok_identifier)<br>
-        ArgNames.push_back(IdentifierStr);<br>
-      if (CurTok != ')')<br>
-        return LogErrorP("Expected ')' in prototype");<br>
-<br>
-      // success.<br>
-      getNextToken();  // eat ')'.<br>
-<br>
-      return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));<br>
-    }<br>
-<br>
-Given this, a function definition is very simple, just a prototype plus<br>
-an expression to implement the body:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// definition ::= 'def' prototype expression<br>
-    static std::unique_ptr<FunctionAST> ParseDefinition() {<br>
-      getNextToken();  // eat def.<br>
-      auto Proto = ParsePrototype();<br>
-      if (!Proto) return nullptr;<br>
-<br>
-      if (auto E = ParseExpression())<br>
-        return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));<br>
-      return nullptr;<br>
-    }<br>
-<br>
-In addition, we support 'extern' to declare functions like 'sin' and<br>
-'cos' as well as to support forward declaration of user functions. These<br>
-'extern's are just prototypes with no body:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// external ::= 'extern' prototype<br>
-    static std::unique_ptr<PrototypeAST> ParseExtern() {<br>
-      getNextToken();  // eat extern.<br>
-      return ParsePrototype();<br>
-    }<br>
-<br>
-Finally, we'll also let the user type in arbitrary top-level expressions<br>
-and evaluate them on the fly. We will handle this by defining anonymous<br>
-nullary (zero argument) functions for them:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// toplevelexpr ::= expression<br>
-    static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {<br>
-      if (auto E = ParseExpression()) {<br>
-        // Make an anonymous proto.<br>
-        auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());<br>
-        return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));<br>
-      }<br>
-      return nullptr;<br>
-    }<br>
-<br>
-Now that we have all the pieces, let's build a little driver that will<br>
-let us actually *execute* this code we've built!<br>
-<br>
-The Driver<br>
-==========<br>
-<br>
-The driver for this simply invokes all of the parsing pieces with a<br>
-top-level dispatch loop. There isn't much interesting here, so I'll just<br>
-include the top-level loop. See `below <#full-code-listing>`_ for full code in the<br>
-"Top-Level Parsing" section.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// top ::= definition | external | expression | ';'<br>
-    static void MainLoop() {<br>
-      while (1) {<br>
-        fprintf(stderr, "ready> ");<br>
-        switch (CurTok) {<br>
-        case tok_eof:<br>
-          return;<br>
-        case ';': // ignore top-level semicolons.<br>
-          getNextToken();<br>
-          break;<br>
-        case tok_def:<br>
-          HandleDefinition();<br>
-          break;<br>
-        case tok_extern:<br>
-          HandleExtern();<br>
-          break;<br>
-        default:<br>
-          HandleTopLevelExpression();<br>
-          break;<br>
-        }<br>
-      }<br>
-    }<br>
-<br>
-The most interesting part of this is that we ignore top-level<br>
-semicolons. Why is this, you ask? The basic reason is that if you type<br>
-"4 + 5" at the command line, the parser doesn't know whether that is the<br>
-end of what you will type or not. For example, on the next line you<br>
-could type "def foo..." in which case 4+5 is the end of a top-level<br>
-expression. Alternatively you could type "\* 6", which would continue<br>
-the expression. Having top-level semicolons allows you to type "4+5;",<br>
-and the parser will know you are done.<br>
-<br>
-Conclusions<br>
-===========<br>
-<br>
-With just under 400 lines of commented code (240 lines of non-comment,<br>
-non-blank code), we fully defined our minimal language, including a<br>
-lexer, parser, and AST builder. With this done, the executable will<br>
-validate Kaleidoscope code and tell us if it is grammatically invalid.<br>
-For example, here is a sample interaction:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    $ ./a.out<br>
-    ready> def foo(x y) x+foo(y, 4.0);<br>
-    Parsed a function definition.<br>
-    ready> def foo(x y) x+y y;<br>
-    Parsed a function definition.<br>
-    Parsed a top-level expr<br>
-    ready> def foo(x y) x+y );<br>
-    Parsed a function definition.<br>
-    Error: unknown token when expecting an expression<br>
-    ready> extern sin(a);<br>
-    ready> Parsed an extern<br>
-    ready> ^D<br>
-    $<br>
-<br>
-There is a lot of room for extension here. You can define new AST nodes,<br>
-extend the language in many ways, etc. In the `next<br>
-installment <LangImpl3.html>`_, we will describe how to generate LLVM<br>
-Intermediate Representation (IR) from the AST.<br>
-<br>
-Full Code Listing<br>
-=================<br>
-<br>
-Here is the complete code listing for this and the previous chapter.<br>
-Note that it is fully self-contained: you don't need LLVM or any<br>
-external libraries at all for this. (Besides the C and C++ standard<br>
-libraries, of course.) To build this, just compile with:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    # Compile<br>
-    clang++ -g -O3 toy.cpp<br>
-    # Run<br>
-    ./a.out<br>
-<br>
-Here is the code:<br>
-<br>
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter2/toy.cpp<br>
-   :language: c++<br>
-<br>
-`Next: Implementing Code Generation to LLVM IR <LangImpl3.html>`_<br>
-<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl3.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl3.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl3.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl3.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl3.rst (removed)<br>
@@ -1,567 +0,0 @@<br>
-========================================<br>
-Kaleidoscope: Code generation to LLVM IR<br>
-========================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Chapter 3 Introduction<br>
-======================<br>
-<br>
-Welcome to Chapter 3 of the "`Implementing a language with<br>
-LLVM <index.html>`_" tutorial. This chapter shows you how to transform<br>
-the `Abstract Syntax Tree <LangImpl2.html>`_, built in Chapter 2, into<br>
-LLVM IR. This will teach you a little bit about how LLVM does things, as<br>
-well as demonstrate how easy it is to use. It's much more work to build<br>
-a lexer and parser than it is to generate LLVM IR code. :)<br>
-<br>
-**Please note**: the code in this chapter and later require LLVM 3.7 or<br>
-later. LLVM 3.6 and before will not work with it. Also note that you<br>
-need to use a version of this tutorial that matches your LLVM release:<br>
-If you are using an official LLVM release, use the version of the<br>
-documentation included with your release or on the `<a href="http://llvm.org" rel="noreferrer" target="_blank">llvm.org</a> releases<br>
-page <<a href="http://llvm.org/releases/" rel="noreferrer" target="_blank">http://llvm.org/releases/</a>>`_.<br>
-<br>
-Code Generation Setup<br>
-=====================<br>
-<br>
-In order to generate LLVM IR, we want some simple setup to get started.<br>
-First we define virtual code generation (codegen) methods in each AST<br>
-class:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// ExprAST - Base class for all expression nodes.<br>
-    class ExprAST {<br>
-    public:<br>
-      virtual ~ExprAST() {}<br>
-      virtual Value *codegen() = 0;<br>
-    };<br>
-<br>
-    /// NumberExprAST - Expression class for numeric literals like "1.0".<br>
-    class NumberExprAST : public ExprAST {<br>
-      double Val;<br>
-<br>
-    public:<br>
-      NumberExprAST(double Val) : Val(Val) {}<br>
-      virtual Value *codegen();<br>
-    };<br>
-    ...<br>
-<br>
-The codegen() method says to emit IR for that AST node along with all<br>
-the things it depends on, and they all return an LLVM Value object.<br>
-"Value" is the class used to represent a "`Static Single Assignment<br>
-(SSA) <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_<br>
-register" or "SSA value" in LLVM. The most distinct aspect of SSA values<br>
-is that their value is computed as the related instruction executes, and<br>
-it does not get a new value until (and if) the instruction re-executes.<br>
-In other words, there is no way to "change" an SSA value. For more<br>
-information, please read up on `Static Single<br>
-Assignment <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_<br>
-- the concepts are really quite natural once you grok them.<br>
-<br>
-Note that instead of adding virtual methods to the ExprAST class<br>
-hierarchy, it could also make sense to use a `visitor<br>
-pattern <<a href="http://en.wikipedia.org/wiki/Visitor_pattern" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Visitor_pattern</a>>`_ or some other<br>
-way to model this. Again, this tutorial won't dwell on good software<br>
-engineering practices: for our purposes, adding a virtual method is<br>
-simplest.<br>
-<br>
-The second thing we want is an "LogError" method like we used for the<br>
-parser, which will be used to report errors found during code generation<br>
-(for example, use of an undeclared parameter):<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    static LLVMContext TheContext;<br>
-    static IRBuilder<> Builder(TheContext);<br>
-    static std::unique_ptr<Module> TheModule;<br>
-    static std::map<std::string, Value *> NamedValues;<br>
-<br>
-    Value *LogErrorV(const char *Str) {<br>
-      LogError(Str);<br>
-      return nullptr;<br>
-    }<br>
-<br>
-The static variables will be used during code generation. ``TheContext``<br>
-is an opaque object that owns a lot of core LLVM data structures, such as<br>
-the type and constant value tables. We don't need to understand it in<br>
-detail, we just need a single instance to pass into APIs that require it.<br>
-<br>
-The ``Builder`` object is a helper object that makes it easy to generate<br>
-LLVM instructions. Instances of the<br>
-`IRBuilder <<a href="http://llvm.org/doxygen/IRBuilder_8h-source.html" rel="noreferrer" target="_blank">http://llvm.org/doxygen/IRBuilder_8h-source.html</a>>`_<br>
-class template keep track of the current place to insert instructions<br>
-and has methods to create new instructions.<br>
-<br>
-``TheModule`` is an LLVM construct that contains functions and global<br>
-variables. In many ways, it is the top-level structure that the LLVM IR<br>
-uses to contain code. It will own the memory for all of the IR that we<br>
-generate, which is why the codegen() method returns a raw Value\*,<br>
-rather than a unique_ptr<Value>.<br>
-<br>
-The ``NamedValues`` map keeps track of which values are defined in the<br>
-current scope and what their LLVM representation is. (In other words, it<br>
-is a symbol table for the code). In this form of Kaleidoscope, the only<br>
-things that can be referenced are function parameters. As such, function<br>
-parameters will be in this map when generating code for their function<br>
-body.<br>
-<br>
-With these basics in place, we can start talking about how to generate<br>
-code for each expression. Note that this assumes that the ``Builder``<br>
-has been set up to generate code *into* something. For now, we'll assume<br>
-that this has already been done, and we'll just use it to emit code.<br>
-<br>
-Expression Code Generation<br>
-==========================<br>
-<br>
-Generating LLVM code for expression nodes is very straightforward: less<br>
-than 45 lines of commented code for all four of our expression nodes.<br>
-First we'll do numeric literals:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *NumberExprAST::codegen() {<br>
-      return ConstantFP::get(LLVMContext, APFloat(Val));<br>
-    }<br>
-<br>
-In the LLVM IR, numeric constants are represented with the<br>
-``ConstantFP`` class, which holds the numeric value in an ``APFloat``<br>
-internally (``APFloat`` has the capability of holding floating point<br>
-constants of Arbitrary Precision). This code basically just creates<br>
-and returns a ``ConstantFP``. Note that in the LLVM IR that constants<br>
-are all uniqued together and shared. For this reason, the API uses the<br>
-"foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *VariableExprAST::codegen() {<br>
-      // Look this variable up in the function.<br>
-      Value *V = NamedValues[Name];<br>
-      if (!V)<br>
-        LogErrorV("Unknown variable name");<br>
-      return V;<br>
-    }<br>
-<br>
-References to variables are also quite simple using LLVM. In the simple<br>
-version of Kaleidoscope, we assume that the variable has already been<br>
-emitted somewhere and its value is available. In practice, the only<br>
-values that can be in the ``NamedValues`` map are function arguments.<br>
-This code simply checks to see that the specified name is in the map (if<br>
-not, an unknown variable is being referenced) and returns the value for<br>
-it. In future chapters, we'll add support for `loop induction<br>
-variables <LangImpl5.html#for-loop-expression>`_ in the symbol table, and for `local<br>
-variables <LangImpl7.html#user-defined-local-variables>`_.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *BinaryExprAST::codegen() {<br>
-      Value *L = LHS->codegen();<br>
-      Value *R = RHS->codegen();<br>
-      if (!L || !R)<br>
-        return nullptr;<br>
-<br>
-      switch (Op) {<br>
-      case '+':<br>
-        return Builder.CreateFAdd(L, R, "addtmp");<br>
-      case '-':<br>
-        return Builder.CreateFSub(L, R, "subtmp");<br>
-      case '*':<br>
-        return Builder.CreateFMul(L, R, "multmp");<br>
-      case '<':<br>
-        L = Builder.CreateFCmpULT(L, R, "cmptmp");<br>
-        // Convert bool 0/1 to double 0.0 or 1.0<br>
-        return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),<br>
-                                    "booltmp");<br>
-      default:<br>
-        return LogErrorV("invalid binary operator");<br>
-      }<br>
-    }<br>
-<br>
-Binary operators start to get more interesting. The basic idea here is<br>
-that we recursively emit code for the left-hand side of the expression,<br>
-then the right-hand side, then we compute the result of the binary<br>
-expression. In this code, we do a simple switch on the opcode to create<br>
-the right LLVM instruction.<br>
-<br>
-In the example above, the LLVM builder class is starting to show its<br>
-value. IRBuilder knows where to insert the newly created instruction,<br>
-all you have to do is specify what instruction to create (e.g. with<br>
-``CreateFAdd``), which operands to use (``L`` and ``R`` here) and<br>
-optionally provide a name for the generated instruction.<br>
-<br>
-One nice thing about LLVM is that the name is just a hint. For instance,<br>
-if the code above emits multiple "addtmp" variables, LLVM will<br>
-automatically provide each one with an increasing, unique numeric<br>
-suffix. Local value names for instructions are purely optional, but it<br>
-makes it much easier to read the IR dumps.<br>
-<br>
-`LLVM instructions <../LangRef.html#instruction-reference>`_ are constrained by strict<br>
-rules: for example, the Left and Right operators of an `add<br>
-instruction <../LangRef.html#add-instruction>`_ must have the same type, and the<br>
-result type of the add must match the operand types. Because all values<br>
-in Kaleidoscope are doubles, this makes for very simple code for add,<br>
-sub and mul.<br>
-<br>
-On the other hand, LLVM specifies that the `fcmp<br>
-instruction <../LangRef.html#fcmp-instruction>`_ always returns an 'i1' value (a<br>
-one bit integer). The problem with this is that Kaleidoscope wants the<br>
-value to be a 0.0 or 1.0 value. In order to get these semantics, we<br>
-combine the fcmp instruction with a `uitofp<br>
-instruction <../LangRef.html#uitofp-to-instruction>`_. This instruction converts its<br>
-input integer into a floating point value by treating the input as an<br>
-unsigned value. In contrast, if we used the `sitofp<br>
-instruction <../LangRef.html#sitofp-to-instruction>`_, the Kaleidoscope '<' operator<br>
-would return 0.0 and -1.0, depending on the input value.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *CallExprAST::codegen() {<br>
-      // Look up the name in the global module table.<br>
-      Function *CalleeF = TheModule->getFunction(Callee);<br>
-      if (!CalleeF)<br>
-        return LogErrorV("Unknown function referenced");<br>
-<br>
-      // If argument mismatch error.<br>
-      if (CalleeF->arg_size() != Args.size())<br>
-        return LogErrorV("Incorrect # arguments passed");<br>
-<br>
-      std::vector<Value *> ArgsV;<br>
-      for (unsigned i = 0, e = Args.size(); i != e; ++i) {<br>
-        ArgsV.push_back(Args[i]->codegen());<br>
-        if (!ArgsV.back())<br>
-          return nullptr;<br>
-      }<br>
-<br>
-      return Builder.CreateCall(CalleeF, ArgsV, "calltmp");<br>
-    }<br>
-<br>
-Code generation for function calls is quite straightforward with LLVM. The code<br>
-above initially does a function name lookup in the LLVM Module's symbol table.<br>
-Recall that the LLVM Module is the container that holds the functions we are<br>
-JIT'ing. By giving each function the same name as what the user specifies, we<br>
-can use the LLVM symbol table to resolve function names for us.<br>
-<br>
-Once we have the function to call, we recursively codegen each argument<br>
-that is to be passed in, and create an LLVM `call<br>
-instruction <../LangRef.html#call-instruction>`_. Note that LLVM uses the native C<br>
-calling conventions by default, allowing these calls to also call into<br>
-standard library functions like "sin" and "cos", with no additional<br>
-effort.<br>
-<br>
-This wraps up our handling of the four basic expressions that we have so<br>
-far in Kaleidoscope. Feel free to go in and add some more. For example,<br>
-by browsing the `LLVM language reference <../LangRef.html>`_ you'll find<br>
-several other interesting instructions that are really easy to plug into<br>
-our basic framework.<br>
-<br>
-Function Code Generation<br>
-========================<br>
-<br>
-Code generation for prototypes and functions must handle a number of<br>
-details, which make their code less beautiful than expression code<br>
-generation, but allows us to illustrate some important points. First,<br>
-lets talk about code generation for prototypes: they are used both for<br>
-function bodies and external function declarations. The code starts<br>
-with:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Function *PrototypeAST::codegen() {<br>
-      // Make the function type:  double(double,double) etc.<br>
-      std::vector<Type*> Doubles(Args.size(),<br>
-                                 Type::getDoubleTy(LLVMContext));<br>
-      FunctionType *FT =<br>
-        FunctionType::get(Type::getDoubleTy(LLVMContext), Doubles, false);<br>
-<br>
-      Function *F =<br>
-        Function::Create(FT, Function::ExternalLinkage, Name, TheModule);<br>
-<br>
-This code packs a lot of power into a few lines. Note first that this<br>
-function returns a "Function\*" instead of a "Value\*". Because a<br>
-"prototype" really talks about the external interface for a function<br>
-(not the value computed by an expression), it makes sense for it to<br>
-return the LLVM Function it corresponds to when codegen'd.<br>
-<br>
-The call to ``FunctionType::get`` creates the ``FunctionType`` that<br>
-should be used for a given Prototype. Since all function arguments in<br>
-Kaleidoscope are of type double, the first line creates a vector of "N"<br>
-LLVM double types. It then uses the ``Functiontype::get`` method to<br>
-create a function type that takes "N" doubles as arguments, returns one<br>
-double as a result, and that is not vararg (the false parameter<br>
-indicates this). Note that Types in LLVM are uniqued just like Constants<br>
-are, so you don't "new" a type, you "get" it.<br>
-<br>
-The final line above actually creates the IR Function corresponding to<br>
-the Prototype. This indicates the type, linkage and name to use, as<br>
-well as which module to insert into. "`external<br>
-linkage <../LangRef.html#linkage>`_" means that the function may be<br>
-defined outside the current module and/or that it is callable by<br>
-functions outside the module. The Name passed in is the name the user<br>
-specified: since "``TheModule``" is specified, this name is registered<br>
-in "``TheModule``"s symbol table.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  // Set names for all arguments.<br>
-  unsigned Idx = 0;<br>
-  for (auto &Arg : F->args())<br>
-    Arg.setName(Args[Idx++]);<br>
-<br>
-  return F;<br>
-<br>
-Finally, we set the name of each of the function's arguments according to the<br>
-names given in the Prototype. This step isn't strictly necessary, but keeping<br>
-the names consistent makes the IR more readable, and allows subsequent code to<br>
-refer directly to the arguments for their names, rather than having to look up<br>
-them up in the Prototype AST.<br>
-<br>
-At this point we have a function prototype with no body. This is how LLVM IR<br>
-represents function declarations. For extern statements in Kaleidoscope, this<br>
-is as far as we need to go. For function definitions however, we need to<br>
-codegen and attach a function body.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  Function *FunctionAST::codegen() {<br>
-      // First, check for an existing function from a previous 'extern' declaration.<br>
-    Function *TheFunction = TheModule->getFunction(Proto->getName());<br>
-<br>
-    if (!TheFunction)<br>
-      TheFunction = Proto->codegen();<br>
-<br>
-    if (!TheFunction)<br>
-      return nullptr;<br>
-<br>
-    if (!TheFunction->empty())<br>
-      return (Function*)LogErrorV("Function cannot be redefined.");<br>
-<br>
-<br>
-For function definitions, we start by searching TheModule's symbol table for an<br>
-existing version of this function, in case one has already been created using an<br>
-'extern' statement. If Module::getFunction returns null then no previous version<br>
-exists, so we'll codegen one from the Prototype. In either case, we want to<br>
-assert that the function is empty (i.e. has no body yet) before we start.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  // Create a new basic block to start insertion into.<br>
-  BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);<br>
-  Builder.SetInsertPoint(BB);<br>
-<br>
-  // Record the function arguments in the NamedValues map.<br>
-  NamedValues.clear();<br>
-  for (auto &Arg : TheFunction->args())<br>
-    NamedValues[Arg.getName()] = &Arg;<br>
-<br>
-Now we get to the point where the ``Builder`` is set up. The first line<br>
-creates a new `basic block <<a href="http://en.wikipedia.org/wiki/Basic_block" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Basic_block</a>>`_<br>
-(named "entry"), which is inserted into ``TheFunction``. The second line<br>
-then tells the builder that new instructions should be inserted into the<br>
-end of the new basic block. Basic blocks in LLVM are an important part<br>
-of functions that define the `Control Flow<br>
-Graph <<a href="http://en.wikipedia.org/wiki/Control_flow_graph" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Control_flow_graph</a>>`_. Since we<br>
-don't have any control flow, our functions will only contain one block<br>
-at this point. We'll fix this in `Chapter 5 <LangImpl5.html>`_ :).<br>
-<br>
-Next we add the function arguments to the NamedValues map (after first clearing<br>
-it out) so that they're accessible to ``VariableExprAST`` nodes.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      if (Value *RetVal = Body->codegen()) {<br>
-        // Finish off the function.<br>
-        Builder.CreateRet(RetVal);<br>
-<br>
-        // Validate the generated code, checking for consistency.<br>
-        verifyFunction(*TheFunction);<br>
-<br>
-        return TheFunction;<br>
-      }<br>
-<br>
-Once the insertion point has been set up and the NamedValues map populated,<br>
-we call the ``codegen()`` method for the root expression of the function. If no<br>
-error happens, this emits code to compute the expression into the entry block<br>
-and returns the value that was computed. Assuming no error, we then create an<br>
-LLVM `ret instruction <../LangRef.html#ret-instruction>`_, which completes the function.<br>
-Once the function is built, we call ``verifyFunction``, which is<br>
-provided by LLVM. This function does a variety of consistency checks on<br>
-the generated code, to determine if our compiler is doing everything<br>
-right. Using this is important: it can catch a lot of bugs. Once the<br>
-function is finished and validated, we return it.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Error reading body, remove function.<br>
-      TheFunction->eraseFromParent();<br>
-      return nullptr;<br>
-    }<br>
-<br>
-The only piece left here is handling of the error case. For simplicity,<br>
-we handle this by merely deleting the function we produced with the<br>
-``eraseFromParent`` method. This allows the user to redefine a function<br>
-that they incorrectly typed in before: if we didn't delete it, it would<br>
-live in the symbol table, with a body, preventing future redefinition.<br>
-<br>
-This code does have a bug, though: If the ``FunctionAST::codegen()`` method<br>
-finds an existing IR Function, it does not validate its signature against the<br>
-definition's own prototype. This means that an earlier 'extern' declaration will<br>
-take precedence over the function definition's signature, which can cause<br>
-codegen to fail, for instance if the function arguments are named differently.<br>
-There are a number of ways to fix this bug, see what you can come up with! Here<br>
-is a testcase:<br>
-<br>
-::<br>
-<br>
-    extern foo(a);     # ok, defines foo.<br>
-    def foo(b) b;      # Error: Unknown variable name. (decl using 'a' takes precedence).<br>
-<br>
-Driver Changes and Closing Thoughts<br>
-===================================<br>
-<br>
-For now, code generation to LLVM doesn't really get us much, except that<br>
-we can look at the pretty IR calls. The sample code inserts calls to<br>
-codegen into the "``HandleDefinition``", "``HandleExtern``" etc<br>
-functions, and then dumps out the LLVM IR. This gives a nice way to look<br>
-at the LLVM IR for simple functions. For example:<br>
-<br>
-::<br>
-<br>
-    ready> 4+5;<br>
-    Read top-level expression:<br>
-    define double @0() {<br>
-    entry:<br>
-      ret double 9.000000e+00<br>
-    }<br>
-<br>
-Note how the parser turns the top-level expression into anonymous<br>
-functions for us. This will be handy when we add `JIT<br>
-support <LangImpl4.html#adding-a-jit-compiler>`_ in the next chapter. Also note that the<br>
-code is very literally transcribed, no optimizations are being performed<br>
-except simple constant folding done by IRBuilder. We will `add<br>
-optimizations <LangImpl4.html#trivial-constant-folding>`_ explicitly in the next<br>
-chapter.<br>
-<br>
-::<br>
-<br>
-    ready> def foo(a b) a*a + 2*a*b + b*b;<br>
-    Read function definition:<br>
-    define double @foo(double %a, double %b) {<br>
-    entry:<br>
-      %multmp = fmul double %a, %a<br>
-      %multmp1 = fmul double 2.000000e+00, %a<br>
-      %multmp2 = fmul double %multmp1, %b<br>
-      %addtmp = fadd double %multmp, %multmp2<br>
-      %multmp3 = fmul double %b, %b<br>
-      %addtmp4 = fadd double %addtmp, %multmp3<br>
-      ret double %addtmp4<br>
-    }<br>
-<br>
-This shows some simple arithmetic. Notice the striking similarity to the<br>
-LLVM builder calls that we use to create the instructions.<br>
-<br>
-::<br>
-<br>
-    ready> def bar(a) foo(a, 4.0) + bar(31337);<br>
-    Read function definition:<br>
-    define double @bar(double %a) {<br>
-    entry:<br>
-      %calltmp = call double @foo(double %a, double 4.000000e+00)<br>
-      %calltmp1 = call double @bar(double 3.133700e+04)<br>
-      %addtmp = fadd double %calltmp, %calltmp1<br>
-      ret double %addtmp<br>
-    }<br>
-<br>
-This shows some function calls. Note that this function will take a long<br>
-time to execute if you call it. In the future we'll add conditional<br>
-control flow to actually make recursion useful :).<br>
-<br>
-::<br>
-<br>
-    ready> extern cos(x);<br>
-    Read extern:<br>
-    declare double @cos(double)<br>
-<br>
-    ready> cos(1.234);<br>
-    Read top-level expression:<br>
-    define double @1() {<br>
-    entry:<br>
-      %calltmp = call double @cos(double 1.234000e+00)<br>
-      ret double %calltmp<br>
-    }<br>
-<br>
-This shows an extern for the libm "cos" function, and a call to it.<br>
-<br>
-.. TODO:: Abandon Pygments' horrible `llvm` lexer. It just totally gives up<br>
-   on highlighting this due to the first line.<br>
-<br>
-::<br>
-<br>
-    ready> ^D<br>
-    ; ModuleID = 'my cool jit'<br>
-<br>
-    define double @0() {<br>
-    entry:<br>
-      %addtmp = fadd double 4.000000e+00, 5.000000e+00<br>
-      ret double %addtmp<br>
-    }<br>
-<br>
-    define double @foo(double %a, double %b) {<br>
-    entry:<br>
-      %multmp = fmul double %a, %a<br>
-      %multmp1 = fmul double 2.000000e+00, %a<br>
-      %multmp2 = fmul double %multmp1, %b<br>
-      %addtmp = fadd double %multmp, %multmp2<br>
-      %multmp3 = fmul double %b, %b<br>
-      %addtmp4 = fadd double %addtmp, %multmp3<br>
-      ret double %addtmp4<br>
-    }<br>
-<br>
-    define double @bar(double %a) {<br>
-    entry:<br>
-      %calltmp = call double @foo(double %a, double 4.000000e+00)<br>
-      %calltmp1 = call double @bar(double 3.133700e+04)<br>
-      %addtmp = fadd double %calltmp, %calltmp1<br>
-      ret double %addtmp<br>
-    }<br>
-<br>
-    declare double @cos(double)<br>
-<br>
-    define double @1() {<br>
-    entry:<br>
-      %calltmp = call double @cos(double 1.234000e+00)<br>
-      ret double %calltmp<br>
-    }<br>
-<br>
-When you quit the current demo, it dumps out the IR for the entire<br>
-module generated. Here you can see the big picture with all the<br>
-functions referencing each other.<br>
-<br>
-This wraps up the third chapter of the Kaleidoscope tutorial. Up next,<br>
-we'll describe how to `add JIT codegen and optimizer<br>
-support <LangImpl4.html>`_ to this so we can actually start running<br>
-code!<br>
-<br>
-Full Code Listing<br>
-=================<br>
-<br>
-Here is the complete code listing for our running example, enhanced with<br>
-the LLVM code generator. Because this uses the LLVM libraries, we need<br>
-to link them in. To do this, we use the<br>
-`llvm-config <<a href="http://llvm.org/cmds/llvm-config.html" rel="noreferrer" target="_blank">http://llvm.org/cmds/llvm-config.html</a>>`_ tool to inform<br>
-our makefile/command line about which options to use:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    # Compile<br>
-    clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core` -o toy<br>
-    # Run<br>
-    ./toy<br>
-<br>
-Here is the code:<br>
-<br>
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter3/toy.cpp<br>
-   :language: c++<br>
-<br>
-`Next: Adding JIT and Optimizer Support <LangImpl4.html>`_<br>
-<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl4.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl4.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl4.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl4.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl4.rst (removed)<br>
@@ -1,610 +0,0 @@<br>
-==============================================<br>
-Kaleidoscope: Adding JIT and Optimizer Support<br>
-==============================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Chapter 4 Introduction<br>
-======================<br>
-<br>
-Welcome to Chapter 4 of the "`Implementing a language with<br>
-LLVM <index.html>`_" tutorial. Chapters 1-3 described the implementation<br>
-of a simple language and added support for generating LLVM IR. This<br>
-chapter describes two new techniques: adding optimizer support to your<br>
-language, and adding JIT compiler support. These additions will<br>
-demonstrate how to get nice, efficient code for the Kaleidoscope<br>
-language.<br>
-<br>
-Trivial Constant Folding<br>
-========================<br>
-<br>
-Our demonstration for Chapter 3 is elegant and easy to extend.<br>
-Unfortunately, it does not produce wonderful code. The IRBuilder,<br>
-however, does give us obvious optimizations when compiling simple code:<br>
-<br>
-::<br>
-<br>
-    ready> def test(x) 1+2+x;<br>
-    Read function definition:<br>
-    define double @test(double %x) {<br>
-    entry:<br>
-            %addtmp = fadd double 3.000000e+00, %x<br>
-            ret double %addtmp<br>
-    }<br>
-<br>
-This code is not a literal transcription of the AST built by parsing the<br>
-input. That would be:<br>
-<br>
-::<br>
-<br>
-    ready> def test(x) 1+2+x;<br>
-    Read function definition:<br>
-    define double @test(double %x) {<br>
-    entry:<br>
-            %addtmp = fadd double 2.000000e+00, 1.000000e+00<br>
-            %addtmp1 = fadd double %addtmp, %x<br>
-            ret double %addtmp1<br>
-    }<br>
-<br>
-Constant folding, as seen above, in particular, is a very common and<br>
-very important optimization: so much so that many language implementors<br>
-implement constant folding support in their AST representation.<br>
-<br>
-With LLVM, you don't need this support in the AST. Since all calls to<br>
-build LLVM IR go through the LLVM IR builder, the builder itself checked<br>
-to see if there was a constant folding opportunity when you call it. If<br>
-so, it just does the constant fold and return the constant instead of<br>
-creating an instruction.<br>
-<br>
-Well, that was easy :). In practice, we recommend always using<br>
-``IRBuilder`` when generating code like this. It has no "syntactic<br>
-overhead" for its use (you don't have to uglify your compiler with<br>
-constant checks everywhere) and it can dramatically reduce the amount of<br>
-LLVM IR that is generated in some cases (particular for languages with a<br>
-macro preprocessor or that use a lot of constants).<br>
-<br>
-On the other hand, the ``IRBuilder`` is limited by the fact that it does<br>
-all of its analysis inline with the code as it is built. If you take a<br>
-slightly more complex example:<br>
-<br>
-::<br>
-<br>
-    ready> def test(x) (1+2+x)*(x+(1+2));<br>
-    ready> Read function definition:<br>
-    define double @test(double %x) {<br>
-    entry:<br>
-            %addtmp = fadd double 3.000000e+00, %x<br>
-            %addtmp1 = fadd double %x, 3.000000e+00<br>
-            %multmp = fmul double %addtmp, %addtmp1<br>
-            ret double %multmp<br>
-    }<br>
-<br>
-In this case, the LHS and RHS of the multiplication are the same value.<br>
-We'd really like to see this generate "``tmp = x+3; result = tmp*tmp;``"<br>
-instead of computing "``x+3``" twice.<br>
-<br>
-Unfortunately, no amount of local analysis will be able to detect and<br>
-correct this. This requires two transformations: reassociation of<br>
-expressions (to make the add's lexically identical) and Common<br>
-Subexpression Elimination (CSE) to delete the redundant add instruction.<br>
-Fortunately, LLVM provides a broad range of optimizations that you can<br>
-use, in the form of "passes".<br>
-<br>
-LLVM Optimization Passes<br>
-========================<br>
-<br>
-LLVM provides many optimization passes, which do many different sorts of<br>
-things and have different tradeoffs. Unlike other systems, LLVM doesn't<br>
-hold to the mistaken notion that one set of optimizations is right for<br>
-all languages and for all situations. LLVM allows a compiler implementor<br>
-to make complete decisions about what optimizations to use, in which<br>
-order, and in what situation.<br>
-<br>
-As a concrete example, LLVM supports both "whole module" passes, which<br>
-look across as large of body of code as they can (often a whole file,<br>
-but if run at link time, this can be a substantial portion of the whole<br>
-program). It also supports and includes "per-function" passes which just<br>
-operate on a single function at a time, without looking at other<br>
-functions. For more information on passes and how they are run, see the<br>
-`How to Write a Pass <../WritingAnLLVMPass.html>`_ document and the<br>
-`List of LLVM Passes <../Passes.html>`_.<br>
-<br>
-For Kaleidoscope, we are currently generating functions on the fly, one<br>
-at a time, as the user types them in. We aren't shooting for the<br>
-ultimate optimization experience in this setting, but we also want to<br>
-catch the easy and quick stuff where possible. As such, we will choose<br>
-to run a few per-function optimizations as the user types the function<br>
-in. If we wanted to make a "static Kaleidoscope compiler", we would use<br>
-exactly the code we have now, except that we would defer running the<br>
-optimizer until the entire file has been parsed.<br>
-<br>
-In order to get per-function optimizations going, we need to set up a<br>
-`FunctionPassManager <../WritingAnLLVMPass.html#what-passmanager-doesr>`_ to hold<br>
-and organize the LLVM optimizations that we want to run. Once we have<br>
-that, we can add a set of optimizations to run. We'll need a new<br>
-FunctionPassManager for each module that we want to optimize, so we'll<br>
-write a function to create and initialize both the module and pass manager<br>
-for us:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    void InitializeModuleAndPassManager(void) {<br>
-      // Open a new module.<br>
-      Context LLVMContext;<br>
-      TheModule = llvm::make_unique<Module>("my cool jit", LLVMContext);<br>
-      TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());<br>
-<br>
-      // Create a new pass manager attached to it.<br>
-      TheFPM = llvm::make_unique<FunctionPassManager>(TheModule.get());<br>
-<br>
-      // Provide basic AliasAnalysis support for GVN.<br>
-      TheFPM.add(createBasicAliasAnalysisPass());<br>
-      // Do simple "peephole" optimizations and bit-twiddling optzns.<br>
-      TheFPM.add(createInstructionCombiningPass());<br>
-      // Reassociate expressions.<br>
-      TheFPM.add(createReassociatePass());<br>
-      // Eliminate Common SubExpressions.<br>
-      TheFPM.add(createGVNPass());<br>
-      // Simplify the control flow graph (deleting unreachable blocks, etc).<br>
-      TheFPM.add(createCFGSimplificationPass());<br>
-<br>
-      TheFPM.doInitialization();<br>
-    }<br>
-<br>
-This code initializes the global module ``TheModule``, and the function pass<br>
-manager ``TheFPM``, which is attached to ``TheModule``. Once the pass manager is<br>
-set up, we use a series of "add" calls to add a bunch of LLVM passes.<br>
-<br>
-In this case, we choose to add five passes: one analysis pass (alias analysis),<br>
-and four optimization passes. The passes we choose here are a pretty standard set<br>
-of "cleanup" optimizations that are useful for a wide variety of code. I won't<br>
-delve into what they do but, believe me, they are a good starting place :).<br>
-<br>
-Once the PassManager is set up, we need to make use of it. We do this by<br>
-running it after our newly created function is constructed (in<br>
-``FunctionAST::codegen()``), but before it is returned to the client:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      if (Value *RetVal = Body->codegen()) {<br>
-        // Finish off the function.<br>
-        Builder.CreateRet(RetVal);<br>
-<br>
-        // Validate the generated code, checking for consistency.<br>
-        verifyFunction(*TheFunction);<br>
-<br>
-        // Optimize the function.<br>
-        TheFPM->run(*TheFunction);<br>
-<br>
-        return TheFunction;<br>
-      }<br>
-<br>
-As you can see, this is pretty straightforward. The<br>
-``FunctionPassManager`` optimizes and updates the LLVM Function\* in<br>
-place, improving (hopefully) its body. With this in place, we can try<br>
-our test above again:<br>
-<br>
-::<br>
-<br>
-    ready> def test(x) (1+2+x)*(x+(1+2));<br>
-    ready> Read function definition:<br>
-    define double @test(double %x) {<br>
-    entry:<br>
-            %addtmp = fadd double %x, 3.000000e+00<br>
-            %multmp = fmul double %addtmp, %addtmp<br>
-            ret double %multmp<br>
-    }<br>
-<br>
-As expected, we now get our nicely optimized code, saving a floating<br>
-point add instruction from every execution of this function.<br>
-<br>
-LLVM provides a wide variety of optimizations that can be used in<br>
-certain circumstances. Some `documentation about the various<br>
-passes <../Passes.html>`_ is available, but it isn't very complete.<br>
-Another good source of ideas can come from looking at the passes that<br>
-``Clang`` runs to get started. The "``opt``" tool allows you to<br>
-experiment with passes from the command line, so you can see if they do<br>
-anything.<br>
-<br>
-Now that we have reasonable code coming out of our front-end, lets talk<br>
-about executing it!<br>
-<br>
-Adding a JIT Compiler<br>
-=====================<br>
-<br>
-Code that is available in LLVM IR can have a wide variety of tools<br>
-applied to it. For example, you can run optimizations on it (as we did<br>
-above), you can dump it out in textual or binary forms, you can compile<br>
-the code to an assembly file (.s) for some target, or you can JIT<br>
-compile it. The nice thing about the LLVM IR representation is that it<br>
-is the "common currency" between many different parts of the compiler.<br>
-<br>
-In this section, we'll add JIT compiler support to our interpreter. The<br>
-basic idea that we want for Kaleidoscope is to have the user enter<br>
-function bodies as they do now, but immediately evaluate the top-level<br>
-expressions they type in. For example, if they type in "1 + 2;", we<br>
-should evaluate and print out 3. If they define a function, they should<br>
-be able to call it from the command line.<br>
-<br>
-In order to do this, we first declare and initialize the JIT. This is<br>
-done by adding a global variable ``TheJIT``, and initializing it in<br>
-``main``:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    static std::unique_ptr<KaleidoscopeJIT> TheJIT;<br>
-    ...<br>
-    int main() {<br>
-      ..<br>
-      TheJIT = llvm::make_unique<KaleidoscopeJIT>();<br>
-<br>
-      // Run the main "interpreter loop" now.<br>
-      MainLoop();<br>
-<br>
-      return 0;<br>
-    }<br>
-<br>
-The KaleidoscopeJIT class is a simple JIT built specifically for these<br>
-tutorials. In later chapters we will look at how it works and extend it with<br>
-new features, but for now we will take it as given. Its API is very simple::<br>
-``addModule`` adds an LLVM IR module to the JIT, making its functions<br>
-available for execution; ``removeModule`` removes a module, freeing any<br>
-memory associated with the code in that module; and ``findSymbol`` allows us<br>
-to look up pointers to the compiled code.<br>
-<br>
-We can take this simple API and change our code that parses top-level expressions to<br>
-look like this:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    static void HandleTopLevelExpression() {<br>
-      // Evaluate a top-level expression into an anonymous function.<br>
-      if (auto FnAST = ParseTopLevelExpr()) {<br>
-        if (FnAST->codegen()) {<br>
-<br>
-          // JIT the module containing the anonymous expression, keeping a handle so<br>
-          // we can free it later.<br>
-          auto H = TheJIT->addModule(std::move(TheModule));<br>
-          InitializeModuleAndPassManager();<br>
-<br>
-          // Search the JIT for the __anon_expr symbol.<br>
-          auto ExprSymbol = TheJIT->findSymbol("__anon_expr");<br>
-          assert(ExprSymbol && "Function not found");<br>
-<br>
-          // Get the symbol's address and cast it to the right type (takes no<br>
-          // arguments, returns a double) so we can call it as a native function.<br>
-          double (*FP)() = (double (*)())(intptr_t)ExprSymbol.getAddress();<br>
-          fprintf(stderr, "Evaluated to %f\n", FP());<br>
-<br>
-          // Delete the anonymous expression module from the JIT.<br>
-          TheJIT->removeModule(H);<br>
-        }<br>
-<br>
-If parsing and codegen succeeed, the next step is to add the module containing<br>
-the top-level expression to the JIT. We do this by calling addModule, which<br>
-triggers code generation for all the functions in the module, and returns a<br>
-handle that can be used to remove the module from the JIT later. Once the module<br>
-has been added to the JIT it can no longer be modified, so we also open a new<br>
-module to hold subsequent code by calling ``InitializeModuleAndPassManager()``.<br>
-<br>
-Once we've added the module to the JIT we need to get a pointer to the final<br>
-generated code. We do this by calling the JIT's findSymbol method, and passing<br>
-the name of the top-level expression function: ``__anon_expr``. Since we just<br>
-added this function, we assert that findSymbol returned a result.<br>
-<br>
-Next, we get the in-memory address of the ``__anon_expr`` function by calling<br>
-``getAddress()`` on the symbol. Recall that we compile top-level expressions<br>
-into a self-contained LLVM function that takes no arguments and returns the<br>
-computed double. Because the LLVM JIT compiler matches the native platform ABI,<br>
-this means that you can just cast the result pointer to a function pointer of<br>
-that type and call it directly. This means, there is no difference between JIT<br>
-compiled code and native machine code that is statically linked into your<br>
-application.<br>
-<br>
-Finally, since we don't support re-evaluation of top-level expressions, we<br>
-remove the module from the JIT when we're done to free the associated memory.<br>
-Recall, however, that the module we created a few lines earlier (via<br>
-``InitializeModuleAndPassManager``) is still open and waiting for new code to be<br>
-added.<br>
-<br>
-With just these two changes, lets see how Kaleidoscope works now!<br>
-<br>
-::<br>
-<br>
-    ready> 4+5;<br>
-    Read top-level expression:<br>
-    define double @0() {<br>
-    entry:<br>
-      ret double 9.000000e+00<br>
-    }<br>
-<br>
-    Evaluated to 9.000000<br>
-<br>
-Well this looks like it is basically working. The dump of the function<br>
-shows the "no argument function that always returns double" that we<br>
-synthesize for each top-level expression that is typed in. This<br>
-demonstrates very basic functionality, but can we do more?<br>
-<br>
-::<br>
-<br>
-    ready> def testfunc(x y) x + y*2;<br>
-    Read function definition:<br>
-    define double @testfunc(double %x, double %y) {<br>
-    entry:<br>
-      %multmp = fmul double %y, 2.000000e+00<br>
-      %addtmp = fadd double %multmp, %x<br>
-      ret double %addtmp<br>
-    }<br>
-<br>
-    ready> testfunc(4, 10);<br>
-    Read top-level expression:<br>
-    define double @1() {<br>
-    entry:<br>
-      %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01)<br>
-      ret double %calltmp<br>
-    }<br>
-<br>
-    Evaluated to 24.000000<br>
-<br>
-    ready> testfunc(5, 10);<br>
-    ready> LLVM ERROR: Program used external function 'testfunc' which could not be resolved!<br>
-<br>
-<br>
-Function definitions and calls also work, but something went very wrong on that<br>
-last line. The call looks valid, so what happened? As you may have guessed from<br>
-the the API a Module is a unit of allocation for the JIT, and testfunc was part<br>
-of the same module that contained anonymous expression. When we removed that<br>
-module from the JIT to free the memory for the anonymous expression, we deleted<br>
-the definition of ``testfunc`` along with it. Then, when we tried to call<br>
-testfunc a second time, the JIT could no longer find it.<br>
-<br>
-The easiest way to fix this is to put the anonymous expression in a separate<br>
-module from the rest of the function definitions. The JIT will happily resolve<br>
-function calls across module boundaries, as long as each of the functions called<br>
-has a prototype, and is added to the JIT before it is called. By putting the<br>
-anonymous expression in a different module we can delete it without affecting<br>
-the rest of the functions.<br>
-<br>
-In fact, we're going to go a step further and put every function in its own<br>
-module. Doing so allows us to exploit a useful property of the KaleidoscopeJIT<br>
-that will make our environment more REPL-like: Functions can be added to the<br>
-JIT more than once (unlike a module where every function must have a unique<br>
-definition). When you look up a symbol in KaleidoscopeJIT it will always return<br>
-the most recent definition:<br>
-<br>
-::<br>
-<br>
-    ready> def foo(x) x + 1;<br>
-    Read function definition:<br>
-    define double @foo(double %x) {<br>
-    entry:<br>
-      %addtmp = fadd double %x, 1.000000e+00<br>
-      ret double %addtmp<br>
-    }<br>
-<br>
-    ready> foo(2);<br>
-    Evaluated to 3.000000<br>
-<br>
-    ready> def foo(x) x + 2;<br>
-    define double @foo(double %x) {<br>
-    entry:<br>
-      %addtmp = fadd double %x, 2.000000e+00<br>
-      ret double %addtmp<br>
-    }<br>
-<br>
-    ready> foo(2);<br>
-    Evaluated to 4.000000<br>
-<br>
-<br>
-To allow each function to live in its own module we'll need a way to<br>
-re-generate previous function declarations into each new module we open:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    static std::unique_ptr<KaleidoscopeJIT> TheJIT;<br>
-<br>
-    ...<br>
-<br>
-    Function *getFunction(std::string Name) {<br>
-      // First, see if the function has already been added to the current module.<br>
-      if (auto *F = TheModule->getFunction(Name))<br>
-        return F;<br>
-<br>
-      // If not, check whether we can codegen the declaration from some existing<br>
-      // prototype.<br>
-      auto FI = FunctionProtos.find(Name);<br>
-      if (FI != FunctionProtos.end())<br>
-        return FI->second->codegen();<br>
-<br>
-      // If no existing prototype exists, return null.<br>
-      return nullptr;<br>
-    }<br>
-<br>
-    ...<br>
-<br>
-    Value *CallExprAST::codegen() {<br>
-      // Look up the name in the global module table.<br>
-      Function *CalleeF = getFunction(Callee);<br>
-<br>
-    ...<br>
-<br>
-    Function *FunctionAST::codegen() {<br>
-      // Transfer ownership of the prototype to the FunctionProtos map, but keep a<br>
-      // reference to it for use below.<br>
-      auto &P = *Proto;<br>
-      FunctionProtos[Proto->getName()] = std::move(Proto);<br>
-      Function *TheFunction = getFunction(P.getName());<br>
-      if (!TheFunction)<br>
-        return nullptr;<br>
-<br>
-<br>
-To enable this, we'll start by adding a new global, ``FunctionProtos``, that<br>
-holds the most recent prototype for each function. We'll also add a convenience<br>
-method, ``getFunction()``, to replace calls to ``TheModule->getFunction()``.<br>
-Our convenience method searches ``TheModule`` for an existing function<br>
-declaration, falling back to generating a new declaration from FunctionProtos if<br>
-it doesn't find one. In ``CallExprAST::codegen()`` we just need to replace the<br>
-call to ``TheModule->getFunction()``. In ``FunctionAST::codegen()`` we need to<br>
-update the FunctionProtos map first, then call ``getFunction()``. With this<br>
-done, we can always obtain a function declaration in the current module for any<br>
-previously declared function.<br>
-<br>
-We also need to update HandleDefinition and HandleExtern:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    static void HandleDefinition() {<br>
-      if (auto FnAST = ParseDefinition()) {<br>
-        if (auto *FnIR = FnAST->codegen()) {<br>
-          fprintf(stderr, "Read function definition:");<br>
-          FnIR->dump();<br>
-          TheJIT->addModule(std::move(TheModule));<br>
-          InitializeModuleAndPassManager();<br>
-        }<br>
-      } else {<br>
-        // Skip token for error recovery.<br>
-         getNextToken();<br>
-      }<br>
-    }<br>
-<br>
-    static void HandleExtern() {<br>
-      if (auto ProtoAST = ParseExtern()) {<br>
-        if (auto *FnIR = ProtoAST->codegen()) {<br>
-          fprintf(stderr, "Read extern: ");<br>
-          FnIR->dump();<br>
-          FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);<br>
-        }<br>
-      } else {<br>
-        // Skip token for error recovery.<br>
-        getNextToken();<br>
-      }<br>
-    }<br>
-<br>
-In HandleDefinition, we add two lines to transfer the newly defined function to<br>
-the JIT and open a new module. In HandleExtern, we just need to add one line to<br>
-add the prototype to FunctionProtos.<br>
-<br>
-With these changes made, lets try our REPL again (I removed the dump of the<br>
-anonymous functions this time, you should get the idea by now :) :<br>
-<br>
-::<br>
-<br>
-    ready> def foo(x) x + 1;<br>
-    ready> foo(2);<br>
-    Evaluated to 3.000000<br>
-<br>
-    ready> def foo(x) x + 2;<br>
-    ready> foo(2);<br>
-    Evaluated to 4.000000<br>
-<br>
-It works!<br>
-<br>
-Even with this simple code, we get some surprisingly powerful capabilities -<br>
-check this out:<br>
-<br>
-::<br>
-<br>
-    ready> extern sin(x);<br>
-    Read extern:<br>
-    declare double @sin(double)<br>
-<br>
-    ready> extern cos(x);<br>
-    Read extern:<br>
-    declare double @cos(double)<br>
-<br>
-    ready> sin(1.0);<br>
-    Read top-level expression:<br>
-    define double @2() {<br>
-    entry:<br>
-      ret double 0x3FEAED548F090CEE<br>
-    }<br>
-<br>
-    Evaluated to 0.841471<br>
-<br>
-    ready> def foo(x) sin(x)*sin(x) + cos(x)*cos(x);<br>
-    Read function definition:<br>
-    define double @foo(double %x) {<br>
-    entry:<br>
-      %calltmp = call double @sin(double %x)<br>
-      %multmp = fmul double %calltmp, %calltmp<br>
-      %calltmp2 = call double @cos(double %x)<br>
-      %multmp4 = fmul double %calltmp2, %calltmp2<br>
-      %addtmp = fadd double %multmp, %multmp4<br>
-      ret double %addtmp<br>
-    }<br>
-<br>
-    ready> foo(4.0);<br>
-    Read top-level expression:<br>
-    define double @3() {<br>
-    entry:<br>
-      %calltmp = call double @foo(double 4.000000e+00)<br>
-      ret double %calltmp<br>
-    }<br>
-<br>
-    Evaluated to 1.000000<br>
-<br>
-Whoa, how does the JIT know about sin and cos? The answer is surprisingly<br>
-simple: The KaleidoscopeJIT has a straightforward symbol resolution rule that<br>
-it uses to find symbols that aren't available in any given module: First<br>
-it searches all the modules that have already been added to the JIT, from the<br>
-most recent to the oldest, to find the newest definition. If no definition is<br>
-found inside the JIT, it falls back to calling "``dlsym("sin")``" on the<br>
-Kaleidoscope process itself. Since "``sin``" is defined within the JIT's<br>
-address space, it simply patches up calls in the module to call the libm<br>
-version of ``sin`` directly.<br>
-<br>
-In the future we'll see how tweaking this symbol resolution rule can be used to<br>
-enable all sorts of useful features, from security (restricting the set of<br>
-symbols available to JIT'd code), to dynamic code generation based on symbol<br>
-names, and even lazy compilation.<br>
-<br>
-One immediate benefit of the symbol resolution rule is that we can now extend<br>
-the language by writing arbitrary C++ code to implement operations. For example,<br>
-if we add:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// putchard - putchar that takes a double and returns 0.<br>
-    extern "C" double putchard(double X) {<br>
-      fputc((char)X, stderr);<br>
-      return 0;<br>
-    }<br>
-<br>
-Now we can produce simple output to the console by using things like:<br>
-"``extern putchard(x); putchard(120);``", which prints a lowercase 'x'<br>
-on the console (120 is the ASCII code for 'x'). Similar code could be<br>
-used to implement file I/O, console input, and many other capabilities<br>
-in Kaleidoscope.<br>
-<br>
-This completes the JIT and optimizer chapter of the Kaleidoscope<br>
-tutorial. At this point, we can compile a non-Turing-complete<br>
-programming language, optimize and JIT compile it in a user-driven way.<br>
-Next up we'll look into `extending the language with control flow<br>
-constructs <LangImpl5.html>`_, tackling some interesting LLVM IR issues<br>
-along the way.<br>
-<br>
-Full Code Listing<br>
-=================<br>
-<br>
-Here is the complete code listing for our running example, enhanced with<br>
-the LLVM JIT and optimizer. To build this example, use:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    # Compile<br>
-    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
-    # Run<br>
-    ./toy<br>
-<br>
-If you are compiling this on Linux, make sure to add the "-rdynamic"<br>
-option as well. This makes sure that the external functions are resolved<br>
-properly at runtime.<br>
-<br>
-Here is the code:<br>
-<br>
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter4/toy.cpp<br>
-   :language: c++<br>
-<br>
-`Next: Extending the language: control flow <LangImpl5.html>`_<br>
-<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl5-cfg.png<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl5-cfg.png?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl5-cfg.png?rev=274440&view=auto</a><br>
==============================================================================<br>
Binary file - no diff available.<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl5.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl5.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl5.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl5.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl5.rst (removed)<br>
@@ -1,790 +0,0 @@<br>
-==================================================<br>
-Kaleidoscope: Extending the Language: Control Flow<br>
-==================================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Chapter 5 Introduction<br>
-======================<br>
-<br>
-Welcome to Chapter 5 of the "`Implementing a language with<br>
-LLVM <index.html>`_" tutorial. Parts 1-4 described the implementation of<br>
-the simple Kaleidoscope language and included support for generating<br>
-LLVM IR, followed by optimizations and a JIT compiler. Unfortunately, as<br>
-presented, Kaleidoscope is mostly useless: it has no control flow other<br>
-than call and return. This means that you can't have conditional<br>
-branches in the code, significantly limiting its power. In this episode<br>
-of "build that compiler", we'll extend Kaleidoscope to have an<br>
-if/then/else expression plus a simple 'for' loop.<br>
-<br>
-If/Then/Else<br>
-============<br>
-<br>
-Extending Kaleidoscope to support if/then/else is quite straightforward.<br>
-It basically requires adding support for this "new" concept to the<br>
-lexer, parser, AST, and LLVM code emitter. This example is nice, because<br>
-it shows how easy it is to "grow" a language over time, incrementally<br>
-extending it as new ideas are discovered.<br>
-<br>
-Before we get going on "how" we add this extension, lets talk about<br>
-"what" we want. The basic idea is that we want to be able to write this<br>
-sort of thing:<br>
-<br>
-::<br>
-<br>
-    def fib(x)<br>
-      if x < 3 then<br>
-        1<br>
-      else<br>
-        fib(x-1)+fib(x-2);<br>
-<br>
-In Kaleidoscope, every construct is an expression: there are no<br>
-statements. As such, the if/then/else expression needs to return a value<br>
-like any other. Since we're using a mostly functional form, we'll have<br>
-it evaluate its conditional, then return the 'then' or 'else' value<br>
-based on how the condition was resolved. This is very similar to the C<br>
-"?:" expression.<br>
-<br>
-The semantics of the if/then/else expression is that it evaluates the<br>
-condition to a boolean equality value: 0.0 is considered to be false and<br>
-everything else is considered to be true. If the condition is true, the<br>
-first subexpression is evaluated and returned, if the condition is<br>
-false, the second subexpression is evaluated and returned. Since<br>
-Kaleidoscope allows side-effects, this behavior is important to nail<br>
-down.<br>
-<br>
-Now that we know what we "want", lets break this down into its<br>
-constituent pieces.<br>
-<br>
-Lexer Extensions for If/Then/Else<br>
----------------------------------<br>
-<br>
-The lexer extensions are straightforward. First we add new enum values<br>
-for the relevant tokens:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // control<br>
-      tok_if = -6,<br>
-      tok_then = -7,<br>
-      tok_else = -8,<br>
-<br>
-Once we have that, we recognize the new keywords in the lexer. This is<br>
-pretty simple stuff:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-        ...<br>
-        if (IdentifierStr == "def")<br>
-          return tok_def;<br>
-        if (IdentifierStr == "extern")<br>
-          return tok_extern;<br>
-        if (IdentifierStr == "if")<br>
-          return tok_if;<br>
-        if (IdentifierStr == "then")<br>
-          return tok_then;<br>
-        if (IdentifierStr == "else")<br>
-          return tok_else;<br>
-        return tok_identifier;<br>
-<br>
-AST Extensions for If/Then/Else<br>
--------------------------------<br>
-<br>
-To represent the new expression we add a new AST node for it:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// IfExprAST - Expression class for if/then/else.<br>
-    class IfExprAST : public ExprAST {<br>
-      std::unique_ptr<ExprAST> Cond, Then, Else;<br>
-<br>
-    public:<br>
-      IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,<br>
-                std::unique_ptr<ExprAST> Else)<br>
-        : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}<br>
-      virtual Value *codegen();<br>
-    };<br>
-<br>
-The AST node just has pointers to the various subexpressions.<br>
-<br>
-Parser Extensions for If/Then/Else<br>
-----------------------------------<br>
-<br>
-Now that we have the relevant tokens coming from the lexer and we have<br>
-the AST node to build, our parsing logic is relatively straightforward.<br>
-First we define a new parsing function:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// ifexpr ::= 'if' expression 'then' expression 'else' expression<br>
-    static std::unique_ptr<ExprAST> ParseIfExpr() {<br>
-      getNextToken();  // eat the if.<br>
-<br>
-      // condition.<br>
-      auto Cond = ParseExpression();<br>
-      if (!Cond)<br>
-        return nullptr;<br>
-<br>
-      if (CurTok != tok_then)<br>
-        return LogError("expected then");<br>
-      getNextToken();  // eat the then<br>
-<br>
-      auto Then = ParseExpression();<br>
-      if (!Then)<br>
-        return nullptr;<br>
-<br>
-      if (CurTok != tok_else)<br>
-        return LogError("expected else");<br>
-<br>
-      getNextToken();<br>
-<br>
-      auto Else = ParseExpression();<br>
-      if (!Else)<br>
-        return nullptr;<br>
-<br>
-      return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),<br>
-                                          std::move(Else));<br>
-    }<br>
-<br>
-Next we hook it up as a primary expression:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    static std::unique_ptr<ExprAST> ParsePrimary() {<br>
-      switch (CurTok) {<br>
-      default:<br>
-        return LogError("unknown token when expecting an expression");<br>
-      case tok_identifier:<br>
-        return ParseIdentifierExpr();<br>
-      case tok_number:<br>
-        return ParseNumberExpr();<br>
-      case '(':<br>
-        return ParseParenExpr();<br>
-      case tok_if:<br>
-        return ParseIfExpr();<br>
-      }<br>
-    }<br>
-<br>
-LLVM IR for If/Then/Else<br>
-------------------------<br>
-<br>
-Now that we have it parsing and building the AST, the final piece is<br>
-adding LLVM code generation support. This is the most interesting part<br>
-of the if/then/else example, because this is where it starts to<br>
-introduce new concepts. All of the code above has been thoroughly<br>
-described in previous chapters.<br>
-<br>
-To motivate the code we want to produce, lets take a look at a simple<br>
-example. Consider:<br>
-<br>
-::<br>
-<br>
-    extern foo();<br>
-    extern bar();<br>
-    def baz(x) if x then foo() else bar();<br>
-<br>
-If you disable optimizations, the code you'll (soon) get from<br>
-Kaleidoscope looks like this:<br>
-<br>
-.. code-block:: llvm<br>
-<br>
-    declare double @foo()<br>
-<br>
-    declare double @bar()<br>
-<br>
-    define double @baz(double %x) {<br>
-    entry:<br>
-      %ifcond = fcmp one double %x, 0.000000e+00<br>
-      br i1 %ifcond, label %then, label %else<br>
-<br>
-    then:       ; preds = %entry<br>
-      %calltmp = call double @foo()<br>
-      br label %ifcont<br>
-<br>
-    else:       ; preds = %entry<br>
-      %calltmp1 = call double @bar()<br>
-      br label %ifcont<br>
-<br>
-    ifcont:     ; preds = %else, %then<br>
-      %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]<br>
-      ret double %iftmp<br>
-    }<br>
-<br>
-To visualize the control flow graph, you can use a nifty feature of the<br>
-LLVM '`opt <<a href="http://llvm.org/cmds/opt.html" rel="noreferrer" target="_blank">http://llvm.org/cmds/opt.html</a>>`_' tool. If you put this LLVM<br>
-IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a<br>
-window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll<br>
-see this graph:<br>
-<br>
-.. figure:: LangImpl5-cfg.png<br>
-   :align: center<br>
-   :alt: Example CFG<br>
-<br>
-   Example CFG<br>
-<br>
-Another way to get this is to call "``F->viewCFG()``" or<br>
-"``F->viewCFGOnly()``" (where F is a "``Function*``") either by<br>
-inserting actual calls into the code and recompiling or by calling these<br>
-in the debugger. LLVM has many nice features for visualizing various<br>
-graphs.<br>
-<br>
-Getting back to the generated code, it is fairly simple: the entry block<br>
-evaluates the conditional expression ("x" in our case here) and compares<br>
-the result to 0.0 with the "``fcmp one``" instruction ('one' is "Ordered<br>
-and Not Equal"). Based on the result of this expression, the code jumps<br>
-to either the "then" or "else" blocks, which contain the expressions for<br>
-the true/false cases.<br>
-<br>
-Once the then/else blocks are finished executing, they both branch back<br>
-to the 'ifcont' block to execute the code that happens after the<br>
-if/then/else. In this case the only thing left to do is to return to the<br>
-caller of the function. The question then becomes: how does the code<br>
-know which expression to return?<br>
-<br>
-The answer to this question involves an important SSA operation: the<br>
-`Phi<br>
-operation <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_.<br>
-If you're not familiar with SSA, `the wikipedia<br>
-article <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_<br>
-is a good introduction and there are various other introductions to it<br>
-available on your favorite search engine. The short version is that<br>
-"execution" of the Phi operation requires "remembering" which block<br>
-control came from. The Phi operation takes on the value corresponding to<br>
-the input control block. In this case, if control comes in from the<br>
-"then" block, it gets the value of "calltmp". If control comes from the<br>
-"else" block, it gets the value of "calltmp1".<br>
-<br>
-At this point, you are probably starting to think "Oh no! This means my<br>
-simple and elegant front-end will have to start generating SSA form in<br>
-order to use LLVM!". Fortunately, this is not the case, and we strongly<br>
-advise *not* implementing an SSA construction algorithm in your<br>
-front-end unless there is an amazingly good reason to do so. In<br>
-practice, there are two sorts of values that float around in code<br>
-written for your average imperative programming language that might need<br>
-Phi nodes:<br>
-<br>
-#. Code that involves user variables: ``x = 1; x = x + 1;``<br>
-#. Values that are implicit in the structure of your AST, such as the<br>
-   Phi node in this case.<br>
-<br>
-In `Chapter 7 <LangImpl7.html>`_ of this tutorial ("mutable variables"),<br>
-we'll talk about #1 in depth. For now, just believe me that you don't<br>
-need SSA construction to handle this case. For #2, you have the choice<br>
-of using the techniques that we will describe for #1, or you can insert<br>
-Phi nodes directly, if convenient. In this case, it is really<br>
-easy to generate the Phi node, so we choose to do it directly.<br>
-<br>
-Okay, enough of the motivation and overview, lets generate code!<br>
-<br>
-Code Generation for If/Then/Else<br>
---------------------------------<br>
-<br>
-In order to generate code for this, we implement the ``codegen`` method<br>
-for ``IfExprAST``:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *IfExprAST::codegen() {<br>
-      Value *CondV = Cond->codegen();<br>
-      if (!CondV)<br>
-        return nullptr;<br>
-<br>
-      // Convert condition to a bool by comparing equal to 0.0.<br>
-      CondV = Builder.CreateFCmpONE(<br>
-          CondV, ConstantFP::get(LLVMContext, APFloat(0.0)), "ifcond");<br>
-<br>
-This code is straightforward and similar to what we saw before. We emit<br>
-the expression for the condition, then compare that value to zero to get<br>
-a truth value as a 1-bit (bool) value.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      Function *TheFunction = Builder.GetInsertBlock()->getParent();<br>
-<br>
-      // Create blocks for the then and else cases.  Insert the 'then' block at the<br>
-      // end of the function.<br>
-      BasicBlock *ThenBB =<br>
-          BasicBlock::Create(LLVMContext, "then", TheFunction);<br>
-      BasicBlock *ElseBB = BasicBlock::Create(LLVMContext, "else");<br>
-      BasicBlock *MergeBB = BasicBlock::Create(LLVMContext, "ifcont");<br>
-<br>
-      Builder.CreateCondBr(CondV, ThenBB, ElseBB);<br>
-<br>
-This code creates the basic blocks that are related to the if/then/else<br>
-statement, and correspond directly to the blocks in the example above.<br>
-The first line gets the current Function object that is being built. It<br>
-gets this by asking the builder for the current BasicBlock, and asking<br>
-that block for its "parent" (the function it is currently embedded<br>
-into).<br>
-<br>
-Once it has that, it creates three blocks. Note that it passes<br>
-"TheFunction" into the constructor for the "then" block. This causes the<br>
-constructor to automatically insert the new block into the end of the<br>
-specified function. The other two blocks are created, but aren't yet<br>
-inserted into the function.<br>
-<br>
-Once the blocks are created, we can emit the conditional branch that<br>
-chooses between them. Note that creating new blocks does not implicitly<br>
-affect the IRBuilder, so it is still inserting into the block that the<br>
-condition went into. Also note that it is creating a branch to the<br>
-"then" block and the "else" block, even though the "else" block isn't<br>
-inserted into the function yet. This is all ok: it is the standard way<br>
-that LLVM supports forward references.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Emit then value.<br>
-      Builder.SetInsertPoint(ThenBB);<br>
-<br>
-      Value *ThenV = Then->codegen();<br>
-      if (!ThenV)<br>
-        return nullptr;<br>
-<br>
-      Builder.CreateBr(MergeBB);<br>
-      // Codegen of 'Then' can change the current block, update ThenBB for the PHI.<br>
-      ThenBB = Builder.GetInsertBlock();<br>
-<br>
-After the conditional branch is inserted, we move the builder to start<br>
-inserting into the "then" block. Strictly speaking, this call moves the<br>
-insertion point to be at the end of the specified block. However, since<br>
-the "then" block is empty, it also starts out by inserting at the<br>
-beginning of the block. :)<br>
-<br>
-Once the insertion point is set, we recursively codegen the "then"<br>
-expression from the AST. To finish off the "then" block, we create an<br>
-unconditional branch to the merge block. One interesting (and very<br>
-important) aspect of the LLVM IR is that it `requires all basic blocks<br>
-to be "terminated" <../LangRef.html#functionstructure>`_ with a `control<br>
-flow instruction <../LangRef.html#terminators>`_ such as return or<br>
-branch. This means that all control flow, *including fall throughs* must<br>
-be made explicit in the LLVM IR. If you violate this rule, the verifier<br>
-will emit an error.<br>
-<br>
-The final line here is quite subtle, but is very important. The basic<br>
-issue is that when we create the Phi node in the merge block, we need to<br>
-set up the block/value pairs that indicate how the Phi will work.<br>
-Importantly, the Phi node expects to have an entry for each predecessor<br>
-of the block in the CFG. Why then, are we getting the current block when<br>
-we just set it to ThenBB 5 lines above? The problem is that the "Then"<br>
-expression may actually itself change the block that the Builder is<br>
-emitting into if, for example, it contains a nested "if/then/else"<br>
-expression. Because calling ``codegen()`` recursively could arbitrarily change<br>
-the notion of the current block, we are required to get an up-to-date<br>
-value for code that will set up the Phi node.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Emit else block.<br>
-      TheFunction->getBasicBlockList().push_back(ElseBB);<br>
-      Builder.SetInsertPoint(ElseBB);<br>
-<br>
-      Value *ElseV = Else->codegen();<br>
-      if (!ElseV)<br>
-        return nullptr;<br>
-<br>
-      Builder.CreateBr(MergeBB);<br>
-      // codegen of 'Else' can change the current block, update ElseBB for the PHI.<br>
-      ElseBB = Builder.GetInsertBlock();<br>
-<br>
-Code generation for the 'else' block is basically identical to codegen<br>
-for the 'then' block. The only significant difference is the first line,<br>
-which adds the 'else' block to the function. Recall previously that the<br>
-'else' block was created, but not added to the function. Now that the<br>
-'then' and 'else' blocks are emitted, we can finish up with the merge<br>
-code:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Emit merge block.<br>
-      TheFunction->getBasicBlockList().push_back(MergeBB);<br>
-      Builder.SetInsertPoint(MergeBB);<br>
-      PHINode *PN =<br>
-        Builder.CreatePHI(Type::getDoubleTy(LLVMContext), 2, "iftmp");<br>
-<br>
-      PN->addIncoming(ThenV, ThenBB);<br>
-      PN->addIncoming(ElseV, ElseBB);<br>
-      return PN;<br>
-    }<br>
-<br>
-The first two lines here are now familiar: the first adds the "merge"<br>
-block to the Function object (it was previously floating, like the else<br>
-block above). The second changes the insertion point so that newly<br>
-created code will go into the "merge" block. Once that is done, we need<br>
-to create the PHI node and set up the block/value pairs for the PHI.<br>
-<br>
-Finally, the CodeGen function returns the phi node as the value computed<br>
-by the if/then/else expression. In our example above, this returned<br>
-value will feed into the code for the top-level function, which will<br>
-create the return instruction.<br>
-<br>
-Overall, we now have the ability to execute conditional code in<br>
-Kaleidoscope. With this extension, Kaleidoscope is a fairly complete<br>
-language that can calculate a wide variety of numeric functions. Next up<br>
-we'll add another useful expression that is familiar from non-functional<br>
-languages...<br>
-<br>
-'for' Loop Expression<br>
-=====================<br>
-<br>
-Now that we know how to add basic control flow constructs to the<br>
-language, we have the tools to add more powerful things. Lets add<br>
-something more aggressive, a 'for' expression:<br>
-<br>
-::<br>
-<br>
-     extern putchard(char)<br>
-     def printstar(n)<br>
-       for i = 1, i < n, 1.0 in<br>
-         putchard(42);  # ascii 42 = '*'<br>
-<br>
-     # print 100 '*' characters<br>
-     printstar(100);<br>
-<br>
-This expression defines a new variable ("i" in this case) which iterates<br>
-from a starting value, while the condition ("i < n" in this case) is<br>
-true, incrementing by an optional step value ("1.0" in this case). If<br>
-the step value is omitted, it defaults to 1.0. While the loop is true,<br>
-it executes its body expression. Because we don't have anything better<br>
-to return, we'll just define the loop as always returning 0.0. In the<br>
-future when we have mutable variables, it will get more useful.<br>
-<br>
-As before, lets talk about the changes that we need to Kaleidoscope to<br>
-support this.<br>
-<br>
-Lexer Extensions for the 'for' Loop<br>
------------------------------------<br>
-<br>
-The lexer extensions are the same sort of thing as for if/then/else:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      ... in enum Token ...<br>
-      // control<br>
-      tok_if = -6, tok_then = -7, tok_else = -8,<br>
-      tok_for = -9, tok_in = -10<br>
-<br>
-      ... in gettok ...<br>
-      if (IdentifierStr == "def")<br>
-        return tok_def;<br>
-      if (IdentifierStr == "extern")<br>
-        return tok_extern;<br>
-      if (IdentifierStr == "if")<br>
-        return tok_if;<br>
-      if (IdentifierStr == "then")<br>
-        return tok_then;<br>
-      if (IdentifierStr == "else")<br>
-        return tok_else;<br>
-      if (IdentifierStr == "for")<br>
-        return tok_for;<br>
-      if (IdentifierStr == "in")<br>
-        return tok_in;<br>
-      return tok_identifier;<br>
-<br>
-AST Extensions for the 'for' Loop<br>
----------------------------------<br>
-<br>
-The AST node is just as simple. It basically boils down to capturing the<br>
-variable name and the constituent expressions in the node.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// ForExprAST - Expression class for for/in.<br>
-    class ForExprAST : public ExprAST {<br>
-      std::string VarName;<br>
-      std::unique_ptr<ExprAST> Start, End, Step, Body;<br>
-<br>
-    public:<br>
-      ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,<br>
-                 std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,<br>
-                 std::unique_ptr<ExprAST> Body)<br>
-        : VarName(VarName), Start(std::move(Start)), End(std::move(End)),<br>
-          Step(std::move(Step)), Body(std::move(Body)) {}<br>
-      virtual Value *codegen();<br>
-    };<br>
-<br>
-Parser Extensions for the 'for' Loop<br>
-------------------------------------<br>
-<br>
-The parser code is also fairly standard. The only interesting thing here<br>
-is handling of the optional step value. The parser code handles it by<br>
-checking to see if the second comma is present. If not, it sets the step<br>
-value to null in the AST node:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression<br>
-    static std::unique_ptr<ExprAST> ParseForExpr() {<br>
-      getNextToken();  // eat the for.<br>
-<br>
-      if (CurTok != tok_identifier)<br>
-        return LogError("expected identifier after for");<br>
-<br>
-      std::string IdName = IdentifierStr;<br>
-      getNextToken();  // eat identifier.<br>
-<br>
-      if (CurTok != '=')<br>
-        return LogError("expected '=' after for");<br>
-      getNextToken();  // eat '='.<br>
-<br>
-<br>
-      auto Start = ParseExpression();<br>
-      if (!Start)<br>
-        return nullptr;<br>
-      if (CurTok != ',')<br>
-        return LogError("expected ',' after for start value");<br>
-      getNextToken();<br>
-<br>
-      auto End = ParseExpression();<br>
-      if (!End)<br>
-        return nullptr;<br>
-<br>
-      // The step value is optional.<br>
-      std::unique_ptr<ExprAST> Step;<br>
-      if (CurTok == ',') {<br>
-        getNextToken();<br>
-        Step = ParseExpression();<br>
-        if (!Step)<br>
-          return nullptr;<br>
-      }<br>
-<br>
-      if (CurTok != tok_in)<br>
-        return LogError("expected 'in' after for");<br>
-      getNextToken();  // eat 'in'.<br>
-<br>
-      auto Body = ParseExpression();<br>
-      if (!Body)<br>
-        return nullptr;<br>
-<br>
-      return llvm::make_unique<ForExprAST>(IdName, std::move(Start),<br>
-                                           std::move(End), std::move(Step),<br>
-                                           std::move(Body));<br>
-    }<br>
-<br>
-LLVM IR for the 'for' Loop<br>
---------------------------<br>
-<br>
-Now we get to the good part: the LLVM IR we want to generate for this<br>
-thing. With the simple example above, we get this LLVM IR (note that<br>
-this dump is generated with optimizations disabled for clarity):<br>
-<br>
-.. code-block:: llvm<br>
-<br>
-    declare double @putchard(double)<br>
-<br>
-    define double @printstar(double %n) {<br>
-    entry:<br>
-      ; initial value = 1.0 (inlined into phi)<br>
-      br label %loop<br>
-<br>
-    loop:       ; preds = %loop, %entry<br>
-      %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]<br>
-      ; body<br>
-      %calltmp = call double @putchard(double 4.200000e+01)<br>
-      ; increment<br>
-      %nextvar = fadd double %i, 1.000000e+00<br>
-<br>
-      ; termination test<br>
-      %cmptmp = fcmp ult double %i, %n<br>
-      %booltmp = uitofp i1 %cmptmp to double<br>
-      %loopcond = fcmp one double %booltmp, 0.000000e+00<br>
-      br i1 %loopcond, label %loop, label %afterloop<br>
-<br>
-    afterloop:      ; preds = %loop<br>
-      ; loop always returns 0.0<br>
-      ret double 0.000000e+00<br>
-    }<br>
-<br>
-This loop contains all the same constructs we saw before: a phi node,<br>
-several expressions, and some basic blocks. Lets see how this fits<br>
-together.<br>
-<br>
-Code Generation for the 'for' Loop<br>
-----------------------------------<br>
-<br>
-The first part of codegen is very simple: we just output the start<br>
-expression for the loop value:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *ForExprAST::codegen() {<br>
-      // Emit the start code first, without 'variable' in scope.<br>
-      Value *StartVal = Start->codegen();<br>
-      if (StartVal == 0) return 0;<br>
-<br>
-With this out of the way, the next step is to set up the LLVM basic<br>
-block for the start of the loop body. In the case above, the whole loop<br>
-body is one block, but remember that the body code itself could consist<br>
-of multiple blocks (e.g. if it contains an if/then/else or a for/in<br>
-expression).<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Make the new basic block for the loop header, inserting after current<br>
-      // block.<br>
-      Function *TheFunction = Builder.GetInsertBlock()->getParent();<br>
-      BasicBlock *PreheaderBB = Builder.GetInsertBlock();<br>
-      BasicBlock *LoopBB =<br>
-          BasicBlock::Create(LLVMContext, "loop", TheFunction);<br>
-<br>
-      // Insert an explicit fall through from the current block to the LoopBB.<br>
-      Builder.CreateBr(LoopBB);<br>
-<br>
-This code is similar to what we saw for if/then/else. Because we will<br>
-need it to create the Phi node, we remember the block that falls through<br>
-into the loop. Once we have that, we create the actual block that starts<br>
-the loop and create an unconditional branch for the fall-through between<br>
-the two blocks.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Start insertion in LoopBB.<br>
-      Builder.SetInsertPoint(LoopBB);<br>
-<br>
-      // Start the PHI node with an entry for Start.<br>
-      PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(LLVMContext),<br>
-                                            2, VarName.c_str());<br>
-      Variable->addIncoming(StartVal, PreheaderBB);<br>
-<br>
-Now that the "preheader" for the loop is set up, we switch to emitting<br>
-code for the loop body. To begin with, we move the insertion point and<br>
-create the PHI node for the loop induction variable. Since we already<br>
-know the incoming value for the starting value, we add it to the Phi<br>
-node. Note that the Phi will eventually get a second value for the<br>
-backedge, but we can't set it up yet (because it doesn't exist!).<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Within the loop, the variable is defined equal to the PHI node.  If it<br>
-      // shadows an existing variable, we have to restore it, so save it now.<br>
-      Value *OldVal = NamedValues[VarName];<br>
-      NamedValues[VarName] = Variable;<br>
-<br>
-      // Emit the body of the loop.  This, like any other expr, can change the<br>
-      // current BB.  Note that we ignore the value computed by the body, but don't<br>
-      // allow an error.<br>
-      if (!Body->codegen())<br>
-        return nullptr;<br>
-<br>
-Now the code starts to get more interesting. Our 'for' loop introduces a<br>
-new variable to the symbol table. This means that our symbol table can<br>
-now contain either function arguments or loop variables. To handle this,<br>
-before we codegen the body of the loop, we add the loop variable as the<br>
-current value for its name. Note that it is possible that there is a<br>
-variable of the same name in the outer scope. It would be easy to make<br>
-this an error (emit an error and return null if there is already an<br>
-entry for VarName) but we choose to allow shadowing of variables. In<br>
-order to handle this correctly, we remember the Value that we are<br>
-potentially shadowing in ``OldVal`` (which will be null if there is no<br>
-shadowed variable).<br>
-<br>
-Once the loop variable is set into the symbol table, the code<br>
-recursively codegen's the body. This allows the body to use the loop<br>
-variable: any references to it will naturally find it in the symbol<br>
-table.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Emit the step value.<br>
-      Value *StepVal = nullptr;<br>
-      if (Step) {<br>
-        StepVal = Step->codegen();<br>
-        if (!StepVal)<br>
-          return nullptr;<br>
-      } else {<br>
-        // If not specified, use 1.0.<br>
-        StepVal = ConstantFP::get(LLVMContext, APFloat(1.0));<br>
-      }<br>
-<br>
-      Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");<br>
-<br>
-Now that the body is emitted, we compute the next value of the iteration<br>
-variable by adding the step value, or 1.0 if it isn't present.<br>
-'``NextVar``' will be the value of the loop variable on the next<br>
-iteration of the loop.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Compute the end condition.<br>
-      Value *EndCond = End->codegen();<br>
-      if (!EndCond)<br>
-        return nullptr;<br>
-<br>
-      // Convert condition to a bool by comparing equal to 0.0.<br>
-      EndCond = Builder.CreateFCmpONE(<br>
-          EndCond, ConstantFP::get(LLVMContext, APFloat(0.0)), "loopcond");<br>
-<br>
-Finally, we evaluate the exit value of the loop, to determine whether<br>
-the loop should exit. This mirrors the condition evaluation for the<br>
-if/then/else statement.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Create the "after loop" block and insert it.<br>
-      BasicBlock *LoopEndBB = Builder.GetInsertBlock();<br>
-      BasicBlock *AfterBB =<br>
-          BasicBlock::Create(LLVMContext, "afterloop", TheFunction);<br>
-<br>
-      // Insert the conditional branch into the end of LoopEndBB.<br>
-      Builder.CreateCondBr(EndCond, LoopBB, AfterBB);<br>
-<br>
-      // Any new code will be inserted in AfterBB.<br>
-      Builder.SetInsertPoint(AfterBB);<br>
-<br>
-With the code for the body of the loop complete, we just need to finish<br>
-up the control flow for it. This code remembers the end block (for the<br>
-phi node), then creates the block for the loop exit ("afterloop"). Based<br>
-on the value of the exit condition, it creates a conditional branch that<br>
-chooses between executing the loop again and exiting the loop. Any<br>
-future code is emitted in the "afterloop" block, so it sets the<br>
-insertion position to it.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Add a new entry to the PHI node for the backedge.<br>
-      Variable->addIncoming(NextVar, LoopEndBB);<br>
-<br>
-      // Restore the unshadowed variable.<br>
-      if (OldVal)<br>
-        NamedValues[VarName] = OldVal;<br>
-      else<br>
-        NamedValues.erase(VarName);<br>
-<br>
-      // for expr always returns 0.0.<br>
-      return Constant::getNullValue(Type::getDoubleTy(LLVMContext));<br>
-    }<br>
-<br>
-The final code handles various cleanups: now that we have the "NextVar"<br>
-value, we can add the incoming value to the loop PHI node. After that,<br>
-we remove the loop variable from the symbol table, so that it isn't in<br>
-scope after the for loop. Finally, code generation of the for loop<br>
-always returns 0.0, so that is what we return from<br>
-``ForExprAST::codegen()``.<br>
-<br>
-With this, we conclude the "adding control flow to Kaleidoscope" chapter<br>
-of the tutorial. In this chapter we added two control flow constructs,<br>
-and used them to motivate a couple of aspects of the LLVM IR that are<br>
-important for front-end implementors to know. In the next chapter of our<br>
-saga, we will get a bit crazier and add `user-defined<br>
-operators <LangImpl6.html>`_ to our poor innocent language.<br>
-<br>
-Full Code Listing<br>
-=================<br>
-<br>
-Here is the complete code listing for our running example, enhanced with<br>
-the if/then/else and for expressions.. To build this example, use:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    # Compile<br>
-    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
-    # Run<br>
-    ./toy<br>
-<br>
-Here is the code:<br>
-<br>
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter5/toy.cpp<br>
-   :language: c++<br>
-<br>
-`Next: Extending the language: user-defined operators <LangImpl6.html>`_<br>
-<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl6.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl6.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl6.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl6.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl6.rst (removed)<br>
@@ -1,768 +0,0 @@<br>
-============================================================<br>
-Kaleidoscope: Extending the Language: User-defined Operators<br>
-============================================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Chapter 6 Introduction<br>
-======================<br>
-<br>
-Welcome to Chapter 6 of the "`Implementing a language with<br>
-LLVM <index.html>`_" tutorial. At this point in our tutorial, we now<br>
-have a fully functional language that is fairly minimal, but also<br>
-useful. There is still one big problem with it, however. Our language<br>
-doesn't have many useful operators (like division, logical negation, or<br>
-even any comparisons besides less-than).<br>
-<br>
-This chapter of the tutorial takes a wild digression into adding<br>
-user-defined operators to the simple and beautiful Kaleidoscope<br>
-language. This digression now gives us a simple and ugly language in<br>
-some ways, but also a powerful one at the same time. One of the great<br>
-things about creating your own language is that you get to decide what<br>
-is good or bad. In this tutorial we'll assume that it is okay to use<br>
-this as a way to show some interesting parsing techniques.<br>
-<br>
-At the end of this tutorial, we'll run through an example Kaleidoscope<br>
-application that `renders the Mandelbrot set <#kicking-the-tires>`_. This gives an<br>
-example of what you can build with Kaleidoscope and its feature set.<br>
-<br>
-User-defined Operators: the Idea<br>
-================================<br>
-<br>
-The "operator overloading" that we will add to Kaleidoscope is more<br>
-general than languages like C++. In C++, you are only allowed to<br>
-redefine existing operators: you can't programatically change the<br>
-grammar, introduce new operators, change precedence levels, etc. In this<br>
-chapter, we will add this capability to Kaleidoscope, which will let the<br>
-user round out the set of operators that are supported.<br>
-<br>
-The point of going into user-defined operators in a tutorial like this<br>
-is to show the power and flexibility of using a hand-written parser.<br>
-Thus far, the parser we have been implementing uses recursive descent<br>
-for most parts of the grammar and operator precedence parsing for the<br>
-expressions. See `Chapter 2 <LangImpl2.html>`_ for details. Without<br>
-using operator precedence parsing, it would be very difficult to allow<br>
-the programmer to introduce new operators into the grammar: the grammar<br>
-is dynamically extensible as the JIT runs.<br>
-<br>
-The two specific features we'll add are programmable unary operators<br>
-(right now, Kaleidoscope has no unary operators at all) as well as<br>
-binary operators. An example of this is:<br>
-<br>
-::<br>
-<br>
-    # Logical unary not.<br>
-    def unary!(v)<br>
-      if v then<br>
-        0<br>
-      else<br>
-        1;<br>
-<br>
-    # Define > with the same precedence as <.<br>
-    def binary> 10 (LHS RHS)<br>
-      RHS < LHS;<br>
-<br>
-    # Binary "logical or", (note that it does not "short circuit")<br>
-    def binary| 5 (LHS RHS)<br>
-      if LHS then<br>
-        1<br>
-      else if RHS then<br>
-        1<br>
-      else<br>
-        0;<br>
-<br>
-    # Define = with slightly lower precedence than relationals.<br>
-    def binary= 9 (LHS RHS)<br>
-      !(LHS < RHS | LHS > RHS);<br>
-<br>
-Many languages aspire to being able to implement their standard runtime<br>
-library in the language itself. In Kaleidoscope, we can implement<br>
-significant parts of the language in the library!<br>
-<br>
-We will break down implementation of these features into two parts:<br>
-implementing support for user-defined binary operators and adding unary<br>
-operators.<br>
-<br>
-User-defined Binary Operators<br>
-=============================<br>
-<br>
-Adding support for user-defined binary operators is pretty simple with<br>
-our current framework. We'll first add support for the unary/binary<br>
-keywords:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    enum Token {<br>
-      ...<br>
-      // operators<br>
-      tok_binary = -11,<br>
-      tok_unary = -12<br>
-    };<br>
-    ...<br>
-    static int gettok() {<br>
-    ...<br>
-        if (IdentifierStr == "for")<br>
-          return tok_for;<br>
-        if (IdentifierStr == "in")<br>
-          return tok_in;<br>
-        if (IdentifierStr == "binary")<br>
-          return tok_binary;<br>
-        if (IdentifierStr == "unary")<br>
-          return tok_unary;<br>
-        return tok_identifier;<br>
-<br>
-This just adds lexer support for the unary and binary keywords, like we<br>
-did in `previous chapters <LangImpl5.html#lexer-extensions-for-if-then-else>`_. One nice thing<br>
-about our current AST, is that we represent binary operators with full<br>
-generalisation by using their ASCII code as the opcode. For our extended<br>
-operators, we'll use this same representation, so we don't need any new<br>
-AST or parser support.<br>
-<br>
-On the other hand, we have to be able to represent the definitions of<br>
-these new operators, in the "def binary\| 5" part of the function<br>
-definition. In our grammar so far, the "name" for the function<br>
-definition is parsed as the "prototype" production and into the<br>
-``PrototypeAST`` AST node. To represent our new user-defined operators<br>
-as prototypes, we have to extend the ``PrototypeAST`` AST node like<br>
-this:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// PrototypeAST - This class represents the "prototype" for a function,<br>
-    /// which captures its argument names as well as if it is an operator.<br>
-    class PrototypeAST {<br>
-      std::string Name;<br>
-      std::vector<std::string> Args;<br>
-      bool IsOperator;<br>
-      unsigned Precedence;  // Precedence if a binary op.<br>
-<br>
-    public:<br>
-      PrototypeAST(const std::string &name, std::vector<std::string> Args,<br>
-                   bool IsOperator = false, unsigned Prec = 0)<br>
-      : Name(name), Args(std::move(Args)), IsOperator(IsOperator),<br>
-        Precedence(Prec) {}<br>
-<br>
-      bool isUnaryOp() const { return IsOperator && Args.size() == 1; }<br>
-      bool isBinaryOp() const { return IsOperator && Args.size() == 2; }<br>
-<br>
-      char getOperatorName() const {<br>
-        assert(isUnaryOp() || isBinaryOp());<br>
-        return Name[Name.size()-1];<br>
-      }<br>
-<br>
-      unsigned getBinaryPrecedence() const { return Precedence; }<br>
-<br>
-      Function *codegen();<br>
-    };<br>
-<br>
-Basically, in addition to knowing a name for the prototype, we now keep<br>
-track of whether it was an operator, and if it was, what precedence<br>
-level the operator is at. The precedence is only used for binary<br>
-operators (as you'll see below, it just doesn't apply for unary<br>
-operators). Now that we have a way to represent the prototype for a<br>
-user-defined operator, we need to parse it:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// prototype<br>
-    ///   ::= id '(' id* ')'<br>
-    ///   ::= binary LETTER number? (id, id)<br>
-    static std::unique_ptr<PrototypeAST> ParsePrototype() {<br>
-      std::string FnName;<br>
-<br>
-      unsigned Kind = 0;  // 0 = identifier, 1 = unary, 2 = binary.<br>
-      unsigned BinaryPrecedence = 30;<br>
-<br>
-      switch (CurTok) {<br>
-      default:<br>
-        return LogErrorP("Expected function name in prototype");<br>
-      case tok_identifier:<br>
-        FnName = IdentifierStr;<br>
-        Kind = 0;<br>
-        getNextToken();<br>
-        break;<br>
-      case tok_binary:<br>
-        getNextToken();<br>
-        if (!isascii(CurTok))<br>
-          return LogErrorP("Expected binary operator");<br>
-        FnName = "binary";<br>
-        FnName += (char)CurTok;<br>
-        Kind = 2;<br>
-        getNextToken();<br>
-<br>
-        // Read the precedence if present.<br>
-        if (CurTok == tok_number) {<br>
-          if (NumVal < 1 || NumVal > 100)<br>
-            return LogErrorP("Invalid precedecnce: must be 1..100");<br>
-          BinaryPrecedence = (unsigned)NumVal;<br>
-          getNextToken();<br>
-        }<br>
-        break;<br>
-      }<br>
-<br>
-      if (CurTok != '(')<br>
-        return LogErrorP("Expected '(' in prototype");<br>
-<br>
-      std::vector<std::string> ArgNames;<br>
-      while (getNextToken() == tok_identifier)<br>
-        ArgNames.push_back(IdentifierStr);<br>
-      if (CurTok != ')')<br>
-        return LogErrorP("Expected ')' in prototype");<br>
-<br>
-      // success.<br>
-      getNextToken();  // eat ')'.<br>
-<br>
-      // Verify right number of names for operator.<br>
-      if (Kind && ArgNames.size() != Kind)<br>
-        return LogErrorP("Invalid number of operands for operator");<br>
-<br>
-      return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames), Kind != 0,<br>
-                                             BinaryPrecedence);<br>
-    }<br>
-<br>
-This is all fairly straightforward parsing code, and we have already<br>
-seen a lot of similar code in the past. One interesting part about the<br>
-code above is the couple lines that set up ``FnName`` for binary<br>
-operators. This builds names like "binary@" for a newly defined "@"<br>
-operator. This then takes advantage of the fact that symbol names in the<br>
-LLVM symbol table are allowed to have any character in them, including<br>
-embedded nul characters.<br>
-<br>
-The next interesting thing to add, is codegen support for these binary<br>
-operators. Given our current structure, this is a simple addition of a<br>
-default case for our existing binary operator node:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *BinaryExprAST::codegen() {<br>
-      Value *L = LHS->codegen();<br>
-      Value *R = RHS->codegen();<br>
-      if (!L || !R)<br>
-        return nullptr;<br>
-<br>
-      switch (Op) {<br>
-      case '+':<br>
-        return Builder.CreateFAdd(L, R, "addtmp");<br>
-      case '-':<br>
-        return Builder.CreateFSub(L, R, "subtmp");<br>
-      case '*':<br>
-        return Builder.CreateFMul(L, R, "multmp");<br>
-      case '<':<br>
-        L = Builder.CreateFCmpULT(L, R, "cmptmp");<br>
-        // Convert bool 0/1 to double 0.0 or 1.0<br>
-        return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),<br>
-                                    "booltmp");<br>
-      default:<br>
-        break;<br>
-      }<br>
-<br>
-      // If it wasn't a builtin binary operator, it must be a user defined one. Emit<br>
-      // a call to it.<br>
-      Function *F = TheModule->getFunction(std::string("binary") + Op);<br>
-      assert(F && "binary operator not found!");<br>
-<br>
-      Value *Ops[2] = { L, R };<br>
-      return Builder.CreateCall(F, Ops, "binop");<br>
-    }<br>
-<br>
-As you can see above, the new code is actually really simple. It just<br>
-does a lookup for the appropriate operator in the symbol table and<br>
-generates a function call to it. Since user-defined operators are just<br>
-built as normal functions (because the "prototype" boils down to a<br>
-function with the right name) everything falls into place.<br>
-<br>
-The final piece of code we are missing, is a bit of top-level magic:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Function *FunctionAST::codegen() {<br>
-      NamedValues.clear();<br>
-<br>
-      Function *TheFunction = Proto->codegen();<br>
-      if (!TheFunction)<br>
-        return nullptr;<br>
-<br>
-      // If this is an operator, install it.<br>
-      if (Proto->isBinaryOp())<br>
-        BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();<br>
-<br>
-      // Create a new basic block to start insertion into.<br>
-      BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);<br>
-      Builder.SetInsertPoint(BB);<br>
-<br>
-      if (Value *RetVal = Body->codegen()) {<br>
-        ...<br>
-<br>
-Basically, before codegening a function, if it is a user-defined<br>
-operator, we register it in the precedence table. This allows the binary<br>
-operator parsing logic we already have in place to handle it. Since we<br>
-are working on a fully-general operator precedence parser, this is all<br>
-we need to do to "extend the grammar".<br>
-<br>
-Now we have useful user-defined binary operators. This builds a lot on<br>
-the previous framework we built for other operators. Adding unary<br>
-operators is a bit more challenging, because we don't have any framework<br>
-for it yet - lets see what it takes.<br>
-<br>
-User-defined Unary Operators<br>
-============================<br>
-<br>
-Since we don't currently support unary operators in the Kaleidoscope<br>
-language, we'll need to add everything to support them. Above, we added<br>
-simple support for the 'unary' keyword to the lexer. In addition to<br>
-that, we need an AST node:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// UnaryExprAST - Expression class for a unary operator.<br>
-    class UnaryExprAST : public ExprAST {<br>
-      char Opcode;<br>
-      std::unique_ptr<ExprAST> Operand;<br>
-<br>
-    public:<br>
-      UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)<br>
-        : Opcode(Opcode), Operand(std::move(Operand)) {}<br>
-      virtual Value *codegen();<br>
-    };<br>
-<br>
-This AST node is very simple and obvious by now. It directly mirrors the<br>
-binary operator AST node, except that it only has one child. With this,<br>
-we need to add the parsing logic. Parsing a unary operator is pretty<br>
-simple: we'll add a new function to do it:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// unary<br>
-    ///   ::= primary<br>
-    ///   ::= '!' unary<br>
-    static std::unique_ptr<ExprAST> ParseUnary() {<br>
-      // If the current token is not an operator, it must be a primary expr.<br>
-      if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')<br>
-        return ParsePrimary();<br>
-<br>
-      // If this is a unary operator, read it.<br>
-      int Opc = CurTok;<br>
-      getNextToken();<br>
-      if (auto Operand = ParseUnary())<br>
-        return llvm::unique_ptr<UnaryExprAST>(Opc, std::move(Operand));<br>
-      return nullptr;<br>
-    }<br>
-<br>
-The grammar we add is pretty straightforward here. If we see a unary<br>
-operator when parsing a primary operator, we eat the operator as a<br>
-prefix and parse the remaining piece as another unary operator. This<br>
-allows us to handle multiple unary operators (e.g. "!!x"). Note that<br>
-unary operators can't have ambiguous parses like binary operators can,<br>
-so there is no need for precedence information.<br>
-<br>
-The problem with this function, is that we need to call ParseUnary from<br>
-somewhere. To do this, we change previous callers of ParsePrimary to<br>
-call ParseUnary instead:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// binoprhs<br>
-    ///   ::= ('+' unary)*<br>
-    static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,<br>
-                                                  std::unique_ptr<ExprAST> LHS) {<br>
-      ...<br>
-        // Parse the unary expression after the binary operator.<br>
-        auto RHS = ParseUnary();<br>
-        if (!RHS)<br>
-          return nullptr;<br>
-      ...<br>
-    }<br>
-    /// expression<br>
-    ///   ::= unary binoprhs<br>
-    ///<br>
-    static std::unique_ptr<ExprAST> ParseExpression() {<br>
-      auto LHS = ParseUnary();<br>
-      if (!LHS)<br>
-        return nullptr;<br>
-<br>
-      return ParseBinOpRHS(0, std::move(LHS));<br>
-    }<br>
-<br>
-With these two simple changes, we are now able to parse unary operators<br>
-and build the AST for them. Next up, we need to add parser support for<br>
-prototypes, to parse the unary operator prototype. We extend the binary<br>
-operator code above with:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// prototype<br>
-    ///   ::= id '(' id* ')'<br>
-    ///   ::= binary LETTER number? (id, id)<br>
-    ///   ::= unary LETTER (id)<br>
-    static std::unique_ptr<PrototypeAST> ParsePrototype() {<br>
-      std::string FnName;<br>
-<br>
-      unsigned Kind = 0;  // 0 = identifier, 1 = unary, 2 = binary.<br>
-      unsigned BinaryPrecedence = 30;<br>
-<br>
-      switch (CurTok) {<br>
-      default:<br>
-        return LogErrorP("Expected function name in prototype");<br>
-      case tok_identifier:<br>
-        FnName = IdentifierStr;<br>
-        Kind = 0;<br>
-        getNextToken();<br>
-        break;<br>
-      case tok_unary:<br>
-        getNextToken();<br>
-        if (!isascii(CurTok))<br>
-          return LogErrorP("Expected unary operator");<br>
-        FnName = "unary";<br>
-        FnName += (char)CurTok;<br>
-        Kind = 1;<br>
-        getNextToken();<br>
-        break;<br>
-      case tok_binary:<br>
-        ...<br>
-<br>
-As with binary operators, we name unary operators with a name that<br>
-includes the operator character. This assists us at code generation<br>
-time. Speaking of, the final piece we need to add is codegen support for<br>
-unary operators. It looks like this:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *UnaryExprAST::codegen() {<br>
-      Value *OperandV = Operand->codegen();<br>
-      if (!OperandV)<br>
-        return nullptr;<br>
-<br>
-      Function *F = TheModule->getFunction(std::string("unary")+Opcode);<br>
-      if (!F)<br>
-        return LogErrorV("Unknown unary operator");<br>
-<br>
-      return Builder.CreateCall(F, OperandV, "unop");<br>
-    }<br>
-<br>
-This code is similar to, but simpler than, the code for binary<br>
-operators. It is simpler primarily because it doesn't need to handle any<br>
-predefined operators.<br>
-<br>
-Kicking the Tires<br>
-=================<br>
-<br>
-It is somewhat hard to believe, but with a few simple extensions we've<br>
-covered in the last chapters, we have grown a real-ish language. With<br>
-this, we can do a lot of interesting things, including I/O, math, and a<br>
-bunch of other things. For example, we can now add a nice sequencing<br>
-operator (printd is defined to print out the specified value and a<br>
-newline):<br>
-<br>
-::<br>
-<br>
-    ready> extern printd(x);<br>
-    Read extern:<br>
-    declare double @printd(double)<br>
-<br>
-    ready> def binary : 1 (x y) 0;  # Low-precedence operator that ignores operands.<br>
-    ..<br>
-    ready> printd(123) : printd(456) : printd(789);<br>
-    123.000000<br>
-    456.000000<br>
-    789.000000<br>
-    Evaluated to 0.000000<br>
-<br>
-We can also define a bunch of other "primitive" operations, such as:<br>
-<br>
-::<br>
-<br>
-    # Logical unary not.<br>
-    def unary!(v)<br>
-      if v then<br>
-        0<br>
-      else<br>
-        1;<br>
-<br>
-    # Unary negate.<br>
-    def unary-(v)<br>
-      0-v;<br>
-<br>
-    # Define > with the same precedence as <.<br>
-    def binary> 10 (LHS RHS)<br>
-      RHS < LHS;<br>
-<br>
-    # Binary logical or, which does not short circuit.<br>
-    def binary| 5 (LHS RHS)<br>
-      if LHS then<br>
-        1<br>
-      else if RHS then<br>
-        1<br>
-      else<br>
-        0;<br>
-<br>
-    # Binary logical and, which does not short circuit.<br>
-    def binary& 6 (LHS RHS)<br>
-      if !LHS then<br>
-        0<br>
-      else<br>
-        !!RHS;<br>
-<br>
-    # Define = with slightly lower precedence than relationals.<br>
-    def binary = 9 (LHS RHS)<br>
-      !(LHS < RHS | LHS > RHS);<br>
-<br>
-    # Define ':' for sequencing: as a low-precedence operator that ignores operands<br>
-    # and just returns the RHS.<br>
-    def binary : 1 (x y) y;<br>
-<br>
-Given the previous if/then/else support, we can also define interesting<br>
-functions for I/O. For example, the following prints out a character<br>
-whose "density" reflects the value passed in: the lower the value, the<br>
-denser the character:<br>
-<br>
-::<br>
-<br>
-    ready><br>
-<br>
-    extern putchard(char)<br>
-    def printdensity(d)<br>
-      if d > 8 then<br>
-        putchard(32)  # ' '<br>
-      else if d > 4 then<br>
-        putchard(46)  # '.'<br>
-      else if d > 2 then<br>
-        putchard(43)  # '+'<br>
-      else<br>
-        putchard(42); # '*'<br>
-    ...<br>
-    ready> printdensity(1): printdensity(2): printdensity(3):<br>
-           printdensity(4): printdensity(5): printdensity(9):<br>
-           putchard(10);<br>
-    **++.<br>
-    Evaluated to 0.000000<br>
-<br>
-Based on these simple primitive operations, we can start to define more<br>
-interesting things. For example, here's a little function that solves<br>
-for the number of iterations it takes a function in the complex plane to<br>
-converge:<br>
-<br>
-::<br>
-<br>
-    # Determine whether the specific location diverges.<br>
-    # Solve for z = z^2 + c in the complex plane.<br>
-    def mandelconverger(real imag iters creal cimag)<br>
-      if iters > 255 | (real*real + imag*imag > 4) then<br>
-        iters<br>
-      else<br>
-        mandelconverger(real*real - imag*imag + creal,<br>
-                        2*real*imag + cimag,<br>
-                        iters+1, creal, cimag);<br>
-<br>
-    # Return the number of iterations required for the iteration to escape<br>
-    def mandelconverge(real imag)<br>
-      mandelconverger(real, imag, 0, real, imag);<br>
-<br>
-This "``z = z2 + c``" function is a beautiful little creature that is<br>
-the basis for computation of the `Mandelbrot<br>
-Set <<a href="http://en.wikipedia.org/wiki/Mandelbrot_set" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Mandelbrot_set</a>>`_. Our<br>
-``mandelconverge`` function returns the number of iterations that it<br>
-takes for a complex orbit to escape, saturating to 255. This is not a<br>
-very useful function by itself, but if you plot its value over a<br>
-two-dimensional plane, you can see the Mandelbrot set. Given that we are<br>
-limited to using putchard here, our amazing graphical output is limited,<br>
-but we can whip together something using the density plotter above:<br>
-<br>
-::<br>
-<br>
-    # Compute and plot the mandelbrot set with the specified 2 dimensional range<br>
-    # info.<br>
-    def mandelhelp(xmin xmax xstep   ymin ymax ystep)<br>
-      for y = ymin, y < ymax, ystep in (<br>
-        (for x = xmin, x < xmax, xstep in<br>
-           printdensity(mandelconverge(x,y)))<br>
-        : putchard(10)<br>
-      )<br>
-<br>
-    # mandel - This is a convenient helper function for plotting the mandelbrot set<br>
-    # from the specified position with the specified Magnification.<br>
-    def mandel(realstart imagstart realmag imagmag)<br>
-      mandelhelp(realstart, realstart+realmag*78, realmag,<br>
-                 imagstart, imagstart+imagmag*40, imagmag);<br>
-<br>
-Given this, we can try plotting out the mandelbrot set! Lets try it out:<br>
-<br>
-::<br>
-<br>
-    ready> mandel(-2.3, -1.3, 0.05, 0.07);<br>
-    *******************************+++++++++++*************************************<br>
-    *************************+++++++++++++++++++++++*******************************<br>
-    **********************+++++++++++++++++++++++++++++****************************<br>
-    *******************+++++++++++++++++++++.. ...++++++++*************************<br>
-    *****************++++++++++++++++++++++.... ...+++++++++***********************<br>
-    ***************+++++++++++++++++++++++.....   ...+++++++++*********************<br>
-    **************+++++++++++++++++++++++....     ....+++++++++********************<br>
-    *************++++++++++++++++++++++......      .....++++++++*******************<br>
-    ************+++++++++++++++++++++.......       .......+++++++******************<br>
-    ***********+++++++++++++++++++....                ... .+++++++*****************<br>
-    **********+++++++++++++++++.......                     .+++++++****************<br>
-    *********++++++++++++++...........                    ...+++++++***************<br>
-    ********++++++++++++............                      ...++++++++**************<br>
-    ********++++++++++... ..........                        .++++++++**************<br>
-    *******+++++++++.....                                   .+++++++++*************<br>
-    *******++++++++......                                  ..+++++++++*************<br>
-    *******++++++.......                                   ..+++++++++*************<br>
-    *******+++++......                                     ..+++++++++*************<br>
-    *******.... ....                                      ...+++++++++*************<br>
-    *******.... .                                         ...+++++++++*************<br>
-    *******+++++......                                    ...+++++++++*************<br>
-    *******++++++.......                                   ..+++++++++*************<br>
-    *******++++++++......                                   .+++++++++*************<br>
-    *******+++++++++.....                                  ..+++++++++*************<br>
-    ********++++++++++... ..........                        .++++++++**************<br>
-    ********++++++++++++............                      ...++++++++**************<br>
-    *********++++++++++++++..........                     ...+++++++***************<br>
-    **********++++++++++++++++........                     .+++++++****************<br>
-    **********++++++++++++++++++++....                ... ..+++++++****************<br>
-    ***********++++++++++++++++++++++.......       .......++++++++*****************<br>
-    ************+++++++++++++++++++++++......      ......++++++++******************<br>
-    **************+++++++++++++++++++++++....      ....++++++++********************<br>
-    ***************+++++++++++++++++++++++.....   ...+++++++++*********************<br>
-    *****************++++++++++++++++++++++....  ...++++++++***********************<br>
-    *******************+++++++++++++++++++++......++++++++*************************<br>
-    *********************++++++++++++++++++++++.++++++++***************************<br>
-    *************************+++++++++++++++++++++++*******************************<br>
-    ******************************+++++++++++++************************************<br>
-    *******************************************************************************<br>
-    *******************************************************************************<br>
-    *******************************************************************************<br>
-    Evaluated to 0.000000<br>
-    ready> mandel(-2, -1, 0.02, 0.04);<br>
-    **************************+++++++++++++++++++++++++++++++++++++++++++++++++++++<br>
-    ***********************++++++++++++++++++++++++++++++++++++++++++++++++++++++++<br>
-    *********************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.<br>
-    *******************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++...<br>
-    *****************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.....<br>
-    ***************++++++++++++++++++++++++++++++++++++++++++++++++++++++++........<br>
-    **************++++++++++++++++++++++++++++++++++++++++++++++++++++++...........<br>
-    ************+++++++++++++++++++++++++++++++++++++++++++++++++++++..............<br>
-    ***********++++++++++++++++++++++++++++++++++++++++++++++++++........        .<br>
-    **********++++++++++++++++++++++++++++++++++++++++++++++.............<br>
-    ********+++++++++++++++++++++++++++++++++++++++++++..................<br>
-    *******+++++++++++++++++++++++++++++++++++++++.......................<br>
-    ******+++++++++++++++++++++++++++++++++++...........................<br>
-    *****++++++++++++++++++++++++++++++++............................<br>
-    *****++++++++++++++++++++++++++++...............................<br>
-    ****++++++++++++++++++++++++++......   .........................<br>
-    ***++++++++++++++++++++++++.........     ......    ...........<br>
-    ***++++++++++++++++++++++............<br>
-    **+++++++++++++++++++++..............<br>
-    **+++++++++++++++++++................<br>
-    *++++++++++++++++++.................<br>
-    *++++++++++++++++............ ...<br>
-    *++++++++++++++..............<br>
-    *+++....++++................<br>
-    *..........  ...........<br>
-    *<br>
-    *..........  ...........<br>
-    *+++....++++................<br>
-    *++++++++++++++..............<br>
-    *++++++++++++++++............ ...<br>
-    *++++++++++++++++++.................<br>
-    **+++++++++++++++++++................<br>
-    **+++++++++++++++++++++..............<br>
-    ***++++++++++++++++++++++............<br>
-    ***++++++++++++++++++++++++.........     ......    ...........<br>
-    ****++++++++++++++++++++++++++......   .........................<br>
-    *****++++++++++++++++++++++++++++...............................<br>
-    *****++++++++++++++++++++++++++++++++............................<br>
-    ******+++++++++++++++++++++++++++++++++++...........................<br>
-    *******+++++++++++++++++++++++++++++++++++++++.......................<br>
-    ********+++++++++++++++++++++++++++++++++++++++++++..................<br>
-    Evaluated to 0.000000<br>
-    ready> mandel(-0.9, -1.4, 0.02, 0.03);<br>
-    *******************************************************************************<br>
-    *******************************************************************************<br>
-    *******************************************************************************<br>
-    **********+++++++++++++++++++++************************************************<br>
-    *+++++++++++++++++++++++++++++++++++++++***************************************<br>
-    +++++++++++++++++++++++++++++++++++++++++++++**********************************<br>
-    ++++++++++++++++++++++++++++++++++++++++++++++++++*****************************<br>
-    ++++++++++++++++++++++++++++++++++++++++++++++++++++++*************************<br>
-    +++++++++++++++++++++++++++++++++++++++++++++++++++++++++**********************<br>
-    +++++++++++++++++++++++++++++++++.........++++++++++++++++++*******************<br>
-    +++++++++++++++++++++++++++++++....   ......+++++++++++++++++++****************<br>
-    +++++++++++++++++++++++++++++.......  ........+++++++++++++++++++**************<br>
-    ++++++++++++++++++++++++++++........   ........++++++++++++++++++++************<br>
-    +++++++++++++++++++++++++++.........     ..  ...+++++++++++++++++++++**********<br>
-    ++++++++++++++++++++++++++...........        ....++++++++++++++++++++++********<br>
-    ++++++++++++++++++++++++.............       .......++++++++++++++++++++++******<br>
-    +++++++++++++++++++++++.............        ........+++++++++++++++++++++++****<br>
-    ++++++++++++++++++++++...........           ..........++++++++++++++++++++++***<br>
-    ++++++++++++++++++++...........                .........++++++++++++++++++++++*<br>
-    ++++++++++++++++++............                  ...........++++++++++++++++++++<br>
-    ++++++++++++++++...............                 .............++++++++++++++++++<br>
-    ++++++++++++++.................                 ...............++++++++++++++++<br>
-    ++++++++++++..................                  .................++++++++++++++<br>
-    +++++++++..................                      .................+++++++++++++<br>
-    ++++++........        .                               .........  ..++++++++++++<br>
-    ++............                                         ......    ....++++++++++<br>
-    ..............                                                    ...++++++++++<br>
-    ..............                                                    ....+++++++++<br>
-    ..............                                                    .....++++++++<br>
-    .............                                                    ......++++++++<br>
-    ...........                                                     .......++++++++<br>
-    .........                                                       ........+++++++<br>
-    .........                                                       ........+++++++<br>
-    .........                                                           ....+++++++<br>
-    ........                                                             ...+++++++<br>
-    .......                                                              ...+++++++<br>
-                                                                        ....+++++++<br>
-                                                                       .....+++++++<br>
-                                                                        ....+++++++<br>
-                                                                        ....+++++++<br>
-                                                                        ....+++++++<br>
-    Evaluated to 0.000000<br>
-    ready> ^D<br>
-<br>
-At this point, you may be starting to realize that Kaleidoscope is a<br>
-real and powerful language. It may not be self-similar :), but it can be<br>
-used to plot things that are!<br>
-<br>
-With this, we conclude the "adding user-defined operators" chapter of<br>
-the tutorial. We have successfully augmented our language, adding the<br>
-ability to extend the language in the library, and we have shown how<br>
-this can be used to build a simple but interesting end-user application<br>
-in Kaleidoscope. At this point, Kaleidoscope can build a variety of<br>
-applications that are functional and can call functions with<br>
-side-effects, but it can't actually define and mutate a variable itself.<br>
-<br>
-Strikingly, variable mutation is an important feature of some languages,<br>
-and it is not at all obvious how to `add support for mutable<br>
-variables <LangImpl7.html>`_ without having to add an "SSA construction"<br>
-phase to your front-end. In the next chapter, we will describe how you<br>
-can add variable mutation without building SSA in your front-end.<br>
-<br>
-Full Code Listing<br>
-=================<br>
-<br>
-Here is the complete code listing for our running example, enhanced with<br>
-the if/then/else and for expressions.. To build this example, use:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    # Compile<br>
-    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
-    # Run<br>
-    ./toy<br>
-<br>
-On some platforms, you will need to specify -rdynamic or<br>
--Wl,--export-dynamic when linking. This ensures that symbols defined in<br>
-the main executable are exported to the dynamic linker and so are<br>
-available for symbol resolution at run time. This is not needed if you<br>
-compile your support code into a shared library, although doing that<br>
-will cause problems on Windows.<br>
-<br>
-Here is the code:<br>
-<br>
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter6/toy.cpp<br>
-   :language: c++<br>
-<br>
-`Next: Extending the language: mutable variables / SSA<br>
-construction <LangImpl7.html>`_<br>
-<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl7.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl7.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl7.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl7.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl7.rst (removed)<br>
@@ -1,881 +0,0 @@<br>
-=======================================================<br>
-Kaleidoscope: Extending the Language: Mutable Variables<br>
-=======================================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Chapter 7 Introduction<br>
-======================<br>
-<br>
-Welcome to Chapter 7 of the "`Implementing a language with<br>
-LLVM <index.html>`_" tutorial. In chapters 1 through 6, we've built a<br>
-very respectable, albeit simple, `functional programming<br>
-language <<a href="http://en.wikipedia.org/wiki/Functional_programming" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Functional_programming</a>>`_. In our<br>
-journey, we learned some parsing techniques, how to build and represent<br>
-an AST, how to build LLVM IR, and how to optimize the resultant code as<br>
-well as JIT compile it.<br>
-<br>
-While Kaleidoscope is interesting as a functional language, the fact<br>
-that it is functional makes it "too easy" to generate LLVM IR for it. In<br>
-particular, a functional language makes it very easy to build LLVM IR<br>
-directly in `SSA<br>
-form <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_.<br>
-Since LLVM requires that the input code be in SSA form, this is a very<br>
-nice property and it is often unclear to newcomers how to generate code<br>
-for an imperative language with mutable variables.<br>
-<br>
-The short (and happy) summary of this chapter is that there is no need<br>
-for your front-end to build SSA form: LLVM provides highly tuned and<br>
-well tested support for this, though the way it works is a bit<br>
-unexpected for some.<br>
-<br>
-Why is this a hard problem?<br>
-===========================<br>
-<br>
-To understand why mutable variables cause complexities in SSA<br>
-construction, consider this extremely simple C example:<br>
-<br>
-.. code-block:: c<br>
-<br>
-    int G, H;<br>
-    int test(_Bool Condition) {<br>
-      int X;<br>
-      if (Condition)<br>
-        X = G;<br>
-      else<br>
-        X = H;<br>
-      return X;<br>
-    }<br>
-<br>
-In this case, we have the variable "X", whose value depends on the path<br>
-executed in the program. Because there are two different possible values<br>
-for X before the return instruction, a PHI node is inserted to merge the<br>
-two values. The LLVM IR that we want for this example looks like this:<br>
-<br>
-.. code-block:: llvm<br>
-<br>
-    @G = weak global i32 0   ; type of @G is i32*<br>
-    @H = weak global i32 0   ; type of @H is i32*<br>
-<br>
-    define i32 @test(i1 %Condition) {<br>
-    entry:<br>
-      br i1 %Condition, label %cond_true, label %cond_false<br>
-<br>
-    cond_true:<br>
-      %X.0 = load i32* @G<br>
-      br label %cond_next<br>
-<br>
-    cond_false:<br>
-      %X.1 = load i32* @H<br>
-      br label %cond_next<br>
-<br>
-    cond_next:<br>
-      %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]<br>
-      ret i32 %X.2<br>
-    }<br>
-<br>
-In this example, the loads from the G and H global variables are<br>
-explicit in the LLVM IR, and they live in the then/else branches of the<br>
-if statement (cond\_true/cond\_false). In order to merge the incoming<br>
-values, the X.2 phi node in the cond\_next block selects the right value<br>
-to use based on where control flow is coming from: if control flow comes<br>
-from the cond\_false block, X.2 gets the value of X.1. Alternatively, if<br>
-control flow comes from cond\_true, it gets the value of X.0. The intent<br>
-of this chapter is not to explain the details of SSA form. For more<br>
-information, see one of the many `online<br>
-references <<a href="http://en.wikipedia.org/wiki/Static_single_assignment_form" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Static_single_assignment_form</a>>`_.<br>
-<br>
-The question for this article is "who places the phi nodes when lowering<br>
-assignments to mutable variables?". The issue here is that LLVM<br>
-*requires* that its IR be in SSA form: there is no "non-ssa" mode for<br>
-it. However, SSA construction requires non-trivial algorithms and data<br>
-structures, so it is inconvenient and wasteful for every front-end to<br>
-have to reproduce this logic.<br>
-<br>
-Memory in LLVM<br>
-==============<br>
-<br>
-The 'trick' here is that while LLVM does require all register values to<br>
-be in SSA form, it does not require (or permit) memory objects to be in<br>
-SSA form. In the example above, note that the loads from G and H are<br>
-direct accesses to G and H: they are not renamed or versioned. This<br>
-differs from some other compiler systems, which do try to version memory<br>
-objects. In LLVM, instead of encoding dataflow analysis of memory into<br>
-the LLVM IR, it is handled with `Analysis<br>
-Passes <../WritingAnLLVMPass.html>`_ which are computed on demand.<br>
-<br>
-With this in mind, the high-level idea is that we want to make a stack<br>
-variable (which lives in memory, because it is on the stack) for each<br>
-mutable object in a function. To take advantage of this trick, we need<br>
-to talk about how LLVM represents stack variables.<br>
-<br>
-In LLVM, all memory accesses are explicit with load/store instructions,<br>
-and it is carefully designed not to have (or need) an "address-of"<br>
-operator. Notice how the type of the @G/@H global variables is actually<br>
-"i32\*" even though the variable is defined as "i32". What this means is<br>
-that @G defines *space* for an i32 in the global data area, but its<br>
-*name* actually refers to the address for that space. Stack variables<br>
-work the same way, except that instead of being declared with global<br>
-variable definitions, they are declared with the `LLVM alloca<br>
-instruction <../LangRef.html#alloca-instruction>`_:<br>
-<br>
-.. code-block:: llvm<br>
-<br>
-    define i32 @example() {<br>
-    entry:<br>
-      %X = alloca i32           ; type of %X is i32*.<br>
-      ...<br>
-      %tmp = load i32* %X       ; load the stack value %X from the stack.<br>
-      %tmp2 = add i32 %tmp, 1   ; increment it<br>
-      store i32 %tmp2, i32* %X  ; store it back<br>
-      ...<br>
-<br>
-This code shows an example of how you can declare and manipulate a stack<br>
-variable in the LLVM IR. Stack memory allocated with the alloca<br>
-instruction is fully general: you can pass the address of the stack slot<br>
-to functions, you can store it in other variables, etc. In our example<br>
-above, we could rewrite the example to use the alloca technique to avoid<br>
-using a PHI node:<br>
-<br>
-.. code-block:: llvm<br>
-<br>
-    @G = weak global i32 0   ; type of @G is i32*<br>
-    @H = weak global i32 0   ; type of @H is i32*<br>
-<br>
-    define i32 @test(i1 %Condition) {<br>
-    entry:<br>
-      %X = alloca i32           ; type of %X is i32*.<br>
-      br i1 %Condition, label %cond_true, label %cond_false<br>
-<br>
-    cond_true:<br>
-      %X.0 = load i32* @G<br>
-      store i32 %X.0, i32* %X   ; Update X<br>
-      br label %cond_next<br>
-<br>
-    cond_false:<br>
-      %X.1 = load i32* @H<br>
-      store i32 %X.1, i32* %X   ; Update X<br>
-      br label %cond_next<br>
-<br>
-    cond_next:<br>
-      %X.2 = load i32* %X       ; Read X<br>
-      ret i32 %X.2<br>
-    }<br>
-<br>
-With this, we have discovered a way to handle arbitrary mutable<br>
-variables without the need to create Phi nodes at all:<br>
-<br>
-#. Each mutable variable becomes a stack allocation.<br>
-#. Each read of the variable becomes a load from the stack.<br>
-#. Each update of the variable becomes a store to the stack.<br>
-#. Taking the address of a variable just uses the stack address<br>
-   directly.<br>
-<br>
-While this solution has solved our immediate problem, it introduced<br>
-another one: we have now apparently introduced a lot of stack traffic<br>
-for very simple and common operations, a major performance problem.<br>
-Fortunately for us, the LLVM optimizer has a highly-tuned optimization<br>
-pass named "mem2reg" that handles this case, promoting allocas like this<br>
-into SSA registers, inserting Phi nodes as appropriate. If you run this<br>
-example through the pass, for example, you'll get:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    $ llvm-as < example.ll | opt -mem2reg | llvm-dis<br>
-    @G = weak global i32 0<br>
-    @H = weak global i32 0<br>
-<br>
-    define i32 @test(i1 %Condition) {<br>
-    entry:<br>
-      br i1 %Condition, label %cond_true, label %cond_false<br>
-<br>
-    cond_true:<br>
-      %X.0 = load i32* @G<br>
-      br label %cond_next<br>
-<br>
-    cond_false:<br>
-      %X.1 = load i32* @H<br>
-      br label %cond_next<br>
-<br>
-    cond_next:<br>
-      %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]<br>
-      ret i32 %X.01<br>
-    }<br>
-<br>
-The mem2reg pass implements the standard "iterated dominance frontier"<br>
-algorithm for constructing SSA form and has a number of optimizations<br>
-that speed up (very common) degenerate cases. The mem2reg optimization<br>
-pass is the answer to dealing with mutable variables, and we highly<br>
-recommend that you depend on it. Note that mem2reg only works on<br>
-variables in certain circumstances:<br>
-<br>
-#. mem2reg is alloca-driven: it looks for allocas and if it can handle<br>
-   them, it promotes them. It does not apply to global variables or heap<br>
-   allocations.<br>
-#. mem2reg only looks for alloca instructions in the entry block of the<br>
-   function. Being in the entry block guarantees that the alloca is only<br>
-   executed once, which makes analysis simpler.<br>
-#. mem2reg only promotes allocas whose uses are direct loads and stores.<br>
-   If the address of the stack object is passed to a function, or if any<br>
-   funny pointer arithmetic is involved, the alloca will not be<br>
-   promoted.<br>
-#. mem2reg only works on allocas of `first<br>
-   class <../LangRef.html#first-class-types>`_ values (such as pointers,<br>
-   scalars and vectors), and only if the array size of the allocation is<br>
-   1 (or missing in the .ll file). mem2reg is not capable of promoting<br>
-   structs or arrays to registers. Note that the "sroa" pass is<br>
-   more powerful and can promote structs, "unions", and arrays in many<br>
-   cases.<br>
-<br>
-All of these properties are easy to satisfy for most imperative<br>
-languages, and we'll illustrate it below with Kaleidoscope. The final<br>
-question you may be asking is: should I bother with this nonsense for my<br>
-front-end? Wouldn't it be better if I just did SSA construction<br>
-directly, avoiding use of the mem2reg optimization pass? In short, we<br>
-strongly recommend that you use this technique for building SSA form,<br>
-unless there is an extremely good reason not to. Using this technique<br>
-is:<br>
-<br>
--  Proven and well tested: clang uses this technique<br>
-   for local mutable variables. As such, the most common clients of LLVM<br>
-   are using this to handle a bulk of their variables. You can be sure<br>
-   that bugs are found fast and fixed early.<br>
--  Extremely Fast: mem2reg has a number of special cases that make it<br>
-   fast in common cases as well as fully general. For example, it has<br>
-   fast-paths for variables that are only used in a single block,<br>
-   variables that only have one assignment point, good heuristics to<br>
-   avoid insertion of unneeded phi nodes, etc.<br>
--  Needed for debug info generation: `Debug information in<br>
-   LLVM <../SourceLevelDebugging.html>`_ relies on having the address of<br>
-   the variable exposed so that debug info can be attached to it. This<br>
-   technique dovetails very naturally with this style of debug info.<br>
-<br>
-If nothing else, this makes it much easier to get your front-end up and<br>
-running, and is very simple to implement. Let's extend Kaleidoscope with<br>
-mutable variables now!<br>
-<br>
-Mutable Variables in Kaleidoscope<br>
-=================================<br>
-<br>
-Now that we know the sort of problem we want to tackle, let's see what<br>
-this looks like in the context of our little Kaleidoscope language.<br>
-We're going to add two features:<br>
-<br>
-#. The ability to mutate variables with the '=' operator.<br>
-#. The ability to define new variables.<br>
-<br>
-While the first item is really what this is about, we only have<br>
-variables for incoming arguments as well as for induction variables, and<br>
-redefining those only goes so far :). Also, the ability to define new<br>
-variables is a useful thing regardless of whether you will be mutating<br>
-them. Here's a motivating example that shows how we could use these:<br>
-<br>
-::<br>
-<br>
-    # Define ':' for sequencing: as a low-precedence operator that ignores operands<br>
-    # and just returns the RHS.<br>
-    def binary : 1 (x y) y;<br>
-<br>
-    # Recursive fib, we could do this before.<br>
-    def fib(x)<br>
-      if (x < 3) then<br>
-        1<br>
-      else<br>
-        fib(x-1)+fib(x-2);<br>
-<br>
-    # Iterative fib.<br>
-    def fibi(x)<br>
-      var a = 1, b = 1, c in<br>
-      (for i = 3, i < x in<br>
-         c = a + b :<br>
-         a = b :<br>
-         b = c) :<br>
-      b;<br>
-<br>
-    # Call it.<br>
-    fibi(10);<br>
-<br>
-In order to mutate variables, we have to change our existing variables<br>
-to use the "alloca trick". Once we have that, we'll add our new<br>
-operator, then extend Kaleidoscope to support new variable definitions.<br>
-<br>
-Adjusting Existing Variables for Mutation<br>
-=========================================<br>
-<br>
-The symbol table in Kaleidoscope is managed at code generation time by<br>
-the '``NamedValues``' map. This map currently keeps track of the LLVM<br>
-"Value\*" that holds the double value for the named variable. In order<br>
-to support mutation, we need to change this slightly, so that<br>
-``NamedValues`` holds the *memory location* of the variable in question.<br>
-Note that this change is a refactoring: it changes the structure of the<br>
-code, but does not (by itself) change the behavior of the compiler. All<br>
-of these changes are isolated in the Kaleidoscope code generator.<br>
-<br>
-At this point in Kaleidoscope's development, it only supports variables<br>
-for two things: incoming arguments to functions and the induction<br>
-variable of 'for' loops. For consistency, we'll allow mutation of these<br>
-variables in addition to other user-defined variables. This means that<br>
-these will both need memory locations.<br>
-<br>
-To start our transformation of Kaleidoscope, we'll change the<br>
-NamedValues map so that it maps to AllocaInst\* instead of Value\*. Once<br>
-we do this, the C++ compiler will tell us what parts of the code we need<br>
-to update:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    static std::map<std::string, AllocaInst*> NamedValues;<br>
-<br>
-Also, since we will need to create these alloca's, we'll use a helper<br>
-function that ensures that the allocas are created in the entry block of<br>
-the function:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of<br>
-    /// the function.  This is used for mutable variables etc.<br>
-    static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,<br>
-                                              const std::string &VarName) {<br>
-      IRBuilder<> TmpB(&TheFunction->getEntryBlock(),<br>
-                     TheFunction->getEntryBlock().begin());<br>
-      return TmpB.CreateAlloca(Type::getDoubleTy(LLVMContext), 0,<br>
-                               VarName.c_str());<br>
-    }<br>
-<br>
-This funny looking code creates an IRBuilder object that is pointing at<br>
-the first instruction (.begin()) of the entry block. It then creates an<br>
-alloca with the expected name and returns it. Because all values in<br>
-Kaleidoscope are doubles, there is no need to pass in a type to use.<br>
-<br>
-With this in place, the first functionality change we want to make is to<br>
-variable references. In our new scheme, variables live on the stack, so<br>
-code generating a reference to them actually needs to produce a load<br>
-from the stack slot:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *VariableExprAST::codegen() {<br>
-      // Look this variable up in the function.<br>
-      Value *V = NamedValues[Name];<br>
-      if (!V)<br>
-        return LogErrorV("Unknown variable name");<br>
-<br>
-      // Load the value.<br>
-      return Builder.CreateLoad(V, Name.c_str());<br>
-    }<br>
-<br>
-As you can see, this is pretty straightforward. Now we need to update<br>
-the things that define the variables to set up the alloca. We'll start<br>
-with ``ForExprAST::codegen()`` (see the `full code listing <#id1>`_ for<br>
-the unabridged code):<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      Function *TheFunction = Builder.GetInsertBlock()->getParent();<br>
-<br>
-      // Create an alloca for the variable in the entry block.<br>
-      AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);<br>
-<br>
-        // Emit the start code first, without 'variable' in scope.<br>
-      Value *StartVal = Start->codegen();<br>
-      if (!StartVal)<br>
-        return nullptr;<br>
-<br>
-      // Store the value into the alloca.<br>
-      Builder.CreateStore(StartVal, Alloca);<br>
-      ...<br>
-<br>
-      // Compute the end condition.<br>
-      Value *EndCond = End->codegen();<br>
-      if (!EndCond)<br>
-        return nullptr;<br>
-<br>
-      // Reload, increment, and restore the alloca.  This handles the case where<br>
-      // the body of the loop mutates the variable.<br>
-      Value *CurVar = Builder.CreateLoad(Alloca);<br>
-      Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");<br>
-      Builder.CreateStore(NextVar, Alloca);<br>
-      ...<br>
-<br>
-This code is virtually identical to the code `before we allowed mutable<br>
-variables <LangImpl5.html#code-generation-for-the-for-loop>`_. The big difference is that we<br>
-no longer have to construct a PHI node, and we use load/store to access<br>
-the variable as needed.<br>
-<br>
-To support mutable argument variables, we need to also make allocas for<br>
-them. The code for this is also pretty simple:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// CreateArgumentAllocas - Create an alloca for each argument and register the<br>
-    /// argument in the symbol table so that references to it will succeed.<br>
-    void PrototypeAST::CreateArgumentAllocas(Function *F) {<br>
-      Function::arg_iterator AI = F->arg_begin();<br>
-      for (unsigned Idx = 0, e = Args.size(); Idx != e; ++Idx, ++AI) {<br>
-        // Create an alloca for this variable.<br>
-        AllocaInst *Alloca = CreateEntryBlockAlloca(F, Args[Idx]);<br>
-<br>
-        // Store the initial value into the alloca.<br>
-        Builder.CreateStore(AI, Alloca);<br>
-<br>
-        // Add arguments to variable symbol table.<br>
-        NamedValues[Args[Idx]] = Alloca;<br>
-      }<br>
-    }<br>
-<br>
-For each argument, we make an alloca, store the input value to the<br>
-function into the alloca, and register the alloca as the memory location<br>
-for the argument. This method gets invoked by ``FunctionAST::codegen()``<br>
-right after it sets up the entry block for the function.<br>
-<br>
-The final missing piece is adding the mem2reg pass, which allows us to<br>
-get good codegen once again:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-        // Set up the optimizer pipeline.  Start with registering info about how the<br>
-        // target lays out data structures.<br>
-        OurFPM.add(new DataLayout(*TheExecutionEngine->getDataLayout()));<br>
-        // Promote allocas to registers.<br>
-        OurFPM.add(createPromoteMemoryToRegisterPass());<br>
-        // Do simple "peephole" optimizations and bit-twiddling optzns.<br>
-        OurFPM.add(createInstructionCombiningPass());<br>
-        // Reassociate expressions.<br>
-        OurFPM.add(createReassociatePass());<br>
-<br>
-It is interesting to see what the code looks like before and after the<br>
-mem2reg optimization runs. For example, this is the before/after code<br>
-for our recursive fib function. Before the optimization:<br>
-<br>
-.. code-block:: llvm<br>
-<br>
-    define double @fib(double %x) {<br>
-    entry:<br>
-      %x1 = alloca double<br>
-      store double %x, double* %x1<br>
-      %x2 = load double* %x1<br>
-      %cmptmp = fcmp ult double %x2, 3.000000e+00<br>
-      %booltmp = uitofp i1 %cmptmp to double<br>
-      %ifcond = fcmp one double %booltmp, 0.000000e+00<br>
-      br i1 %ifcond, label %then, label %else<br>
-<br>
-    then:       ; preds = %entry<br>
-      br label %ifcont<br>
-<br>
-    else:       ; preds = %entry<br>
-      %x3 = load double* %x1<br>
-      %subtmp = fsub double %x3, 1.000000e+00<br>
-      %calltmp = call double @fib(double %subtmp)<br>
-      %x4 = load double* %x1<br>
-      %subtmp5 = fsub double %x4, 2.000000e+00<br>
-      %calltmp6 = call double @fib(double %subtmp5)<br>
-      %addtmp = fadd double %calltmp, %calltmp6<br>
-      br label %ifcont<br>
-<br>
-    ifcont:     ; preds = %else, %then<br>
-      %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]<br>
-      ret double %iftmp<br>
-    }<br>
-<br>
-Here there is only one variable (x, the input argument) but you can<br>
-still see the extremely simple-minded code generation strategy we are<br>
-using. In the entry block, an alloca is created, and the initial input<br>
-value is stored into it. Each reference to the variable does a reload<br>
-from the stack. Also, note that we didn't modify the if/then/else<br>
-expression, so it still inserts a PHI node. While we could make an<br>
-alloca for it, it is actually easier to create a PHI node for it, so we<br>
-still just make the PHI.<br>
-<br>
-Here is the code after the mem2reg pass runs:<br>
-<br>
-.. code-block:: llvm<br>
-<br>
-    define double @fib(double %x) {<br>
-    entry:<br>
-      %cmptmp = fcmp ult double %x, 3.000000e+00<br>
-      %booltmp = uitofp i1 %cmptmp to double<br>
-      %ifcond = fcmp one double %booltmp, 0.000000e+00<br>
-      br i1 %ifcond, label %then, label %else<br>
-<br>
-    then:<br>
-      br label %ifcont<br>
-<br>
-    else:<br>
-      %subtmp = fsub double %x, 1.000000e+00<br>
-      %calltmp = call double @fib(double %subtmp)<br>
-      %subtmp5 = fsub double %x, 2.000000e+00<br>
-      %calltmp6 = call double @fib(double %subtmp5)<br>
-      %addtmp = fadd double %calltmp, %calltmp6<br>
-      br label %ifcont<br>
-<br>
-    ifcont:     ; preds = %else, %then<br>
-      %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]<br>
-      ret double %iftmp<br>
-    }<br>
-<br>
-This is a trivial case for mem2reg, since there are no redefinitions of<br>
-the variable. The point of showing this is to calm your tension about<br>
-inserting such blatent inefficiencies :).<br>
-<br>
-After the rest of the optimizers run, we get:<br>
-<br>
-.. code-block:: llvm<br>
-<br>
-    define double @fib(double %x) {<br>
-    entry:<br>
-      %cmptmp = fcmp ult double %x, 3.000000e+00<br>
-      %booltmp = uitofp i1 %cmptmp to double<br>
-      %ifcond = fcmp ueq double %booltmp, 0.000000e+00<br>
-      br i1 %ifcond, label %else, label %ifcont<br>
-<br>
-    else:<br>
-      %subtmp = fsub double %x, 1.000000e+00<br>
-      %calltmp = call double @fib(double %subtmp)<br>
-      %subtmp5 = fsub double %x, 2.000000e+00<br>
-      %calltmp6 = call double @fib(double %subtmp5)<br>
-      %addtmp = fadd double %calltmp, %calltmp6<br>
-      ret double %addtmp<br>
-<br>
-    ifcont:<br>
-      ret double 1.000000e+00<br>
-    }<br>
-<br>
-Here we see that the simplifycfg pass decided to clone the return<br>
-instruction into the end of the 'else' block. This allowed it to<br>
-eliminate some branches and the PHI node.<br>
-<br>
-Now that all symbol table references are updated to use stack variables,<br>
-we'll add the assignment operator.<br>
-<br>
-New Assignment Operator<br>
-=======================<br>
-<br>
-With our current framework, adding a new assignment operator is really<br>
-simple. We will parse it just like any other binary operator, but handle<br>
-it internally (instead of allowing the user to define it). The first<br>
-step is to set a precedence:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-     int main() {<br>
-       // Install standard binary operators.<br>
-       // 1 is lowest precedence.<br>
-       BinopPrecedence['='] = 2;<br>
-       BinopPrecedence['<'] = 10;<br>
-       BinopPrecedence['+'] = 20;<br>
-       BinopPrecedence['-'] = 20;<br>
-<br>
-Now that the parser knows the precedence of the binary operator, it<br>
-takes care of all the parsing and AST generation. We just need to<br>
-implement codegen for the assignment operator. This looks like:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *BinaryExprAST::codegen() {<br>
-      // Special case '=' because we don't want to emit the LHS as an expression.<br>
-      if (Op == '=') {<br>
-        // Assignment requires the LHS to be an identifier.<br>
-        VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS.get());<br>
-        if (!LHSE)<br>
-          return LogErrorV("destination of '=' must be a variable");<br>
-<br>
-Unlike the rest of the binary operators, our assignment operator doesn't<br>
-follow the "emit LHS, emit RHS, do computation" model. As such, it is<br>
-handled as a special case before the other binary operators are handled.<br>
-The other strange thing is that it requires the LHS to be a variable. It<br>
-is invalid to have "(x+1) = expr" - only things like "x = expr" are<br>
-allowed.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-        // Codegen the RHS.<br>
-        Value *Val = RHS->codegen();<br>
-        if (!Val)<br>
-          return nullptr;<br>
-<br>
-        // Look up the name.<br>
-        Value *Variable = NamedValues[LHSE->getName()];<br>
-        if (!Variable)<br>
-          return LogErrorV("Unknown variable name");<br>
-<br>
-        Builder.CreateStore(Val, Variable);<br>
-        return Val;<br>
-      }<br>
-      ...<br>
-<br>
-Once we have the variable, codegen'ing the assignment is<br>
-straightforward: we emit the RHS of the assignment, create a store, and<br>
-return the computed value. Returning a value allows for chained<br>
-assignments like "X = (Y = Z)".<br>
-<br>
-Now that we have an assignment operator, we can mutate loop variables<br>
-and arguments. For example, we can now run code like this:<br>
-<br>
-::<br>
-<br>
-    # Function to print a double.<br>
-    extern printd(x);<br>
-<br>
-    # Define ':' for sequencing: as a low-precedence operator that ignores operands<br>
-    # and just returns the RHS.<br>
-    def binary : 1 (x y) y;<br>
-<br>
-    def test(x)<br>
-      printd(x) :<br>
-      x = 4 :<br>
-      printd(x);<br>
-<br>
-    test(123);<br>
-<br>
-When run, this example prints "123" and then "4", showing that we did<br>
-actually mutate the value! Okay, we have now officially implemented our<br>
-goal: getting this to work requires SSA construction in the general<br>
-case. However, to be really useful, we want the ability to define our<br>
-own local variables, let's add this next!<br>
-<br>
-User-defined Local Variables<br>
-============================<br>
-<br>
-Adding var/in is just like any other extension we made to<br>
-Kaleidoscope: we extend the lexer, the parser, the AST and the code<br>
-generator. The first step for adding our new 'var/in' construct is to<br>
-extend the lexer. As before, this is pretty trivial, the code looks like<br>
-this:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    enum Token {<br>
-      ...<br>
-      // var definition<br>
-      tok_var = -13<br>
-    ...<br>
-    }<br>
-    ...<br>
-    static int gettok() {<br>
-    ...<br>
-        if (IdentifierStr == "in")<br>
-          return tok_in;<br>
-        if (IdentifierStr == "binary")<br>
-          return tok_binary;<br>
-        if (IdentifierStr == "unary")<br>
-          return tok_unary;<br>
-        if (IdentifierStr == "var")<br>
-          return tok_var;<br>
-        return tok_identifier;<br>
-    ...<br>
-<br>
-The next step is to define the AST node that we will construct. For<br>
-var/in, it looks like this:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// VarExprAST - Expression class for var/in<br>
-    class VarExprAST : public ExprAST {<br>
-      std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;<br>
-      std::unique_ptr<ExprAST> Body;<br>
-<br>
-    public:<br>
-      VarExprAST(std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,<br>
-                 std::unique_ptr<ExprAST> body)<br>
-      : VarNames(std::move(VarNames)), Body(std::move(Body)) {}<br>
-<br>
-      virtual Value *codegen();<br>
-    };<br>
-<br>
-var/in allows a list of names to be defined all at once, and each name<br>
-can optionally have an initializer value. As such, we capture this<br>
-information in the VarNames vector. Also, var/in has a body, this body<br>
-is allowed to access the variables defined by the var/in.<br>
-<br>
-With this in place, we can define the parser pieces. The first thing we<br>
-do is add it as a primary expression:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// primary<br>
-    ///   ::= identifierexpr<br>
-    ///   ::= numberexpr<br>
-    ///   ::= parenexpr<br>
-    ///   ::= ifexpr<br>
-    ///   ::= forexpr<br>
-    ///   ::= varexpr<br>
-    static std::unique_ptr<ExprAST> ParsePrimary() {<br>
-      switch (CurTok) {<br>
-      default:<br>
-        return LogError("unknown token when expecting an expression");<br>
-      case tok_identifier:<br>
-        return ParseIdentifierExpr();<br>
-      case tok_number:<br>
-        return ParseNumberExpr();<br>
-      case '(':<br>
-        return ParseParenExpr();<br>
-      case tok_if:<br>
-        return ParseIfExpr();<br>
-      case tok_for:<br>
-        return ParseForExpr();<br>
-      case tok_var:<br>
-        return ParseVarExpr();<br>
-      }<br>
-    }<br>
-<br>
-Next we define ParseVarExpr:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    /// varexpr ::= 'var' identifier ('=' expression)?<br>
-    //                    (',' identifier ('=' expression)?)* 'in' expression<br>
-    static std::unique_ptr<ExprAST> ParseVarExpr() {<br>
-      getNextToken();  // eat the var.<br>
-<br>
-      std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;<br>
-<br>
-      // At least one variable name is required.<br>
-      if (CurTok != tok_identifier)<br>
-        return LogError("expected identifier after var");<br>
-<br>
-The first part of this code parses the list of identifier/expr pairs<br>
-into the local ``VarNames`` vector.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      while (1) {<br>
-        std::string Name = IdentifierStr;<br>
-        getNextToken();  // eat identifier.<br>
-<br>
-        // Read the optional initializer.<br>
-        std::unique_ptr<ExprAST> Init;<br>
-        if (CurTok == '=') {<br>
-          getNextToken(); // eat the '='.<br>
-<br>
-          Init = ParseExpression();<br>
-          if (!Init) return nullptr;<br>
-        }<br>
-<br>
-        VarNames.push_back(std::make_pair(Name, std::move(Init)));<br>
-<br>
-        // End of var list, exit loop.<br>
-        if (CurTok != ',') break;<br>
-        getNextToken(); // eat the ','.<br>
-<br>
-        if (CurTok != tok_identifier)<br>
-          return LogError("expected identifier list after var");<br>
-      }<br>
-<br>
-Once all the variables are parsed, we then parse the body and create the<br>
-AST node:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // At this point, we have to have 'in'.<br>
-      if (CurTok != tok_in)<br>
-        return LogError("expected 'in' keyword after 'var'");<br>
-      getNextToken();  // eat 'in'.<br>
-<br>
-      auto Body = ParseExpression();<br>
-      if (!Body)<br>
-        return nullptr;<br>
-<br>
-      return llvm::make_unique<VarExprAST>(std::move(VarNames),<br>
-                                           std::move(Body));<br>
-    }<br>
-<br>
-Now that we can parse and represent the code, we need to support<br>
-emission of LLVM IR for it. This code starts out with:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-    Value *VarExprAST::codegen() {<br>
-      std::vector<AllocaInst *> OldBindings;<br>
-<br>
-      Function *TheFunction = Builder.GetInsertBlock()->getParent();<br>
-<br>
-      // Register all variables and emit their initializer.<br>
-      for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {<br>
-        const std::string &VarName = VarNames[i].first;<br>
-        ExprAST *Init = VarNames[i].second.get();<br>
-<br>
-Basically it loops over all the variables, installing them one at a<br>
-time. For each variable we put into the symbol table, we remember the<br>
-previous value that we replace in OldBindings.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-        // Emit the initializer before adding the variable to scope, this prevents<br>
-        // the initializer from referencing the variable itself, and permits stuff<br>
-        // like this:<br>
-        //  var a = 1 in<br>
-        //    var a = a in ...   # refers to outer 'a'.<br>
-        Value *InitVal;<br>
-        if (Init) {<br>
-          InitVal = Init->codegen();<br>
-          if (!InitVal)<br>
-            return nullptr;<br>
-        } else { // If not specified, use 0.0.<br>
-          InitVal = ConstantFP::get(LLVMContext, APFloat(0.0));<br>
-        }<br>
-<br>
-        AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);<br>
-        Builder.CreateStore(InitVal, Alloca);<br>
-<br>
-        // Remember the old variable binding so that we can restore the binding when<br>
-        // we unrecurse.<br>
-        OldBindings.push_back(NamedValues[VarName]);<br>
-<br>
-        // Remember this binding.<br>
-        NamedValues[VarName] = Alloca;<br>
-      }<br>
-<br>
-There are more comments here than code. The basic idea is that we emit<br>
-the initializer, create the alloca, then update the symbol table to<br>
-point to it. Once all the variables are installed in the symbol table,<br>
-we evaluate the body of the var/in expression:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Codegen the body, now that all vars are in scope.<br>
-      Value *BodyVal = Body->codegen();<br>
-      if (!BodyVal)<br>
-        return nullptr;<br>
-<br>
-Finally, before returning, we restore the previous variable bindings:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-      // Pop all our variables from scope.<br>
-      for (unsigned i = 0, e = VarNames.size(); i != e; ++i)<br>
-        NamedValues[VarNames[i].first] = OldBindings[i];<br>
-<br>
-      // Return the body computation.<br>
-      return BodyVal;<br>
-    }<br>
-<br>
-The end result of all of this is that we get properly scoped variable<br>
-definitions, and we even (trivially) allow mutation of them :).<br>
-<br>
-With this, we completed what we set out to do. Our nice iterative fib<br>
-example from the intro compiles and runs just fine. The mem2reg pass<br>
-optimizes all of our stack variables into SSA registers, inserting PHI<br>
-nodes where needed, and our front-end remains simple: no "iterated<br>
-dominance frontier" computation anywhere in sight.<br>
-<br>
-Full Code Listing<br>
-=================<br>
-<br>
-Here is the complete code listing for our running example, enhanced with<br>
-mutable variables and var/in support. To build this example, use:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    # Compile<br>
-    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
-    # Run<br>
-    ./toy<br>
-<br>
-Here is the code:<br>
-<br>
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter7/toy.cpp<br>
-   :language: c++<br>
-<br>
-`Next: Adding Debug Information <LangImpl8.html>`_<br>
-<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl8.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl8.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl8.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl8.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl8.rst (removed)<br>
@@ -1,462 +0,0 @@<br>
-======================================<br>
-Kaleidoscope: Adding Debug Information<br>
-======================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Chapter 8 Introduction<br>
-======================<br>
-<br>
-Welcome to Chapter 8 of the "`Implementing a language with<br>
-LLVM <index.html>`_" tutorial. In chapters 1 through 7, we've built a<br>
-decent little programming language with functions and variables.<br>
-What happens if something goes wrong though, how do you debug your<br>
-program?<br>
-<br>
-Source level debugging uses formatted data that helps a debugger<br>
-translate from binary and the state of the machine back to the<br>
-source that the programmer wrote. In LLVM we generally use a format<br>
-called `DWARF <<a href="http://dwarfstd.org" rel="noreferrer" target="_blank">http://dwarfstd.org</a>>`_. DWARF is a compact encoding<br>
-that represents types, source locations, and variable locations.<br>
-<br>
-The short summary of this chapter is that we'll go through the<br>
-various things you have to add to a programming language to<br>
-support debug info, and how you translate that into DWARF.<br>
-<br>
-Caveat: For now we can't debug via the JIT, so we'll need to compile<br>
-our program down to something small and standalone. As part of this<br>
-we'll make a few modifications to the running of the language and<br>
-how programs are compiled. This means that we'll have a source file<br>
-with a simple program written in Kaleidoscope rather than the<br>
-interactive JIT. It does involve a limitation that we can only<br>
-have one "top level" command at a time to reduce the number of<br>
-changes necessary.<br>
-<br>
-Here's the sample program we'll be compiling:<br>
-<br>
-.. code-block:: python<br>
-<br>
-   def fib(x)<br>
-     if x < 3 then<br>
-       1<br>
-     else<br>
-       fib(x-1)+fib(x-2);<br>
-<br>
-   fib(10)<br>
-<br>
-<br>
-Why is this a hard problem?<br>
-===========================<br>
-<br>
-Debug information is a hard problem for a few different reasons - mostly<br>
-centered around optimized code. First, optimization makes keeping source<br>
-locations more difficult. In LLVM IR we keep the original source location<br>
-for each IR level instruction on the instruction. Optimization passes<br>
-should keep the source locations for newly created instructions, but merged<br>
-instructions only get to keep a single location - this can cause jumping<br>
-around when stepping through optimized programs. Secondly, optimization<br>
-can move variables in ways that are either optimized out, shared in memory<br>
-with other variables, or difficult to track. For the purposes of this<br>
-tutorial we're going to avoid optimization (as you'll see with one of the<br>
-next sets of patches).<br>
-<br>
-Ahead-of-Time Compilation Mode<br>
-==============================<br>
-<br>
-To highlight only the aspects of adding debug information to a source<br>
-language without needing to worry about the complexities of JIT debugging<br>
-we're going to make a few changes to Kaleidoscope to support compiling<br>
-the IR emitted by the front end into a simple standalone program that<br>
-you can execute, debug, and see results.<br>
-<br>
-First we make our anonymous function that contains our top level<br>
-statement be our "main":<br>
-<br>
-.. code-block:: udiff<br>
-<br>
-  -    auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());<br>
-  +    auto Proto = llvm::make_unique<PrototypeAST>("main", std::vector<std::string>());<br>
-<br>
-just with the simple change of giving it a name.<br>
-<br>
-Then we're going to remove the command line code wherever it exists:<br>
-<br>
-.. code-block:: udiff<br>
-<br>
-  @@ -1129,7 +1129,6 @@ static void HandleTopLevelExpression() {<br>
-   /// top ::= definition | external | expression | ';'<br>
-   static void MainLoop() {<br>
-     while (1) {<br>
-  -    fprintf(stderr, "ready> ");<br>
-       switch (CurTok) {<br>
-       case tok_eof:<br>
-         return;<br>
-  @@ -1184,7 +1183,6 @@ int main() {<br>
-     BinopPrecedence['*'] = 40; // highest.<br>
-<br>
-     // Prime the first token.<br>
-  -  fprintf(stderr, "ready> ");<br>
-     getNextToken();<br>
-<br>
-Lastly we're going to disable all of the optimization passes and the JIT so<br>
-that the only thing that happens after we're done parsing and generating<br>
-code is that the llvm IR goes to standard error:<br>
-<br>
-.. code-block:: udiff<br>
-<br>
-  @@ -1108,17 +1108,8 @@ static void HandleExtern() {<br>
-   static void HandleTopLevelExpression() {<br>
-     // Evaluate a top-level expression into an anonymous function.<br>
-     if (auto FnAST = ParseTopLevelExpr()) {<br>
-  -    if (auto *FnIR = FnAST->codegen()) {<br>
-  -      // We're just doing this to make sure it executes.<br>
-  -      TheExecutionEngine->finalizeObject();<br>
-  -      // JIT the function, returning a function pointer.<br>
-  -      void *FPtr = TheExecutionEngine->getPointerToFunction(FnIR);<br>
-  -<br>
-  -      // Cast it to the right type (takes no arguments, returns a double) so we<br>
-  -      // can call it as a native function.<br>
-  -      double (*FP)() = (double (*)())(intptr_t)FPtr;<br>
-  -      // Ignore the return value for this.<br>
-  -      (void)FP;<br>
-  +    if (!F->codegen()) {<br>
-  +      fprintf(stderr, "Error generating code for top level expr");<br>
-       }<br>
-     } else {<br>
-       // Skip token for error recovery.<br>
-  @@ -1439,11 +1459,11 @@ int main() {<br>
-     // target lays out data structures.<br>
-     TheModule->setDataLayout(TheExecutionEngine->getDataLayout());<br>
-     OurFPM.add(new DataLayoutPass());<br>
-  +#if 0<br>
-     OurFPM.add(createBasicAliasAnalysisPass());<br>
-     // Promote allocas to registers.<br>
-     OurFPM.add(createPromoteMemoryToRegisterPass());<br>
-  @@ -1218,7 +1210,7 @@ int main() {<br>
-     OurFPM.add(createGVNPass());<br>
-     // Simplify the control flow graph (deleting unreachable blocks, etc).<br>
-     OurFPM.add(createCFGSimplificationPass());<br>
-  -<br>
-  +  #endif<br>
-     OurFPM.doInitialization();<br>
-<br>
-     // Set the global so the code gen can use this.<br>
-<br>
-This relatively small set of changes get us to the point that we can compile<br>
-our piece of Kaleidoscope language down to an executable program via this<br>
-command line:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-  Kaleidoscope-Ch8 < fib.ks | & clang -x ir -<br>
-<br>
-which gives an a.out/a.exe in the current working directory.<br>
-<br>
-Compile Unit<br>
-============<br>
-<br>
-The top level container for a section of code in DWARF is a compile unit.<br>
-This contains the type and function data for an individual translation unit<br>
-(read: one file of source code). So the first thing we need to do is<br>
-construct one for our fib.ks file.<br>
-<br>
-DWARF Emission Setup<br>
-====================<br>
-<br>
-Similar to the ``IRBuilder`` class we have a<br>
-`DIBuilder <<a href="http://llvm.org/doxygen/classllvm_1_1DIBuilder.html" rel="noreferrer" target="_blank">http://llvm.org/doxygen/classllvm_1_1DIBuilder.html</a>>`_ class<br>
-that helps in constructing debug metadata for an llvm IR file. It<br>
-corresponds 1:1 similarly to ``IRBuilder`` and llvm IR, but with nicer names.<br>
-Using it does require that you be more familiar with DWARF terminology than<br>
-you needed to be with ``IRBuilder`` and ``Instruction`` names, but if you<br>
-read through the general documentation on the<br>
-`Metadata Format <<a href="http://llvm.org/docs/SourceLevelDebugging.html" rel="noreferrer" target="_blank">http://llvm.org/docs/SourceLevelDebugging.html</a>>`_ it<br>
-should be a little more clear. We'll be using this class to construct all<br>
-of our IR level descriptions. Construction for it takes a module so we<br>
-need to construct it shortly after we construct our module. We've left it<br>
-as a global static variable to make it a bit easier to use.<br>
-<br>
-Next we're going to create a small container to cache some of our frequent<br>
-data. The first will be our compile unit, but we'll also write a bit of<br>
-code for our one type since we won't have to worry about multiple typed<br>
-expressions:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  static DIBuilder *DBuilder;<br>
-<br>
-  struct DebugInfo {<br>
-    DICompileUnit *TheCU;<br>
-    DIType *DblTy;<br>
-<br>
-    DIType *getDoubleTy();<br>
-  } KSDbgInfo;<br>
-<br>
-  DIType *DebugInfo::getDoubleTy() {<br>
-    if (DblTy.isValid())<br>
-      return DblTy;<br>
-<br>
-    DblTy = DBuilder->createBasicType("double", 64, 64, dwarf::DW_ATE_float);<br>
-    return DblTy;<br>
-  }<br>
-<br>
-And then later on in ``main`` when we're constructing our module:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  DBuilder = new DIBuilder(*TheModule);<br>
-<br>
-  KSDbgInfo.TheCU = DBuilder->createCompileUnit(<br>
-      dwarf::DW_LANG_C, "fib.ks", ".", "Kaleidoscope Compiler", 0, "", 0);<br>
-<br>
-There are a couple of things to note here. First, while we're producing a<br>
-compile unit for a language called Kaleidoscope we used the language<br>
-constant for C. This is because a debugger wouldn't necessarily understand<br>
-the calling conventions or default ABI for a language it doesn't recognize<br>
-and we follow the C ABI in our llvm code generation so it's the closest<br>
-thing to accurate. This ensures we can actually call functions from the<br>
-debugger and have them execute. Secondly, you'll see the "fib.ks" in the<br>
-call to ``createCompileUnit``. This is a default hard coded value since<br>
-we're using shell redirection to put our source into the Kaleidoscope<br>
-compiler. In a usual front end you'd have an input file name and it would<br>
-go there.<br>
-<br>
-One last thing as part of emitting debug information via DIBuilder is that<br>
-we need to "finalize" the debug information. The reasons are part of the<br>
-underlying API for DIBuilder, but make sure you do this near the end of<br>
-main:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  DBuilder->finalize();<br>
-<br>
-before you dump out the module.<br>
-<br>
-Functions<br>
-=========<br>
-<br>
-Now that we have our ``Compile Unit`` and our source locations, we can add<br>
-function definitions to the debug info. So in ``PrototypeAST::codegen()`` we<br>
-add a few lines of code to describe a context for our subprogram, in this<br>
-case the "File", and the actual definition of the function itself.<br>
-<br>
-So the context:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(),<br>
-                                      KSDbgInfo.TheCU.getDirectory());<br>
-<br>
-giving us an DIFile and asking the ``Compile Unit`` we created above for the<br>
-directory and filename where we are currently. Then, for now, we use some<br>
-source locations of 0 (since our AST doesn't currently have source location<br>
-information) and construct our function definition:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  DIScope *FContext = Unit;<br>
-  unsigned LineNo = 0;<br>
-  unsigned ScopeLine = 0;<br>
-  DISubprogram *SP = DBuilder->createFunction(<br>
-      FContext, Name, StringRef(), Unit, LineNo,<br>
-      CreateFunctionType(Args.size(), Unit), false /* internal linkage */,<br>
-      true /* definition */, ScopeLine, DINode::FlagPrototyped, false);<br>
-  F->setSubprogram(SP);<br>
-<br>
-and we now have an DISubprogram that contains a reference to all of our<br>
-metadata for the function.<br>
-<br>
-Source Locations<br>
-================<br>
-<br>
-The most important thing for debug information is accurate source location -<br>
-this makes it possible to map your source code back. We have a problem though,<br>
-Kaleidoscope really doesn't have any source location information in the lexer<br>
-or parser so we'll need to add it.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-   struct SourceLocation {<br>
-     int Line;<br>
-     int Col;<br>
-   };<br>
-   static SourceLocation CurLoc;<br>
-   static SourceLocation LexLoc = {1, 0};<br>
-<br>
-   static int advance() {<br>
-     int LastChar = getchar();<br>
-<br>
-     if (LastChar == '\n' || LastChar == '\r') {<br>
-       LexLoc.Line++;<br>
-       LexLoc.Col = 0;<br>
-     } else<br>
-       LexLoc.Col++;<br>
-     return LastChar;<br>
-   }<br>
-<br>
-In this set of code we've added some functionality on how to keep track of the<br>
-line and column of the "source file". As we lex every token we set our current<br>
-current "lexical location" to the assorted line and column for the beginning<br>
-of the token. We do this by overriding all of the previous calls to<br>
-``getchar()`` with our new ``advance()`` that keeps track of the information<br>
-and then we have added to all of our AST classes a source location:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-   class ExprAST {<br>
-     SourceLocation Loc;<br>
-<br>
-     public:<br>
-       ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}<br>
-       virtual ~ExprAST() {}<br>
-       virtual Value* codegen() = 0;<br>
-       int getLine() const { return Loc.Line; }<br>
-       int getCol() const { return Loc.Col; }<br>
-       virtual raw_ostream &dump(raw_ostream &out, int ind) {<br>
-         return out << ':' << getLine() << ':' << getCol() << '\n';<br>
-       }<br>
-<br>
-that we pass down through when we create a new expression:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-   LHS = llvm::make_unique<BinaryExprAST>(BinLoc, BinOp, std::move(LHS),<br>
-                                          std::move(RHS));<br>
-<br>
-giving us locations for each of our expressions and variables.<br>
-<br>
-From this we can make sure to tell ``DIBuilder`` when we're at a new source<br>
-location so it can use that when we generate the rest of our code and make<br>
-sure that each instruction has source location information. We do this<br>
-by constructing another small function:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  void DebugInfo::emitLocation(ExprAST *AST) {<br>
-    DIScope *Scope;<br>
-    if (LexicalBlocks.empty())<br>
-      Scope = TheCU;<br>
-    else<br>
-      Scope = LexicalBlocks.back();<br>
-    Builder.SetCurrentDebugLocation(<br>
-        DebugLoc::get(AST->getLine(), AST->getCol(), Scope));<br>
-  }<br>
-<br>
-that both tells the main ``IRBuilder`` where we are, but also what scope<br>
-we're in. Since we've just created a function above we can either be in<br>
-the main file scope (like when we created our function), or now we can be<br>
-in the function scope we just created. To represent this we create a stack<br>
-of scopes:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-   std::vector<DIScope *> LexicalBlocks;<br>
-   std::map<const PrototypeAST *, DIScope *> FnScopeMap;<br>
-<br>
-and keep a map of each function to the scope that it represents (an<br>
-DISubprogram is also an DIScope).<br>
-<br>
-Then we make sure to:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-   KSDbgInfo.emitLocation(this);<br>
-<br>
-emit the location every time we start to generate code for a new AST, and<br>
-also:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  KSDbgInfo.FnScopeMap[this] = SP;<br>
-<br>
-store the scope (function) when we create it and use it:<br>
-<br>
-  KSDbgInfo.LexicalBlocks.push_back(&KSDbgInfo.FnScopeMap[Proto]);<br>
-<br>
-when we start generating the code for each function.<br>
-<br>
-also, don't forget to pop the scope back off of your scope stack at the<br>
-end of the code generation for the function:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  // Pop off the lexical block for the function since we added it<br>
-  // unconditionally.<br>
-  KSDbgInfo.LexicalBlocks.pop_back();<br>
-<br>
-Variables<br>
-=========<br>
-<br>
-Now that we have functions, we need to be able to print out the variables<br>
-we have in scope. Let's get our function arguments set up so we can get<br>
-decent backtraces and see how our functions are being called. It isn't<br>
-a lot of code, and we generally handle it when we're creating the<br>
-argument allocas in ``PrototypeAST::CreateArgumentAllocas``.<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  DIScope *Scope = KSDbgInfo.LexicalBlocks.back();<br>
-  DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(),<br>
-                                      KSDbgInfo.TheCU.getDirectory());<br>
-  DILocalVariable D = DBuilder->createParameterVariable(<br>
-      Scope, Args[Idx], Idx + 1, Unit, Line, KSDbgInfo.getDoubleTy(), true);<br>
-<br>
-  DBuilder->insertDeclare(Alloca, D, DBuilder->createExpression(),<br>
-                          DebugLoc::get(Line, 0, Scope),<br>
-                          Builder.GetInsertBlock());<br>
-<br>
-Here we're doing a few things. First, we're grabbing our current scope<br>
-for the variable so we can say what range of code our variable is valid<br>
-through. Second, we're creating the variable, giving it the scope,<br>
-the name, source location, type, and since it's an argument, the argument<br>
-index. Third, we create an ``lvm.dbg.declare`` call to indicate at the IR<br>
-level that we've got a variable in an alloca (and it gives a starting<br>
-location for the variable), and setting a source location for the<br>
-beginning of the scope on the declare.<br>
-<br>
-One interesting thing to note at this point is that various debuggers have<br>
-assumptions based on how code and debug information was generated for them<br>
-in the past. In this case we need to do a little bit of a hack to avoid<br>
-generating line information for the function prologue so that the debugger<br>
-knows to skip over those instructions when setting a breakpoint. So in<br>
-``FunctionAST::CodeGen`` we add a couple of lines:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  // Unset the location for the prologue emission (leading instructions with no<br>
-  // location in a function are considered part of the prologue and the debugger<br>
-  // will run past them when breaking on a function)<br>
-  KSDbgInfo.emitLocation(nullptr);<br>
-<br>
-and then emit a new location when we actually start generating code for the<br>
-body of the function:<br>
-<br>
-.. code-block:: c++<br>
-<br>
-  KSDbgInfo.emitLocation(Body);<br>
-<br>
-With this we have enough debug information to set breakpoints in functions,<br>
-print out argument variables, and call functions. Not too bad for just a<br>
-few simple lines of code!<br>
-<br>
-Full Code Listing<br>
-=================<br>
-<br>
-Here is the complete code listing for our running example, enhanced with<br>
-debug information. To build this example, use:<br>
-<br>
-.. code-block:: bash<br>
-<br>
-    # Compile<br>
-    clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy<br>
-    # Run<br>
-    ./toy<br>
-<br>
-Here is the code:<br>
-<br>
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter8/toy.cpp<br>
-   :language: c++<br>
-<br>
-`Next: Conclusion and other useful LLVM tidbits <LangImpl9.html>`_<br>
-<br>
<br>
Removed: llvm/trunk/docs/tutorial/LangImpl9.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl9.rst?rev=274440&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl9.rst?rev=274440&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/LangImpl9.rst (original)<br>
+++ llvm/trunk/docs/tutorial/LangImpl9.rst (removed)<br>
@@ -1,259 +0,0 @@<br>
-======================================================<br>
-Kaleidoscope: Conclusion and other useful LLVM tidbits<br>
-======================================================<br>
-<br>
-.. contents::<br>
-   :local:<br>
-<br>
-Tutorial Conclusion<br>
-===================<br>
-<br>
-Welcome to the final chapter of the "`Implementing a language with<br>
-LLVM <index.html>`_" tutorial. In the course of this tutorial, we have<br>
-grown our little Kaleidoscope language from being a useless toy, to<br>
-being a semi-interesting (but probably still useless) toy. :)<br>
-<br>
-It is interesting to see how far we've come, and how little code it has<br>
-taken. We built the entire lexer, parser, AST, code generator, an<br>
-interactive run-loop (with a JIT!), and emitted debug information in<br>
-standalone executables - all in under 1000 lines of (non-comment/non-blank)<br>
-code.<br>
-<br>
-Our little language supports a couple of interesting features: it<br>
-supports user defined binary and unary operators, it uses JIT<br>
-compilation for immediate evaluation, and it supports a few control flow<br>
-constructs with SSA construction.<br>
-<br>
-Part of the idea of this tutorial was to show you how easy and fun it<br>
-can be to define, build, and play with languages. Building a compiler<br>
-need not be a scary or mystical process! Now that you've seen some of<br>
-the basics, I strongly encourage you to take the code and hack on it.<br>
-For example, try adding:<br>
-<br>
--  **global variables** - While global variables have questional value<br>
-   in modern software engineering, they are often useful when putting<br>
-   together quick little hacks like the Kaleidoscope compiler itself.<br>
-   Fortunately, our current setup makes it very easy to add global<br>
-   variables: just have value lookup check to see if an unresolved<br>
-   variable is in the global variable symbol table before rejecting it.<br>
-   To create a new global variable, make an instance of the LLVM<br>
-   ``GlobalVariable`` class.<br>
--  **typed variables** - Kaleidoscope currently only supports variables<br>
-   of type double. This gives the language a very nice elegance, because<br>
-   only supporting one type means that you never have to specify types.<br>
-   Different languages have different ways of handling this. The easiest<br>
-   way is to require the user to specify types for every variable<br>
-   definition, and record the type of the variable in the symbol table<br>
-   along with its Value\*.<br>
--  **arrays, structs, vectors, etc** - Once you add types, you can start<br>
-   extending the type system in all sorts of interesting ways. Simple<br>
-   arrays are very easy and are quite useful for many different<br>
-   applications. Adding them is mostly an exercise in learning how the<br>
-   LLVM `getelementptr <../LangRef.html#getelementptr-instruction>`_ instruction<br>
-   works: it is so nifty/unconventional, it `has its own<br>
-   FAQ <../GetElementPtr.html>`_!<br>
--  **standard runtime** - Our current language allows the user to access<br>
-   arbitrary external functions, and we use it for things like "printd"<br>
-   and "putchard". As you extend the language to add higher-level<br>
-   constructs, often these constructs make the most sense if they are<br>
-   lowered to calls into a language-supplied runtime. For example, if<br>
-   you add hash tables to the language, it would probably make sense to<br>
-   add the routines to a runtime, instead of inlining them all the way.<br>
--  **memory management** - Currently we can only access the stack in<br>
-   Kaleidoscope. It would also be useful to be able to allocate heap<br>
-   memory, either with calls to the standard libc malloc/free interface<br>
-   or with a garbage collector. If you would like to use garbage<br>
-   collection, note that LLVM fully supports `Accurate Garbage<br>
-   Collection <../GarbageCollection.html>`_ including algorithms that<br>
-   move objects and need to scan/update the stack.<br>
--  **exception handling support** - LLVM supports generation of `zero<br>
-   cost exceptions <../ExceptionHandling.html>`_ which interoperate with<br>
-   code compiled in other languages. You could also generate code by<br>
-   implicitly making every function return an error value and checking<br>
-   it. You could also make explicit use of setjmp/longjmp. There are<br>
-   many different ways to go here.<br>
--  **object orientation, generics, database access, complex numbers,<br>
-   geometric programming, ...** - Really, there is no end of crazy<br>
-   features that you can add to the language.<br>
--  **unusual domains** - We've been talking about applying LLVM to a<br>
-   domain that many people are interested in: building a compiler for a<br>
-   specific language. However, there are many other domains that can use<br>
-   compiler technology that are not typically considered. For example,<br>
-   LLVM has been used to implement OpenGL graphics acceleration,<br>
-   translate C++ code to ActionScript, and many other cute and clever<br>
-   things. Maybe you will be the first to JIT compile a regular<br>
-   expression interpreter into native code with LLVM?<br>
-<br>
-Have fun - try doing something crazy and unusual. Building a language<br>
-like everyone else always has, is much less fun than trying something a<br>
-little crazy or off the wall and seeing how it turns out. If you get<br>
-stuck or want to talk about it, feel free to email the `llvm-dev mailing<br>
-list <<a href="http://lists.llvm.org/mailman/listinfo/llvm-dev" rel="noreferrer" target="_blank">http://lists.llvm.org/mailman/listinfo/llvm-dev</a>>`_: it has lots<br>
-of people who are interested in languages and are often willing to help<br>
-out.<br>
-<br>
-Before we end this tutorial, I want to talk about some "tips and tricks"<br>
-for generating LLVM IR. These are some of the more subtle things that<br>
-may not be obvious, but are very useful if you want to take advantage of<br>
-LLVM's capabilities.<br>
-<br>
-Properties of the LLVM IR<br>
-=========================<br>
-<br>
-We have a couple of common questions about code in the LLVM IR form -<br>
-let's just get these out of the way right now, shall we?<br>
-<br>
-Target Independence<br>
--------------------<br>
-<br>
-Kaleidoscope is an example of a "portable language": any program written<br>
-in Kaleidoscope will work the same way on any target that it runs on.<br>
-Many other languages have this property, e.g. lisp, java, haskell,<br>
-javascript, python, etc (note that while these languages are portable,<br>
-not all their libraries are).<br>
-<br>
-One nice aspect of LLVM is that it is often capable of preserving target<br>
-independence in the IR: you can take the LLVM IR for a<br>
-Kaleidoscope-compiled program and run it on any target that LLVM<br>
-supports, even emitting C code and compiling that on targets that LLVM<br>
-doesn't support natively. You can trivially tell that the Kaleidoscope<br>
-compiler generates target-independent code because it never queries for<br>
-any target-specific information when generating code.<br>
-<br>
-The fact that LLVM provides a compact, target-independent,<br>
-representation for code gets a lot of people excited. Unfortunately,<br>
-these people are usually thinking about C or a language from the C<br>
-family when they are asking questions about language portability. I say<br>
-"unfortunately", because there is really no way to make (fully general)<br>
-C code portable, other than shipping the source code around (and of<br>
-course, C source code is not actually portable in general either - ever<br>
-port a really old application from 32- to 64-bits?).<br>
-<br>
-The problem with C (again, in its full generality) is that it is heavily<br>
-laden with target specific assumptions. As one simple example, the<br>
-preprocessor often destructively removes target-independence from the<br>
-code when it processes the input text:<br>
-<br>
-.. code-block:: c<br>
-<br>
-    #ifdef __i386__<br>
-      int X = 1;<br>
-    #else<br>
-      int X = 42;<br>
-    #endif<br>
-<br>
-While it is possible to engineer more and more complex solutions to<br>
-problems like this, it cannot be solved in full generality in a way that<br>
-is better than shipping the actual source code.<br>
-<br>
-That said, there are interesting subsets of C that can be made portable.<br>
-If you are willing to fix primitive types to a fixed size (say int =<br>
-32-bits, and long = 64-bits), don't care about ABI compatibility with<br>
-existing binaries, and are willing to give up some other minor features,<br>
-you can have portable code. This can make sense for specialized domains<br>
-such as an in-kernel language.<br>
-<br>
-Safety Guarantees<br>
------------------<br>
-<br>
-Many of the languages above are also "safe" languages: it is impossible<br>
-for a program written in Java to corrupt its address space and crash the<br>
-process (assuming the JVM has no bugs). Safety is an interesting<br>
-property that requires a combination of language design, runtime<br>
-support, and often operating system support.<br>
-<br>
-It is certainly possible to implement a safe language in LLVM, but LLVM<br>
-IR does not itself guarantee safety. The LLVM IR allows unsafe pointer<br>
-casts, use after free bugs, buffer over-runs, and a variety of other<br>
-problems. Safety needs to be implemented as a layer on top of LLVM and,<br>
-conveniently, several groups have investigated this. Ask on the `llvm-dev<br>
-mailing list <<a href="http://lists.llvm.org/mailman/listinfo/llvm-dev" rel="noreferrer" target="_blank">http://lists.llvm.org/mailman/listinfo/llvm-dev</a>>`_ if<br>
-you are interested in more details.<br>
-<br>
-Language-Specific Optimizations<br>
--------------------------------<br>
-<br>
-One thing about LLVM that turns off many people is that it does not<br>
-solve all the world's problems in one system (sorry 'world hunger',<br>
-someone else will have to solve you some other day). One specific<br>
-complaint is that people perceive LLVM as being incapable of performing<br>
-high-level language-specific optimization: LLVM "loses too much<br>
-information".<br>
-<br>
-Unfortunately, this is really not the place to give you a full and<br>
-unified version of "Chris Lattner's theory of compiler design". Instead,<br>
-I'll make a few observations:<br>
-<br>
-First, you're right that LLVM does lose information. For example, as of<br>
-this writing, there is no way to distinguish in the LLVM IR whether an<br>
-SSA-value came from a C "int" or a C "long" on an ILP32 machine (other<br>
-than debug info). Both get compiled down to an 'i32' value and the<br>
-information about what it came from is lost. The more general issue<br>
-here, is that the LLVM type system uses "structural equivalence" instead<br>
-of "name equivalence". Another place this surprises people is if you<br>
-have two types in a high-level language that have the same structure<br>
-(e.g. two different structs that have a single int field): these types<br>
-will compile down into a single LLVM type and it will be impossible to<br>
-tell what it came from.<br>
-<br>
-Second, while LLVM does lose information, LLVM is not a fixed target: we<br>
-continue to enhance and improve it in many different ways. In addition<br>
-to adding new features (LLVM did not always support exceptions or debug<br>
-info), we also extend the IR to capture important information for<br>
-optimization (e.g. whether an argument is sign or zero extended,<br>
-information about pointers aliasing, etc). Many of the enhancements are<br>
-user-driven: people want LLVM to include some specific feature, so they<br>
-go ahead and extend it.<br>
-<br>
-Third, it is *possible and easy* to add language-specific optimizations,<br>
-and you have a number of choices in how to do it. As one trivial<br>
-example, it is easy to add language-specific optimization passes that<br>
-"know" things about code compiled for a language. In the case of the C<br>
-family, there is an optimization pass that "knows" about the standard C<br>
-library functions. If you call "exit(0)" in main(), it knows that it is<br>
-safe to optimize that into "return 0;" because C specifies what the<br>
-'exit' function does.<br>
-<br>
-In addition to simple library knowledge, it is possible to embed a<br>
-variety of other language-specific information into the LLVM IR. If you<br>
-have a specific need and run into a wall, please bring the topic up on<br>
-the llvm-dev list. At the very worst, you can always treat LLVM as if it<br>
-were a "dumb code generator" and implement the high-level optimizations<br>
-you desire in your front-end, on the language-specific AST.<br>
-<br>
-Tips and Tricks<br>
-===============<br>
-<br>
-There is a variety of useful tips and tricks that you come to know after<br>
-working on/with LLVM that aren't obvious at first glance. Instead of<br>
-letting everyone rediscover them, this section talks about some of these<br>
-issues.<br>
-<br>
-Implementing portable offsetof/sizeof<br>
--------------------------------------<br>
-<br>
-One interesting thing that comes up, if you are trying to keep the code<br>
-generated by your compiler "target independent", is that you often need<br>
-to know the size of some LLVM type or the offset of some field in an<br>
-llvm structure. For example, you might need to pass the size of a type<br>
-into a function that allocates memory.<br>
-<br>
-Unfortunately, this can vary widely across targets: for example the<br>
-width of a pointer is trivially target-specific. However, there is a<br>
-`clever way to use the getelementptr<br>
-instruction <<a href="http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt" rel="noreferrer" target="_blank">http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt</a>>`_<br>
-that allows you to compute this in a portable way.<br>
-<br>
-Garbage Collected Stack Frames<br>
-------------------------------<br>
-<br>
-Some languages want to explicitly manage their stack frames, often so<br>
-that they are garbage collected or to allow easy implementation of<br>
-closures. There are often better ways to implement these features than<br>
-explicit stack frames, but `LLVM does support<br>
-them, <<a href="http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt" rel="noreferrer" target="_blank">http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt</a>>`_<br>
-if you want. It requires your front-end to convert the code into<br>
-`Continuation Passing<br>
-Style <<a href="http://en.wikipedia.org/wiki/Continuation-passing_style" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/Continuation-passing_style</a>>`_ and<br>
-the use of tail calls (which LLVM also supports).<br>
-<br>
<br>
Modified: llvm/trunk/docs/tutorial/OCamlLangImpl5.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/OCamlLangImpl5.rst?rev=274441&r1=274440&r2=274441&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/OCamlLangImpl5.rst?rev=274441&r1=274440&r2=274441&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/tutorial/OCamlLangImpl5.rst (original)<br>
+++ llvm/trunk/docs/tutorial/OCamlLangImpl5.rst Sat Jul  2 12:01:59 2016<br>
@@ -178,7 +178,7 @@ IR into "t.ll" and run "``llvm-as < t.ll<br>
 window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll<br>
 see this graph:<br>
<br>
-.. figure:: LangImpl5-cfg.png<br>
+.. figure:: LangImpl05-cfg.png<br>
    :align: center<br>
    :alt: Example CFG<br>
<br>
<br>
Modified: llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt?rev=274441&r1=274440&r2=274441&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt?rev=274441&r1=274440&r2=274441&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt (original)<br>
+++ llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt Sat Jul  2 12:01:59 2016<br>
@@ -1,9 +1,5 @@<br>
 set(LLVM_LINK_COMPONENTS<br>
-  Core<br>
-  ExecutionEngine<br>
-  Object<br>
-  Support<br>
-  native<br>
+  all<br>
   )<br>
<br>
 add_kaleidoscope_chapter(Kaleidoscope-Ch8<br>
<br>
Modified: llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp?rev=274441&r1=274440&r2=274441&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp?rev=274441&r1=274440&r2=274441&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp (original)<br>
+++ llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp Sat Jul  2 12:01:59 2016<br>
@@ -1,28 +1,20 @@<br>
 #include "llvm/ADT/APFloat.h"<br>
-#include "llvm/ADT/SmallVector.h"<br>
 #include "llvm/ADT/STLExtras.h"<br>
-#include "llvm/ADT/StringRef.h"<br>
-#include "llvm/ADT/Triple.h"<br>
-#include "llvm/IR/BasicBlock.h"<br>
-#include "llvm/IR/Constants.h"<br>
-#include "llvm/IR/DebugInfoMetadata.h"<br>
-#include "llvm/IR/DebugLoc.h"<br>
-#include "llvm/IR/DerivedTypes.h"<br>
-#include "llvm/IR/DIBuilder.h"<br>
-#include "llvm/IR/Function.h"<br>
-#include "llvm/IR/Instructions.h"<br>
+#include "llvm/ADT/SmallVector.h"<br>
+#include "llvm/Analysis/Passes.h"<br>
 #include "llvm/IR/IRBuilder.h"<br>
 #include "llvm/IR/LLVMContext.h"<br>
+#include "llvm/IR/LegacyPassManager.h"<br>
 #include "llvm/IR/Metadata.h"<br>
 #include "llvm/IR/Module.h"<br>
 #include "llvm/IR/Type.h"<br>
 #include "llvm/IR/Verifier.h"<br>
-#include "llvm/Support/Host.h"<br>
-#include "llvm/Support/raw_ostream.h"<br>
+#include "llvm/Support/FileSystem.h"<br>
+#include "llvm/Support/TargetRegistry.h"<br>
 #include "llvm/Support/TargetSelect.h"<br>
 #include "llvm/Target/TargetMachine.h"<br>
-#include "../include/KaleidoscopeJIT.h"<br>
-#include <cassert><br>
+#include "llvm/Target/TargetOptions.h"<br>
+#include "llvm/Transforms/Scalar.h"<br>
 #include <cctype><br>
 #include <cstdio><br>
 #include <cstdlib><br>
@@ -33,7 +25,7 @@<br>
 #include <vector><br>
<br>
 using namespace llvm;<br>
-using namespace llvm::orc;<br>
+using namespace llvm::sys;<br>
<br>
 //===----------------------------------------------------------------------===//<br>
 // Lexer<br>
@@ -67,71 +59,6 @@ enum Token {<br>
   tok_var = -13<br>
 };<br>
<br>
-std::string getTokName(int Tok) {<br>
-  switch (Tok) {<br>
-  case tok_eof:<br>
-    return "eof";<br>
-  case tok_def:<br>
-    return "def";<br>
-  case tok_extern:<br>
-    return "extern";<br>
-  case tok_identifier:<br>
-    return "identifier";<br>
-  case tok_number:<br>
-    return "number";<br>
-  case tok_if:<br>
-    return "if";<br>
-  case tok_then:<br>
-    return "then";<br>
-  case tok_else:<br>
-    return "else";<br>
-  case tok_for:<br>
-    return "for";<br>
-  case tok_in:<br>
-    return "in";<br>
-  case tok_binary:<br>
-    return "binary";<br>
-  case tok_unary:<br>
-    return "unary";<br>
-  case tok_var:<br>
-    return "var";<br>
-  }<br>
-  return std::string(1, (char)Tok);<br>
-}<br>
-<br>
-namespace {<br>
-class ExprAST;<br>
-} // end anonymous namespace<br>
-<br>
-static LLVMContext TheContext;<br>
-static IRBuilder<> Builder(TheContext);<br>
-struct DebugInfo {<br>
-  DICompileUnit *TheCU;<br>
-  DIType *DblTy;<br>
-  std::vector<DIScope *> LexicalBlocks;<br>
-<br>
-  void emitLocation(ExprAST *AST);<br>
-  DIType *getDoubleTy();<br>
-} KSDbgInfo;<br>
-<br>
-struct SourceLocation {<br>
-  int Line;<br>
-  int Col;<br>
-};<br>
-static SourceLocation CurLoc;<br>
-static SourceLocation LexLoc = {1, 0};<br>
-<br>
-static int advance() {<br>
-  int LastChar = getchar();<br>
-<br>
-  if (LastChar == '\n' || LastChar == '\r') {<br>
-    LexLoc.Line++;<br>
-    LexLoc.Col = 0;<br>
-  } else<br>
-    LexLoc.Col++;<br>
-  return LastChar;<br>
-}<br>
-<br>
 static std::string IdentifierStr; // Filled in if tok_identifier<br>
 static double NumVal;             // Filled in if tok_number<br>
<br>
@@ -141,13 +68,11 @@ static int gettok() {<br>
<br>
   // Skip any whitespace.<br>
   while (isspace(LastChar))<br>
-    LastChar = advance();<br>
-<br>
-  CurLoc = LexLoc;<br>
+    LastChar = getchar();<br>
<br>
   if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*<br>
     IdentifierStr = LastChar;<br>
-    while (isalnum((LastChar = advance())))<br>
+    while (isalnum((LastChar = getchar())))<br>
       IdentifierStr += LastChar;<br>
<br>
     if (IdentifierStr == "def")<br>
@@ -177,7 +102,7 @@ static int gettok() {<br>
     std::string NumStr;<br>
     do {<br>
       NumStr += LastChar;<br>
-      LastChar = advance();<br>
+      LastChar = getchar();<br>
     } while (isdigit(LastChar) || LastChar == '.');<br>
<br>
     NumVal = strtod(NumStr.c_str(), nullptr);<br>
@@ -187,7 +112,7 @@ static int gettok() {<br>
   if (LastChar == '#') {<br>
     // Comment until end of line.<br>
     do<br>
-      LastChar = advance();<br>
+      LastChar = getchar();<br>
     while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');<br>
<br>
     if (LastChar != EOF)<br>
@@ -200,7 +125,7 @@ static int gettok() {<br>
<br>
   // Otherwise, just return the character as its ascii value.<br>
   int ThisChar = LastChar;<br>
-  LastChar = advance();<br>
+  LastChar = getchar();<br>
   return ThisChar;<br>
 }<br>
<br>
@@ -208,25 +133,11 @@ static int gettok() {<br>
 // Abstract Syntax Tree (aka Parse Tree)<br>
 //===----------------------------------------------------------------------===//<br>
 namespace {<br>
-<br>
-raw_ostream &indent(raw_ostream &O, int size) {<br>
-  return O << std::string(size, ' ');<br>
-}<br>
-<br>
 /// ExprAST - Base class for all expression nodes.<br>
 class ExprAST {<br>
-  SourceLocation Loc;<br>
-<br>
 public:<br>
-  ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}<br>
   virtual ~ExprAST() {}<br>
   virtual Value *codegen() = 0;<br>
-  int getLine() const { return Loc.Line; }<br>
-  int getCol() const { return Loc.Col; }<br>
-<br>
-  virtual raw_ostream &dump(raw_ostream &out, int ind) {<br>
-    return out << ':' << getLine() << ':' << getCol() << '\n';<br>
-  }<br>
 };<br>
<br>
 /// NumberExprAST - Expression class for numeric literals like "1.0".<br>
@@ -236,10 +147,6 @@ class NumberExprAST : public ExprAST {<br>
 public:<br>
   NumberExprAST(double Val) : Val(Val) {}<br>
   Value *codegen() override;<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
-    return ExprAST::dump(out << Val, ind);<br>
-  }<br>
 };<br>
<br>
 /// VariableExprAST - Expression class for referencing a variable, like "a".<br>
@@ -247,14 +154,9 @@ class VariableExprAST : public ExprAST {<br>
   std::string Name;<br>
<br>
 public:<br>
-  VariableExprAST(SourceLocation Loc, const std::string &Name)<br>
-      : ExprAST(Loc), Name(Name) {}<br>
+  VariableExprAST(const std::string &Name) : Name(Name) {}<br>
   const std::string &getName() const { return Name; }<br>
   Value *codegen() override;<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
-    return ExprAST::dump(out << Name, ind);<br>
-  }<br>
 };<br>
<br>
 /// UnaryExprAST - Expression class for a unary operator.<br>
@@ -266,12 +168,6 @@ public:<br>
   UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)<br>
       : Opcode(Opcode), Operand(std::move(Operand)) {}<br>
   Value *codegen() override;<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
-    ExprAST::dump(out << "unary" << Opcode, ind);<br>
-    Operand->dump(out, ind + 1);<br>
-    return out;<br>
-  }<br>
 };<br>
<br>
 /// BinaryExprAST - Expression class for a binary operator.<br>
@@ -280,17 +176,10 @@ class BinaryExprAST : public ExprAST {<br>
   std::unique_ptr<ExprAST> LHS, RHS;<br>
<br>
 public:<br>
-  BinaryExprAST(SourceLocation Loc, char Op, std::unique_ptr<ExprAST> LHS,<br>
+  BinaryExprAST(char Op, std::unique_ptr<ExprAST> LHS,<br>
                 std::unique_ptr<ExprAST> RHS)<br>
-      : ExprAST(Loc), Op(Op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}<br>
+      : Op(Op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}<br>
   Value *codegen() override;<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
-    ExprAST::dump(out << "binary" << Op, ind);<br>
-    LHS->dump(indent(out, ind) << "LHS:", ind + 1);<br>
-    RHS->dump(indent(out, ind) << "RHS:", ind + 1);<br>
-    return out;<br>
-  }<br>
 };<br>
<br>
 /// CallExprAST - Expression class for function calls.<br>
@@ -299,17 +188,10 @@ class CallExprAST : public ExprAST {<br>
   std::vector<std::unique_ptr<ExprAST>> Args;<br>
<br>
 public:<br>
-  CallExprAST(SourceLocation Loc, const std::string &Callee,<br>
+  CallExprAST(const std::string &Callee,<br>
               std::vector<std::unique_ptr<ExprAST>> Args)<br>
-      : ExprAST(Loc), Callee(Callee), Args(std::move(Args)) {}<br>
+      : Callee(Callee), Args(std::move(Args)) {}<br>
   Value *codegen() override;<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
-    ExprAST::dump(out << "call " << Callee, ind);<br>
-    for (const auto &Arg : Args)<br>
-      Arg->dump(indent(out, ind + 1), ind + 1);<br>
-    return out;<br>
-  }<br>
 };<br>
<br>
 /// IfExprAST - Expression class for if/then/else.<br>
@@ -317,19 +199,10 @@ class IfExprAST : public ExprAST {<br>
   std::unique_ptr<ExprAST> Cond, Then, Else;<br>
<br>
 public:<br>
-  IfExprAST(SourceLocation Loc, std::unique_ptr<ExprAST> Cond,<br>
-            std::unique_ptr<ExprAST> Then, std::unique_ptr<ExprAST> Else)<br>
-      : ExprAST(Loc), Cond(std::move(Cond)), Then(std::move(Then)),<br>
-        Else(std::move(Else)) {}<br>
+  IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,<br>
+            std::unique_ptr<ExprAST> Else)<br>
+      : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}<br>
   Value *codegen() override;<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
-    ExprAST::dump(out << "if", ind);<br>
-    Cond->dump(indent(out, ind) << "Cond:", ind + 1);<br>
-    Then->dump(indent(out, ind) << "Then:", ind + 1);<br>
-    Else->dump(indent(out, ind) << "Else:", ind + 1);<br>
-    return out;<br>
-  }<br>
 };<br>
<br>
 /// ForExprAST - Expression class for for/in.<br>
@@ -344,15 +217,6 @@ public:<br>
       : VarName(VarName), Start(std::move(Start)), End(std::move(End)),<br>
         Step(std::move(Step)), Body(std::move(Body)) {}<br>
   Value *codegen() override;<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
-    ExprAST::dump(out << "for", ind);<br>
-    Start->dump(indent(out, ind) << "Cond:", ind + 1);<br>
-    End->dump(indent(out, ind) << "End:", ind + 1);<br>
-    Step->dump(indent(out, ind) << "Step:", ind + 1);<br>
-    Body->dump(indent(out, ind) << "Body:", ind + 1);<br>
-    return out;<br>
-  }<br>
 };<br>
<br>
 /// VarExprAST - Expression class for var/in<br>
@@ -366,14 +230,6 @@ public:<br>
       std::unique_ptr<ExprAST> Body)<br>
       : VarNames(std::move(VarNames)), Body(std::move(Body)) {}<br>
   Value *codegen() override;<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
-    ExprAST::dump(out << "var", ind);<br>
-    for (const auto &NamedVar : VarNames)<br>
-      NamedVar.second->dump(indent(out, ind) << NamedVar.first << ':', ind + 1);<br>
-    Body->dump(indent(out, ind) << "Body:", ind + 1);<br>
-    return out;<br>
-  }<br>
 };<br>
<br>
 /// PrototypeAST - This class represents the "prototype" for a function,<br>
@@ -384,14 +240,12 @@ class PrototypeAST {<br>
   std::vector<std::string> Args;<br>
   bool IsOperator;<br>
   unsigned Precedence; // Precedence if a binary op.<br>
-  int Line;<br>
<br>
 public:<br>
-  PrototypeAST(SourceLocation Loc, const std::string &Name,<br>
-               std::vector<std::string> Args, bool IsOperator = false,<br>
-               unsigned Prec = 0)<br>
+  PrototypeAST(const std::string &Name, std::vector<std::string> Args,<br>
+               bool IsOperator = false, unsigned Prec = 0)<br>
       : Name(Name), Args(std::move(Args)), IsOperator(IsOperator),<br>
-        Precedence(Prec), Line(Loc.Line) {}<br>
+        Precedence(Prec) {}<br>
   Function *codegen();<br>
   const std::string &getName() const { return Name; }<br>
<br>
@@ -404,7 +258,6 @@ public:<br>
   }<br>
<br>
   unsigned getBinaryPrecedence() const { return Precedence; }<br>
-  int getLine() const { return Line; }<br>
 };<br>
<br>
 /// FunctionAST - This class represents a function definition itself.<br>
@@ -417,13 +270,6 @@ public:<br>
               std::unique_ptr<ExprAST> Body)<br>
       : Proto(std::move(Proto)), Body(std::move(Body)) {}<br>
   Function *codegen();<br>
-<br>
-  raw_ostream &dump(raw_ostream &out, int ind) {<br>
-    indent(out, ind) << "FunctionAST\n";<br>
-    ++ind;<br>
-    indent(out, ind) << "Body:";<br>
-    return Body ? Body->dump(out, ind) : out << "null\n";<br>
-  }<br>
 };<br>
 } // end anonymous namespace<br>
<br>
@@ -492,12 +338,10 @@ static std::unique_ptr<ExprAST> ParsePar<br>
 static std::unique_ptr<ExprAST> ParseIdentifierExpr() {<br>
   std::string IdName = IdentifierStr;<br>
<br>
-  SourceLocation LitLoc = CurLoc;<br>
-<br>
   getNextToken(); // eat identifier.<br>
<br>
   if (CurTok != '(') // Simple variable ref.<br>
-    return llvm::make_unique<VariableExprAST>(LitLoc, IdName);<br>
+    return llvm::make_unique<VariableExprAST>(IdName);<br>
<br>
   // Call.<br>
   getNextToken(); // eat (<br>
@@ -521,13 +365,11 @@ static std::unique_ptr<ExprAST> ParseIde<br>
   // Eat the ')'.<br>
   getNextToken();<br>
<br>
-  return llvm::make_unique<CallExprAST>(LitLoc, IdName, std::move(Args));<br>
+  return llvm::make_unique<CallExprAST>(IdName, std::move(Args));<br>
 }<br>
<br>
 /// ifexpr ::= 'if' expression 'then' expression 'else' expression<br>
 static std::unique_ptr<ExprAST> ParseIfExpr() {<br>
-  SourceLocation IfLoc = CurLoc;<br>
-<br>
   getNextToken(); // eat the if.<br>
<br>
   // condition.<br>
@@ -552,7 +394,7 @@ static std::unique_ptr<ExprAST> ParseIfE<br>
   if (!Else)<br>
     return nullptr;<br>
<br>
-  return llvm::make_unique<IfExprAST>(IfLoc, std::move(Cond), std::move(Then),<br>
+  return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),<br>
                                       std::move(Else));<br>
 }<br>
<br>
@@ -707,7 +549,6 @@ static std::unique_ptr<ExprAST> ParseBin<br>
<br>
     // Okay, we know this is a binop.<br>
     int BinOp = CurTok;<br>
-    SourceLocation BinLoc = CurLoc;<br>
     getNextToken(); // eat binop<br>
<br>
     // Parse the unary expression after the binary operator.<br>
@@ -725,8 +566,8 @@ static std::unique_ptr<ExprAST> ParseBin<br>
     }<br>
<br>
     // Merge LHS/RHS.<br>
-    LHS = llvm::make_unique<BinaryExprAST>(BinLoc, BinOp, std::move(LHS),<br>
-                                           std::move(RHS));<br>
+    LHS =<br>
+        llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS), std::move(RHS));<br>
   }<br>
 }<br>
<br>
@@ -748,8 +589,6 @@ static std::unique_ptr<ExprAST> ParseExp<br>
 static std::unique_ptr<PrototypeAST> ParsePrototype() {<br>
   std::string FnName;<br>
<br>
-  SourceLocation FnLoc = CurLoc;<br>
-<br>
   unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.<br>
   unsigned BinaryPrecedence = 30;<br>
<br>
@@ -805,7 +644,7 @@ static std::unique_ptr<PrototypeAST> Par<br>
   if (Kind && ArgNames.size() != Kind)<br>
     return LogErrorP("Invalid number of operands for operator");<br>
<br>
-  return llvm::make_unique<PrototypeAST>(FnLoc, FnName, ArgNames, Kind != 0,<br>
+  return llvm::make_unique<PrototypeAST>(FnName, ArgNames, Kind != 0,<br>
                                          BinaryPrecedence);<br>
 }<br>
<br>
@@ -823,10 +662,9 @@ static std::unique_ptr<FunctionAST> Pars<br>
<br>
 /// toplevelexpr ::= expression<br>
 static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {<br>
-  SourceLocation FnLoc = CurLoc;<br>
   if (auto E = ParseExpression()) {<br>
     // Make an anonymous proto.<br>
-    auto Proto = llvm::make_unique<PrototypeAST>(FnLoc, "__anon_expr",<br>
+    auto Proto = llvm::make_unique<PrototypeAST>("__anon_expr",<br>
                                                  std::vector<std::string>());<br>
     return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));<br>
   }<br>
@@ -840,51 +678,13 @@ static std::unique_ptr<PrototypeAST> Par<br>
 }<br>
<br>
 //===----------------------------------------------------------------------===//<br>
-// Debug Info Support<br>
-//===----------------------------------------------------------------------===//<br>
-<br>
-static std::unique_ptr<DIBuilder> DBuilder;<br>
-<br>
-DIType *DebugInfo::getDoubleTy() {<br>
-  if (DblTy)<br>
-    return DblTy;<br>
-<br>
-  DblTy = DBuilder->createBasicType("double", 64, 64, dwarf::DW_ATE_float);<br>
-  return DblTy;<br>
-}<br>
-<br>
-void DebugInfo::emitLocation(ExprAST *AST) {<br>
-  if (!AST)<br>
-    return Builder.SetCurrentDebugLocation(DebugLoc());<br>
-  DIScope *Scope;<br>
-  if (LexicalBlocks.empty())<br>
-    Scope = TheCU;<br>
-  else<br>
-    Scope = LexicalBlocks.back();<br>
-  Builder.SetCurrentDebugLocation(<br>
-      DebugLoc::get(AST->getLine(), AST->getCol(), Scope));<br>
-}<br>
-<br>
-static DISubroutineType *CreateFunctionType(unsigned NumArgs, DIFile *Unit) {<br>
-  SmallVector<Metadata *, 8> EltTys;<br>
-  DIType *DblTy = KSDbgInfo.getDoubleTy();<br>
-<br>
-  // Add the result type.<br>
-  EltTys.push_back(DblTy);<br>
-<br>
-  for (unsigned i = 0, e = NumArgs; i != e; ++i)<br>
-    EltTys.push_back(DblTy);<br>
-<br>
-  return DBuilder->createSubroutineType(DBuilder->getOrCreateTypeArray(EltTys));<br>
-}<br>
-<br>
-//===----------------------------------------------------------------------===//<br>
 // Code Generation<br>
 //===----------------------------------------------------------------------===//<br>
<br>
+static LLVMContext TheContext;<br>
+static IRBuilder<> Builder(TheContext);<br>
 static std::unique_ptr<Module> TheModule;<br>
 static std::map<std::string, AllocaInst *> NamedValues;<br>
-static std::unique_ptr<KaleidoscopeJIT> TheJIT;<br>
 static std::map<std::string, std::unique_ptr<PrototypeAST>> FunctionProtos;<br>
<br>
 Value *LogErrorV(const char *Str) {<br>
@@ -917,7 +717,6 @@ static AllocaInst *CreateEntryBlockAlloc<br>
 }<br>
<br>
 Value *NumberExprAST::codegen() {<br>
-  KSDbgInfo.emitLocation(this);<br>
   return ConstantFP::get(TheContext, APFloat(Val));<br>
 }<br>
<br>
@@ -927,7 +726,6 @@ Value *VariableExprAST::codegen() {<br>
   if (!V)<br>
     return LogErrorV("Unknown variable name");<br>
<br>
-  KSDbgInfo.emitLocation(this);<br>
   // Load the value.<br>
   return Builder.CreateLoad(V, Name.c_str());<br>
 }<br>
@@ -941,13 +739,10 @@ Value *UnaryExprAST::codegen() {<br>
   if (!F)<br>
     return LogErrorV("Unknown unary operator");<br>
<br>
-  KSDbgInfo.emitLocation(this);<br>
   return Builder.CreateCall(F, OperandV, "unop");<br>
 }<br>
<br>
 Value *BinaryExprAST::codegen() {<br>
-  KSDbgInfo.emitLocation(this);<br>
-<br>
   // Special case '=' because we don't want to emit the LHS as an expression.<br>
   if (Op == '=') {<br>
     // Assignment requires the LHS to be an identifier.<br>
@@ -1001,8 +796,6 @@ Value *BinaryExprAST::codegen() {<br>
 }<br>
<br>
 Value *CallExprAST::codegen() {<br>
-  KSDbgInfo.emitLocation(this);<br>
-<br>
   // Look up the name in the global module table.<br>
   Function *CalleeF = getFunction(Callee);<br>
   if (!CalleeF)<br>
@@ -1023,8 +816,6 @@ Value *CallExprAST::codegen() {<br>
 }<br>
<br>
 Value *IfExprAST::codegen() {<br>
-  KSDbgInfo.emitLocation(this);<br>
-<br>
   Value *CondV = Cond->codegen();<br>
   if (!CondV)<br>
     return nullptr;<br>
@@ -1101,8 +892,6 @@ Value *ForExprAST::codegen() {<br>
   // Create an alloca for the variable in the entry block.<br>
   AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);<br>
<br>
-  KSDbgInfo.emitLocation(this);<br>
-<br>
   // Emit the start code first, without 'variable' in scope.<br>
   Value *StartVal = Start->codegen();<br>
   if (!StartVal)<br>
@@ -1213,8 +1002,6 @@ Value *VarExprAST::codegen() {<br>
     NamedValues[VarName] = Alloca;<br>
   }<br>
<br>
-  KSDbgInfo.emitLocation(this);<br>
-<br>
   // Codegen the body, now that all vars are in scope.<br>
   Value *BodyVal = Body->codegen();<br>
   if (!BodyVal)<br>
@@ -1262,43 +1049,12 @@ Function *FunctionAST::codegen() {<br>
   BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);<br>
   Builder.SetInsertPoint(BB);<br>
<br>
-  // Create a subprogram DIE for this function.<br>
-  DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU->getFilename(),<br>
-                                      KSDbgInfo.TheCU->getDirectory());<br>
-  DIScope *FContext = Unit;<br>
-  unsigned LineNo = P.getLine();<br>
-  unsigned ScopeLine = LineNo;<br>
-  DISubprogram *SP = DBuilder->createFunction(<br>
-      FContext, P.getName(), StringRef(), Unit, LineNo,<br>
-      CreateFunctionType(TheFunction->arg_size(), Unit),<br>
-      false /* internal linkage */, true /* definition */, ScopeLine,<br>
-      DINode::FlagPrototyped, false);<br>
-  TheFunction->setSubprogram(SP);<br>
-<br>
-  // Push the current scope.<br>
-  KSDbgInfo.LexicalBlocks.push_back(SP);<br>
-<br>
-  // Unset the location for the prologue emission (leading instructions with no<br>
-  // location in a function are considered part of the prologue and the debugger<br>
-  // will run past them when breaking on a function)<br>
-  KSDbgInfo.emitLocation(nullptr);<br>
-<br>
   // Record the function arguments in the NamedValues map.<br>
   NamedValues.clear();<br>
-  unsigned ArgIdx = 0;<br>
   for (auto &Arg : TheFunction->args()) {<br>
     // Create an alloca for this variable.<br>
     AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, Arg.getName());<br>
<br>
-    // Create a debug descriptor for the variable.<br>
-    DILocalVariable *D = DBuilder->createParameterVariable(<br>
-        SP, Arg.getName(), ++ArgIdx, Unit, LineNo, KSDbgInfo.getDoubleTy(),<br>
-        true);<br>
-<br>
-    DBuilder->insertDeclare(Alloca, D, DBuilder->createExpression(),<br>
-                            DebugLoc::get(LineNo, 0, SP),<br>
-                            Builder.GetInsertBlock());<br>
-<br>
     // Store the initial value into the alloca.<br>
     Builder.CreateStore(&Arg, Alloca);<br>
<br>
@@ -1306,15 +1062,10 @@ Function *FunctionAST::codegen() {<br>
     NamedValues[Arg.getName()] = Alloca;<br>
   }<br>
<br>
-  KSDbgInfo.emitLocation(Body.get());<br>
-<br>
   if (Value *RetVal = Body->codegen()) {<br>
     // Finish off the function.<br>
     Builder.CreateRet(RetVal);<br>
<br>
-    // Pop off the lexical block for the function.<br>
-    KSDbgInfo.LexicalBlocks.pop_back();<br>
-<br>
     // Validate the generated code, checking for consistency.<br>
     verifyFunction(*TheFunction);<br>
<br>
@@ -1326,11 +1077,6 @@ Function *FunctionAST::codegen() {<br>
<br>
   if (P.isBinaryOp())<br>
     BinopPrecedence.erase(Proto->getOperatorName());<br>
-<br>
-  // Pop off the lexical block for the function since we added it<br>
-  // unconditionally.<br>
-  KSDbgInfo.LexicalBlocks.pop_back();<br>
-<br>
   return nullptr;<br>
 }<br>
<br>
@@ -1338,16 +1084,17 @@ Function *FunctionAST::codegen() {<br>
 // Top-Level parsing and JIT Driver<br>
 //===----------------------------------------------------------------------===//<br>
<br>
-static void InitializeModule() {<br>
+static void InitializeModuleAndPassManager() {<br>
   // Open a new module.<br>
   TheModule = llvm::make_unique<Module>("my cool jit", TheContext);<br>
-  TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());<br>
 }<br>
<br>
 static void HandleDefinition() {<br>
   if (auto FnAST = ParseDefinition()) {<br>
-    if (!FnAST->codegen())<br>
-      fprintf(stderr, "Error reading function definition:");<br>
+    if (auto *FnIR = FnAST->codegen()) {<br>
+      fprintf(stderr, "Read function definition:");<br>
+      FnIR->dump();<br>
+    }<br>
   } else {<br>
     // Skip token for error recovery.<br>
     getNextToken();<br>
@@ -1356,10 +1103,11 @@ static void HandleDefinition() {<br>
<br>
 static void HandleExtern() {<br>
   if (auto ProtoAST = ParseExtern()) {<br>
-    if (!ProtoAST->codegen())<br>
-      fprintf(stderr, "Error reading extern");<br>
-    else<br>
+    if (auto *FnIR = ProtoAST->codegen()) {<br>
+      fprintf(stderr, "Read extern: ");<br>
+      FnIR->dump();<br>
       FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);<br>
+    }<br>
   } else {<br>
     // Skip token for error recovery.<br>
     getNextToken();<br>
@@ -1369,9 +1117,7 @@ static void HandleExtern() {<br>
 static void HandleTopLevelExpression() {<br>
   // Evaluate a top-level expression into an anonymous function.<br>
   if (auto FnAST = ParseTopLevelExpr()) {<br>
-    if (!FnAST->codegen()) {<br>
-      fprintf(stderr, "Error generating code for top level expr");<br>
-    }<br>
+    FnAST->codegen();<br>
   } else {<br>
     // Skip token for error recovery.<br>
     getNextToken();<br>
@@ -1421,50 +1167,74 @@ extern "C" double printd(double X) {<br>
 //===----------------------------------------------------------------------===//<br>
<br>
 int main() {<br>
-  InitializeNativeTarget();<br>
-  InitializeNativeTargetAsmPrinter();<br>
-  InitializeNativeTargetAsmParser();<br>
-<br>
   // Install standard binary operators.<br>
   // 1 is lowest precedence.<br>
-  BinopPrecedence['='] = 2;<br>
   BinopPrecedence['<'] = 10;<br>
   BinopPrecedence['+'] = 20;<br>
   BinopPrecedence['-'] = 20;<br>
   BinopPrecedence['*'] = 40; // highest.<br>
<br>
   // Prime the first token.<br>
+  fprintf(stderr, "ready> ");<br>
   getNextToken();<br>
<br>
-  TheJIT = llvm::make_unique<KaleidoscopeJIT>();<br>
-<br>
-  InitializeModule();<br>
-<br>
-  // Add the current debug info version into the module.<br>
-  TheModule->addModuleFlag(Module::Warning, "Debug Info Version",<br>
-                           DEBUG_METADATA_VERSION);<br>
-<br>
-  // Darwin only supports dwarf2.<br>
-  if (Triple(sys::getProcessTriple()).isOSDarwin())<br>
-    TheModule->addModuleFlag(llvm::Module::Warning, "Dwarf Version", 2);<br>
-<br>
-  // Construct the DIBuilder, we do this here because we need the module.<br>
-  DBuilder = llvm::make_unique<DIBuilder>(*TheModule);<br>
-<br>
-  // Create the compile unit for the module.<br>
-  // Currently down as "fib.ks" as a filename since we're redirecting stdin<br>
-  // but we'd like actual source locations.<br>
-  KSDbgInfo.TheCU = DBuilder->createCompileUnit(<br>
-      dwarf::DW_LANG_C, "fib.ks", ".", "Kaleidoscope Compiler", false, "", 0);<br>
+  InitializeModuleAndPassManager();<br>
<br>
   // Run the main "interpreter loop" now.<br>
   MainLoop();<br>
<br>
-  // Finalize the debug info.<br>
-  DBuilder->finalize();<br>
+  // Initialize the target registry etc.<br>
+  InitializeAllTargetInfos();<br>
+  InitializeAllTargets();<br>
+  InitializeAllTargetMCs();<br>
+  InitializeAllAsmParsers();<br>
+  InitializeAllAsmPrinters();<br>
+<br>
+  auto TargetTriple = sys::getDefaultTargetTriple();<br>
+  TheModule->setTargetTriple(TargetTriple);<br>
+<br>
+  std::string Error;<br>
+  auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);<br>
+<br>
+  // Print an error and exit if we couldn't find the requested target.<br>
+  // This generally occurs if we've forgotten to initialise the<br>
+  // TargetRegistry or we have a bogus target triple.<br>
+  if (!Target) {<br>
+    errs() << Error;<br>
+    return 1;<br>
+  }<br>
+<br>
+  auto CPU = "generic";<br>
+  auto Features = "";<br>
+<br>
+  TargetOptions opt;<br>
+  auto RM = Optional<Reloc::Model>();<br>
+  auto TheTargetMachine =<br>
+      Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);<br>
+<br>
+  TheModule->setDataLayout(TheTargetMachine->createDataLayout());<br>
+<br>
+  auto Filename = "output.o";<br>
+  std::error_code EC;<br>
+  raw_fd_ostream dest(Filename, EC, sys::fs::F_None);<br>
+<br>
+  if (EC) {<br>
+    errs() << "Could not open file: " << EC.message();<br>
+    return 1;<br>
+  }<br>
+<br>
+  legacy::PassManager pass;<br>
+  auto FileType = TargetMachine::CGFT_ObjectFile;<br>
+<br>
+  if (TheTargetMachine->addPassesToEmitFile(pass, dest, FileType)) {<br>
+    errs() << "TheTargetMachine can't emit a file of this type";<br>
+    return 1;<br>
+  }<br>
+<br>
+  pass.run(*TheModule);<br>
+  dest.flush();<br>
<br>
-  // Print out all of the generated code.<br>
-  TheModule->dump();<br>
+  outs() << "Wrote " << Filename << "\n";<br>
<br>
   return 0;<br>
 }<br>
<br>
Added: llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt (added)<br>
+++ llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,13 @@<br>
+set(LLVM_LINK_COMPONENTS<br>
+  Core<br>
+  ExecutionEngine<br>
+  Object<br>
+  Support<br>
+  native<br>
+  )<br>
+<br>
+add_kaleidoscope_chapter(Kaleidoscope-Ch9<br>
+  toy.cpp<br>
+  )<br>
+<br>
+export_executable_symbols(Kaleidoscope-Ch9)<br>
<br>
Added: llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp?rev=274441&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp?rev=274441&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp (added)<br>
+++ llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp Sat Jul  2 12:01:59 2016<br>
@@ -0,0 +1,1445 @@<br>
+#include "llvm/ADT/STLExtras.h"<br>
+#include "llvm/Analysis/BasicAliasAnalysis.h"<br>
+#include "llvm/Analysis/Passes.h"<br>
+#include "llvm/IR/DIBuilder.h"<br>
+#include "llvm/IR/IRBuilder.h"<br>
+#include "llvm/IR/LLVMContext.h"<br>
+#include "llvm/IR/LegacyPassManager.h"<br>
+#include "llvm/IR/Module.h"<br>
+#include "llvm/IR/Verifier.h"<br>
+#include "llvm/Support/TargetSelect.h"<br>
+#include "llvm/Transforms/Scalar.h"<br>
+#include <cctype><br>
+#include <cstdio><br>
+#include <map><br>
+#include <string><br>
+#include <vector><br>
+#include "../include/KaleidoscopeJIT.h"<br>
+<br>
+using namespace llvm;<br>
+using namespace llvm::orc;<br>
+<br>
+//===----------------------------------------------------------------------===//<br>
+// Lexer<br>
+//===----------------------------------------------------------------------===//<br>
+<br>
+// The lexer returns tokens [0-255] if it is an unknown character, otherwise one<br>
+// of these for known things.<br>
+enum Token {<br>
+  tok_eof = -1,<br>
+<br>
+  // commands<br>
+  tok_def = -2,<br>
+  tok_extern = -3,<br>
+<br>
+  // primary<br>
+  tok_identifier = -4,<br>
+  tok_number = -5,<br>
+<br>
+  // control<br>
+  tok_if = -6,<br>
+  tok_then = -7,<br>
+  tok_else = -8,<br>
+  tok_for = -9,<br>
+  tok_in = -10,<br>
+<br>
+  // operators<br>
+  tok_binary = -11,<br>
+  tok_unary = -12,<br>
+<br>
+  // var definition<br>
+  tok_var = -13<br>
+};<br>
+<br>
+std::string getTokName(int Tok) {<br>
+  switch (Tok) {<br>
+  case tok_eof:<br>
+    return "eof";<br>
+  case tok_def:<br>
+    return "def";<br>
+  case tok_extern:<br>
+    return "extern";<br>
+  case tok_identifier:<br>
+    return "identifier";<br>
+  case tok_number:<br>
+    return "number";<br>
+  case tok_if:<br>
+    return "if";<br>
+  case tok_then:<br>
+    return "then";<br>
+  case tok_else:<br>
+    return "else";<br>
+  case tok_for:<br>
+    return "for";<br>
+  case tok_in:<br>
+    return "in";<br>
+  case tok_binary:<br>
+    return "binary";<br>
+  case tok_unary:<br>
+    return "unary";<br>
+  case tok_var:<br>
+    return "var";<br>
+  }<br>
+  return std::string(1, (char)Tok);<br>
+}<br>
+<br>
+namespace {<br>
+class PrototypeAST;<br>
+class ExprAST;<br>
+}<br>
+static LLVMContext TheContext;<br>
+static IRBuilder<> Builder(TheContext);<br>
+struct DebugInfo {<br>
+  DICompileUnit *TheCU;<br>
+  DIType *DblTy;<br>
+  std::vector<DIScope *> LexicalBlocks;<br>
+<br>
+  void emitLocation(ExprAST *AST);<br>
+  DIType *getDoubleTy();<br>
+} KSDbgInfo;<br>
+<br>
+struct SourceLocation {<br>
+  int Line;<br>
+  int Col;<br>
+};<br>
+static SourceLocation CurLoc;<br>
+static SourceLocation LexLoc = {1, 0};<br>
+<br>
+static int advance() {<br>
+  int LastChar = getchar();<br>
+<br>
+  if (LastChar == '\n' || LastChar == '\r') {<br>
+    LexLoc.Line++;<br>
+    LexLoc.Col = 0;<br>
+  } else<br>
+    LexLoc.Col++;<br>
+  return LastChar;<br>
+}<br>
+<br>
+static std::string IdentifierStr; // Filled in if tok_identifier<br>
+static double NumVal;             // Filled in if tok_number<br>
+<br>
+/// gettok - Return the next token from standard input.<br>
+static int gettok() {<br>
+  static int LastChar = ' ';<br>
+<br>
+  // Skip any whitespace.<br>
+  while (isspace(LastChar))<br>
+    LastChar = advance();<br>
+<br>
+  CurLoc = LexLoc;<br>
+<br>
+  if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*<br>
+    IdentifierStr = LastChar;<br>
+    while (isalnum((LastChar = advance())))<br>
+      IdentifierStr += LastChar;<br>
+<br>
+    if (IdentifierStr == "def")<br>
+      return tok_def;<br>
+    if (IdentifierStr == "extern")<br>
+      return tok_extern;<br>
+    if (IdentifierStr == "if")<br>
+      return tok_if;<br>
+    if (IdentifierStr == "then")<br>
+      return tok_then;<br>
+    if (IdentifierStr == "else")<br>
+      return tok_else;<br>
+    if (IdentifierStr == "for")<br>
+      return tok_for;<br>
+    if (IdentifierStr == "in")<br>
+      return tok_in;<br>
+    if (IdentifierStr == "binary")<br>
+      return tok_binary;<br>
+    if (IdentifierStr == "unary")<br>
+      return tok_unary;<br>
+    if (IdentifierStr == "var")<br>
+      return tok_var;<br>
+    return tok_identifier;<br>
+  }<br>
+<br>
+  if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+<br>
+    std::string NumStr;<br>
+    do {<br>
+      NumStr += LastChar;<br>
+      LastChar = advance();<br>
+    } while (isdigit(LastChar) || LastChar == '.');<br>
+<br>
+    NumVal = strtod(NumStr.c_str(), nullptr);<br>
+    return tok_number;<br>
+  }<br>
+<br>
+  if (LastChar == '#') {<br>
+    // Comment until end of line.<br>
+    do<br>
+      LastChar = advance();<br>
+    while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');<br>
+<br>
+    if (LastChar != EOF)<br>
+      return gettok();<br>
+  }<br>
+<br>
+  // Check for end of file.  Don't eat the EOF.<br>
+  if (LastChar == EOF)<br>
+    return tok_eof;<br>
+<br>
+  // Otherwise, just return the character as its ascii value.<br>
+  int ThisChar = LastChar;<br>
+  LastChar = advance();<br>
+  return ThisChar;<br>
+}<br>
+<br>
+//===----------------------------------------------------------------------===//<br>
+// Abstract Syntax Tree (aka Parse Tree)<br>
+//===----------------------------------------------------------------------===//<br>
+namespace {<br>
+<br>
+raw_ostream &indent(raw_ostream &O, int size) {<br>
+  return O << std::string(size, ' ');<br>
+}<br>
+<br>
+/// ExprAST - Base class for all expression nodes.<br>
+class ExprAST {<br>
+  SourceLocation Loc;<br>
+<br>
+public:<br>
+  ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}<br>
+  virtual ~ExprAST() {}<br>
+  virtual Value *codegen() = 0;<br>
+  int getLine() const { return Loc.Line; }<br>
+  int getCol() const { return Loc.Col; }<br>
+  virtual raw_ostream &dump(raw_ostream &out, int ind) {<br>
+    return out << ':' << getLine() << ':' << getCol() << '\n';<br>
+  }<br>
+};<br>
+<br>
+/// NumberExprAST - Expression class for numeric literals like "1.0".<br>
+class NumberExprAST : public ExprAST {<br>
+  double Val;<br>
+<br>
+public:<br>
+  NumberExprAST(double Val) : Val(Val) {}<br>
+  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
+    return ExprAST::dump(out << Val, ind);<br>
+  }<br>
+  Value *codegen() override;<br>
+};<br>
+<br>
+/// VariableExprAST - Expression class for referencing a variable, like "a".<br>
+class VariableExprAST : public ExprAST {<br>
+  std::string Name;<br>
+<br>
+public:<br>
+  VariableExprAST(SourceLocation Loc, const std::string &Name)<br>
+      : ExprAST(Loc), Name(Name) {}<br>
+  const std::string &getName() const { return Name; }<br>
+  Value *codegen() override;<br>
+  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
+    return ExprAST::dump(out << Name, ind);<br>
+  }<br>
+};<br>
+<br>
+/// UnaryExprAST - Expression class for a unary operator.<br>
+class UnaryExprAST : public ExprAST {<br>
+  char Opcode;<br>
+  std::unique_ptr<ExprAST> Operand;<br>
+<br>
+public:<br>
+  UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)<br>
+      : Opcode(Opcode), Operand(std::move(Operand)) {}<br>
+  Value *codegen() override;<br>
+  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
+    ExprAST::dump(out << "unary" << Opcode, ind);<br>
+    Operand->dump(out, ind + 1);<br>
+    return out;<br>
+  }<br>
+};<br>
+<br>
+/// BinaryExprAST - Expression class for a binary operator.<br>
+class BinaryExprAST : public ExprAST {<br>
+  char Op;<br>
+  std::unique_ptr<ExprAST> LHS, RHS;<br>
+<br>
+public:<br>
+  BinaryExprAST(SourceLocation Loc, char Op, std::unique_ptr<ExprAST> LHS,<br>
+                std::unique_ptr<ExprAST> RHS)<br>
+      : ExprAST(Loc), Op(Op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}<br>
+  Value *codegen() override;<br>
+  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
+    ExprAST::dump(out << "binary" << Op, ind);<br>
+    LHS->dump(indent(out, ind) << "LHS:", ind + 1);<br>
+    RHS->dump(indent(out, ind) << "RHS:", ind + 1);<br>
+    return out;<br>
+  }<br>
+};<br>
+<br>
+/// CallExprAST - Expression class for function calls.<br>
+class CallExprAST : public ExprAST {<br>
+  std::string Callee;<br>
+  std::vector<std::unique_ptr<ExprAST>> Args;<br>
+<br>
+public:<br>
+  CallExprAST(SourceLocation Loc, const std::string &Callee,<br>
+              std::vector<std::unique_ptr<ExprAST>> Args)<br>
+      : ExprAST(Loc), Callee(Callee), Args(std::move(Args)) {}<br>
+  Value *codegen() override;<br>
+  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
+    ExprAST::dump(out << "call " << Callee, ind);<br>
+    for (const auto &Arg : Args)<br>
+      Arg->dump(indent(out, ind + 1), ind + 1);<br>
+    return out;<br>
+  }<br>
+};<br>
+<br>
+/// IfExprAST - Expression class for if/then/else.<br>
+class IfExprAST : public ExprAST {<br>
+  std::unique_ptr<ExprAST> Cond, Then, Else;<br>
+<br>
+public:<br>
+  IfExprAST(SourceLocation Loc, std::unique_ptr<ExprAST> Cond,<br>
+            std::unique_ptr<ExprAST> Then, std::unique_ptr<ExprAST> Else)<br>
+      : ExprAST(Loc), Cond(std::move(Cond)), Then(std::move(Then)),<br>
+        Else(std::move(Else)) {}<br>
+  Value *codegen() override;<br>
+  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
+    ExprAST::dump(out << "if", ind);<br>
+    Cond->dump(indent(out, ind) << "Cond:", ind + 1);<br>
+    Then->dump(indent(out, ind) << "Then:", ind + 1);<br>
+    Else->dump(indent(out, ind) << "Else:", ind + 1);<br>
+    return out;<br>
+  }<br>
+};<br>
+<br>
+/// ForExprAST - Expression class for for/in.<br>
+class ForExprAST : public ExprAST {<br>
+  std::string VarName;<br>
+  std::unique_ptr<ExprAST> Start, End, Step, Body;<br>
+<br>
+public:<br>
+  ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,<br>
+             std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,<br>
+             std::unique_ptr<ExprAST> Body)<br>
+      : VarName(VarName), Start(std::move(Start)), End(std::move(End)),<br>
+        Step(std::move(Step)), Body(std::move(Body)) {}<br>
+  Value *codegen() override;<br>
+  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
+    ExprAST::dump(out << "for", ind);<br>
+    Start->dump(indent(out, ind) << "Cond:", ind + 1);<br>
+    End->dump(indent(out, ind) << "End:", ind + 1);<br>
+    Step->dump(indent(out, ind) << "Step:", ind + 1);<br>
+    Body->dump(indent(out, ind) << "Body:", ind + 1);<br>
+    return out;<br>
+  }<br>
+};<br>
+<br>
+/// VarExprAST - Expression class for var/in<br>
+class VarExprAST : public ExprAST {<br>
+  std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;<br>
+  std::unique_ptr<ExprAST> Body;<br>
+<br>
+public:<br>
+  VarExprAST(<br>
+      std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,<br>
+      std::unique_ptr<ExprAST> Body)<br>
+      : VarNames(std::move(VarNames)), Body(std::move(Body)) {}<br>
+  Value *codegen() override;<br>
+  raw_ostream &dump(raw_ostream &out, int ind) override {<br>
+    ExprAST::dump(out << "var", ind);<br>
+    for (const auto &NamedVar : VarNames)<br>
+      NamedVar.second->dump(indent(out, ind) << NamedVar.first << ':', ind + 1);<br>
+    Body->dump(indent(out, ind) << "Body:", ind + 1);<br>
+    return out;<br>
+  }<br>
+};<br>
+<br>
+/// PrototypeAST - This class represents the "prototype" for a function,<br>
+/// which captures its name, and its argument names (thus implicitly the number<br>
+/// of arguments the function takes), as well as if it is an operator.<br>
+class PrototypeAST {<br>
+  std::string Name;<br>
+  std::vector<std::string> Args;<br>
+  bool IsOperator;<br>
+  unsigned Precedence; // Precedence if a binary op.<br>
+  int Line;<br>
+<br>
+public:<br>
+  PrototypeAST(SourceLocation Loc, const std::string &Name,<br>
+               std::vector<std::string> Args, bool IsOperator = false,<br>
+               unsigned Prec = 0)<br>
+      : Name(Name), Args(std::move(Args)), IsOperator(IsOperator),<br>
+        Precedence(Prec), Line(Loc.Line) {}<br>
+  Function *codegen();<br>
+  const std::string &getName() const { return Name; }<br>
+<br>
+  bool isUnaryOp() const { return IsOperator && Args.size() == 1; }<br>
+  bool isBinaryOp() const { return IsOperator && Args.size() == 2; }<br>
+<br>
+  char getOperatorName() const {<br>
+    assert(isUnaryOp() || isBinaryOp());<br>
+    return Name[Name.size() - 1];<br>
+  }<br>
+<br>
+  unsigned getBinaryPrecedence() const { return Precedence; }<br>
+  int getLine() const { return Line; }<br>
+};<br>
+<br>
+/// FunctionAST - This class represents a function definition itself.<br>
+class FunctionAST {<br>
+  std::unique_ptr<PrototypeAST> Proto;<br>
+  std::unique_ptr<ExprAST> Body;<br>
+<br>
+public:<br>
+  FunctionAST(std::unique_ptr<PrototypeAST> Proto,<br>
+              std::unique_ptr<ExprAST> Body)<br>
+      : Proto(std::move(Proto)), Body(std::move(Body)) {}<br>
+  Function *codegen();<br>
+  raw_ostream &dump(raw_ostream &out, int ind) {<br>
+    indent(out, ind) << "FunctionAST\n";<br>
+    ++ind;<br>
+    indent(out, ind) << "Body:";<br>
+    return Body ? Body->dump(out, ind) : out << "null\n";<br>
+  }<br>
+};<br>
+} // end anonymous namespace<br>
+<br>
+//===----------------------------------------------------------------------===//<br>
+// Parser<br>
+//===----------------------------------------------------------------------===//<br>
+<br>
+/// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current<br>
+/// token the parser is looking at.  getNextToken reads another token from the<br>
+/// lexer and updates CurTok with its results.<br>
+static int CurTok;<br>
+static int getNextToken() { return CurTok = gettok(); }<br>
+<br>
+/// BinopPrecedence - This holds the precedence for each binary operator that is<br>
+/// defined.<br>
+static std::map<char, int> BinopPrecedence;<br>
+<br>
+/// GetTokPrecedence - Get the precedence of the pending binary operator token.<br>
+static int GetTokPrecedence() {<br>
+  if (!isascii(CurTok))<br>
+    return -1;<br>
+<br>
+  // Make sure it's a declared binop.<br>
+  int TokPrec = BinopPrecedence[CurTok];<br>
+  if (TokPrec <= 0)<br>
+    return -1;<br>
+  return TokPrec;<br>
+}<br>
+<br>
+/// LogError* - These are little helper functions for error handling.<br>
+std::unique_ptr<ExprAST> LogError(const char *Str) {<br>
+  fprintf(stderr, "Error: %s\n", Str);<br>
+  return nullptr;<br>
+}<br>
+<br>
+std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {<br>
+  LogError(Str);<br>
+  return nullptr;<br>
+}<br>
+<br>
+static std::unique_ptr<ExprAST> ParseExpression();<br>
+<br>
+/// numberexpr ::= number<br>
+static std::unique_ptr<ExprAST> ParseNumberExpr() {<br>
+  auto Result = llvm::make_unique<NumberExprAST>(NumVal);<br>
+  getNextToken(); // consume the number<br>
+  return std::move(Result);<br>
+}<br>
+<br>
+/// parenexpr ::= '(' expression ')'<br>
+static std::unique_ptr<ExprAST> ParseParenExpr() {<br>
+  getNextToken(); // eat (.<br>
+  auto V = ParseExpression();<br>
+  if (!V)<br>
+    return nullptr;<br>
+<br>
+  if (CurTok != ')')<br>
+    return LogError("expected ')'");<br>
+  getNextToken(); // eat ).<br>
+  return V;<br>
+}<br>
+<br>
+/// identifierexpr<br>
+///   ::= identifier<br>
+///   ::= identifier '(' expression* ')'<br>
+static std::unique_ptr<ExprAST> ParseIdentifierExpr() {<br>
+  std::string IdName = IdentifierStr;<br>
+<br>
+  SourceLocation LitLoc = CurLoc;<br>
+<br>
+  getNextToken(); // eat identifier.<br>
+<br>
+  if (CurTok != '(') // Simple variable ref.<br>
+    return llvm::make_unique<VariableExprAST>(LitLoc, IdName);<br>
+<br>
+  // Call.<br>
+  getNextToken(); // eat (<br>
+  std::vector<std::unique_ptr<ExprAST>> Args;<br>
+  if (CurTok != ')') {<br>
+    while (1) {<br>
+      if (auto Arg = ParseExpression())<br>
+        Args.push_back(std::move(Arg));<br>
+      else<br>
+        return nullptr;<br>
+<br>
+      if (CurTok == ')')<br>
+        break;<br>
+<br>
+      if (CurTok != ',')<br>
+        return LogError("Expected ')' or ',' in argument list");<br>
+      getNextToken();<br>
+    }<br>
+  }<br>
+<br>
+  // Eat the ')'.<br>
+  getNextToken();<br>
+<br>
+  return llvm::make_unique<CallExprAST>(LitLoc, IdName, std::move(Args));<br>
+}<br>
+<br>
+/// ifexpr ::= 'if' expression 'then' expression 'else' expression<br>
+static std::unique_ptr<ExprAST> ParseIfExpr() {<br>
+  SourceLocation IfLoc = CurLoc;<br>
+<br>
+  getNextToken(); // eat the if.<br>
+<br>
+  // condition.<br>
+  auto Cond = ParseExpression();<br>
+  if (!Cond)<br>
+    return nullptr;<br>
+<br>
+  if (CurTok != tok_then)<br>
+    return LogError("expected then");<br>
+  getNextToken(); // eat the then<br>
+<br>
+  auto Then = ParseExpression();<br>
+  if (!Then)<br>
+    return nullptr;<br>