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
Merged

Add missing documentation for running tests with GCC backend #2587

Changes from 1 commit
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
33 changes: 32 additions & 1 deletion 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,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"]
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.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
Copy link
Member

Choose a reason for hiding this comment

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

Do I also have to add this to --set to avoid waiting hours until GCC is built?

Why is true not the default?

Copy link
Member Author

Choose a reason for hiding this comment

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

Do I also have to add this to --set to avoid waiting hours until GCC is built?

Yes.

Why is true not the default?

Good question. But not something to be discussed in here I think. 😉

Copy link
Member

@Noratrieb Noratrieb Sep 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Yeah it should really be the default for any non-dist profile. No one wants to build GCC except for the few people working on it.

Copy link
Member

Choose a reason for hiding this comment

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

I agree: rust-lang/rust#146435.

```

Then when running tests, add the `--test-codegen-backend gcc` option. For example:

```bash
./x.py test tests/ui --test-codegen-backend gcc
Copy link

Choose a reason for hiding this comment

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

With this flag, it is not necessary to add gcc to codegen-backends above, no?

Copy link
Member

Choose a reason for hiding this comment

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

It is still needed. The user could specify an external rustc sysroot that we don't build, and still ask for GCC to be used in tests.

--test-codegen-backend => which backend to use in tests
codegen-backends => which backends should be built and included in rustc's sysroot

Copy link

Choose a reason for hiding this comment

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

codegen-backends => which backends should be built and included in rustc's sysroot

Does that mean that the sysroot will be built with LLVM with the config above?

Copy link
Member

Choose a reason for hiding this comment

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

If by sysroot you mean the standard library, then yes. To build the standard library with GCC, you'd need to set codegen-backends = ["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"]
```