Skip to content

Commit b7d930b

Browse files
committed
Steal eddyb's words to say why link-stage is useful
1 parent aef16f8 commit b7d930b

File tree

1 file changed

+11
-1
lines changed

1 file changed

+11
-1
lines changed

src/building/bootstrapping.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,17 @@ but `stageN-component` never has enough components to be usable (since it only h
5757
Copying these artifacts from `stage(N-1)-component` to `stageN`
5858
is called _uplifting_ the artifacts to `stageN`.
5959

60-
<!-- TODO: say _why_ build-stage exists and is separate. -->
60+
### Why have `link-stage` at all?
61+
62+
`stage0/bin/rustc` can't open an rlib from stage1-* or vice-versa.
63+
They are completely separate worlds, and `link-stage` reflects those worlds quite directly.
64+
Say you want to build a custom driver and you've run
65+
`rustup toolchain link build/*/stage1`: you have to run
66+
`x.py build --stage 1 src/librustc_driver` to have it available.
67+
The stage number corresponds to the "world" you have to be in to use it.
68+
If this used `run-stage` instead, you'd need `x.py build --stage 1` to build
69+
a regular program, but `x.py build --stage 2 src/librustc_driver` to build a
70+
custom driver.
6171

6272
## Complications of bootstrapping
6373

0 commit comments

Comments
 (0)