mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rewrite the section on passing flags to subcommands 

- Move the reference for directories and actions to the very end; it's the most rare to need to know
- Add `RUSTDOCFLAGS*`, `CARGOFLAGS*`, `-vvv`, and `--test-args`
- Remove the incorrect `--on-fail` command
This commit is contained in:
Joshua Nelson 2022-09-10 11:25:17 -05:00 committed by Joshua Nelson
parent c3232c4541
commit 6b3a5fb9d7
1 changed files with 39 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
src/building/bootstrapping.md
View File

@ -370,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`
The following tables indicate the outputs of various stage actions:
`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 anologously 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.
## 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 |
|-----------------------------------------------------------|----------------------------------------------|
@ -411,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`.