'target' or 'object' libraries (`std` and `rustc`). Both are staged, but in a staggered manner.


### Stage 1: from current code, by an earlier compiler

The rustc source code is then compiled with the `stage0` compiler to produce the
`stage1` compiler.

### Stage 2: the truly current compiler

We then rebuild the compiler using `stage1` compiler with in-tree std to produce the `stage2`
compiler.

The `stage1` compiler itself was built by precompiled `stage0` compiler and std
and hence not by the source in your working directory. 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 `stage1`.

The `stage2` compiler is the one distributed with `rustup` and all other install
methods. However, it takes a very long time to build because one must first
build the new compiler with an older compiler and then use that to build the new
compiler with itself.

For development, you usually only want to use `--stage 1` flag to build things.
See [Building the compiler](../how-to-build-and-run.html#building-the-compiler).

### Stage 3: the same-result test

Stage 3 is optional. To sanity check our new compiler we can build the libraries
with the `stage2` compiler. The result ought to be identical to before, unless
something has broken.

### Building the stages

The script [`./x`] tries to be helpful and pick the stage you most likely meant
for each subcommand. Here are some `x` commands with their default stages:

- `check`: `--stage 1`
- `clippy`: `--stage 1`
- `doc`: `--stage 1`
- `build`: `--stage 1`
- `test`: `--stage 1`
- `dist`: `--stage 2`
- `install`: `--stage 2`
- `bench`: `--stage 2`

You can always override the stage by passing `--stage N` explicitly.

For more information about stages, [see
below](#understanding-stages-of-bootstrap).


## Complications of bootstrapping

Since the build system uses the current beta compiler to build a `stage1`
bootstrapping compiler, the compiler source code can't use some features until
they reach beta (because otherwise the beta compiler doesn't support them). On
the other hand, for [compiler intrinsics][intrinsics] and internal features, the
features _have_ to be used. Additionally, the compiler makes heavy use of
`nightly` features (`#![feature(...)]`). How can we resolve this problem?

There are two methods used:

1. The build system sets `--cfg bootstrap` when building with `stage0`, so we
   can use `cfg(not(bootstrap))` to only use features when built with `stage1`.
   Setting `--cfg bootstrap` in this way is used for features that were just
   stabilized, which require `#![feature(...)]` when built with `stage0`, but
   not for `stage1`.
2. The build system sets `RUSTC_BOOTSTRAP=1`. This special variable means to
   _break the stability guarantees_ of Rust: allowing use of `#![feature(...)]`
   with a compiler that's not `nightly`. _Setting `RUSTC_BOOTSTRAP=1` should
   never be used except when bootstrapping the compiler._


## Understanding stages of bootstrap

### Overview

This is a detailed look into the separate bootstrap stages.

The convention `./x` uses is that:

- A `--stage N` flag means to run the stage N compiler (`stageN/rustc`).
- A "stage N artifact" is a build artifact that is _produced_ by the stage N
  compiler.
- The stage N+1 compiler is assembled from stage N *artifacts*. This process is
  called _uplifting_.

#### Build artifacts

Anything you can build with `./x` is a _build artifact_. Build artifacts
include, but are not limited to:

- binaries, like `stage0-rustc/rustc-main`
- shared objects, like `stage0-sysroot/rustlib/libstd-6fae108520cf72fe.so`
- [rlib] files, like `stage0-sysroot/rustlib/libstd-6fae108520cf72fe.rlib`
- HTML files generated by rustdoc, like `doc/std`