numbering.txt

Currently the behavior is as follows (where stageN <-> stage(N-1) artifacts, except for stage0 libstd):

- `x.py build --stage 0`:
  - stage0 libstd
  - stage0 rustc (but without putting rustc in stage1/)

This leaves you without any rustc at all except for the beta compiler
(https://github.com/rust-lang/rust/issues/73519). This is never what you want (currently you should use either `x.py check` or `x.py build --stage 0 src/libstd` instead).

- `x.py build --stage 1`:
  - stage0 libstd
  - stage0 rustc
  - stage1 libstd
  - stage1 rustc
  - stage1 rustdoc

This leaves you with a stage1 rustc which doesn't even have
libcore and is effectively useless. Additionally, it compiles rustc
twice, which is not normally what you want.

- `x.py build --stage 2`:
  - stage0 libstd
  - stage0 rustc
  - stage1 libstd
  - stage1 rustc
  - stage2 libstd
  - stage2 rustc
  - stage2 rustdoc

This builds the whole source tree in release mode. This is the correct usage for CI,
but takes far too long for development.

The proposed new behavior is as follows:

- `x.py build --stage 0`:
  - stage0 libstd

This is suitable for contributors only working on the standard library,
as it means rustc never has to be compiled.

- `x.py build --stage 1`:
  - stage0 libstd
  - stage0 rustc
  - stage1 libstd
  - stage1 rustdoc

This is suitable for contributors working on the compiler. It ensures
that you have a working rustc and libstd without having to pass
`src/libstd` in addition.

- `x.py build --stage 2`:
  - stage0 libstd
  - stage0 rustc
  - stage1 libstd
  - stage1 rustc
  - stage2 libstd
  - stage2 rustdoc

This is suitable for debugging failures which only occur the second time rustc is built.

CI wants even more than this: `x.py build --stage 2` + stage2 rustc. There will be a new option added to meet this use case: `x.py build src/rustc`.

To get the previous behavior of `x.py build --stage 1`, use `x.py build --stage 2 src/libstd`, which also builds a working libstd, but does not build the release tools. `--stage 2` works the same, and `--stage 0` was broken anyway.