Skip to content

Add missing documentation for running tests with GCC backend #2587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 18, 2025
+55 −2
Merged

Add missing documentation for running tests with GCC backend #2587

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f764662
Add missing documentation for running tests with GCC backend
GuillaumeGomez Sep 10, 2025
bbaa54b
Restructure the docs
Kobzol Sep 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 55 additions & 2 deletions src/tests/codegen-backend-tests/cg_gcc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,56 @@
# GCC codegen backend tests
# GCC codegen backend

TODO: please add some more information to this page.
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"]
Copy link
Member

@RalfJung RalfJung Sep 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this can hit any contributor in any PR, I think it should be possible to run these tests in a one-shot way without permanently altering one's configuration.

I don't know what exactly altering the config in this way does, but if it means during my next PR it will build this backend, then that's not great -- it's unlikely to be relevant again then.

Please put yourself into the shoes of a rustc contributor that has nothing to do with the GCC backend, and is unlikely to encounter it for most of their PRs -- and tell that contributor what they should do to fix the PR where this weird failure they didn't expect shows up. :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be done with ./x test ... --test-codegen-backend gcc --set 'rust.codegen-backends=["llvm", "gcc"]'. A bit of a mouthful, but it will likely be copy-pasted from the docs anyway, or stored in some local helper file.

Copy link
Member

@RalfJung RalfJung Sep 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Somewhere on this page, in a super obvious place that the reader will find immediately when going here the first time (i.e., probably at the top), should be a command to copy-paste to run the tests. That's still not the case, isn't it? I have to copy multiple things together to get the actual command I need to use.

I don't know how much more clear I can be about optimizing this for an inexperienced contributor who doesn't want to do much work on the GCC backend, they just want to fix their PR. Or even an experienced contributor who doesn't normally touch GCC but has their tests fail in GCC every 4 months (i.e., too rarely to remember the command). Please, when writing this, put yourself in the shoes of such a contributor, not in the shoes of someone who's been working on rustc and its GCC backend for years.

I think that command is

x.py test --set 'rust.codegen-backends=["llvm", "gcc"]' tests/ui --test-codegen-backend gcc

but I am not actually sure.

```

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 build --set 'rust.codegen-backends=["llvm", "gcc"]'
```

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:

```bash
./x build --set 'rust.codegen-backends=["gcc"]' library
```

## 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 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).

## 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.