Home • Explore • Blog • CI
☰



rustc
6th chunk of `src/building/bootstrapping/what-bootstrapping-does.md`
45547fa90e194000d9bc696056e4202716d3f4d1aa03f2a000000001000009a7
crates. This is needed for things which link `rustc` its self, such as `MIRI` or
`clippy`.

You can find more discussion about sysroots in:
- The [rustdoc PR] explaining why it uses `extern crate` for dependencies loaded
  from `sysroot`
- [Discussions about sysroot on
  Zulip](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/deps.20in.20sysroot/)
- [Discussions about building rustdoc out of
  tree](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/How.20to.20create.20an.20executable.20accessing.20.60rustc_private.60.3F)


## Passing flags to commands invoked by `bootstrap`

Conveniently `./x` 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
  analogous 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 `tests/ui`,
  this is `compiletest`. For unit tests and doc tests this is the `libtest`
  runner.

Most test runners 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 -- such as you're trying to compile `rustc` or
`std` or something which depends on environment variables. In the unlikely case
that you actually need to invoke `rustc` in such a situation, you can tell the
Title: Passing Flags to Bootstrap and Environment Variables
Summary
The `./x` tool allows passing stage-specific flags to `rustc` and `cargo` during bootstrapping using environment variables like `RUSTFLAGS_BOOTSTRAP` (for stage0) and `RUSTFLAGS_NOT_BOOTSTRAP` (for later stages). `MAGIC_EXTRA_RUSTFLAGS` bypasses the cargo cache. Analogous variables exist for `rustdoc` and `cargo` itself. `--test-args` passes arguments to the test runner. During bootstrapping, compiler-internal environment variables are used, and you may need to set them manually when running intermediate versions of `rustc`. Errors about missing environment variables usually indicate an issue, like trying to compile `rustc` or `std` directly.