diff options
Diffstat (limited to '')
| -rw-r--r-- | src/doc/rustc-dev-guide/src/building/bootstrapping.md | 86 |
1 files changed, 47 insertions, 39 deletions
diff --git a/src/doc/rustc-dev-guide/src/building/bootstrapping.md b/src/doc/rustc-dev-guide/src/building/bootstrapping.md index 939c47f1b..3bacc21d3 100644 --- a/src/doc/rustc-dev-guide/src/building/bootstrapping.md +++ b/src/doc/rustc-dev-guide/src/building/bootstrapping.md @@ -54,7 +54,7 @@ and its associated dynamic libraries, which `x.py` will download for you. (You can also configure `x.py` to use something else.) -The stage0 compiler is then used only to compile `rustbuild`, `std`, and `rustc`. +The stage0 compiler is then used only to compile `src/bootstrap`, `std`, and `rustc`. When compiling `rustc`, the stage0 compiler uses the freshly compiled `std`. There are two concepts at play here: a compiler (with its set of dependencies) @@ -73,9 +73,12 @@ 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, -which can cause problems for dynamic libraries and tests. +This means that the ABI generated by the stage0 compiler may not match the ABI that would have been +made by the stage1 compiler, which can cause problems for dynamic libraries, tests, and tools using +`rustc_private`. + +Note that the `proc_macro` crate avoids this issue with a C FFI layer called `proc_macro::bridge`, +allowing it to be used with stage 1. The `stage2` compiler is the one distributed with `rustup` and all other install methods. However, it takes a very long time to build @@ -226,14 +229,6 @@ another program we are building with the stage N compiler: `build --stage N compiler/rustc` is linking the stage N artifacts to the `std` built by the stage N compiler. -Here is a chart of a full build using `x.py`: - -<img alt="A diagram of the rustc compilation phases" src="../img/rustc_stages.svg" class="center" /> - -Keep in mind this diagram is a simplification, i.e. `rustdoc` can be built at -different stages, the process is a bit different when passing flags such as -`--keep-stage`, or if there are non-host targets. - ### Stages and `std` Note that there are two `std` libraries in play here: @@ -365,7 +360,7 @@ This flag has the following effects: Code which does not use `-Z force-unstable-if-unmarked` should include the `#![feature(rustc_private)]` crate attribute to access these force-unstable -crates. This is needed for things that link `rustc`, such as `miri`, `rls`, or +crates. This is needed for things that link `rustc`, such as `miri` or `clippy`. You can find more discussion about sysroots in: @@ -375,9 +370,46 @@ You can find more discussion about sysroots in: [rustdoc PR]: https://github.com/rust-lang/rust/pull/76728 -### Directories and artifacts generated by `x.py` +## Passing flags to commands invoked by `bootstrap` + +`x.py` allows you to pass stage-specific flags to `rustc` and `cargo` when bootstrapping. +The `RUSTFLAGS_BOOTSTRAP` environment variable is passed as `RUSTFLAGS` to the bootstrap stage +(stage0), and `RUSTFLAGS_NOT_BOOTSTRAP` is passed when building artifacts for later stages. +`RUSTFLAGS` will work, but also affects the build of `bootstrap` itself, so it will be rare to want +to use it. +Finally, `MAGIC_EXTRA_RUSTFLAGS` bypasses the `cargo` cache to pass flags to rustc without +recompiling all dependencies. + +`RUSTDOCFLAGS`, `RUSTDOCFLAGS_BOOTSTRAP`, and `RUSTDOCFLAGS_NOT_BOOTSTRAP` are anologous to +`RUSTFLAGS`, but for rustdoc. + +`CARGOFLAGS` will pass arguments to cargo itself (e.g. `--timings`). `CARGOFLAGS_BOOTSTRAP` and +`CARGOFLAGS_NOT_BOOTSTRAP` work analogously to `RUSTFLAGS_BOOTSTRAP`. + +`--test-args` will pass arguments through to the test runner. For `src/test/ui`, this is +compiletest; for unit tests and doctests this is the `libtest` runner. Most test runner accept +`--help`, which you can use to find out the options accepted by the runner. -The following tables indicate the outputs of various stage actions: +## Environment Variables + +During bootstrapping, there are a bunch of compiler-internal environment +variables that are used. If you are trying to run an intermediate version of +`rustc`, sometimes you may need to set some of these environment variables +manually. Otherwise, you get an error like the following: + +```text +thread 'main' panicked at 'RUSTC_STAGE was not set: NotPresent', library/core/src/result.rs:1165:5 +``` + +If `./stageN/bin/rustc` gives an error about environment variables, that +usually means something is quite wrong -- or you're trying to compile e.g. +`rustc` or `std` or something that depends on environment variables. In +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 | |-----------------------------------------------------------|----------------------------------------------| @@ -416,27 +448,3 @@ The following tables indicate the outputs of various stage actions: | copy `rustdoc` | `build/HOST/stage2/bin` | `--stage=2` stops here. - -## Passing stage-specific flags to `rustc` - -`x.py` allows you to pass stage-specific flags to `rustc` when bootstrapping. -The `RUSTFLAGS_BOOTSTRAP` environment variable is passed as RUSTFLAGS to the bootstrap stage -(stage0), and `RUSTFLAGS_NOT_BOOTSTRAP` is passed when building artifacts for later stages. - -## Environment Variables - -During bootstrapping, there are a bunch of compiler-internal environment -variables that are used. If you are trying to run an intermediate version of -`rustc`, sometimes you may need to set some of these environment variables -manually. Otherwise, you get an error like the following: - -```text -thread 'main' panicked at 'RUSTC_STAGE was not set: NotPresent', library/core/src/result.rs:1165:5 -``` - -If `./stageN/bin/rustc` gives an error about environment variables, that -usually means something is quite wrong -- or you're trying to compile e.g. -`rustc` or `std` or something that depends on environment variables. In -the unlikely case that you actually need to invoke rustc in such a situation, -you can find the environment variable values by adding the following flag to -your `x.py` command: `--on-fail=print-env`. |