From 2a0600e32037f452b9433f79c2c4af3dda29b362 Mon Sep 17 00:00:00 2001 From: Urgau Date: Mon, 6 Oct 2025 19:20:23 +0200 Subject: [PATCH 01/10] Update to new `S-waiting-on-compiler` and `I-compiler-nominated` labels --- src/doc/rustc-dev-guide/src/compiler-team.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/rustc-dev-guide/src/compiler-team.md b/src/doc/rustc-dev-guide/src/compiler-team.md index 8c0481f6ea8f5..79dfbdc8265fc 100644 --- a/src/doc/rustc-dev-guide/src/compiler-team.md +++ b/src/doc/rustc-dev-guide/src/compiler-team.md @@ -54,8 +54,8 @@ They are held on [Zulip][zulip-meetings]. It works roughly as follows: those that are sufficiently important for us to actively track progress. P-critical and P-high bugs should ideally always have an assignee. -- **Check S-waiting-on-team and I-nominated issues:** These are issues where feedback from - the team is desired. +- **Check `S-waiting-on-compiler` and `I-compiler-nominated` issues:** These are issues where + feedback from the team is desired. - **Look over the performance triage report:** We check for PRs that made the performance worse and try to decide if it's worth reverting the performance regression or if the regression can be addressed in a future PR. From 957b415c9aade955be987a14ad1a379c43271892 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Mon, 6 Oct 2025 20:12:34 +0200 Subject: [PATCH 02/10] name of the tool is lower case --- src/doc/rustc-dev-guide/src/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md index 3d196ae2308f0..b4c8f9e9a58c0 100644 --- a/src/doc/rustc-dev-guide/src/contributing.md +++ b/src/doc/rustc-dev-guide/src/contributing.md @@ -461,7 +461,7 @@ Please see . [S-tracking-]: https://github.com/rust-lang/rust/labels?q=s-tracking [the rustc-dev-guide working group documentation]: https://forge.rust-lang.org/wg-rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes -### Rfcbot labels +### rfcbot labels [rfcbot] uses its own labels for tracking the process of coordinating asynchronous decisions, such as approving or rejecting a change. From 673fa837197a9e878ee78fbe3a1dfb325c27a8df Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Tue, 7 Oct 2025 14:18:19 +0800 Subject: [PATCH 03/10] Remove outdated recurring work item --- src/doc/rustc-dev-guide/src/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustc-dev-guide/src/getting-started.md b/src/doc/rustc-dev-guide/src/getting-started.md index 87e26d3796881..685b97329bb0c 100644 --- a/src/doc/rustc-dev-guide/src/getting-started.md +++ b/src/doc/rustc-dev-guide/src/getting-started.md @@ -98,7 +98,7 @@ Some work is too large to be done by a single person. In this case, it's common issues" to co-ordinate the work between contributors. Here are some example tracking issues where it's easy to pick up work without a large time commitment: -- [Move UI tests to subdirectories](https://github.com/rust-lang/rust/issues/73494) +- *Add recurring work items here.* If you find more recurring work, please feel free to add it here! From 8a18afd29022508a22a3a52e12d6681b71e36e69 Mon Sep 17 00:00:00 2001 From: Urgau Date: Tue, 7 Oct 2025 18:13:13 +0200 Subject: [PATCH 04/10] Add `t-` prefix to `S-waiting-on-compiler` label --- src/doc/rustc-dev-guide/src/compiler-team.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustc-dev-guide/src/compiler-team.md b/src/doc/rustc-dev-guide/src/compiler-team.md index 79dfbdc8265fc..9556811e842c2 100644 --- a/src/doc/rustc-dev-guide/src/compiler-team.md +++ b/src/doc/rustc-dev-guide/src/compiler-team.md @@ -54,7 +54,7 @@ They are held on [Zulip][zulip-meetings]. It works roughly as follows: those that are sufficiently important for us to actively track progress. P-critical and P-high bugs should ideally always have an assignee. -- **Check `S-waiting-on-compiler` and `I-compiler-nominated` issues:** These are issues where +- **Check `S-waiting-on-t-compiler` and `I-compiler-nominated` issues:** These are issues where feedback from the team is desired. - **Look over the performance triage report:** We check for PRs that made the performance worse and try to decide if it's worth reverting the performance regression or if From be95904e578ad19bc421a11b18dc4ea062c1e851 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= Date: Tue, 7 Oct 2025 22:20:53 +0200 Subject: [PATCH 05/10] Add debug assertions flag to `cg_gcc` invocation --- .../src/tests/codegen-backend-tests/cg_gcc.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md index aa337754186d6..ddfc2a3829135 100644 --- a/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md +++ b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md @@ -1,12 +1,17 @@ # GCC codegen backend If you ran into an error related to tests executed with the GCC codegen backend on CI, -you can use the following command to run tests locally using the GCC backend: +you can use the following command to run UI tests locally using the GCC backend: ```bash -./x test tests/ui --set 'rust.codegen-backends = ["llvm", "gcc"]' --test-codegen-backend gcc +./x test tests/ui \ + --set 'rust.codegen-backends = ["llvm", "gcc"]' \ + --set 'rust.debug-assertions = false' \ + --test-codegen-backend gcc ``` +If a different test suite has failed on CI, you will have to modify the `tests/ui` part. + Below, you can find more information about how to configure the GCC backend in bootstrap. ## Choosing which codegen backends are built From e9560cb786418c13a250a6c9a32364ed724ff535 Mon Sep 17 00:00:00 2001 From: Zalathar Date: Sun, 12 Oct 2025 16:57:17 +1100 Subject: [PATCH 06/10] Building a fully-functional compiler requires `x build library` --- .../rustc-dev-guide/src/building/how-to-build-and-run.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md index 2e5f0e43df1e5..5ee12f1b7312f 100644 --- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md +++ b/src/doc/rustc-dev-guide/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 455025c8c6da934ad73d1a52bac53c924ff5b59b Mon Sep 17 00:00:00 2001 From: Zalathar Date: Sun, 12 Oct 2025 17:10:48 +1100 Subject: [PATCH 07/10] Restore section "Faster builds with `--keep-stage`" as-is --- .../rustc-dev-guide/src/building/suggested.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md index 35c7e935b5688..ea917ac98d343 100644 --- a/src/doc/rustc-dev-guide/src/building/suggested.md +++ b/src/doc/rustc-dev-guide/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 3505f2cd924337f6a989b1fbb1ab89475d5a5b0c Mon Sep 17 00:00:00 2001 From: Zalathar Date: Sun, 12 Oct 2025 17:05:04 +1100 Subject: [PATCH 08/10] Prefer `--keep-stage-std` for compiler rebuilds --- .../src/building/how-to-build-and-run.md | 2 +- .../rustc-dev-guide/src/building/suggested.md | 24 +++++++------------ 2 files changed, 10 insertions(+), 16 deletions(-) diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md index 5ee12f1b7312f..ace834a55b71f 100644 --- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md +++ b/src/doc/rustc-dev-guide/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/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md index ea917ac98d343..6d3590eef64a3 100644 --- a/src/doc/rustc-dev-guide/src/building/suggested.md +++ b/src/doc/rustc-dev-guide/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 From 5189a68cb6d1877deeb5fe8bca7b8fa0130d3a14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= Date: Mon, 13 Oct 2025 09:50:26 +0200 Subject: [PATCH 09/10] Overhaul GCC codegen backend section --- .../src/tests/codegen-backend-tests/cg_gcc.md | 36 +++++++++++++++---- src/doc/rustc-dev-guide/src/tests/running.md | 35 ------------------ 2 files changed, 30 insertions(+), 41 deletions(-) diff --git a/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md index ddfc2a3829135..6bd6007c8969e 100644 --- a/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md +++ b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md @@ -1,7 +1,16 @@ # GCC codegen backend -If you ran into an error related to tests executed with the GCC codegen backend on CI, -you can use the following command to run UI tests locally using the GCC backend: +We run a subset of the compiler test suite with the GCC codegen backend on our CI, to help find changes that could break the integration of this backend with the compiler. + +If you encounter any bugs or problems with the GCC codegen backend in general, don't hesitate to open issues on the +[`rustc_codegen_gcc` repository](https://github.com/rust-lang/rustc_codegen_gcc). + +Note that the backend currently only supports the `x86_64-unknown-linux-gnu` target. + +## Running into GCC backend CI errors + +If you ran into an error related to tests executed with the GCC codegen backend on CI in the `x86_64-gnu-gcc` job, +you can use the following command to run UI tests locally using the GCC backend, which reproduces what happens on CI: ```bash ./x test tests/ui \ @@ -12,7 +21,13 @@ you can use the following command to run UI tests locally using the GCC backend: If a different test suite has failed on CI, you will have to modify the `tests/ui` part. -Below, you can find more information about how to configure the GCC backend in bootstrap. +To reproduce the whole CI job locally, you can run `cargo run --manifest-path src/ci/citool/Cargo.toml run-local x86_64-gnu-gcc`. See [Testing with Docker](../docker.md) for more information. + +### What to do in case of a GCC job failure? + +If the GCC job test fails and it seems like the failure could be caused by the GCC backend, you can ping the [cg-gcc working group](https://github.com/orgs/rust-lang/teams/wg-gcc-backend) using `@rust-lang/wg-gcc-backend` + +If fixing a compiler test that fails with the GCC backend is non-trivial, you can ignore that test when executed with `cg_gcc` using the `//@ ignore-backends: gcc` [compiletest directive](../directives.md). ## Choosing which codegen backends are built @@ -49,8 +64,7 @@ To run compiler tests with the GCC codegen backend being used to build the test ./x test tests/ui --test-codegen-backend gcc ``` -Note that in order for this to work, the tested compiler must have the GCC codegen backend available in its sysroot -directory. You can achieve that using the [instructions above](#choosing-which-codegen-backends-are-built). +Note that in order for this to work, the tested compiler must have the GCC codegen backend [available](#choosing-which-codegen-backends-are-built) in its sysroot directory. ## Downloading GCC from CI @@ -58,4 +72,14 @@ The `gcc.download-ci-gcc` bootstrap option controls if GCC (which is a dependenc will be downloaded from CI or built locally. The default value is `true`, which will download GCC from CI if there are no local changes to the GCC sources and the given host target is available on CI. -Note that GCC can currently only be downloaded from CI for the `x86_64-unknown-linux-gnu` target. +## Running tests of the backend itself + +In addition to running the compiler's test suites using the GCC codegen backend, you can also run the test suite of the backend itself. + +Now you do that using the following command: + +```text +./x test rustc_codegen_gcc +``` + +The backend needs to be [enabled](#choosing-which-codegen-backends-are-built) for this to work. diff --git a/src/doc/rustc-dev-guide/src/tests/running.md b/src/doc/rustc-dev-guide/src/tests/running.md index 482f3c42578ae..5c1d667685cec 100644 --- a/src/doc/rustc-dev-guide/src/tests/running.md +++ b/src/doc/rustc-dev-guide/src/tests/running.md @@ -396,39 +396,4 @@ Now, tests should just run, you don't have to set up anything else. [wasm32-wasip1 target support page]: https://github.com/rust-lang/rust/blob/master/src/doc/rustc/src/platform-support/wasm32-wasip1.md#building-the-target. -## Running rustc_codegen_gcc tests - -First thing to know is that it only supports linux x86_64 at the moment. We will -extend its support later on. - -You need to update `codegen-backends` value in your `bootstrap.toml` file in the -`[rust]` section and add "gcc" in the array: - -```toml -codegen-backends = ["llvm", "gcc"] -``` - -Then you need to install libgccjit 12. For example with `apt`: - -```text -apt install libgccjit-12-dev -``` - -Now you can run the following command: - -```text -./x test compiler/rustc_codegen_gcc/ -``` - -If it cannot find the `.so` library (if you installed it with `apt` for example), you -need to pass the library file path with `LIBRARY_PATH`: - -```text -LIBRARY_PATH=/usr/lib/gcc/x86_64-linux-gnu/12/ ./x test compiler/rustc_codegen_gcc/ -``` - -If you encounter bugs or problems, don't hesitate to open issues on the -[`rustc_codegen_gcc` -repository](https://github.com/rust-lang/rustc_codegen_gcc/). - [`tests/ui`]: https://github.com/rust-lang/rust/tree/master/tests/ui From 578d06d320c859f68bec684bde72f011a6782613 Mon Sep 17 00:00:00 2001 From: Martin Nordholts Date: Mon, 20 Oct 2025 19:31:44 +0200 Subject: [PATCH 10/10] debugging.md: Remove wrong claim that LLVM bitcode is not the same as IR They are the same thing since they can be converted back and forth without loss. --- src/doc/rustc-dev-guide/src/backend/debugging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustc-dev-guide/src/backend/debugging.md b/src/doc/rustc-dev-guide/src/backend/debugging.md index 4f8712dfaf3cc..a569813db82cf 100644 --- a/src/doc/rustc-dev-guide/src/backend/debugging.md +++ b/src/doc/rustc-dev-guide/src/backend/debugging.md @@ -77,7 +77,7 @@ llvm-ir`). `--build-type=debug` emits code for debug builds. There are also other useful options. Also, debug info in LLVM IR can clutter the output a lot: `RUSTFLAGS="-C debuginfo=0"` is really useful. -`RUSTFLAGS="-C save-temps"` outputs LLVM bitcode (not the same as IR) at +`RUSTFLAGS="-C save-temps"` outputs LLVM bitcode at different stages during compilation, which is sometimes useful. The output LLVM bitcode will be in `.bc` files in the compiler's output directory, set via the `--out-dir DIR` argument to `rustc`.