1=============================================
2My First Language Frontend with LLVM Tutorial
3=============================================
4
5.. toctree::
6   :hidden:
7
8   LangImpl01
9   LangImpl02
10   LangImpl03
11   LangImpl04
12   LangImpl05
13   LangImpl06
14   LangImpl07
15   LangImpl08
16   LangImpl09
17   LangImpl10
18
19**Requirements:** This tutorial assumes you know C++, but no previous
20compiler experience is necessary.
21
22Welcome to the "My First Language Frontend with LLVM" tutorial. Here we
23run through the implementation of a simple language, showing
24how fun and easy it can be.  This tutorial will get you up and running
25fast and show a concrete example of something that uses LLVM to generate
26code.
27
28This tutorial introduces the simple "Kaleidoscope" language, building it
29iteratively over the course of several chapters, showing how it is built
30over time. This lets us cover a range of language design and LLVM-specific
31ideas, showing and explaining the code for it all along the way,
32and reduces the overwhelming amount of details up front.  We strongly
33encourage that you *work with this code* - make a copy and hack it up and
34experiment.
35
36**Warning**: In order to focus on teaching compiler techniques and LLVM
37specifically,
38this tutorial does *not* show best practices in software engineering
39principles.  For example, the code uses global variables
40pervasively, doesn't use
41`visitors <http://en.wikipedia.org/wiki/Visitor_pattern>`_, etc... but
42instead keeps things simple and focuses on the topics at hand.
43
44This tutorial is structured into chapters covering individual topics,
45allowing you to skip ahead as you wish:
46
47-  `Chapter #1: Kaleidoscope language and Lexer <LangImpl01.html>`_ -
48   This shows where we are
49   going and the basic functionality that we want to build.  A lexer
50   is also the first part of building a parser for a language, and we
51   use a simple C++ lexer which is easy to understand.
52-  `Chapter #2: Implementing a Parser and AST <LangImpl02.html>`_ -
53   With the lexer in place, we can talk about parsing techniques and
54   basic AST construction. This tutorial describes recursive descent
55   parsing and operator precedence parsing.
56-  `Chapter #3: Code generation to LLVM IR <LangImpl03.html>`_ - with
57   the AST ready, we show how easy it is to generate LLVM IR, and show
58   a simple way to incorporate LLVM into your project.
59-  `Chapter #4: Adding JIT and Optimizer Support <LangImpl04.html>`_ -
60   One great thing about LLVM is its support for JIT compilation, so
61   we'll dive right into it and show you the 3 lines it takes to add JIT
62   support. Later chapters show how to generate .o files.
63-  `Chapter #5: Extending the Language: Control Flow <LangImpl05.html>`_ - With
64   the basic language up and running, we show how to extend
65   it with control flow operations ('if' statement and a 'for' loop). This
66   gives us a chance to talk about SSA construction and control
67   flow.
68-  `Chapter #6: Extending the Language: User-defined Operators
69   <LangImpl06.html>`_ - This chapter extends the language to let
70   users define arbitrary unary and binary operators - with assignable
71   precedence!  This allows us to build a significant piece of the
72   "language" as library routines.
73-  `Chapter #7: Extending the Language: Mutable Variables
74   <LangImpl07.html>`_ - This chapter talks about adding user-defined local
75   variables along with an assignment operator. This shows how easy it is
76   to construct SSA form in LLVM: LLVM does *not* require your front-end
77   to construct SSA form in order to use it!
78-  `Chapter #8: Compiling to Object Files <LangImpl08.html>`_ - This
79   chapter explains how to take LLVM IR and compile it down to object
80   files, like a static compiler does.
81-  `Chapter #9: Debug Information <LangImpl09.html>`_ - A real language
82   needs to support debuggers, so we
83   add debug information that allows setting breakpoints in Kaleidoscope
84   functions, print out argument variables, and call functions!
85-  `Chapter #10: Conclusion and other tidbits <LangImpl10.html>`_ - This
86   chapter wraps up the series by discussing ways to extend the language
87   and includes pointers to info on "special topics" like adding garbage
88   collection support, exceptions, debugging, support for "spaghetti
89   stacks", etc.
90
91By the end of the tutorial, we'll have written a bit less than 1000 lines
92of (non-comment, non-blank) lines of code. With this small amount of
93code, we'll have built up a nice little compiler for a non-trivial
94language including a hand-written lexer, parser, AST, as well as code
95generation support - both static and JIT!  The breadth of this is a great
96testament to the strengths of LLVM and shows why it is such a popular
97target for language designers and others who need high performance code
98generation.
99