diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 5ac26f150..b905e7ef3 100644 --- a/src/SUMMARY.md +++ b/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) diff --git a/src/building/bootstrapping/how-bootstrap-does-it.md b/src/building/bootstrapping/how-bootstrap-does-it.md new file mode 100644 index 000000000..6b32845f0 --- /dev/null +++ b/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 diff --git a/src/building/bootstrapping/intro.md b/src/building/bootstrapping/intro.md new file mode 100644 index 000000000..f829884fb --- /dev/null +++ b/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 diff --git a/src/building/bootstrapping.md b/src/building/bootstrapping/what-bootstrapping-does.md similarity index 96% rename from src/building/bootstrapping.md rename to src/building/bootstrapping/what-bootstrapping-does.md index 7bee8d3aa..6920ee526 100644 --- a/src/building/bootstrapping.md +++ b/src/building/bootstrapping/what-bootstrapping-does.md @@ -1,20 +1,7 @@ -# Bootstrapping the compiler +# What Bootstrapping does -[*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.