Merge pull request #33 from mark-i-m/stages

Add a paragraph about bootstrapping

src/how-to-build-and-run.md

@@ -48,6 +48,19 @@ use-jemalloc = false
 
 ### Running x.py and building a stage1 compiler
 
+One thing to keep in mind is that `rustc` is a _bootstrapping_ compiler. That
+is, since `rustc` is written in Rust, we need to use an older version of the
+compiler to compile the newer version. In particular, the newer version of the
+compiler, `libstd`, and other tooling may use some unstable features
+internally. The result is the compiling `rustc` is done in stages.
+
+- Stage 0: the current _beta_ compiler is compiled using the current _stable_ compiler.
+- Stage 1: the code in your clone is then compiled with the stage 0 compiler.
+- Stage 2: the code in your clone is then compiled with the stage 1 compiler (i.e. it builds itself).
+
+For hacking, often building the stage 1 compiler is enough, but for testing and
+release, the stage 2 compiler is used.
+
 Once you've created a config.toml, you are now ready to run
 `x.py`. There are a lot of options here, but let's start with what is
 probably the best "go to" command for building a local rust: