Skip to content

Commit 2d1e71a

Browse files
onur-ozkanonur-ozkan
authored
update bootstrap guide (#1583)
Signed-off-by: ozkanonur <[email protected]>
1 parent 5c65222 commit 2d1e71a

File tree

1 file changed

+11
-67
lines changed

1 file changed

+11
-67
lines changed

‎src/building/bootstrapping.md

+11-67
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22

33
<!-- toc -->
44

5-
65
[*Bootstrapping*][boot] is the process of using a compiler to compile itself.
76
More accurately, it means using an older compiler to compile a newer version
87
of the same compiler.
@@ -16,6 +15,11 @@ version.
1615
This is exactly how `x.py` works: it downloads the current beta release of
1716
rustc, then uses it to compile the new compiler.
1817

18+
Note that this documentation mostly covers user-facing information. See
19+
[bootstrap/README.md][bootstrap-internals] to read about bootstrap internals.
20+
21+
[bootstrap-internals]: https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md
22+
1923
## Stages of bootstrapping
2024

2125
Compiling `rustc` is done in stages. Here's a diagram, adapted from Joshua Nelson's
@@ -135,31 +139,6 @@ bootstrapping the compiler.
135139
[intrinsics]: ../appendix/glossary.md#intrinsic
136140
[ocaml-compiler]: https://github.com/rust-lang/rust/tree/ef75860a0a72f79f97216f8aaa5b388d98da6480/src/boot
137141

138-
## Contributing to bootstrap
139-
140-
When you use the bootstrap system, you'll call it through `x.py`.
141-
However, most of the code lives in `src/bootstrap`.
142-
`bootstrap` has a difficult problem: it is written in Rust, but yet it is run
143-
before the Rust compiler is built! To work around this, there are two
144-
components of bootstrap: the main one written in rust, and `bootstrap.py`.
145-
`bootstrap.py` is what gets run by `x.py`. It takes care of downloading the
146-
`stage0` compiler, which will then build the bootstrap binary written in
147-
Rust.
148-
149-
Because there are two separate codebases behind `x.py`, they need to
150-
be kept in sync. In particular, both `bootstrap.py` and the bootstrap binary
151-
parse `config.toml` and read the same command line arguments. `bootstrap.py`
152-
keeps these in sync by setting various environment variables, and the
153-
programs sometimes have to add arguments that are explicitly ignored, to be
154-
read by the other.
155-
156-
### Adding a setting to config.toml
157-
158-
This section is a work in progress. In the meantime, you can see an example
159-
contribution [here][bootstrap-build].
160-
161-
[bootstrap-build]: https://github.com/rust-lang/rust/pull/71994
162-
163142
## Understanding stages of bootstrap
164143

165144
### Overview
@@ -407,47 +386,12 @@ usually means something is quite wrong -- or you're trying to compile e.g.
407386
the unlikely case that you actually need to invoke rustc in such a situation,
408387
you can tell the bootstrap shim to print all env variables by adding `-vvv` to your `x.py` command.
409388

410-
## Directories and artifacts generated by `bootstrap`
411-
412-
This is an incomplete reference for the outputs generated by bootstrap:
413-
414-
| Stage 0 Action | Output |
415-
| ------------------------------------------------------------------ | -------------------------------------------- |
416-
| `beta` extracted | `build/HOST/stage0` |
417-
| `stage0` builds `bootstrap` | `build/bootstrap` |
418-
| `stage0` builds `test`/`std` | `build/HOST/stage0-std/TARGET` |
419-
| copy `stage0-std` (HOST only) | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
420-
| `stage0` builds `rustc` with `stage0-sysroot` | `build/HOST/stage0-rustc/HOST` |
421-
| copy `stage0-rustc` (except executable) | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
422-
| build `llvm` | `build/HOST/llvm` |
423-
| `stage0` builds `codegen` with `stage0-sysroot` | `build/HOST/stage0-codegen/HOST` |
424-
| `stage0` builds `rustdoc`, `clippy`, `miri`, with `stage0-sysroot` | `build/HOST/stage0-tools/HOST` |
425-
426-
`--stage=0` stops here.
427-
428-
| Stage 1 Action | Output |
429-
|-----------------------------------------------------|---------------------------------------|
430-
| copy (uplift) `stage0-rustc` executable to `stage1` | `build/HOST/stage1/bin` |
431-
| copy (uplift) `stage0-codegen` to `stage1` | `build/HOST/stage1/lib` |
432-
| copy (uplift) `stage0-sysroot` to `stage1` | `build/HOST/stage1/lib` |
433-
| `stage1` builds `test`/`std` | `build/HOST/stage1-std/TARGET` |
434-
| copy `stage1-std` (HOST only) | `build/HOST/stage1/lib/rustlib/HOST` |
435-
| `stage1` builds `rustc` | `build/HOST/stage1-rustc/HOST` |
436-
| copy `stage1-rustc` (except executable) | `build/HOST/stage1/lib/rustlib/HOST` |
437-
| `stage1` builds `codegen` | `build/HOST/stage1-codegen/HOST` |
438-
439-
`--stage=1` stops here.
440-
441-
| Stage 2 Action | Output |
442-
|--------------------------------------------------------|-----------------------------------------------------------------|
443-
| copy (uplift) `stage1-rustc` executable | `build/HOST/stage2/bin` |
444-
| copy (uplift) `stage1-sysroot` | `build/HOST/stage2/lib and build/HOST/stage2/lib/rustlib/HOST` |
445-
| `stage2` builds `test`/`std` (not HOST targets) | `build/HOST/stage2-std/TARGET` |
446-
| copy `stage2-std` (not HOST targets) | `build/HOST/stage2/lib/rustlib/TARGET` |
447-
| `stage2` builds `rustdoc`, `clippy`, `miri` | `build/HOST/stage2-tools/HOST` |
448-
| copy `rustdoc` | `build/HOST/stage2/bin` |
449-
450-
`--stage=2` stops here.
389+
Finally, bootstrap makes use of the [cc-rs crate] which has [its own
390+
method][env-vars] of configuring C compilers and C flags via environment
391+
variables.
392+
393+
[cc-rs crate]: https://github.com/rust-lang/cc-rs
394+
[env-vars]: https://github.com/rust-lang/cc-rs#external-configuration-via-environment-variables
451395

452396
## Clarification of build command's stdout
453397

0 commit comments

Comments
 (0)