From b63bbaf0194311f407050f9e673a4ca407d0228e Mon Sep 17 00:00:00 2001 From: Zalathar Date: Sun, 12 Oct 2025 16:57:17 +1100 Subject: [PATCH 1/3] Building a fully-functional compiler requires `x build library` --- src/building/how-to-build-and-run.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 2e5f0e43d..5ee12f1b7 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -227,15 +227,18 @@ Once you've created a `bootstrap.toml`, you are now ready to run probably the best "go to" command for building a local compiler: ```console -./x build rustc +./x build library ``` -What this command does is build `rustc` using the stage0 compiler and stage0 `std`. +What this command does is: +- Build `rustc` using the stage0 compiler and stage0 `std`. +- Build `library` (the standard libraries) with the stage1 compiler that was just built. +- Assemble a working stage1 sysroot, containing the stage1 compiler and stage1 standard libraries. To build `rustc` with the in-tree `std`, use this command instead: ```console -./x build rustc --stage 2 +./x build library --stage 2 ``` This final product (stage1 compiler + libs built using that compiler) From 259e207b58fd7dd39e2f8103f4fb1b0c3c623dff Mon Sep 17 00:00:00 2001 From: Zalathar Date: Sun, 12 Oct 2025 17:10:48 +1100 Subject: [PATCH 2/3] Restore section "Faster builds with `--keep-stage`" as-is --- src/building/suggested.md | 40 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/building/suggested.md b/src/building/suggested.md index 35c7e935b..ea917ac98 100644 --- a/src/building/suggested.md +++ b/src/building/suggested.md @@ -306,6 +306,46 @@ steps, meaning it will have two precompiled compilers: stage0 compiler and `down for `stage > 0` steps. This way, it will never need to build the in-tree compiler. As a result, your build time will be significantly reduced by not building the in-tree compiler. +## Faster builds with `--keep-stage`. + +Sometimes just checking whether the compiler builds is not enough. A common +example is that you need to add a `debug!` statement to inspect the value of +some state or better understand the problem. In that case, you don't really need +a full build. By bypassing bootstrap's cache invalidation, you can often get +these builds to complete very fast (e.g., around 30 seconds). The only catch is +this requires a bit of fudging and may produce compilers that don't work (but +that is easily detected and fixed). + +The sequence of commands you want is as follows: + +- Initial build: `./x build library` + - As [documented previously], this will build a functional stage1 compiler as + part of running all stage0 commands (which include building a `std` + compatible with the stage1 compiler) as well as the first few steps of the + "stage 1 actions" up to "stage1 (sysroot stage1) builds std". +- Subsequent builds: `./x build library --keep-stage 1` + - Note that we added the `--keep-stage 1` flag here + +[documented previously]: ./how-to-build-and-run.md#building-the-compiler + +As mentioned, the effect of `--keep-stage 1` is that we just _assume_ that the +old standard library can be re-used. If you are editing the compiler, this is +almost always true: you haven't changed the standard library, after all. But +sometimes, it's not true: for example, if you are editing the "metadata" part of +the compiler, which controls how the compiler encodes types and other states +into the `rlib` files, or if you are editing things that wind up in the metadata +(such as the definition of the MIR). + +**The TL;DR is that you might get weird behavior from a compile when using +`--keep-stage 1`** -- for example, strange [ICEs](../appendix/glossary.html#ice) +or other panics. In that case, you should simply remove the `--keep-stage 1` +from the command and rebuild. That ought to fix the problem. + +You can also use `--keep-stage 1` when running tests. Something like this: + +- Initial test run: `./x test tests/ui` +- Subsequent test run: `./x test tests/ui --keep-stage 1` + ## Using incremental compilation You can further enable the `--incremental` flag to save additional time in From c7f1fe6107b52982c31eebf6d2a1c5ceed9a0c8b Mon Sep 17 00:00:00 2001 From: Zalathar Date: Sun, 12 Oct 2025 17:05:04 +1100 Subject: [PATCH 3/3] Prefer `--keep-stage-std` for compiler rebuilds --- src/building/how-to-build-and-run.md | 2 +- src/building/suggested.md | 24 +++++++++--------------- 2 files changed, 10 insertions(+), 16 deletions(-) diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 5ee12f1b7..ace834a55 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -249,7 +249,7 @@ You will probably find that building the stage1 `std` is a bottleneck for you, but fear not, there is a (hacky) workaround... see [the section on avoiding rebuilds for std][keep-stage]. -[keep-stage]: ./suggested.md#faster-builds-with---keep-stage +[keep-stage]: ./suggested.md#faster-rebuilds-with---keep-stage-std Sometimes you don't need a full build. When doing some kind of "type-based refactoring", like renaming a method, or changing the diff --git a/src/building/suggested.md b/src/building/suggested.md index ea917ac98..6d3590eef 100644 --- a/src/building/suggested.md +++ b/src/building/suggested.md @@ -306,7 +306,7 @@ steps, meaning it will have two precompiled compilers: stage0 compiler and `down for `stage > 0` steps. This way, it will never need to build the in-tree compiler. As a result, your build time will be significantly reduced by not building the in-tree compiler. -## Faster builds with `--keep-stage`. +## Faster rebuilds with `--keep-stage-std` Sometimes just checking whether the compiler builds is not enough. A common example is that you need to add a `debug!` statement to inspect the value of @@ -319,32 +319,26 @@ that is easily detected and fixed). The sequence of commands you want is as follows: - Initial build: `./x build library` - - As [documented previously], this will build a functional stage1 compiler as - part of running all stage0 commands (which include building a `std` - compatible with the stage1 compiler) as well as the first few steps of the - "stage 1 actions" up to "stage1 (sysroot stage1) builds std". -- Subsequent builds: `./x build library --keep-stage 1` - - Note that we added the `--keep-stage 1` flag here +- Subsequent builds: `./x build library --keep-stage-std=1` + - Note that we added the `--keep-stage-std=1` flag here -[documented previously]: ./how-to-build-and-run.md#building-the-compiler - -As mentioned, the effect of `--keep-stage 1` is that we just _assume_ that the +As mentioned, the effect of `--keep-stage-std=1` is that we just _assume_ that the old standard library can be re-used. If you are editing the compiler, this is -almost always true: you haven't changed the standard library, after all. But +often true: you haven't changed the standard library, after all. But sometimes, it's not true: for example, if you are editing the "metadata" part of the compiler, which controls how the compiler encodes types and other states into the `rlib` files, or if you are editing things that wind up in the metadata (such as the definition of the MIR). **The TL;DR is that you might get weird behavior from a compile when using -`--keep-stage 1`** -- for example, strange [ICEs](../appendix/glossary.html#ice) -or other panics. In that case, you should simply remove the `--keep-stage 1` +`--keep-stage-std=1`** -- for example, strange [ICEs](../appendix/glossary.html#ice) +or other panics. In that case, you should simply remove the `--keep-stage-std=1` from the command and rebuild. That ought to fix the problem. -You can also use `--keep-stage 1` when running tests. Something like this: +You can also use `--keep-stage-std=1` when running tests. Something like this: - Initial test run: `./x test tests/ui` -- Subsequent test run: `./x test tests/ui --keep-stage 1` +- Subsequent test run: `./x test tests/ui --keep-stage-std=1` ## Using incremental compilation