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
llvm-svn: 274441
diff --git a/llvm/docs/tutorial/LangImpl1.rst b/llvm/docs/tutorial/LangImpl01.rst
similarity index 91%
rename from llvm/docs/tutorial/LangImpl1.rst
rename to llvm/docs/tutorial/LangImpl01.rst
index 0b8ed7b..f7fbd15 100644
--- a/llvm/docs/tutorial/LangImpl1.rst
+++ b/llvm/docs/tutorial/LangImpl01.rst
@@ -42,45 +42,48 @@
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 @@
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 @@
}
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/llvm/docs/tutorial/LangImpl2.rst b/llvm/docs/tutorial/LangImpl02.rst
similarity index 99%
rename from llvm/docs/tutorial/LangImpl2.rst
rename to llvm/docs/tutorial/LangImpl02.rst
index f01e3f9..701cbc9 100644
--- a/llvm/docs/tutorial/LangImpl2.rst
+++ b/llvm/docs/tutorial/LangImpl02.rst
@@ -731,5 +731,5 @@
.. 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/llvm/docs/tutorial/LangImpl3.rst b/llvm/docs/tutorial/LangImpl03.rst
similarity index 99%
rename from llvm/docs/tutorial/LangImpl3.rst
rename to llvm/docs/tutorial/LangImpl03.rst
index e3a3ae9..2bb3a30 100644
--- a/llvm/docs/tutorial/LangImpl3.rst
+++ b/llvm/docs/tutorial/LangImpl03.rst
@@ -563,5 +563,5 @@
.. 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/llvm/docs/tutorial/LangImpl4.rst b/llvm/docs/tutorial/LangImpl04.rst
similarity index 99%
rename from llvm/docs/tutorial/LangImpl4.rst
rename to llvm/docs/tutorial/LangImpl04.rst
index 7668a29..78596cd 100644
--- a/llvm/docs/tutorial/LangImpl4.rst
+++ b/llvm/docs/tutorial/LangImpl04.rst
@@ -606,5 +606,5 @@
.. 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/llvm/docs/tutorial/LangImpl5-cfg.png b/llvm/docs/tutorial/LangImpl05-cfg.png
similarity index 100%
rename from llvm/docs/tutorial/LangImpl5-cfg.png
rename to llvm/docs/tutorial/LangImpl05-cfg.png
Binary files differ
diff --git a/llvm/docs/tutorial/LangImpl5.rst b/llvm/docs/tutorial/LangImpl05.rst
similarity index 99%
rename from llvm/docs/tutorial/LangImpl5.rst
rename to llvm/docs/tutorial/LangImpl05.rst
index eb76e66..ae0935d 100644
--- a/llvm/docs/tutorial/LangImpl5.rst
+++ b/llvm/docs/tutorial/LangImpl05.rst
@@ -217,7 +217,7 @@
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 @@
.. 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/llvm/docs/tutorial/LangImpl6.rst b/llvm/docs/tutorial/LangImpl06.rst
similarity index 99%
rename from llvm/docs/tutorial/LangImpl6.rst
rename to llvm/docs/tutorial/LangImpl06.rst
index c30eaed..7c9a212 100644
--- a/llvm/docs/tutorial/LangImpl6.rst
+++ b/llvm/docs/tutorial/LangImpl06.rst
@@ -764,5 +764,5 @@
:language: c++
`Next: Extending the language: mutable variables / SSA
-construction <LangImpl7.html>`_
+construction <LangImpl07.html>`_
diff --git a/llvm/docs/tutorial/LangImpl7.rst b/llvm/docs/tutorial/LangImpl07.rst
similarity index 99%
rename from llvm/docs/tutorial/LangImpl7.rst
rename to llvm/docs/tutorial/LangImpl07.rst
index 68a86ed..4d86eca 100644
--- a/llvm/docs/tutorial/LangImpl7.rst
+++ b/llvm/docs/tutorial/LangImpl07.rst
@@ -877,5 +877,5 @@
.. literalinclude:: ../../examples/Kaleidoscope/Chapter7/toy.cpp
:language: c++
-`Next: Adding Debug Information <LangImpl8.html>`_
+`Next: Compiling to Object Code <LangImpl08.html>`_
diff --git a/llvm/docs/tutorial/LangImpl08.rst b/llvm/docs/tutorial/LangImpl08.rst
new file mode 100644
index 0000000..b2eeb35
--- /dev/null
+++ b/llvm/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/llvm/docs/tutorial/LangImpl8.rst b/llvm/docs/tutorial/LangImpl09.rst
similarity index 97%
rename from llvm/docs/tutorial/LangImpl8.rst
rename to llvm/docs/tutorial/LangImpl09.rst
index 3b0f443..0053960 100644
--- a/llvm/docs/tutorial/LangImpl8.rst
+++ b/llvm/docs/tutorial/LangImpl09.rst
@@ -5,11 +5,11 @@
.. 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 @@
.. 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 @@
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/llvm/docs/tutorial/LangImpl9.rst b/llvm/docs/tutorial/LangImpl10.rst
similarity index 100%
rename from llvm/docs/tutorial/LangImpl9.rst
rename to llvm/docs/tutorial/LangImpl10.rst
diff --git a/llvm/docs/tutorial/OCamlLangImpl5.rst b/llvm/docs/tutorial/OCamlLangImpl5.rst
index 675b9bc..3a135b2 100644
--- a/llvm/docs/tutorial/OCamlLangImpl5.rst
+++ b/llvm/docs/tutorial/OCamlLangImpl5.rst
@@ -178,7 +178,7 @@
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
