blob: 2b589d19180e37f7989db03443e2ed6a6e2d35a9 [file] [log] [blame]
Hans Wennborg74e4f8a2019-04-11 07:46:25 +00001:orphan:
2
Chris Lattner2243a1652019-04-07 13:17:16 +00003=============================================
Chris Lattner13d35052019-04-07 13:42:29 +00004My First Language Frontend with LLVM Tutorial
Chris Lattner2243a1652019-04-07 13:17:16 +00005=============================================
6
Chris Lattner0fa6c152019-04-07 14:23:11 +00007**Requirements:** This tutorial assumes you know C++, but no previous
8compiler experience is necessary.
9
Chris Lattner13d35052019-04-07 13:42:29 +000010Welcome to the "My First Language Frontend with LLVM" tutorial. Here we
11run through the implementation of a simple language, showing
12how fun and easy it can be. This tutorial will get you up and running
13fast and show a concrete example of something that uses LLVM to generate
14code.
Chris Lattner2243a1652019-04-07 13:17:16 +000015
Chris Lattner13d35052019-04-07 13:42:29 +000016This tutorial introduces the simple "Kaleidoscope" language, building it
17iteratively over the course of several chapters, showing how it is built
18over time. This lets us cover a range of language design and LLVM-specific
19ideas, showing and explaining the code for it all along the way,
Chris Lattner0fa6c152019-04-07 14:23:11 +000020and reduces the overwhelming amount of details up front. We strongly
Chris Lattner13d35052019-04-07 13:42:29 +000021encourage that you *work with this code* - make a copy and hack it up and
22experiment.
Chris Lattner2243a1652019-04-07 13:17:16 +000023
Chris Lattner0fa6c152019-04-07 14:23:11 +000024**Warning**: In order to focus on teaching compiler techniques and LLVM
Chris Lattner13d35052019-04-07 13:42:29 +000025specifically,
26this tutorial does *not* show best practices in software engineering
27principles. For example, the code uses global variables
Chris Lattner0fa6c152019-04-07 14:23:11 +000028pervasively, doesn't use
Chris Lattner2243a1652019-04-07 13:17:16 +000029`visitors <http://en.wikipedia.org/wiki/Visitor_pattern>`_, etc... but
Chris Lattner13d35052019-04-07 13:42:29 +000030instead keeps things simple and focuses on the topics at hand.
Chris Lattner2243a1652019-04-07 13:17:16 +000031
Chris Lattner13d35052019-04-07 13:42:29 +000032This tutorial is structured into chapters covering individual topics,
Chris Lattner0fa6c152019-04-07 14:23:11 +000033allowing you to skip ahead as you wish:
Chris Lattner2243a1652019-04-07 13:17:16 +000034
Chris Lattner0fa6c152019-04-07 14:23:11 +000035- `Chapter #1: Kaleidoscope language and Lexer <LangImpl01.html>`_ -
36 This shows where we are
Chris Lattner13d35052019-04-07 13:42:29 +000037 going and the basic functionality that we want to build. A lexer
38 is also the first part of building a parser for a language, and we
39 use a simple C++ lexer which is easy to understand.
Chris Lattner0fa6c152019-04-07 14:23:11 +000040- `Chapter #2: Implementing a Parser and AST <LangImpl02.html>`_ -
Chris Lattner2243a1652019-04-07 13:17:16 +000041 With the lexer in place, we can talk about parsing techniques and
42 basic AST construction. This tutorial describes recursive descent
Chris Lattner13d35052019-04-07 13:42:29 +000043 parsing and operator precedence parsing.
Chris Lattner0fa6c152019-04-07 14:23:11 +000044- `Chapter #3: Code generation to LLVM IR <LangImpl03.html>`_ - with
Chris Lattner13d35052019-04-07 13:42:29 +000045 the AST ready, we show how easy it is to generate LLVM IR, and show
46 a simple way to incorporate LLVM into your project.
Chris Lattner0fa6c152019-04-07 14:23:11 +000047- `Chapter #4: Adding JIT and Optimizer Support <LangImpl04.html>`_ -
48 One great thing about LLVM is its support for JIT compilation, so
Chris Lattner2243a1652019-04-07 13:17:16 +000049 we'll dive right into it and show you the 3 lines it takes to add JIT
Chris Lattner13d35052019-04-07 13:42:29 +000050 support. Later chapters show how to generate .o files.
Chris Lattner0fa6c152019-04-07 14:23:11 +000051- `Chapter #5: Extending the Language: Control Flow <LangImpl05.html>`_ - With the basic language up and running, we show how to extend
Chris Lattner13d35052019-04-07 13:42:29 +000052 it with control flow operations ('if' statement and a 'for' loop). This
53 gives us a chance to talk about SSA construction and control
Chris Lattner2243a1652019-04-07 13:17:16 +000054 flow.
Chris Lattner0fa6c152019-04-07 14:23:11 +000055- `Chapter #6: Extending the Language: User-defined Operators
56 <LangImpl06.html>`_ - This chapter extends the language to let
57 users define arbitrary unary and binary operators - with assignable
58 precedence! This allows us to build a significant piece of the
Chris Lattner13d35052019-04-07 13:42:29 +000059 "language" as library routines.
Chris Lattner0fa6c152019-04-07 14:23:11 +000060- `Chapter #7: Extending the Language: Mutable Variables
61 <LangImpl07.html>`_ - This chapter talks about adding user-defined local
Chris Lattner13d35052019-04-07 13:42:29 +000062 variables along with an assignment operator. This shows how easy it is
63 to construct SSA form in LLVM: LLVM does *not* require your front-end
64 to construct SSA form in order to use it!
Chris Lattner0fa6c152019-04-07 14:23:11 +000065- `Chapter #8: Compiling to Object Files <LangImpl08.html>`_ - This
Chris Lattner2243a1652019-04-07 13:17:16 +000066 chapter explains how to take LLVM IR and compile it down to object
Chris Lattner13d35052019-04-07 13:42:29 +000067 files, like a static compiler does.
Chris Lattner32a8e742019-04-07 14:34:24 +000068- `Chapter #9: Debug Information <LangImpl09.html>`_ - A real language
69 needs to support debuggers, so we
Chris Lattner0fa6c152019-04-07 14:23:11 +000070 add debug information that allows setting breakpoints in Kaleidoscope
Chris Lattner13d35052019-04-07 13:42:29 +000071 functions, print out argument variables, and call functions!
Chris Lattner0fa6c152019-04-07 14:23:11 +000072- `Chapter #10: Conclusion and other tidbits <LangImpl10.html>`_ - This
73 chapter wraps up the series by discussing ways to extend the language
74 and includes pointers to info on "special topics" like adding garbage
Chris Lattner2243a1652019-04-07 13:17:16 +000075 collection support, exceptions, debugging, support for "spaghetti
Chris Lattner0fa6c152019-04-07 14:23:11 +000076 stacks", etc.
Chris Lattner2243a1652019-04-07 13:17:16 +000077
78By the end of the tutorial, we'll have written a bit less than 1000 lines
Chris Lattner0fa6c152019-04-07 14:23:11 +000079of (non-comment, non-blank) lines of code. With this small amount of
Chris Lattner13d35052019-04-07 13:42:29 +000080code, we'll have built up a nice little compiler for a non-trivial
Chris Lattner2243a1652019-04-07 13:17:16 +000081language including a hand-written lexer, parser, AST, as well as code
Chris Lattner0fa6c152019-04-07 14:23:11 +000082generation support - both static and JIT! The breadth of this is a great
83testament to the strengths of LLVM and shows why it is such a popular
84target for language designers and others who need high performance code
85generation.