Skip to content

Commit

Permalink
update bootstrap guide (#1583)
Browse files Browse the repository at this point in the history 
Signed-off-by: ozkanonur <[email protected]>
  • Loading branch information
@onur-ozkan
onur-ozkan authored Feb 4, 2023
1 parent 5c65222 commit 2d1e71a
Showing 1 changed file with 11 additions and 67 deletions.
78 changes: 11 additions & 67 deletions src/building/bootstrapping.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

<!-- 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.
Expand All @@ -16,6 +15,11 @@ 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.

[bootstrap-internals]: https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md

## Stages of bootstrapping

Compiling `rustc` is done in stages. Here's a diagram, adapted from Joshua Nelson's
Expand Down Expand Up @@ -135,31 +139,6 @@ bootstrapping the compiler.
[intrinsics]: ../appendix/glossary.md#intrinsic
[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

### Overview
Expand Down Expand Up @@ -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,
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`

This is an incomplete reference for the outputs generated by bootstrap:

| 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.
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.

[cc-rs crate]: https://github.com/rust-lang/cc-rs
[env-vars]: https://github.com/rust-lang/cc-rs#external-configuration-via-environment-variables

## Clarification of build command's stdout

Expand Down

0 comments on commit 2d1e71a

Please sign in to comment.