Merge pull request rust-lang#2611 from Kobzol/gcc-unify

Overhaul GCC codegen backend section

Author: GuillaumeGomez

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,13 +64,22 @@ 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
 
 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.
+## 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.

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