Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update bootstrap guide #1583

Merged
merged 2 commits into from
Feb 4, 2023
Merged

update bootstrap guide #1583

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
245039c
update bootstrap guide
onur-ozkan Feb 1, 2023
f32d1b6
Merge branch 'master' into update-bootstrap-related-docs
onur-ozkan Feb 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 11 additions & 67 deletions src/building/bootstrapping.md
View file
Open in desktop
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