Skip to content

Commit 0c3ec37

Browse files
committed
Steal eddyb's words to say why link-stage is useful
1 parent 13772e6 commit 0c3ec37

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
@@ -87,7 +87,17 @@ but `stageN-component` never has enough components to be usable (since it only h
8787
Copying these artifacts from `stage(N-1)-component` to `stageN`
8888
is called _uplifting_ the artifacts to `stageN`.
8989

90-
<!-- TODO: say _why_ build-stage exists and is separate. -->
90+
### Why have `link-stage` at all?
91+
92+
`stage0/bin/rustc` can't open an rlib from stage1-* or vice-versa.
93+
They are completely separate worlds, and `link-stage` reflects those worlds quite directly.
94+
Say you want to build a custom driver and you've run
95+
`rustup toolchain link build/*/stage1`: you have to run
96+
`x.py build --stage 1 src/librustc_driver` to have it available.
97+
The stage number corresponds to the "world" you have to be in to use it.
98+
If this used `run-stage` instead, you'd need `x.py build --stage 1` to build
99+
a regular program, but `x.py build --stage 2 src/librustc_driver` to build a
100+
custom driver.
91101

92102
## Complications of bootstrapping
93103

0 commit comments

Comments
 (0)