update bootstrap guide (#1583)
Signed-off-by: ozkanonur <work@onurozkan.dev>
This commit is contained in:
Onur
GitHub
parent
69ef8a3924
commit
347b3633f1
|
|
@ -2,7 +2,6 @@
|
||||||
|
|
||||||
<!-- toc -->
|
<!-- toc -->
|
||||||
|
|
||||||
|
|
||||||
[*Bootstrapping*][boot] is the process of using a compiler to compile itself.
|
[*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
|
More accurately, it means using an older compiler to compile a newer version
|
||||||
of the same compiler.
|
of the same compiler.
|
||||||
|
|
@ -16,6 +15,11 @@ version.
|
||||||
This is exactly how `x.py` works: it downloads the current beta release of
|
This is exactly how `x.py` works: it downloads the current beta release of
|
||||||
rustc, then uses it to compile the new compiler.
|
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.
|
||||||
|
|
||||||
|
[bootstrap-internals]: https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md
|
||||||
|
|
||||||
## Stages of bootstrapping
|
## Stages of bootstrapping
|
||||||
|
|
||||||
Compiling `rustc` is done in stages. Here's a diagram, adapted from Joshua Nelson's
|
Compiling `rustc` is done in stages. Here's a diagram, adapted from Joshua Nelson's
|
||||||
|
|
@ -135,31 +139,6 @@ bootstrapping the compiler.
|
||||||
[intrinsics]: ../appendix/glossary.md#intrinsic
|
[intrinsics]: ../appendix/glossary.md#intrinsic
|
||||||
[ocaml-compiler]: https://github.com/rust-lang/rust/tree/ef75860a0a72f79f97216f8aaa5b388d98da6480/src/boot
|
[ocaml-compiler]: https://github.com/rust-lang/rust/tree/ef75860a0a72f79f97216f8aaa5b388d98da6480/src/boot
|
||||||
|
|
||||||
## Contributing to bootstrap
|
|
||||||
|
|
||||||
When you use the bootstrap system, you'll call it through `x.py`.
|
|
||||||
However, most of the code lives in `src/bootstrap`.
|
|
||||||
`bootstrap` has a difficult problem: it is written in Rust, but yet it is run
|
|
||||||
before the Rust compiler is built! To work around this, there are two
|
|
||||||
components of bootstrap: the main one written in rust, and `bootstrap.py`.
|
|
||||||
`bootstrap.py` is what gets run by `x.py`. It takes care of downloading the
|
|
||||||
`stage0` compiler, which will then build the bootstrap binary written in
|
|
||||||
Rust.
|
|
||||||
|
|
||||||
Because there are two separate codebases behind `x.py`, they need to
|
|
||||||
be kept in sync. In particular, both `bootstrap.py` and the bootstrap binary
|
|
||||||
parse `config.toml` and read the same command line arguments. `bootstrap.py`
|
|
||||||
keeps these in sync by setting various environment variables, and the
|
|
||||||
programs sometimes have to add arguments that are explicitly ignored, to be
|
|
||||||
read by the other.
|
|
||||||
|
|
||||||
### Adding a setting to config.toml
|
|
||||||
|
|
||||||
This section is a work in progress. In the meantime, you can see an example
|
|
||||||
contribution [here][bootstrap-build].
|
|
||||||
|
|
||||||
[bootstrap-build]: https://github.com/rust-lang/rust/pull/71994
|
|
||||||
|
|
||||||
## Understanding stages of bootstrap
|
## Understanding stages of bootstrap
|
||||||
|
|
||||||
### Overview
|
### Overview
|
||||||
|
|
@ -407,47 +386,12 @@ usually means something is quite wrong -- or you're trying to compile e.g.
|
||||||
the unlikely case that you actually need to invoke rustc in such a situation,
|
the unlikely case that you actually need to invoke rustc in such a situation,
|
||||||
you can tell the bootstrap shim to print all env variables by adding `-vvv` to your `x.py` command.
|
you can tell the bootstrap shim to print all env variables by adding `-vvv` to your `x.py` command.
|
||||||
|
|
||||||
## Directories and artifacts generated by `bootstrap`
|
Finally, bootstrap makes use of the [cc-rs crate] which has [its own
|
||||||
|
method][env-vars] of configuring C compilers and C flags via environment
|
||||||
|
variables.
|
||||||
|
|
||||||
This is an incomplete reference for the outputs generated by bootstrap:
|
[cc-rs crate]: https://github.com/rust-lang/cc-rs
|
||||||
|
[env-vars]: https://github.com/rust-lang/cc-rs#external-configuration-via-environment-variables
|
||||||
| Stage 0 Action | Output |
|
|
||||||
| ------------------------------------------------------------------ | -------------------------------------------- |
|
|
||||||
| `beta` extracted | `build/HOST/stage0` |
|
|
||||||
| `stage0` builds `bootstrap` | `build/bootstrap` |
|
|
||||||
| `stage0` builds `test`/`std` | `build/HOST/stage0-std/TARGET` |
|
|
||||||
| copy `stage0-std` (HOST only) | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
|
|
||||||
| `stage0` builds `rustc` with `stage0-sysroot` | `build/HOST/stage0-rustc/HOST` |
|
|
||||||
| copy `stage0-rustc` (except executable) | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
|
|
||||||
| build `llvm` | `build/HOST/llvm` |
|
|
||||||
| `stage0` builds `codegen` with `stage0-sysroot` | `build/HOST/stage0-codegen/HOST` |
|
|
||||||
| `stage0` builds `rustdoc`, `clippy`, `miri`, with `stage0-sysroot` | `build/HOST/stage0-tools/HOST` |
|
|
||||||
|
|
||||||
`--stage=0` stops here.
|
|
||||||
|
|
||||||
| Stage 1 Action | Output |
|
|
||||||
|-----------------------------------------------------|---------------------------------------|
|
|
||||||
| copy (uplift) `stage0-rustc` executable to `stage1` | `build/HOST/stage1/bin` |
|
|
||||||
| copy (uplift) `stage0-codegen` to `stage1` | `build/HOST/stage1/lib` |
|
|
||||||
| copy (uplift) `stage0-sysroot` to `stage1` | `build/HOST/stage1/lib` |
|
|
||||||
| `stage1` builds `test`/`std` | `build/HOST/stage1-std/TARGET` |
|
|
||||||
| copy `stage1-std` (HOST only) | `build/HOST/stage1/lib/rustlib/HOST` |
|
|
||||||
| `stage1` builds `rustc` | `build/HOST/stage1-rustc/HOST` |
|
|
||||||
| copy `stage1-rustc` (except executable) | `build/HOST/stage1/lib/rustlib/HOST` |
|
|
||||||
| `stage1` builds `codegen` | `build/HOST/stage1-codegen/HOST` |
|
|
||||||
|
|
||||||
`--stage=1` stops here.
|
|
||||||
|
|
||||||
| Stage 2 Action | Output |
|
|
||||||
|--------------------------------------------------------|-----------------------------------------------------------------|
|
|
||||||
| copy (uplift) `stage1-rustc` executable | `build/HOST/stage2/bin` |
|
|
||||||
| copy (uplift) `stage1-sysroot` | `build/HOST/stage2/lib and build/HOST/stage2/lib/rustlib/HOST` |
|
|
||||||
| `stage2` builds `test`/`std` (not HOST targets) | `build/HOST/stage2-std/TARGET` |
|
|
||||||
| copy `stage2-std` (not HOST targets) | `build/HOST/stage2/lib/rustlib/TARGET` |
|
|
||||||
| `stage2` builds `rustdoc`, `clippy`, `miri` | `build/HOST/stage2-tools/HOST` |
|
|
||||||
| copy `rustdoc` | `build/HOST/stage2/bin` |
|
|
||||||
|
|
||||||
`--stage=2` stops here.
|
|
||||||
|
|
||||||
## Clarification of build command's stdout
|
## Clarification of build command's stdout
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue