diff --git a/src/building/bootstrapping.md b/src/building/bootstrapping.md index ed0d9693c..dd24699fe 100644 --- a/src/building/bootstrapping.md +++ b/src/building/bootstrapping.md @@ -15,11 +15,41 @@ 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. The beta release is -called `stage0` and the newly built compiler is `stage1` (or `stage0 -artifacts`). To get the full benefits of the new compiler (e.g. optimizations -and new features), the `stage1` compiler then compiles _itself_ again. This -last compiler is called `stage2` (or `stage1 artifacts`). +rustc, then uses it to compile the new compiler. + +## Stages of bootstrapping + +Compiling `rustc` is done in stages: + +- **Stage 0:** the stage0 compiler is usually (you can configure `x.py` to use + something else) the current _beta_ `rustc` compiler and its associated dynamic + libraries (which `x.py` will download for you). This stage0 compiler is then + used only to compile `rustbuild`, `std`, and `rustc`. When compiling + `rustc`, this stage0 compiler uses the freshly compiled `std`. + There are two concepts at play here: a compiler (with its set of dependencies) + and its 'target' or 'object' libraries (`std` and `rustc`). + Both are staged, but in a staggered manner. +- **Stage 1:** the code in your clone (for new version) is then + compiled with the stage0 compiler to produce the stage1 compiler. + However, it was built with an older compiler (stage0), so to + optimize the stage1 compiler we go to next the stage. + - In theory, the stage1 compiler is functionally identical to the + stage2 compiler, but in practice there are subtle differences. In + particular, the stage1 compiler itself was built by stage0 and + hence not by the source in your working directory: this means that + the symbol names used in the compiler source may not match the + symbol names that would have been made by the stage1 compiler. This is + important when using dynamic linking and the lack of ABI compatibility + between versions. This primarily manifests when tests try to link with any + of the `rustc_*` crates or use the (now deprecated) plugin infrastructure. + These tests are marked with `ignore-stage1`. +- **Stage 2:** we rebuild our stage1 compiler with itself to produce + the stage2 compiler (i.e. it builds itself) to have all the _latest + optimizations_. (By default, we copy the stage1 libraries for use by + the stage2 compiler, since they ought to be identical.) +- _(Optional)_ **Stage 3**: to sanity check our new compiler, we + can build the libraries with the stage2 compiler. The result ought + to be identical to before, unless something has broken. The `stage2` compiler is the one distributed with `rustup` and all other install methods. However, it takes a very long time to build because one must @@ -76,7 +106,7 @@ contribution [here][bootstrap-build]. [bootstrap-build]: https://github.com/rust-lang/rust/pull/71994 -## Stages of bootstrap +## Understanding stages of bootstrap This is a detailed look into the separate bootstrap stages. When running `x.py` you will see output such as: diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 364a307d3..01ed3c04c 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -77,50 +77,8 @@ effectively deal with the repo for various common tasks. This chapter focuses on the basics to be productive, but if you want to learn more about `x.py`, read its README.md [here](https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md). - -## Bootstrapping - -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 and some of the artifacts needed -to build it, such as `std` and other tooling, may use some unstable features -internally, requiring a specific version which understands these unstable -features. - -The result is that compiling `rustc` is done in stages: - -- **Stage 0:** the stage0 compiler is usually (you can configure `x.py` to use - something else) the current _beta_ `rustc` compiler and its associated dynamic - libraries (which `x.py` will download for you). This stage0 compiler is then - used only to compile `rustbuild`, `std`, and `rustc`. When compiling - `rustc`, this stage0 compiler uses the freshly compiled `std`. - There are two concepts at play here: a compiler (with its set of dependencies) - and its 'target' or 'object' libraries (`std` and `rustc`). - Both are staged, but in a staggered manner. -- **Stage 1:** the code in your clone (for new version) is then - compiled with the stage0 compiler to produce the stage1 compiler. - However, it was built with an older compiler (stage0), so to - optimize the stage1 compiler we go to next the stage. - - In theory, the stage1 compiler is functionally identical to the - stage2 compiler, but in practice there are subtle differences. In - particular, the stage1 compiler itself was built by stage0 and - hence not by the source in your working directory: this means that - the symbol names used in the compiler source may not match the - symbol names that would have been made by the stage1 compiler. This is - important when using dynamic linking and the lack of ABI compatibility - between versions. This primarily manifests when tests try to link with any - of the `rustc_*` crates or use the (now deprecated) plugin infrastructure. - These tests are marked with `ignore-stage1`. -- **Stage 2:** we rebuild our stage1 compiler with itself to produce - the stage2 compiler (i.e. it builds itself) to have all the _latest - optimizations_. (By default, we copy the stage1 libraries for use by - the stage2 compiler, since they ought to be identical.) -- _(Optional)_ **Stage 3**: to sanity check our new compiler, we - can build the libraries with the stage2 compiler. The result ought - to be identical to before, unless something has broken. - -To read more about the bootstrap process, [read this chapter][bootstrap]. +To read more about the bootstrap process and why `x.py` is necessary, +[read this chapter][bootstrap]. [bootstrap]: ./bootstrapping.md