From 82ff0025b7e12b2bbd9ddff4a5fed685c491bd34 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 10 Sep 2025 17:13:49 +0200 Subject: 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(-) (limited to 'src/doc/rustc-dev-guide') 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 4caf4c0e0ee..ef407797fea 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,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"] +``` -- cgit 1.4.1-3-g733a5 From d588c110102b803ebb2d3d26d8c24346bb4968a5 Mon Sep 17 00:00:00 2001 From: Jakub Beránek Date: Thu, 11 Sep 2025 12:45:28 +0200 Subject: Restructure the docs --- .../src/tests/codegen-backend-tests/cg_gcc.md | 52 +++++++++++++++------- 1 file changed, 37 insertions(+), 15 deletions(-) (limited to 'src/doc/rustc-dev-guide') 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 ef407797fea..74dbfb7d31b 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,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. -- cgit 1.4.1-3-g733a5