[WIP] Fix and clean up the terminology for stages

[jyn514]

• Name rustbuild instead of saying 'the bootstrap binary'
• Use 'stage0 rustc' and 'stage0 compiler' to mean stage0-rustc
• Use 'bootstrap' to mean build/$target/stage0 (i.e. the beta compiler)
• Mention that 'ignore-stage1' means 'ignore programs linked to stage1',
  not built by it.

r? @eddyb

[eddyb]

Name rustbuild instead of saying 'the bootstrap binary'

sigh We should rename src/bootstrap, I remember discussing it with @Mark-Simulacrum but I forget what we thought might work well.

Use 'stage0 rustc' and 'stage0 compiler' to mean stage0-rustc

I think "stageN rustc", and even more so "stageN compiler" is ambiguous and ideally we would never use it in documentation. It could mean one of two things:

• stageN/bin/rustc input i.e. "compiler used to compile stageN-*"
• stageN-rustc output i.e. "compiler built at stage N"

Use 'bootstrap' to mean build/$target/stage0 (i.e. the beta compiler)

This probably is fine, i.e. referring to "bootstrap compiler" and explaining it's one of these:

• latest beta for building nightly
• latest stable for building beta
• previous stable for building stable

Mention that 'ignore-stage1' means 'ignore programs linked to stage1', not built by it.

Isn't it simpler to say "tests ran at stage 1" , meaning as part of x.py test --stage 1?

---

We never use "built by stage N" to mean "compiled by stageN-rustc/release/rustc (aka stageN+1/bin/rustc)" and I'd much rather prefer disambiguating than jumping from one side of an ambiguity to the other (in this case, to the side that's even less commonly used/understood).

[jyn514]

sigh We should rename src/bootstrap, I remember discussing it with @Mark-Simulacrum but I forget what we thought might work well.

FWIW it's called rustbuild on the tags for rust-lang/rust: https://github.com/rust-lang/rust/labels/A-rustbuild

I think "stageN rustc", and even more so "stageN compiler" is ambiguous and ideally we would never use it in documentation. It could mean one of two things:

What could I say instead? I need to refer to 'the rustc that's part of stageN' somehow :/

Isn't it simpler to say "tests ran at stage 1" , meaning as part of x.py test --stage 1?

Good idea, I'll add that since it gives an easy shorthand. I think the point about linking is helpful for understanding it though.

We never use "built by stage N" to mean "compiled by stageN-rustc/release/rustc (aka stageN+1/bin/rustc)" and I'd much rather prefer disambiguating than jumping from one side of an ambiguity to the other (in this case, to the side that's even less commonly used/understood).

Whoops, I thought I said 'stage N compiler' everywhere but it turns out I just said 'stage N' in the stage 1 section. I'll change it.

What would you consider disambiguating? I'm all for making things more clear but I'm not sure how to do that here.

[Mark-Simulacrum]

This is .. well, not quite true. stage0/bin/rustc is the bootstrap compiler. Really, we should rename it, but "to what?" then the question is.

[ehuss]

fwiw, I feel like this doesn't seem correct. I call the stage0 compiler the beta compiler which appears in the stage0 directory which is used during stage0. It creates artifacts in the stage0-* directories, which during stage1 uses Assemble to create the stage1 compiler. There's a phrase in the bootstrapping guide (which I may have written) which I think sums it up succinctly:

Stage 0 uses the stage0 compiler to create stage0 artifacts which will later be uplifted to stage1.

It seems to me a lot of confusion stems from the --stage command-line flag, and that the terminology for "the stage" and "the compiler used in the stage" and "the compiler created by the stage" are all sort of the same. Another problem I think is that a stage's output is written to directories with the same stage, but not actually used from there (they get copied out into stageN+1), so it straddles the boundary. Also, people have different preconceived notions, and the numbering often seems off-by-one (rust-lang/rust#57963 and rust-lang/rust#59864). But just changing that in the documentation I think will make things worse.

[jyn514]

Ok, it's clear that this hurts more than it helps. How about the following scheme?

• Rename build/stageN to build/stageN-toolchain, by analogy to rustup toolchain link. Any other directory won't work with rustup (this is already the case).
• Describe build --stage N as 'building a component to put in stageN-toolchain'. This works for libstd, tools, etc - it only breaks for rustc (because it will go in stage(N+1)-toolchain). It even works with the current numbering for rustdoc because x.py build --stage N rustdoc will put rustdoc in build/stageN/bin.

I'm not sure how we should describe build --stage N src/rustc, which builds it for the next toolchain. I'm open to suggestions on that front.

[jyn514]

Name rustbuild instead of saying 'the bootstrap binary'

I'm going to make a separate PR for this since I expect it to be uncontroversial.

[mark-i-m]

Ok, we discussed this extensively in today's meeting, and I think I'm now more on board with renaming the stages...

We also created this graphic: diagram.pdf

[jyn514]

Note that what we discussed was moving build from the 'columns' in the diagram to the 'rows', not what I have in this PR, which essentially goes from stageN to stageN - 1.

[mark-i-m]

Ah, I didn't read carefully.

[jyn514]

Closing this since it doesn't reflect the changes I want to make. Hopefully someone gets a chance to make a PR for #807 (comment) soon :)