Extract Bootstrap into its own section (#1939)

* Extract Bootstrap into its own section

Add brief explanation for `Step` and `Builder::ensure` as core
Bootstrap internal concepts.

* Drop common commands page (use `x --help` instead)

* Add `make` as an alternative entry point

* Add src/bootstrap/README.md link

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,17 @@
 - [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)
+
 # 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/how-bootstrap-does-it.md

@@ -0,0 +1,51 @@
+# 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 or `make`: [`./x`](https://github.com/rust-lang/rust/blob/master/x) or [`./x.ps1`](https://github.com/rust-lang/rust/blob/master/x.ps1) or `make`
+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)
+
+See [src/bootstrap/README.md](https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md)
+for a more specific description of the implementation details.
+
+[`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,21 @@
+# 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).
+
+[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.