From 9d1e802ea5f54d79da352a0df1c1526541f0a8a0 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 7 Oct 2025 11:00:30 +0200 Subject: [PATCH 1/2] how-to-build-and-run.md: fix some text regarding bootstraping --- src/building/how-to-build-and-run.md | 29 +++++++++++++--------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 2e5f0e43d..bfef4059c 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -224,37 +224,33 @@ You may want to have upwards of 10 or 15 gigabytes available to build the compil Once you've created a `bootstrap.toml`, you are now ready to run `x`. There are a lot of options here, but let's start with what is -probably the best "go to" command for building a local compiler: +probably the best "go to" command: ```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 the following: +- Build in-tree rustc using stage0[^stage0] rustc and std, producing stage1 rustc. +- Build in-tree std using that (stage1) rustc, producing stage std. -To build `rustc` with the in-tree `std`, use this command instead: +This final product, stage1 rustc + std, +is what you need to build other Rust programs +(unless you use `#![no_std]` or `#![no_core]`). + +If your changes are only to rustc, you would save build time by using this hack: ```console -./x build rustc --stage 2 +./x build library --keep-stage-std 1 ``` -This final product (stage1 compiler + libs built using that compiler) -is what you need to build other Rust programs (unless you use `#![no_std]` or -`#![no_core]`). - -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 - Sometimes you don't need a full build. When doing some kind of "type-based refactoring", like renaming a method, or changing the signature of some function, you can use `./x check` instead for a much faster build. Note that this whole command just gives you a subset of the full `rustc` build. The **full** `rustc` build (what you get with `./x build ---stage 2 rustc`) has quite a few more steps: +--stage 2 compiler`) has quite a few more steps: - Build `rustc` with the stage1 compiler. - The resulting compiler here is called the "stage2" compiler, which uses stage1 std from the previous command. @@ -416,3 +412,4 @@ for each user, but this also applies to local development as well. Occasionally, are installed with `rustup toolchain list`. [^1]: issue[#1707](https://github.com/rust-lang/rustc-dev-guide/issues/1707) +[^stage0]: _stage0_ means something already built, typically downloaded From a7411babe1c55a5e7f755e481496817fc0da7c5f Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Thu, 9 Oct 2025 00:12:38 +0200 Subject: [PATCH 2/2] be more direct Co-authored-by: Amanjeev Sethi --- src/building/how-to-build-and-run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index bfef4059c..a86ca49b7 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -230,7 +230,7 @@ probably the best "go to" command: ./x build library ``` -What this command does is the following: +This command does the following: - Build in-tree rustc using stage0[^stage0] rustc and std, producing stage1 rustc. - Build in-tree std using that (stage1) rustc, producing stage std.