Extract Bootstrap into its own section

src/SUMMARY.md

@@ -33,7 +33,6 @@
     - [with Windows Performance Analyzer](./profiling/wpa_profiling.md)
 - [crates.io Dependencies](./crates-io.md)
 
-
 # Contributing to Rust
 
 - [Contribution Procedures](./contributing.md)
@@ -58,12 +57,18 @@
 - [Licenses](./licenses.md)
 - [Editions](guides/editions.md)
 
+# Bootstrapping
+
+- [Prologue](./building/bootstrapping/intro.md)
+- [What Bootstrapping does](./building/bootstrapping/what-bootstrapping-does.md)
+- [How Bootstrap does it](./building/bootstrapping/how-bootstrap-does-it.md)
+- [Common Bootstrap commands](./building/bootstrapping/common-commands.md)
+
 # High-level Compiler Architecture
 
 - [Prologue](./part-2-intro.md)
 - [Overview of the compiler](./overview.md)
 - [The compiler source code](./compiler-src.md)
-- [Bootstrapping](./building/bootstrapping.md)
 - [Queries: demand-driven compilation](./query.md)
     - [The Query Evaluation Model in Detail](./queries/query-evaluation-model-in-detail.md)
     - [Incremental compilation](./queries/incremental-compilation.md)

src/building/bootstrapping/common-commands.md

@@ -0,0 +1,15 @@
+# Common `x` commands
+
+| Command                                        | Explanation                                 | Remarks                                                                                                                                                                     |
+|------------------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `x build --keep-stage 0`                       | Assume stage0 std can be reused             |                                                                                                                                                                             |
+| `x build --stage 1`                            | Build up to stage1 std and create a sysroot |                                                                                                                                                                             |
+| `x clean`                                      | Invalidate build config cache               | Does not clean LLVM cache                                                                                                                                                   |
+| `x dist rustc-dev`                             | Build rustc-dev                             |                                                                                                                                                                             |
+| `x test --stage 0 library/std`                 | Test standard library                       |                                                                                                                                                                             |
+| `x check library/std`                          | Only check standard library                 |                                                                                                                                                                             |
+| `x check`                                      | Check compiler/rustc                        |                                                                                                                                                                             |
+| `x check --all-targets`                        | Cross-compile for a lot of targets          | Can be made less failure-prone by putting the imports inside   the function where they're used rather than using separate configs; creates a   problem of missing functions |
+| `x build library/std --stage 0`                | If only working on standard library         | Builds library/std then compiler/rustc then library/std again                                                                                                               |
+| `x test --stage 1`                             | Test the compiler                           |                                                                                                                                                                             |
+| `x test --stage 1 --keep-stage-std 1 tests/ui` | Run UI tests with cached stage1 std         |                                                                                                                                                                             |

src/building/bootstrapping/how-bootstrap-does-it.md

@@ -0,0 +1,48 @@
+# How Bootstrap does it
+
+The core concept in Bootstrap is a build [`Step`],  which are chained together
+by [`Builder::ensure`]. [`Builder::ensure`] takes a [`Step`] as input, and runs
+the [`Step`] if and only if it has not already been run. Let's take a closer
+look at [`Step`].
+
+## Synopsis of [`Step`]
+
+A [`Step`] represents a granular collection of actions involved in the process
+of producing some artifact. It can be thought of like a rule in Makefiles.
+The [`Step`] trait is defined as:
+
+```rs,no_run
+pub trait Step: 'static + Clone + Debug + PartialEq + Eq + Hash {
+    type Output: Clone;
+
+    const DEFAULT: bool = false;
+    const ONLY_HOSTS: bool = false;
+
+    // Required methods
+    fn run(self, builder: &Builder<'_>) -> Self::Output;
+    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_>;
+
+    // Provided method
+    fn make_run(_run: RunConfig<'_>) { ... }
+}
+```
+
+- `run` is the function that is responsible for doing the work.
+  [`Builder::ensure`] invokes `run`.
+- `should_run` is the command-line interface, which determines if an invocation
+  such as `x build foo` should run a given [`Step`]. In a "default" context
+  where no paths are provided, then `make_run` is called directly.
+- `make_run` is invoked only for things directly asked via the CLI and not
+  for steps which are dependencies of other steps.
+
+## The entry points
+
+There's a couple of preliminary steps before core Bootstrap code is reached:
+
+1. Shell script: [`./x`](https://github.com/rust-lang/rust/blob/master/x) or [`./x.ps1`](https://github.com/rust-lang/rust/blob/master/x.ps1)
+2. Convenience wrapper script: [`x.py`](https://github.com/rust-lang/rust/blob/master/x.py)
+3. [`src/bootstrap/bootstrap.py`](https://github.com/rust-lang/rust/blob/master/src/bootstrap/bootstrap.py)
+4. [`src/bootstrap/src/bin/main.rs`](https://github.com/rust-lang/rust/blob/master/src/bootstrap/src/bin/main.rs)
+
+[`Step`]: https://doc.rust-lang.org/nightly/nightly-rustc/bootstrap/core/builder/trait.Step.html
+[`Builder::ensure`]: https://doc.rust-lang.org/nightly/nightly-rustc/bootstrap/core/builder/struct.Builder.html#method.ensure

src/building/bootstrapping/intro.md

@@ -0,0 +1,23 @@
+# Bootstrapping the compiler
+
+[*Bootstrapping*][boot] is the process of using a compiler to compile itself.
+More accurately, it means using an older compiler to compile a newer version
+of the same compiler.
+
+This raises a chicken-and-egg paradox: where did the first compiler come from?
+It must have been written in a different language. In Rust's case it was
+[written in OCaml][ocaml-compiler]. However it was abandoned long ago and the
+only way to build a modern version of rustc is a slightly less modern
+version.
+
+This is exactly how `x.py` works: it downloads the current beta release of
+rustc, then uses it to compile the new compiler.
+
+In this section, we give a high-level overview of
+[what Bootstrap does](./what-bootstrapping-does.md), followed by a high-level
+introduction to [how Bootstrap does it](./how-bootstrap-does-it.md). A
+[listing of common bootstrap commands](./common-commands.md) is also provided
+for convenience.
+
+[boot]: https://en.wikipedia.org/wiki/Bootstrapping_(compilers)
+[ocaml-compiler]: https://github.com/rust-lang/rust/tree/ef75860a0a72f79f97216f8aaa5b388d98da6480/src/boot

src/building/bootstrapping.md → src/building/bootstrapping/what-bootstrapping-does.md

@@ -1,20 +1,7 @@
-# Bootstrapping the compiler
+# What Bootstrapping does
 
 <!-- toc -->
 
-[*Bootstrapping*][boot] is the process of using a compiler to compile itself.
-More accurately, it means using an older compiler to compile a newer version
-of the same compiler.
-
-This raises a chicken-and-egg paradox: where did the first compiler come from?
-It must have been written in a different language. In Rust's case it was
-[written in OCaml][ocaml-compiler]. However it was abandoned long ago and the
-only way to build a modern version of rustc is a slightly less modern
-version.
-
-This is exactly how `x.py` works: it downloads the current beta release of
-rustc, then uses it to compile the new compiler.
-
 Note that this documentation mostly covers user-facing information. See
 [bootstrap/README.md][bootstrap-internals] to read about bootstrap internals.