Rollup merge of rust-lang#147924 - tshepang:rdg-sync, r=tshepang

rustc-dev-guide subtree update

Subtree update of `rustc-dev-guide` to rust-lang/rustc-dev-guide@7cb1f42.

Created using https://github.com/rust-lang/josh-sync.

r? `@ghost`

Author: Zalathar

src/doc/rustc-dev-guide/src/backend/debugging.md

@@ -77,7 +77,7 @@ llvm-ir`). `--build-type=debug` emits code for debug builds. There are also
 other useful options. Also, debug info in LLVM IR can clutter the output a lot:
 `RUSTFLAGS="-C debuginfo=0"` is really useful.
 
-`RUSTFLAGS="-C save-temps"` outputs LLVM bitcode (not the same as IR) at
+`RUSTFLAGS="-C save-temps"` outputs LLVM bitcode at
 different stages during compilation, which is sometimes useful. The output LLVM
 bitcode will be in `.bc` files in the compiler's output directory, set via the
 `--out-dir DIR` argument to `rustc`.

src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md

@@ -227,15 +227,18 @@ Once you've created a `bootstrap.toml`, you are now ready to run
 probably the best "go to" command for building a local compiler:
 
 ```console
-./x build rustc
+./x build library
 ```
 
-What this command does is build `rustc` using the stage0 compiler and stage0 `std`.
+What this command does is:
+- Build `rustc` using the stage0 compiler and stage0 `std`.
+- Build `library` (the standard libraries) with the stage1 compiler that was just built.
+- Assemble a working stage1 sysroot, containing the stage1 compiler and stage1 standard libraries.
 
 To build `rustc` with the in-tree `std`, use this command instead:
 
 ```console
-./x build rustc --stage 2
+./x build library --stage 2
 ```
 
 This final product (stage1 compiler + libs built using that compiler)
@@ -246,7 +249,7 @@ You will probably find that building the stage1 `std` is a bottleneck for you,
 but fear not, there is a (hacky) workaround...
 see [the section on avoiding rebuilds for std][keep-stage].
 
-[keep-stage]: ./suggested.md#faster-builds-with---keep-stage
+[keep-stage]: ./suggested.md#faster-rebuilds-with---keep-stage-std
 
 Sometimes you don't need a full build. When doing some kind of
 "type-based refactoring", like renaming a method, or changing the

src/doc/rustc-dev-guide/src/building/suggested.md

@@ -306,6 +306,40 @@ steps, meaning it will have two precompiled compilers: stage0 compiler and `down
 for `stage > 0` steps. This way, it will never need to build the in-tree compiler. As a result, your
 build time will be significantly reduced by not building the in-tree compiler.
 
+## Faster rebuilds with `--keep-stage-std`
+
+Sometimes just checking whether the compiler builds is not enough. A common
+example is that you need to add a `debug!` statement to inspect the value of
+some state or better understand the problem. In that case, you don't really need
+a full build. By bypassing bootstrap's cache invalidation, you can often get
+these builds to complete very fast (e.g., around 30 seconds). The only catch is
+this requires a bit of fudging and may produce compilers that don't work (but
+that is easily detected and fixed).
+
+The sequence of commands you want is as follows:
+
+- Initial build: `./x build library`
+- Subsequent builds: `./x build library --keep-stage-std=1`
+  - Note that we added the `--keep-stage-std=1` flag here
+
+As mentioned, the effect of `--keep-stage-std=1` is that we just _assume_ that the
+old standard library can be re-used. If you are editing the compiler, this is
+often true: you haven't changed the standard library, after all. But
+sometimes, it's not true: for example, if you are editing the "metadata" part of
+the compiler, which controls how the compiler encodes types and other states
+into the `rlib` files, or if you are editing things that wind up in the metadata
+(such as the definition of the MIR).
+
+**The TL;DR is that you might get weird behavior from a compile when using
+`--keep-stage-std=1`** -- for example, strange [ICEs](../appendix/glossary.html#ice)
+or other panics. In that case, you should simply remove the `--keep-stage-std=1`
+from the command and rebuild. That ought to fix the problem.
+
+You can also use `--keep-stage-std=1` when running tests. Something like this:
+
+- Initial test run: `./x test tests/ui`
+- Subsequent test run: `./x test tests/ui --keep-stage-std=1`
+
 ## Using incremental compilation
 
 You can further enable the `--incremental` flag to save additional time in

src/doc/rustc-dev-guide/src/compiler-team.md

@@ -54,8 +54,8 @@ They are held on [Zulip][zulip-meetings]. It works roughly as follows:
   those that are sufficiently important for us to actively track
   progress. P-critical and P-high bugs should ideally always have an
   assignee.
-- **Check S-waiting-on-team and I-nominated issues:** These are issues where feedback from
-  the team is desired.
+- **Check `S-waiting-on-t-compiler` and `I-compiler-nominated` issues:** These are issues where
+  feedback from the team is desired.
 - **Look over the performance triage report:** We check for PRs that made the
     performance worse and try to decide if it's worth reverting the performance regression or if
     the regression can be addressed in a future PR.

src/doc/rustc-dev-guide/src/contributing.md

@@ -461,7 +461,7 @@ Please see <https://forge.rust-lang.org/release/issue-triaging.html>.
 [S-tracking-]: https://github.com/rust-lang/rust/labels?q=s-tracking
 [the rustc-dev-guide working group documentation]: https://forge.rust-lang.org/wg-rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes
 
-### Rfcbot labels
+### rfcbot labels
 
 [rfcbot] uses its own labels for tracking the process of coordinating
 asynchronous decisions, such as approving or rejecting a change.

src/doc/rustc-dev-guide/src/getting-started.md

@@ -98,7 +98,7 @@ Some work is too large to be done by a single person. In this case, it's common
 issues" to co-ordinate the work between contributors. Here are some example tracking issues where
 it's easy to pick up work without a large time commitment:
 
-- [Move UI tests to subdirectories](https://github.com/rust-lang/rust/issues/73494)
+- *Add recurring work items here.*
 
 If you find more recurring work, please feel free to add it here!
 

src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md

@@ -1,13 +1,33 @@
 # 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 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 --set 'rust.codegen-backends = ["llvm", "gcc"]' --test-codegen-backend gcc
+./x test tests/ui \
+  --set 'rust.codegen-backends = ["llvm", "gcc"]' \
+  --set 'rust.debug-assertions = false' \
+  --test-codegen-backend gcc
 ```
 
-Below, you can find more information about how to configure the GCC backend in bootstrap.
+If a different test suite has failed on CI, you will have to modify the `tests/ui` part.
+
+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
 
@@ -44,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