From f764662980b30a510b933ec4c034cb0980ecbeb6 Mon Sep 17 00:00:00 2001
From: Guillaume Gomez <guillaume1.gomez@gmail.com>
Date: Wed, 10 Sep 2025 17:13:49 +0200
Subject: [PATCH 1/2] Add missing documentation for running tests with GCC
 backend

---
 src/tests/codegen-backend-tests/cg_gcc.md | 33 ++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/src/tests/codegen-backend-tests/cg_gcc.md b/src/tests/codegen-backend-tests/cg_gcc.md
index 4caf4c0e0..ef407797f 100644
--- a/src/tests/codegen-backend-tests/cg_gcc.md
+++ b/src/tests/codegen-backend-tests/cg_gcc.md
@@ -1,3 +1,34 @@
 # GCC codegen backend tests
 
-TODO: please add some more information to this page.
+To test the GCC codegen backend, you need to add `"gcc"` into the `rust.codegen-backends`
+setting in `bootstrap.toml`:
+
+```toml
+rust.codegen-backends = ["llvm", "gcc"]
+```
+
+If you don't want to change your `bootstrap.toml` file, you can alternatively run your `x.py`
+commands with `--set rust.codegen-backends=["llvm", "gcc"]'`. For example:
+
+```bash
+x.py test --set 'rust.codegen-backends=["llvm", "gcc"]'
+```
+
+If you don't want to build `gcc` yourself, you also need to set:
+
+```toml
+gcc.download-ci-gcc = true
+```
+
+Then when running tests, add the `--test-codegen-backend gcc` option. For example:
+
+```bash
+./x.py test tests/ui --test-codegen-backend gcc
+```
+
+If you want to build the sysroot using the GCC backend, you need to set it first
+in `rust.codegen-backends`:
+
+```toml
+rust.codegen-backends = ["llvm", "gcc"]
+```

From bbaa54b704447e91b648c2bc43bb6a3812f88a8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= <berykubik@gmail.com>
Date: Thu, 11 Sep 2025 12:45:28 +0200
Subject: [PATCH 2/2] Restructure the docs

---
 src/tests/codegen-backend-tests/cg_gcc.md | 52 ++++++++++++++++-------
 1 file changed, 37 insertions(+), 15 deletions(-)

diff --git a/src/tests/codegen-backend-tests/cg_gcc.md b/src/tests/codegen-backend-tests/cg_gcc.md
index ef407797f..74dbfb7d3 100644
--- a/src/tests/codegen-backend-tests/cg_gcc.md
+++ b/src/tests/codegen-backend-tests/cg_gcc.md
@@ -1,34 +1,56 @@
-# GCC codegen backend tests
+# GCC codegen backend
 
-To test the GCC codegen backend, you need to add `"gcc"` into the `rust.codegen-backends`
-setting in `bootstrap.toml`:
+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:
+
+```bash
+./x test tests/ui --set 'rust.codegen-backends = ["llvm", "gcc"]' --test-codegen-backend gcc
+```
+
+Below, you can find more information about how to configure the GCC backend in bootstrap.
+
+## Choosing which codegen backends are built
+
+The `rust.codegen-backends = [...]` bootstrap option affects which codegen backends will be built and
+included in the sysroot of the produced `rustc`. To use the GCC codegen backend, `"gcc"` has to
+be included in this array in `bootstrap.toml`:
 
 ```toml
 rust.codegen-backends = ["llvm", "gcc"]
 ```
 
-If you don't want to change your `bootstrap.toml` file, you can alternatively run your `x.py`
+If you don't want to change your `bootstrap.toml` file, you can alternatively run your `x`
 commands with `--set rust.codegen-backends=["llvm", "gcc"]'`. For example:
 
 ```bash
-x.py test --set 'rust.codegen-backends=["llvm", "gcc"]'
+./x build --set 'rust.codegen-backends=["llvm", "gcc"]'
 ```
 
-If you don't want to build `gcc` yourself, you also need to set:
+The first backend in the `codegen-backends` array will determine which backend will be used as the
+*default backend* of the built `rustc`. This also determines which backend will be used to compile the
+stage 1 standard library (or anything built in stage 2+). To produce `rustc` that uses the GCC backend
+by default, you can thus put `"gcc"` as the first element of this array:
 
-```toml
-gcc.download-ci-gcc = true
+```bash
+./x build --set 'rust.codegen-backends=["gcc"]' library
 ```
 
-Then when running tests, add the `--test-codegen-backend gcc` option. For example:
+## Choosing the codegen backend used in tests
+
+To run compiler tests with the GCC codegen backend being used to build the test Rust programs, you can use the
+`--test-codegen-backend` flag:
 
 ```bash
-./x.py test tests/ui --test-codegen-backend gcc
+./x test tests/ui --test-codegen-backend gcc
 ```
 
-If you want to build the sysroot using the GCC backend, you need to set it first
-in `rust.codegen-backends`:
+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).
 
-```toml
-rust.codegen-backends = ["llvm", "gcc"]
-```
+## Downloading GCC from CI
+
+The `gcc.download-ci-gcc` bootstrap option controls if GCC (which is a dependency of the GCC codegen backend)
+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.