Author: lattner
Date: Sun Apr 7 06:42:29 2019
New Revision: 357865
URL: http://llvm.org/viewvc/llvm-project?rev=357865&view=rev
Log:
make a bunch of cleanups in wording and tone
Modified:
llvm/trunk/docs/tutorial/MyFirstLanguageFrontend/index.rst
Modified: llvm/trunk/docs/tutorial/MyFirstLanguageFrontend/index.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/MyFirstLanguageFrontend/index.rst?rev=357865&r1=357864&r2=357865&view=diff
==============================================================================
--- llvm/trunk/docs/tutorial/MyFirstLanguageFrontend/index.rst (original)
+++ llvm/trunk/docs/tutorial/MyFirstLanguageFrontend/index.rst Sun Apr 7 06:42:29 2019
@@ -1,104 +1,81 @@
=============================================
-My First Language Frontend: Table of Contents
+My First Language Frontend with LLVM Tutorial
=============================================
-Introduction to the "Kaleidoscope" Language Tutorial
-====================================================
-
-Welcome to the "Implementing a language with LLVM" tutorial. This
-tutorial runs through the implementation of a simple language, showing
-how fun and easy it can be. This tutorial will get you up and started as
-well as help to build a framework you can extend to other languages. The
-code in this tutorial can also be used as a playground to hack on other
-LLVM specific things.
-
-The goal of this tutorial is to progressively unveil our language,
-describing how it is built up over time. This will let us cover a fairly
-broad range of language design and LLVM-specific usage issues, showing
-and explaining the code for it all along the way, without overwhelming
-you with tons of details up front.
-
-It is useful to point out ahead of time that this tutorial is really
-about teaching compiler techniques and LLVM specifically, *not* about
-teaching modern and sane software engineering principles. In practice,
-this means that we'll take a number of shortcuts to simplify the
-exposition. For example, the code uses global variables
+Welcome to the "My First Language Frontend with LLVM" tutorial. Here we
+run through the implementation of a simple language, showing
+how fun and easy it can be. This tutorial will get you up and running
+fast and show a concrete example of something that uses LLVM to generate
+code.
+
+This tutorial introduces the simple "Kaleidoscope" language, building it
+iteratively over the course of several chapters, showing how it is built
+over time. This lets us cover a range of language design and LLVM-specific
+ideas, showing and explaining the code for it all along the way,
+and reduces the amount of overwhelming details up front. We strongly
+encourage that you *work with this code* - make a copy and hack it up and
+experiment.
+
+Warning: In order to focus on teaching compiler techniques and LLVM
+specifically,
+this tutorial does *not* show best practices in software engineering
+principles. For example, the code uses global variables
all over the place, doesn't use nice design patterns like
`visitors <http://en.wikipedia.org/wiki/Visitor_pattern>`_, etc... but
-it is very simple. If you dig in and use the code as a basis for future
-projects, fixing these deficiencies shouldn't be hard.
+instead keeps things simple and focuses on the topics at hand.
+
+This tutorial is structured into chapters covering individual topics,
+allowing you to skip ahead or over things as you wish:
-I've tried to put this tutorial together in a way that makes chapters
-easy to skip over if you are already familiar with or are uninterested
-in the various pieces. The structure of the tutorial is:
-
-- `Chapter #1 <#language>`_: Introduction to the Kaleidoscope
- language, and the definition of its Lexer - This shows where we are
- going and the basic functionality that we want it to do. In order to
- make this tutorial maximally understandable and hackable, we choose
- to implement everything in C++ instead of using lexer and parser
- generators. LLVM works just fine with such tools, feel free
- to use one if you prefer.
+- `Chapter #1 <LangImpl01.html>`_: Introduction to the Kaleidoscope
+ language, and the definition of its Lexer. This shows where we are
+ going and the basic functionality that we want to build. A lexer
+ is also the first part of building a parser for a language, and we
+ use a simple C++ lexer which is easy to understand.
- `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 <LangImpl03.html>`_: Code generation to LLVM IR - With
- the AST ready, we can show off how easy generation of LLVM IR really
- is.
+ parsing and operator precedence parsing.
+- `Chapter #3 <LangImpl03.html>`_: Code generation to LLVM IR - with
+ the AST ready, we show how easy it is to generate LLVM IR, and show
+ a simple way to incorporate LLVM into your project.
- `Chapter #4 <LangImpl04.html>`_: Adding JIT and Optimizer Support
- - Because a lot of people are interested in using LLVM as a JIT,
+ - One great thing about LLVM is its support for JIT compilation, so
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. :)
+ support. Later chapters show how to generate .o files.
- `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 - With the basic language up and running, we show how to extend
+ it with control flow operations ('if' statement and a 'for' loop). This
+ gives us a chance to talk about SSA construction and control
flow.
- `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.
+ User-defined Operators - This chapter extends the language to let
+ users define arbitrary unary and binary operators (with assignable
+ precedence!). This lets us build a significant piece of the
+ "language" as library routines.
- `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!
+ variables along with an assignment operator. This shows how easy it is
+ to construct SSA form in LLVM: LLVM does *not* require your front-end
+ to construct SSA form in order to use it!
- `Chapter #8 <LangImpl08.html>`_: Compiling to Object Files - This
chapter explains how to take LLVM IR and compile it down to object
- files.
+ files, like a static compiler does.
- `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!
+ Information - A real language needs to support debuggers, so we add
+ debug information that allows setting breakpoints in Kaleidoscope
+ functions, print out argument variables, and call functions!
- `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
+ potential ways to extend the language, and includes some
+ pointers to info on "special topics" like adding garbage
collection support, exceptions, debugging, support for "spaghetti
- stacks", and a bunch of other tips and tricks.
+ stacks", and random tips and tricks.
By the end of the tutorial, we'll have written a bit less than 1000 lines
of non-comment, non-blank, lines of code. With this small amount of
-code, we'll have built up a very reasonable compiler for a non-trivial
+code, we'll have built up a nice little compiler for a non-trivial
language including a hand-written lexer, parser, AST, as well as code
-generation support with a JIT compiler. While other systems may have
-interesting "hello world" tutorials, I think the breadth of this
-tutorial is a great testament to the strengths of LLVM and why you
-should consider it if you're interested in language or compiler design.
-
-A note about this tutorial: we expect you to extend the language and
-play with it on your own. Take the code and go crazy hacking away at it,
-compilers don't need to be scary creatures - it can be a lot of fun to
-play with languages!
-
-
+generation support with a JIT compiler. The breadth of this
+tutorial is a great testament to the strengths of LLVM and shows why
+it is such a popular target for language designers.