New Kaleidoscope chapter: Creating object files

This new chapter describes compiling LLVM IR to object files.

The new chaper is chapter 8, so later chapters have been renumbered.
Since this brings us to 10 chapters total, I've also needed to rename
the other chapters to use two digit numbering.

Differential Revision: http://reviews.llvm.org/D18070



git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@274441 91177308-0d34-0410-b5e6-96231b3b80d8

12 files changed, 248 insertions, 27 deletions

diff --git a/docs/tutorial/LangImpl1.rst b/docs/tutorial/LangImpl01.rst
index 0b8ed7b1b6c..f7fbd150ef1 100644
--- a/docs/tutorial/LangImpl1.rst
+++ b/docs/tutorial/LangImpl01.rst
@@ -42,45 +42,48 @@ in the various pieces. The structure of the tutorial is:
    to implement everything in C++ instead of using lexer and parser
    generators. LLVM obviously works just fine with such tools, feel free
    to use one if you prefer.
--  `Chapter #2 <LangImpl2.html>`_: Implementing a Parser and AST -
+-  `Chapter #2 <LangImpl02.html>`_: Implementing a Parser and AST -
    With the lexer in place, we can talk about parsing techniques and
    basic AST construction. This tutorial describes recursive descent
    parsing and operator precedence parsing. Nothing in Chapters 1 or 2
    is LLVM-specific, the code doesn't even link in LLVM at this point.
    :)
--  `Chapter #3 <LangImpl3.html>`_: Code generation to LLVM IR - With
+-  `Chapter #3 <LangImpl03.html>`_: Code generation to LLVM IR - With
    the AST ready, we can show off how easy generation of LLVM IR really
    is.
--  `Chapter #4 <LangImpl4.html>`_: Adding JIT and Optimizer Support
+-  `Chapter #4 <LangImpl04.html>`_: Adding JIT and Optimizer Support
    - Because a lot of people are interested in using LLVM as a JIT,
    we'll dive right into it and show you the 3 lines it takes to add JIT
    support. LLVM is also useful in many other ways, but this is one
    simple and "sexy" way to show off its power. :)
--  `Chapter #5 <LangImpl5.html>`_: Extending the Language: Control
+-  `Chapter #5 <LangImpl05.html>`_: Extending the Language: Control
    Flow - With the language up and running, we show how to extend it
    with control flow operations (if/then/else and a 'for' loop). This
    gives us a chance to talk about simple SSA construction and control
    flow.
--  `Chapter #6 <LangImpl6.html>`_: Extending the Language:
+-  `Chapter #6 <LangImpl06.html>`_: Extending the Language:
    User-defined Operators - This is a silly but fun chapter that talks
    about extending the language to let the user program define their own
    arbitrary unary and binary operators (with assignable precedence!).
    This lets us build a significant piece of the "language" as library
    routines.
--  `Chapter #7 <LangImpl7.html>`_: Extending the Language: Mutable
+-  `Chapter #7 <LangImpl07.html>`_: Extending the Language: Mutable
    Variables - This chapter talks about adding user-defined local
    variables along with an assignment operator. The interesting part
    about this is how easy and trivial it is to construct SSA form in
    LLVM: no, LLVM does *not* require your front-end to construct SSA
    form!
--  `Chapter #8 <LangImpl8.html>`_: Extending the Language: Debug
+-  `Chapter #8 <LangImpl08.html>`_: Compiling to Object Files - This
+   chapter explains how to take LLVM IR and compile it down to object
+   files.
+-  `Chapter #9 <LangImpl09.html>`_: Extending the Language: Debug
    Information - Having built a decent little programming language with
    control flow, functions and mutable variables, we consider what it
    takes to add debug information to standalone executables. This debug
    information will allow you to set breakpoints in Kaleidoscope
    functions, print out argument variables, and call functions - all
    from within the debugger!
--  `Chapter #9 <LangImpl9.html>`_: Conclusion and other useful LLVM
+-  `Chapter #10 <LangImpl10.html>`_: Conclusion and other useful LLVM
    tidbits - This chapter wraps up the series by talking about
    potential ways to extend the language, but also includes a bunch of
    pointers to info about "special topics" like adding garbage
@@ -146,7 +149,7 @@ useful for mutually recursive functions). For example:
 
 A more interesting example is included in Chapter 6 where we write a
 little Kaleidoscope application that `displays a Mandelbrot
-Set <LangImpl6.html#kicking-the-tires>`_ at various levels of magnification.
+Set <LangImpl06.html#kicking-the-tires>`_ at various levels of magnification.
 
 Lets dive into the implementation of this language!
 
@@ -280,11 +283,11 @@ file. These are handled with this code:
     }
 
 With this, we have the complete lexer for the basic Kaleidoscope
-language (the `full code listing <LangImpl2.html#full-code-listing>`_ for the Lexer
-is available in the `next chapter <LangImpl2.html>`_ of the tutorial).
+language (the `full code listing <LangImpl02.html#full-code-listing>`_ for the Lexer
+is available in the `next chapter <LangImpl02.html>`_ of the tutorial).
 Next we'll `build a simple parser that uses this to build an Abstract
-Syntax Tree <LangImpl2.html>`_. When we have that, we'll include a
+Syntax Tree <LangImpl02.html>`_. When we have that, we'll include a
 driver so that you can use the lexer and parser together.
 
-`Next: Implementing a Parser and AST <LangImpl2.html>`_
+`Next: Implementing a Parser and AST <LangImpl02.html>`_
 
diff --git a/docs/tutorial/LangImpl2.rst b/docs/tutorial/LangImpl02.rst
index f01e3f90f20..701cbc96113 100644
--- a/docs/tutorial/LangImpl2.rst
+++ b/docs/tutorial/LangImpl02.rst
@@ -731,5 +731,5 @@ Here is the code:
 .. literalinclude:: ../../examples/Kaleidoscope/Chapter2/toy.cpp
    :language: c++
 
-`Next: Implementing Code Generation to LLVM IR <LangImpl3.html>`_
+`Next: Implementing Code Generation to LLVM IR <LangImpl03.html>`_
 
diff --git a/docs/tutorial/LangImpl3.rst b/docs/tutorial/LangImpl03.rst
index e3a3ae99334..2bb3a300026 100644
--- a/docs/tutorial/LangImpl3.rst
+++ b/docs/tutorial/LangImpl03.rst
@@ -563,5 +563,5 @@ Here is the code:
 .. literalinclude:: ../../examples/Kaleidoscope/Chapter3/toy.cpp
    :language: c++
 
-`Next: Adding JIT and Optimizer Support <LangImpl4.html>`_
+`Next: Adding JIT and Optimizer Support <LangImpl04.html>`_
 
diff --git a/docs/tutorial/LangImpl4.rst b/docs/tutorial/LangImpl04.rst
index 7668a2974a7..78596cd8eee 100644
--- a/docs/tutorial/LangImpl4.rst
+++ b/docs/tutorial/LangImpl04.rst
@@ -606,5 +606,5 @@ Here is the code:
 .. literalinclude:: ../../examples/Kaleidoscope/Chapter4/toy.cpp
    :language: c++
 
-`Next: Extending the language: control flow <LangImpl5.html>`_
+`Next: Extending the language: control flow <LangImpl05.html>`_
 
diff --git a/docs/tutorial/LangImpl5-cfg.png b/docs/tutorial/LangImpl05-cfg.png
index cdba92ff6c5..cdba92ff6c5 100644
--- a/docs/tutorial/LangImpl5-cfg.png
+++ b/docs/tutorial/LangImpl05-cfg.png
diff --git a/docs/tutorial/LangImpl5.rst b/docs/tutorial/LangImpl05.rst
index eb76e663be5..ae0935d9ba1 100644
--- a/docs/tutorial/LangImpl5.rst
+++ b/docs/tutorial/LangImpl05.rst
@@ -217,7 +217,7 @@ IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a
 window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll
 see this graph:
 
-.. figure:: LangImpl5-cfg.png
+.. figure:: LangImpl05-cfg.png
    :align: center
    :alt: Example CFG
 
@@ -786,5 +786,5 @@ Here is the code:
 .. literalinclude:: ../../examples/Kaleidoscope/Chapter5/toy.cpp
    :language: c++
 
-`Next: Extending the language: user-defined operators <LangImpl6.html>`_
+`Next: Extending the language: user-defined operators <LangImpl06.html>`_
 
diff --git a/docs/tutorial/LangImpl6.rst b/docs/tutorial/LangImpl06.rst
index c30eaedad12..7c9a2123e8f 100644
--- a/docs/tutorial/LangImpl6.rst
+++ b/docs/tutorial/LangImpl06.rst
@@ -764,5 +764,5 @@ Here is the code:
    :language: c++
 
 `Next: Extending the language: mutable variables / SSA
-construction <LangImpl7.html>`_
+construction <LangImpl07.html>`_
 
diff --git a/docs/tutorial/LangImpl7.rst b/docs/tutorial/LangImpl07.rst
index 68a86eda8a7..4d86ecad38a 100644
--- a/docs/tutorial/LangImpl7.rst
+++ b/docs/tutorial/LangImpl07.rst
@@ -877,5 +877,5 @@ Here is the code:
 .. literalinclude:: ../../examples/Kaleidoscope/Chapter7/toy.cpp
    :language: c++
 
-`Next: Adding Debug Information <LangImpl8.html>`_
+`Next: Compiling to Object Code <LangImpl08.html>`_
 
diff --git a/docs/tutorial/LangImpl08.rst b/docs/tutorial/LangImpl08.rst
new file mode 100644
index 00000000000..b2eeb35ae3a
--- /dev/null
+++ b/docs/tutorial/LangImpl08.rst
@@ -0,0 +1,218 @@
+========================================
+ Kaleidoscope: Compiling to Object Code
+========================================
+
+.. contents::
+   :local:
+
+Chapter 8 Introduction
+======================
+
+Welcome to Chapter 8 of the "`Implementing a language with LLVM
+<index.html>`_" tutorial. This chapter describes how to compile our
+language down to object files.
+
+Choosing a target
+=================
+
+LLVM has native support for cross-compilation. You can compile to the
+architecture of your current machine, or just as easily compile for
+other architectures. In this tutorial, we'll target the current
+machine.
+
+To specify the architecture that you want to target, we use a string
+called a "target triple". This takes the form
+``<arch><sub>-<vendor>-<sys>-<abi>`` (see the `cross compilation docs
+<http://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_).
+
+As an example, we can see what clang thinks is our current target
+triple:
+
+::
+
+    $ clang --version | grep Target
+    Target: x86_64-unknown-linux-gnu
+
+Running this command may show something different on your machine as
+you might be using a different architecture or operating system to me.
+
+Fortunately, we don't need to hard-code a target triple to target the
+current machine. LLVM provides ``sys::getDefaultTargetTriple``, which
+returns the target triple of the current machine.
+
+.. code-block:: c++
+
+    auto TargetTriple = sys::getDefaultTargetTriple();
+
+LLVM doesn't require us to to link in all the target
+functionality. For example, if we're just using the JIT, we don't need
+the assembly printers. Similarly, if we're only targetting certain
+architectures, we can only link in the functionality for those
+architectures.
+
+For this example, we'll initialize all the targets for emitting object
+code.
+
+.. code-block:: c++
+
+    InitializeAllTargetInfos();
+    InitializeAllTargets();
+    InitializeAllTargetMCs();
+    InitializeAllAsmParsers();
+    InitializeAllAsmPrinters();
+
+We can now use our target triple to get a ``Target``:
+
+.. code-block:: c++
+
+  std::string Error;
+  auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);
+
+  // Print an error and exit if we couldn't find the requested target.
+  // This generally occurs if we've forgotten to initialise the
+  // TargetRegistry or we have a bogus target triple.
+  if (!Target) {
+    errs() << Error;
+    return 1;
+  }
+
+Target Machine
+==============
+
+We will also need a ``TargetMachine``. This class provides a complete
+machine description of the machine we're targetting. If we want to
+target a specific feature (such as SSE) or a specific CPU (such as
+Intel's Sandylake), we do so now.
+
+To see which features and CPUs that LLVM knows about, we can use
+``llc``. For example, let's look at x86:
+
+::
+
+    $ llvm-as < /dev/null | llc -march=x86 -mattr=help
+    Available CPUs for this target:
+
+      amdfam10      - Select the amdfam10 processor.
+      athlon        - Select the athlon processor.
+      athlon-4      - Select the athlon-4 processor.
+      ...
+
+    Available features for this target:
+
+      16bit-mode            - 16-bit mode (i8086).
+      32bit-mode            - 32-bit mode (80386).
+      3dnow                 - Enable 3DNow! instructions.
+      3dnowa                - Enable 3DNow! Athlon instructions.
+      ...
+
+For our example, we'll use the generic CPU without any additional
+features, options or relocation model.
+
+.. code-block:: c++
+
+  auto CPU = "generic";
+  auto Features = "";
+
+  TargetOptions opt;
+  auto RM = Optional<Reloc::Model>();
+  auto TargetMachine = Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);
+
+
+Configuring the Module
+======================
+
+We're now ready to configure our module, to specify the target and
+data layout. This isn't strictly necessary, but the `frontend
+performance guide <../Frontend/PerformanceTips.html>`_ recommends
+this. Optimizations benefit from knowing about the target and data
+layout.
+
+.. code-block:: c++
+
+  TheModule->setDataLayout(TargetMachine->createDataLayout());
+  TheModule->setTargetTriple(TargetTriple);   
+  
+Emit Object Code
+================
+
+We're ready to emit object code! Let's define where we want to write
+our file to:
+
+.. code-block:: c++
+
+  auto Filename = "output.o";
+  std::error_code EC;
+  raw_fd_ostream dest(Filename, EC, sys::fs::F_None);
+
+  if (EC) {
+    errs() << "Could not open file: " << EC.message();
+    return 1;
+  }
+
+Finally, we define a pass that emits object code, then we run that
+pass:
+
+.. code-block:: c++
+
+  legacy::PassManager pass;
+  auto FileType = TargetMachine::CGFT_ObjectFile;
+
+  if (TargetMachine->addPassesToEmitFile(pass, dest, FileType)) {
+    errs() << "TargetMachine can't emit a file of this type";
+    return 1;
+  }
+
+  pass.run(*TheModule);
+  dest.flush();
+
+Putting It All Together
+=======================
+
+Does it work? Let's give it a try. We need to compile our code, but
+note that the arguments to ``llvm-config`` are different to the previous chapters.
+
+::
+
+    $ clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs all` -o toy
+
+Let's run it, and define a simple ``average`` function. Press Ctrl-D
+when you're done.
+
+::
+   
+    $ ./toy
+    ready> def average(x y) (x + y) * 0.5;
+    ^D
+    Wrote output.o
+
+We have an object file! To test it, let's write a simple program and
+link it with our output. Here's the source code:
+
+.. code-block:: c++
+
+    #include <iostream>
+
+    extern "C" {
+        double average(double, double);
+    }
+
+    int main() {
+        std::cout << "average of 3.0 and 4.0: " << average(3.0, 4.0) << std::endl;
+    }
+
+We link our program to output.o and check the result is what we
+expected:
+
+::
+
+    $ clang++ main.cpp output.o -o main
+    $ ./main
+    average of 3.0 and 4.0: 3.5
+
+Full Code Listing
+=================
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter8/toy.cpp
+   :language: c++
+
+`Next: Adding Debug Information <LangImpl09.html>`_
diff --git a/docs/tutorial/LangImpl8.rst b/docs/tutorial/LangImpl09.rst
index 3b0f443f08d..0053960756d 100644
--- a/docs/tutorial/LangImpl8.rst
+++ b/docs/tutorial/LangImpl09.rst
@@ -5,11 +5,11 @@ Kaleidoscope: Adding Debug Information
 .. contents::
    :local:
 
-Chapter 8 Introduction
+Chapter 9 Introduction
 ======================
 
-Welcome to Chapter 8 of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. In chapters 1 through 7, we've built a
+Welcome to Chapter 9 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. In chapters 1 through 8, we've built a
 decent little programming language with functions and variables.
 What happens if something goes wrong though, how do you debug your
 program?
@@ -149,7 +149,7 @@ command line:
 
 .. code-block:: bash
 
-  Kaleidoscope-Ch8 < fib.ks | & clang -x ir -
+  Kaleidoscope-Ch9 < fib.ks | & clang -x ir -
 
 which gives an a.out/a.exe in the current working directory.
 
@@ -455,8 +455,8 @@ debug information. To build this example, use:
 
 Here is the code:
 
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter8/toy.cpp
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter9/toy.cpp
    :language: c++
 
-`Next: Conclusion and other useful LLVM tidbits <LangImpl9.html>`_
+`Next: Conclusion and other useful LLVM tidbits <LangImpl10.html>`_
 
diff --git a/docs/tutorial/LangImpl9.rst b/docs/tutorial/LangImpl10.rst
index 5799c99402c..5799c99402c 100644
--- a/docs/tutorial/LangImpl9.rst
+++ b/docs/tutorial/LangImpl10.rst
diff --git a/docs/tutorial/OCamlLangImpl5.rst b/docs/tutorial/OCamlLangImpl5.rst
index 675b9bc1978..3a135b23337 100644
--- a/docs/tutorial/OCamlLangImpl5.rst
+++ b/docs/tutorial/OCamlLangImpl5.rst
@@ -178,7 +178,7 @@ IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a
 window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll
 see this graph:
 
-.. figure:: LangImpl5-cfg.png
+.. figure:: LangImpl05-cfg.png
    :align: center
    :alt: Example CFG