Skip to content

Commit c0bd637

Browse files
committed
Use _both_ models for stages
1 parent fb88941 commit c0bd637

File tree

2 files changed

+32
-0
lines changed

2 files changed

+32
-0
lines changed

src/building/bootstrapping.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,38 @@ first build the new compiler with an older compiler and then use that to
5757
build the new compiler with itself. For development, you usually only want
5858
the `stage1` compiler: `x.py build library/std`.
5959

60+
## Where do stages start and end?
61+
62+
A common question is what exactly happens when you run `x.py build` or `x.py test`.
63+
Does `--stage 1` mean to _build_ the stage 1 artifacts or to _run_ them?
64+
In fact, it means both!
65+
66+
<!-- TODO: label each of the cells with the name of the directory in `build` it corresponds to -->
67+
68+
![stages](./stages.png)
69+
70+
So, for example, when you run `x.py test [--stage 1]`,
71+
that means to build the compiler in row 1 and column 0, then run it on the testsuite.
72+
This corresponds to the `run-stage` diagram.
73+
However, when you run `x.py build [--stage 1]`, that means to build the compiler in
74+
row 2 and column 1. This corresponds to the `link-stage` diagram.
75+
Building any of the items in the diagram also requires first building all items with arrows pointing to it.
76+
77+
### What are `run-stage` and `link-stage`?
78+
79+
`run-stage` means that this deals with _running_ the compiler,
80+
so `--stage N` refers to the artifacts in `build/stageN`.
81+
82+
`link-stage` means that this deals with _building_ the compiler,
83+
and it refers to `build/stageN-component`.
84+
85+
`build/stageN` is suitable for use with `rustup toolchain link`,
86+
but `stageN-component` never has enough components to be usable (since it only has one).
87+
Copying these artifacts from `stage(N-1)-component` to `stageN`
88+
is called _uplifting_ the artifacts to `stageN`.
89+
90+
<!-- TODO: say _why_ build-stage exists and is separate. -->
91+
6092
## Complications of bootstrapping
6193

6294
Since the build system uses the current beta compiler to build the stage-1

src/building/stages.png

91.9 KB
Loading

0 commit comments

Comments
 (0)