From 249e5b5a0302830eafb914bff5ff80033e065b62 Mon Sep 17 00:00:00 2001
From: Samson <16504129+sagudev@users.noreply.github.com>
Date: Tue, 7 Jan 2025 21:29:45 +0100
Subject: [PATCH 01/39] Fix rib example

related zulip thread: https://rust-lang.zulipchat.com/#narrow/channel/182449-t-compiler.2Fhelp/topic/Ribs.20in.20name.20resolution
---
 src/doc/rustc-dev-guide/src/name-resolution.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/name-resolution.md b/src/doc/rustc-dev-guide/src/name-resolution.md
index 2727b8142f2a8..719ebce855366 100644
--- a/src/doc/rustc-dev-guide/src/name-resolution.md
+++ b/src/doc/rustc-dev-guide/src/name-resolution.md
@@ -120,9 +120,9 @@ even though they should be visible by ordinary scoping rules. An example:
 fn do_something<T: Default>(val: T) { // <- New rib in both types and values (1)
     // `val` is accessible, as is the helper function
     // `T` is accessible
-    let helper = || { // New rib on `helper` (2) and another on the block (3)
+   let helper = || { // New rib on the block (2)
         // `val` is accessible here
-    }; // End of (3)
+    }; // End of (2), new rib on `helper` (3)
     // `val` is accessible, `helper` variable shadows `helper` function
     fn helper() { // <- New rib in both types and values (4)
         // `val` is not accessible here, (4) is not transparent for locals
@@ -130,7 +130,7 @@ fn do_something<T: Default>(val: T) { // <- New rib in both types and values (1)
     } // End of (4)
     let val = T::default(); // New rib (5)
     // `val` is the variable, not the parameter here
-} // End of (5), (2) and (1)
+} // End of (5), (3) and (1)
 ```
 
 Because the rules for different namespaces are a bit different, each namespace

From a4b76e31f8f906e31256b2c8f696e39b2ee36c41 Mon Sep 17 00:00:00 2001
From: Yang Lin <yanglin@smail.nju.edu.cn>
Date: Sun, 16 Mar 2025 23:27:10 +0800
Subject: [PATCH 02/39] Adapt to rust-lang/rust#136466: Start removing
 `rustc_middle::hir::map::Map`

Following commit f86f7ad from pull request #136466
in the Rust project
(https://github.com/rust-lang/rust),
some methods in `Map` were moved to `TyCtxt`.
This update reimplements `rustc-drive-example.rs`,
`rustc-driver-interacting-with-the-ast.rs`,
and `rustc-interface-example.rs` using the new
versions of these methods, ensuring compatibility
with the nightly-2025-03-08 toolchain.
---
 src/doc/rustc-dev-guide/examples/rustc-driver-example.rs  | 7 +++----
 .../examples/rustc-driver-interacting-with-the-ast.rs     | 8 +++-----
 .../rustc-dev-guide/examples/rustc-interface-example.rs   | 7 +++----
 3 files changed, 9 insertions(+), 13 deletions(-)

diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
index 984bd3e37ae30..35dd07dd13657 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
@@ -1,4 +1,4 @@
-// Tested with nightly-2025-02-13
+// Tested with nightly-2025-03-08
 
 #![feature(rustc_private)]
 
@@ -71,9 +71,8 @@ impl rustc_driver::Callbacks for MyCallbacks {
 
     fn after_analysis(&mut self, _compiler: &Compiler, tcx: TyCtxt<'_>) -> Compilation {
         // Analyze the program and inspect the types of definitions.
-        for id in tcx.hir().items() {
-            let hir = tcx.hir();
-            let item = hir.item(id);
+        for id in tcx.hir_free_items(){
+            let item = &tcx.hir_item(id);
             match item.kind {
                 rustc_hir::ItemKind::Static(_, _, _) | rustc_hir::ItemKind::Fn { .. } => {
                     let name = item.ident;
diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
index 3270c722e0772..2a43ba476e1ea 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
@@ -1,4 +1,4 @@
-// Tested with nightly-2025-02-13
+// Tested with nightly-2025-03-08
 
 #![feature(rustc_private)]
 
@@ -70,11 +70,9 @@ impl rustc_driver::Callbacks for MyCallbacks {
     }
 
     fn after_analysis(&mut self, _compiler: &Compiler, tcx: TyCtxt<'_>) -> Compilation {
-        // Every compilation contains a single crate.
-        let hir_krate = tcx.hir();
         // Iterate over the top-level items in the crate, looking for the main function.
-        for id in hir_krate.items() {
-            let item = hir_krate.item(id);
+        for id in tcx.hir_free_items(){
+            let item = &tcx.hir_item(id);
             // Use pattern-matching to find a specific node inside the main function.
             if let rustc_hir::ItemKind::Fn { body, .. } = item.kind {
                 let expr = &tcx.hir_body(body).value;
diff --git a/src/doc/rustc-dev-guide/examples/rustc-interface-example.rs b/src/doc/rustc-dev-guide/examples/rustc-interface-example.rs
index 70f27c2a82a9c..11125caec7040 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-interface-example.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-interface-example.rs
@@ -1,4 +1,4 @@
-// Tested with nightly-2025-02-13
+// Tested with nightly-2025-03-08
 
 #![feature(rustc_private)]
 
@@ -64,9 +64,8 @@ fn main() {
         println!("{krate:?}");
         // Analyze the program and inspect the types of definitions.
         rustc_interface::create_and_enter_global_ctxt(&compiler, krate, |tcx| {
-            for id in tcx.hir().items() {
-                let hir = tcx.hir();
-                let item = hir.item(id);
+            for id in tcx.hir_free_items() {
+                let item = tcx.hir_item(id);
                 match item.kind {
                     rustc_hir::ItemKind::Static(_, _, _) | rustc_hir::ItemKind::Fn { .. } => {
                         let name = item.ident;

From 9a2d1fdb141ec2db9be1802316c66722f7b678f8 Mon Sep 17 00:00:00 2001
From: Yang Lin <yanglin@smail.nju.edu.cn>
Date: Sun, 16 Mar 2025 23:43:17 +0800
Subject: [PATCH 03/39] Following commit 401dd84 in the Rust project
 (https://github.com/rust-lang/rust), `ErrorGuaranteed` was replaced by fatal
 errors. As a result, `tcx.analysis()` now aborts directly instead of
 returning an error guard. To accommodate this change, this update replaces
 `tcx.analysis()` with `typeck()` to perform type checking in the example.

---
 .../examples/rustc-interface-getting-diagnostics.rs       | 8 +++++---
 .../src/rustc-driver/getting-diagnostics.md               | 3 ++-
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/doc/rustc-dev-guide/examples/rustc-interface-getting-diagnostics.rs b/src/doc/rustc-dev-guide/examples/rustc-interface-getting-diagnostics.rs
index 39b236e1783a6..9bb93ab495878 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-interface-getting-diagnostics.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-interface-getting-diagnostics.rs
@@ -1,4 +1,4 @@
-// Tested with nightly-2025-02-13
+// Tested with nightly-2025-03-08
 
 #![feature(rustc_private)]
 
@@ -86,8 +86,10 @@ fn main() {
     rustc_interface::run_compiler(config, |compiler| {
         let krate = rustc_interface::passes::parse(&compiler.sess);
         rustc_interface::create_and_enter_global_ctxt(&compiler, krate, |tcx| {
-            // Run the analysis phase on the local crate to trigger the type error.
-            let _ = tcx.analysis(());
+            // Iterate all the items defined and perform type checking.
+            tcx.par_hir_body_owners(|item_def_id| {
+                tcx.ensure_ok().typeck(item_def_id);
+            });
         });
         // If the compiler has encountered errors when this closure returns, it will abort (!) the program.
         // We avoid this by resetting the error count before returning
diff --git a/src/doc/rustc-dev-guide/src/rustc-driver/getting-diagnostics.md b/src/doc/rustc-dev-guide/src/rustc-driver/getting-diagnostics.md
index 1043df6ecb65c..518cf4e821a72 100644
--- a/src/doc/rustc-dev-guide/src/rustc-driver/getting-diagnostics.md
+++ b/src/doc/rustc-dev-guide/src/rustc-driver/getting-diagnostics.md
@@ -7,7 +7,7 @@ otherwise be printed to stderr.
 
 To get diagnostics from the compiler,
 configure [`rustc_interface::Config`] to output diagnostic to a buffer,
-and run [`TyCtxt.analysis`].
+and run [`rustc_hir_typeck::typeck`] for each item.
 
 ```rust
 {{#include ../../examples/rustc-interface-getting-diagnostics.rs}}
@@ -16,3 +16,4 @@ and run [`TyCtxt.analysis`].
 [`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html
 [`rustc_interface::Config`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Config.html
 [`TyCtxt.analysis`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/passes/fn.analysis.html
+[`rustc_hir_typeck::typeck`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn.typeck.html

From 3e448fd4f5e55b24b943dd4d85287ce0b17105ee Mon Sep 17 00:00:00 2001
From: xizheyin <xizheyin@smail.nju.edu.cn>
Date: Wed, 5 Mar 2025 13:18:17 +0800
Subject: [PATCH 04/39] Add chapter Remarks on perma-unstable features

Signed-off-by: xizheyin <xizheyin@smail.nju.edu.cn>
---
 src/doc/rustc-dev-guide/src/SUMMARY.md        |  1 +
 .../remarks-on-perma-unstable-features.md     | 55 +++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index 106db508ebbc7..71b58f79daf28 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -124,6 +124,7 @@
 - [rustc_driver and rustc_interface](./rustc-driver/intro.md)
     - [Example: Type checking](./rustc-driver/interacting-with-the-ast.md)
     - [Example: Getting diagnostics](./rustc-driver/getting-diagnostics.md)
+    - [Remarks on perma-unstable features](./rustc-driver/remarks-on-perma-unstable-features.md)
 - [Errors and Lints](diagnostics.md)
     - [Diagnostic and subdiagnostic structs](./diagnostics/diagnostic-structs.md)
     - [Translation](./diagnostics/translation.md)
diff --git a/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md b/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md
new file mode 100644
index 0000000000000..c307adc00a006
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md
@@ -0,0 +1,55 @@
+
+# Remarks on perma unstable features
+
+## `rustc_private`
+
+### Overview
+
+The `rustc_private` feature allows external crates to use compiler internals.
+
+### Using `rustc-private` with Official Toolchains
+
+When using the `rustc_private` feature with official Rust toolchains distributed via rustup, you need to install two additional components:
+
+1. **`rustc-dev`**: Provides compiler libraries
+2. **`llvm-tools`**: Provides LLVM libraries required for linking
+
+#### Installation Steps
+
+Install both components using rustup:
+
+```bash
+rustup component add rustc-dev llvm-tools
+```
+
+#### Common Error
+
+Without the `llvm-tools` component, you'll encounter linking errors like:
+
+```
+error: linking with `cc` failed: exit status: 1
+  |
+  = note: rust-lld: error: unable to find library -lLLVM-{version}
+```
+
+### Using `rustc-private` with Custom Toolchains
+
+For custom-built toolchains or environments not using rustup, additional configuration is typically required:
+
+#### Requirements
+
+- LLVM libraries must be available in your system's library search paths
+- The LLVM version must match the one used to build your Rust toolchain
+
+#### Troubleshooting Steps
+
+1. **Check LLVM installation**: Verify LLVM is installed and accessible
+2. **Configure library paths**: You may need to set environment variables:
+   ```bash
+   export LD_LIBRARY_PATH=/path/to/llvm/lib:$LD_LIBRARY_PATH
+   ```
+3. **Check version compatibility**: Ensure your LLVM version is compatible with your Rust toolchain
+
+### Additional Resources
+
+- [GitHub Issue #137421](https://github.com/rust-lang/rust/issues/137421): Explains that `rustc_private` linker failures often occur because `llvm-tools` is not installed

From 74698d7c2cb9cc6722b9ce5c7b32e3da61e38e1a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= <berykubik@gmail.com>
Date: Tue, 18 Mar 2025 16:16:28 +0100
Subject: [PATCH 05/39] Add Fuchsia ping group notice

---
 src/doc/rustc-dev-guide/src/tests/fuchsia.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/doc/rustc-dev-guide/src/tests/fuchsia.md b/src/doc/rustc-dev-guide/src/tests/fuchsia.md
index e96290b921529..926803368f087 100644
--- a/src/doc/rustc-dev-guide/src/tests/fuchsia.md
+++ b/src/doc/rustc-dev-guide/src/tests/fuchsia.md
@@ -4,6 +4,14 @@
 million lines of Rust code.[^loc] It has caught a large number of [regressions]
 in the past and was subsequently included in CI.
 
+## What to do if the Fuchsia job breaks?
+
+Please contact the `fuchsia` ping group and ask them for help.
+
+```text
+@rustbot ping fuchsia
+```
+
 ## Building Fuchsia in CI
 
 Fuchsia builds as part of the suite of bors tests that run before a pull request

From 9ff4936afbc57912aed05f822133af6b5da3f0f4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= <berykubik@gmail.com>
Date: Tue, 18 Mar 2025 16:17:59 +0100
Subject: [PATCH 06/39] Reorder RfL tests page to move the "what if it breaks"
 section to the top

---
 .../src/tests/rust-for-linux.md               | 40 +++++++++----------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/tests/rust-for-linux.md b/src/doc/rustc-dev-guide/src/tests/rust-for-linux.md
index c674d1575b781..bdf32ffc398db 100644
--- a/src/doc/rustc-dev-guide/src/tests/rust-for-linux.md
+++ b/src/doc/rustc-dev-guide/src/tests/rust-for-linux.md
@@ -3,26 +3,7 @@
 [Rust for Linux](https://rust-for-linux.com/) (RfL) is an effort for adding
 support for the Rust programming language into the Linux kernel.
 
-## Building Rust for Linux in CI
-
-Rust for Linux builds as part of the suite of bors tests that run before a pull
-request is merged.
-
-The workflow builds a stage1 sysroot of the Rust compiler, downloads the Linux
-kernel, and tries to compile several Rust for Linux drivers and examples using
-this sysroot. RfL uses several unstable compiler/language features, therefore
-this workflow notifies us if a given compiler change would break it.
-
-If you are worried that a pull request might break the Rust for Linux builder
-and want to test it out before submitting it to the bors queue, simply add this
-line to your PR description:
-
-> try-job: x86_64-rust-for-linux
-
-Then when you `@bors try` it will pick the job that builds the Rust for Linux
-integration.
-
-## What to do in case of failure
+## What to do if the Rust for Linux job breaks?
 
 If a PR breaks the Rust for Linux CI job, then:
 
@@ -48,4 +29,23 @@ ping group to ask for help:
 @rustbot ping rfl
 ```
 
+## Building Rust for Linux in CI
+
+Rust for Linux builds as part of the suite of bors tests that run before a pull
+request is merged.
+
+The workflow builds a stage1 sysroot of the Rust compiler, downloads the Linux
+kernel, and tries to compile several Rust for Linux drivers and examples using
+this sysroot. RfL uses several unstable compiler/language features, therefore
+this workflow notifies us if a given compiler change would break it.
+
+If you are worried that a pull request might break the Rust for Linux builder
+and want to test it out before submitting it to the bors queue, simply add this
+line to your PR description:
+
+> try-job: x86_64-rust-for-linux
+
+Then when you `@bors try` it will pick the job that builds the Rust for Linux
+integration.
+
 [rfl-ping]: ../notification-groups/rust-for-linux.md

From c987d34a7e14abf5b7065bfd6c27eb52d2863773 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= <berykubik@gmail.com>
Date: Tue, 18 Mar 2025 16:19:55 +0100
Subject: [PATCH 07/39] Add Fuchsia ping group page

---
 src/doc/rustc-dev-guide/src/SUMMARY.md               |  3 ++-
 .../src/notification-groups/fuchsia.md               | 12 ++++++++++++
 src/doc/rustc-dev-guide/src/tests/fuchsia.md         |  3 ++-
 3 files changed, 16 insertions(+), 2 deletions(-)
 create mode 100644 src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index a090f96f3f806..9e2d0774aab0b 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -61,12 +61,13 @@
     - [ARM](notification-groups/arm.md)
     - [Cleanup Crew](notification-groups/cleanup-crew.md)
     - [Emscripten](notification-groups/emscripten.md)
+    - [Fuchsia](notification-groups/fuchsia.md)
     - [LLVM](notification-groups/llvm.md)
     - [RISC-V](notification-groups/risc-v.md)
+    - [Rust for Linux](notification-groups/rust-for-linux.md)
     - [WASI](notification-groups/wasi.md)
     - [WebAssembly](notification-groups/wasm.md)
     - [Windows](notification-groups/windows.md)
-    - [Rust for Linux](notification-groups/rust-for-linux.md)
 - [Licenses](./licenses.md)
 - [Editions](guides/editions.md)
 
diff --git a/src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md b/src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md
new file mode 100644
index 0000000000000..a4658e0d842f9
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md
@@ -0,0 +1,12 @@
+# Fuchsia notification group
+
+**Github Label:** [O-fuchsia] <br>
+**Ping command:** `@rustbot ping fuchsia`
+
+[O-fuchsia]: https://github.com/rust-lang/rust/labels/O-fuchsia
+
+This list will be used to notify [Fuchsia][fuchsia] maintainers
+when the compiler or the standard library changes in a way that would
+break the Fuchsia integration.
+
+[fuchsia]: ../tests/fuchsia.md
diff --git a/src/doc/rustc-dev-guide/src/tests/fuchsia.md b/src/doc/rustc-dev-guide/src/tests/fuchsia.md
index 926803368f087..2766c362cc266 100644
--- a/src/doc/rustc-dev-guide/src/tests/fuchsia.md
+++ b/src/doc/rustc-dev-guide/src/tests/fuchsia.md
@@ -6,7 +6,7 @@ in the past and was subsequently included in CI.
 
 ## What to do if the Fuchsia job breaks?
 
-Please contact the `fuchsia` ping group and ask them for help.
+Please contact the [fuchsia][fuchsia-ping] ping group and ask them for help.
 
 ```text
 @rustbot ping fuchsia
@@ -170,6 +170,7 @@ rustc book][platform-support].
 [`public_configs`]: https://gn.googlesource.com/gn/+/main/docs/reference.md#var_public_configs
 [`//build/config:compiler`]: https://cs.opensource.google/fuchsia/fuchsia/+/main:build/config/BUILD.gn;l=121;drc=c26c473bef93b33117ae417893118907a026fec7
 [build system]: https://fuchsia.dev/fuchsia-src/development/build/build_system
+[fuchsia-ping]: ../notification-groups/fuchsia.md
 
 [^loc]: As of June 2024, Fuchsia had about 2 million lines of first-party Rust
 code and a roughly equal amount of third-party code, as counted by tokei

From 4f053a9ee9f6816cad66c13b0777b22b0d8854bf Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 18 Mar 2025 12:04:47 -0500
Subject: [PATCH 08/39] add new section on the `rustdoc` test suite

---
 .../src/rustdoc-internals/htmldocck.md        | 101 ++++++++++++++++++
 src/doc/rustc-dev-guide/src/rustdoc.md        |  14 +--
 .../rustc-dev-guide/src/tests/compiletest.md  |   2 +-
 3 files changed, 109 insertions(+), 8 deletions(-)
 create mode 100644 src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md

diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
new file mode 100644
index 0000000000000..d69627f46cc5c
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
@@ -0,0 +1,101 @@
+# `rustdoc` tests
+
+This page is specifically about the `rustdoc` test suite, for other test suites used for testing rustdoc, see [Rustdoc § Tests](../rustdoc.md#tests).
+
+`htmldocck.py` is a custom checker script that uses [XPath] to verify the HTML output of rustdoc.
+
+[XPath]: https://en.wikipedia.org/wiki/XPath
+
+## Directives
+Directives to htmldocck are similar to those given to `compiletest` in that they take the form of `//@` comments.
+
+All `PATH`s in directives are relative to the the rustdoc output directory (`build/TARGET/test/rustdoc/TESTNAME`),
+so it is conventional to use a `#![crate_name = "foo"]` attribute to avoid writing paths.
+To avoid repetion, `-` can be used in any `PATH` argument to re-use the previous `PATH` argument.
+
+All arguments take the form of quoted strings,
+with the exception of `COUNT` and the special `-` form of `PATH`.
+
+Directives are assertions that place constraints on the generated HTML.
+
+All directives (except `files`) can be negated by putting a `!` in front of their name.
+
+Similar to shell commands,
+directives can extend across multiple lines if their last char is `\`.
+In this case, the start of the next line should be `//`, with no `@`.
+
+For example, `//@ !has 'foo/struct.Bar.html'` checks that crate `foo` does not have a page for a struct named `Bar` in the crate root.
+
+### `has`
+
+Usage 1: `//@ has PATH`
+Usage 2: `//@ has PATH XPATH PATTERN`
+
+In the first form, `has` checks that a given file exists.
+
+In the second form, `has` is an alias for `matches`,
+except `PATTERN` is a whitespace-normalized[^1] string instead of a regex.
+
+### `matches`
+
+Usage: `//@ matches PATH XPATH PATTERN`
+
+Checks that the text of each element selected by `XPATH` in `PATH` matches the python-flavored regex `PATTERN`.
+
+### `matchesraw`
+
+Usage: `//@ matchesraw PATH PATTERN`
+
+Checks that the contents of the file `PATH` matches the regex `PATTERN`.
+
+### `hasraw`
+
+Usage: `//@ hasraw PATH PATTERN`
+
+Same as `matchesraw`, except `PATTERN` is a whitespace-normalized[^1] string instead of a regex.
+
+### `count`
+
+Usage: `//@ count PATH XPATH COUNT`
+
+Checks that there are exactly `COUNT` matches for `XPATH` within the file `PATH`.
+
+### `snapshot`
+
+Usage: `//@ snapshot NAME PATH XPATH`
+
+Creates a snapshot test named NAME.
+A snapshot test captures a subtree of the DOM, at the location
+determined by the XPath, and compares it to a pre-recorded value
+in a file. The file's name is the test's name with the `.rs` extension
+replaced with `.NAME.html`, where NAME is the snapshot's name.
+
+htmldocck supports the `--bless` option to accept the current subtree
+as expected, saving it to the file determined by the snapshot's name.
+compiletest's `--bless` flag is forwarded to htmldocck.
+
+### `has-dir`
+
+Usage: `//@ has-dir PATH`
+
+Checks for the existance of directory `PATH`.
+
+### `files`
+
+Usage: `//@ files PATH ENTRIES`
+
+Checks that the directory `PATH` contains exactly `ENTRIES`.
+`ENTRIES` is a python list of strings inside a quoted string,
+as if it were to be parsed by `eval`.
+(note that the list is actually parsed by `shlex.split`,
+so it cannot contain arbitrary python expressions).
+
+Example: `//@ files "foo/bar" '["index.html", "sidebar-items.js"]'`
+
+[^1]: Whitespace normalization means that all spans of consecutive whitespace are replaced with a single space.  The files themselves are also whitespace-normalized.
+
+## Limitations
+All `XPATH` arguments must start with `//` due to a flaw in the implemention.
+
+Only well-formed HTML can be parsed (hopefully rustdoc doesn't output mismatched tags).
+
diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md
index 356698148e405..5ac62aa2c3768 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc.md
@@ -77,27 +77,27 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
   `doctest.rs`.
 * The Markdown renderer is loaded up in `html/markdown.rs`, including functions
   for extracting doctests from a given block of Markdown.
-* The tests on the structure of rustdoc HTML output are located in `tests/rustdoc`, where
-  they're handled by the test runner of bootstrap and the supplementary script
-  `src/etc/htmldocck.py`.
 * Frontend CSS and JavaScript are stored in `html/static/`.
 
 ## Tests
 
-* All paths in this section are relative to `tests` in the rust-lang/rust repository.
-* Tests on search engine and index are located in `rustdoc-js` and `rustdoc-js-std`.
+* Tests on search engine and index are located in `tests/rustdoc-js` and `tests/rustdoc-js-std`.
   The format is specified
   [in the search guide](rustdoc-internals/search.md#testing-the-search-engine).
 * Tests on the "UI" of rustdoc (the terminal output it produces when run) are in
-  `rustdoc-ui`
+  `tests/rustdoc-ui`
 * Tests on the "GUI" of rustdoc (the HTML, JS, and CSS as rendered in a browser)
-  are in `rustdoc-gui`. These use a [NodeJS tool called
+  are in `tests/rustdoc-gui`. These use a [NodeJS tool called
   browser-UI-test](https://github.com/GuillaumeGomez/browser-UI-test/) that uses
   puppeteer to run tests in a headless browser and check rendering and
   interactivity.
 * Additionally, JavaScript type annotations are written using [TypeScript-flavored JSDoc]
   comments and an external d.ts file. The code itself is plain, valid JavaScript; we only
   use tsc as a linter.
+* The tests on the structure of rustdoc HTML output are located in `tests/rustdoc`,
+  where they're handled by the test runner of bootstrap and
+  the supplementary script `src/etc/htmldocck.py`.
+  [These tests have several extra directives available to them](./rustdoc-internals/htmldocck.md).
 
 [TypeScript-flavored JSDoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
 
diff --git a/src/doc/rustc-dev-guide/src/tests/compiletest.md b/src/doc/rustc-dev-guide/src/tests/compiletest.md
index 2c35381eadfb5..ee66b787bf1b2 100644
--- a/src/doc/rustc-dev-guide/src/tests/compiletest.md
+++ b/src/doc/rustc-dev-guide/src/tests/compiletest.md
@@ -78,7 +78,7 @@ The following test suites are available, with links for more information:
 
 ### Rustdoc test suites
 
-See [Rustdoc tests](../rustdoc.md#tests) for more details.
+See [Rustdoc § Tests](../rustdoc.md#tests) for more details.
 
 | Test suite       | Purpose                                                                  |
 |------------------|--------------------------------------------------------------------------|

From 3668c366621043dce7dc9fddca19a60945526fae Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 18 Mar 2025 12:10:43 -0500
Subject: [PATCH 09/39] add htmldocck.md to SUMMARY.md

---
 src/doc/rustc-dev-guide/src/SUMMARY.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index 9e2d0774aab0b..fb468777409be 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -95,7 +95,7 @@
 - [Parallel Compilation](./parallel-rustc.md)
 - [Rustdoc internals](./rustdoc-internals.md)
     - [Search](./rustdoc-internals/search.md)
-
+	- [`rustdoc` tests](./rustdoc-internals/htmldocck.md)
 # Source Code Representation
 
 - [Prologue](./part-3-intro.md)

From a172f23df0b108d6d615d1433ae3de51afd292b6 Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 18 Mar 2025 13:10:26 -0500
Subject: [PATCH 10/39] htmldocck: expand limitations and mention compiletest
 directives

---
 .../src/rustdoc-internals/htmldocck.md               | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
index d69627f46cc5c..b37c1ac3de1b2 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
@@ -9,6 +9,10 @@ This page is specifically about the `rustdoc` test suite, for other test suites
 ## Directives
 Directives to htmldocck are similar to those given to `compiletest` in that they take the form of `//@` comments.
 
+In addition to the directives listed here,
+`rustdoc` tests also support most
+[compiletest directives](../tests/directives.html).
+
 All `PATH`s in directives are relative to the the rustdoc output directory (`build/TARGET/test/rustdoc/TESTNAME`),
 so it is conventional to use a `#![crate_name = "foo"]` attribute to avoid writing paths.
 To avoid repetion, `-` can be used in any `PATH` argument to re-use the previous `PATH` argument.
@@ -95,7 +99,9 @@ Example: `//@ files "foo/bar" '["index.html", "sidebar-items.js"]'`
 [^1]: Whitespace normalization means that all spans of consecutive whitespace are replaced with a single space.  The files themselves are also whitespace-normalized.
 
 ## Limitations
-All `XPATH` arguments must start with `//` due to a flaw in the implemention.
-
-Only well-formed HTML can be parsed (hopefully rustdoc doesn't output mismatched tags).
+`htmldocck.py` uses the xpath implementation from the standard library.
+This leads to several limitations:
+* All `XPATH` arguments must start with `//` due to a flaw in the implemention.
+* Many XPath features (functions, axies, etc.) are not supported.
+* Only well-formed HTML can be parsed (hopefully rustdoc doesn't output mismatched tags).
 

From 6893f0ac7aaf2c02e48c6434f98febe58def1f95 Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 18 Mar 2025 13:19:33 -0500
Subject: [PATCH 11/39] rustdoc test suite: clean up wording and intro

---
 .../rustc-dev-guide/src/rustdoc-internals/htmldocck.md   | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
index b37c1ac3de1b2..97c40c8a8202a 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
@@ -1,8 +1,10 @@
-# `rustdoc` tests
+# the `rustdoc` test suite
 
 This page is specifically about the `rustdoc` test suite, for other test suites used for testing rustdoc, see [Rustdoc § Tests](../rustdoc.md#tests).
 
-`htmldocck.py` is a custom checker script that uses [XPath] to verify the HTML output of rustdoc.
+The `rustdoc` test suite is specifically used to test the HTML output of rustdoc.
+
+This is achived by means of `htmldocck.py`, a custom checker script that leverages [XPath].
 
 [XPath]: https://en.wikipedia.org/wiki/XPath
 
@@ -14,7 +16,8 @@ In addition to the directives listed here,
 [compiletest directives](../tests/directives.html).
 
 All `PATH`s in directives are relative to the the rustdoc output directory (`build/TARGET/test/rustdoc/TESTNAME`),
-so it is conventional to use a `#![crate_name = "foo"]` attribute to avoid writing paths.
+so it is conventional to use a `#![crate_name = "foo"]` attribute to avoid
+having to write a long crate name multiple times.
 To avoid repetion, `-` can be used in any `PATH` argument to re-use the previous `PATH` argument.
 
 All arguments take the form of quoted strings,

From 1081d98cf679560b02f6db4b2d72bb3103b92073 Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 18 Mar 2025 13:21:15 -0500
Subject: [PATCH 12/39] rename htmldocck.md -> rustdoc-test-suite.md

---
 src/doc/rustc-dev-guide/src/SUMMARY.md                          | 2 +-
 .../rustdoc-internals/{htmldocck.md => rustdoc-test-suite.md}   | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename src/doc/rustc-dev-guide/src/rustdoc-internals/{htmldocck.md => rustdoc-test-suite.md} (100%)

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index fb468777409be..8ea5e86cd63a6 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -95,7 +95,7 @@
 - [Parallel Compilation](./parallel-rustc.md)
 - [Rustdoc internals](./rustdoc-internals.md)
     - [Search](./rustdoc-internals/search.md)
-	- [`rustdoc` tests](./rustdoc-internals/htmldocck.md)
+	- [the `rustdoc` test suite](./rustdoc-internals/rustdoc-test-suite.md)
 # Source Code Representation
 
 - [Prologue](./part-3-intro.md)
diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
similarity index 100%
rename from src/doc/rustc-dev-guide/src/rustdoc-internals/htmldocck.md
rename to src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md

From 40b9be0c456d32cf01441ec1c96fec1523d4737f Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 18 Mar 2025 13:23:37 -0500
Subject: [PATCH 13/39] clean up wording/grammar and mention double quotes

---
 src/doc/rustc-dev-guide/src/SUMMARY.md                     | 2 +-
 .../src/rustdoc-internals/rustdoc-test-suite.md            | 7 ++++---
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index 8ea5e86cd63a6..075d5af4c24a5 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -95,7 +95,7 @@
 - [Parallel Compilation](./parallel-rustc.md)
 - [Rustdoc internals](./rustdoc-internals.md)
     - [Search](./rustdoc-internals/search.md)
-	- [the `rustdoc` test suite](./rustdoc-internals/rustdoc-test-suite.md)
+	- [The `rustdoc` test suite](./rustdoc-internals/rustdoc-test-suite.md)
 # Source Code Representation
 
 - [Prologue](./part-3-intro.md)
diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
index 97c40c8a8202a..fb4be51c278a9 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
@@ -1,6 +1,6 @@
-# the `rustdoc` test suite
+# The `rustdoc` test suite
 
-This page is specifically about the `rustdoc` test suite, for other test suites used for testing rustdoc, see [Rustdoc § Tests](../rustdoc.md#tests).
+This page is specifically about the test suite named `rustdoc`, for other test suites used for testing rustdoc, see [Rustdoc Tests](../rustdoc.md#tests).
 
 The `rustdoc` test suite is specifically used to test the HTML output of rustdoc.
 
@@ -20,7 +20,8 @@ so it is conventional to use a `#![crate_name = "foo"]` attribute to avoid
 having to write a long crate name multiple times.
 To avoid repetion, `-` can be used in any `PATH` argument to re-use the previous `PATH` argument.
 
-All arguments take the form of quoted strings,
+All arguments take the form of quoted strings
+(both single and double quotes are supported),
 with the exception of `COUNT` and the special `-` form of `PATH`.
 
 Directives are assertions that place constraints on the generated HTML.

From 7f29b47410d62cc1d81c0105add357552a0f1c99 Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 18 Mar 2025 13:25:39 -0500
Subject: [PATCH 14/39] normalize link titles

---
 .../rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md | 2 +-
 src/doc/rustc-dev-guide/src/tests/compiletest.md                | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
index fb4be51c278a9..c2a2e6495f82c 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
@@ -1,6 +1,6 @@
 # The `rustdoc` test suite
 
-This page is specifically about the test suite named `rustdoc`, for other test suites used for testing rustdoc, see [Rustdoc Tests](../rustdoc.md#tests).
+This page is specifically about the test suite named `rustdoc`, for other test suites used for testing rustdoc, see [Rustdoc tests](../rustdoc.md#tests).
 
 The `rustdoc` test suite is specifically used to test the HTML output of rustdoc.
 
diff --git a/src/doc/rustc-dev-guide/src/tests/compiletest.md b/src/doc/rustc-dev-guide/src/tests/compiletest.md
index ee66b787bf1b2..2c35381eadfb5 100644
--- a/src/doc/rustc-dev-guide/src/tests/compiletest.md
+++ b/src/doc/rustc-dev-guide/src/tests/compiletest.md
@@ -78,7 +78,7 @@ The following test suites are available, with links for more information:
 
 ### Rustdoc test suites
 
-See [Rustdoc § Tests](../rustdoc.md#tests) for more details.
+See [Rustdoc tests](../rustdoc.md#tests) for more details.
 
 | Test suite       | Purpose                                                                  |
 |------------------|--------------------------------------------------------------------------|

From eeda54f1102d514a9f73c2d5ed92e75b2edfe94e Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Tue, 18 Mar 2025 13:29:14 -0500
Subject: [PATCH 15/39] update filename in link

---
 src/doc/rustc-dev-guide/src/rustdoc.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md
index 5ac62aa2c3768..320dc9d582584 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc.md
@@ -97,7 +97,7 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
 * The tests on the structure of rustdoc HTML output are located in `tests/rustdoc`,
   where they're handled by the test runner of bootstrap and
   the supplementary script `src/etc/htmldocck.py`.
-  [These tests have several extra directives available to them](./rustdoc-internals/htmldocck.md).
+  [These tests have several extra directives available to them](./rustdoc-internals/rustdoc-test-suite.md).
 
 [TypeScript-flavored JSDoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
 

From 88478aca86706a7b2cc1db4c27add28ee374d376 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= <berykubik@gmail.com>
Date: Wed, 19 Mar 2025 09:36:05 +0100
Subject: [PATCH 16/39] Set linkcheck in `ci.yml`

---
 src/doc/rustc-dev-guide/.github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/doc/rustc-dev-guide/.github/workflows/ci.yml b/src/doc/rustc-dev-guide/.github/workflows/ci.yml
index 22a4fb1901ab8..415d0dc397dc9 100644
--- a/src/doc/rustc-dev-guide/.github/workflows/ci.yml
+++ b/src/doc/rustc-dev-guide/.github/workflows/ci.yml
@@ -18,6 +18,7 @@ jobs:
       MDBOOK_LINKCHECK2_VERSION: 0.9.1
       MDBOOK_MERMAID_VERSION: 0.12.6
       MDBOOK_TOC_VERSION: 0.11.2
+      MDBOOK_OUTPUT__LINKCHECK__FOLLOW_WEB_LINKS: ${{ github.event_name != 'pull_request' }}
       DEPLOY_DIR: book/html
       BASE_SHA: ${{ github.event.pull_request.base.sha }}
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

From 2daaf493815e8b4bfa9862559cecf6f0f2383314 Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <tshepang@gmail.com>
Date: Wed, 19 Mar 2025 18:06:50 +0200
Subject: [PATCH 17/39] use correct code block markers

This makes this command pass

  mdbook test --chapter "Remarks on perma-unstable features"
---
 .../src/rustc-driver/remarks-on-perma-unstable-features.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md b/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md
index c307adc00a006..b434cfc9cf146 100644
--- a/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md
+++ b/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md
@@ -1,4 +1,3 @@
-
 # Remarks on perma unstable features
 
 ## `rustc_private`
@@ -18,7 +17,7 @@ When using the `rustc_private` feature with official Rust toolchains distributed
 
 Install both components using rustup:
 
-```bash
+```text
 rustup component add rustc-dev llvm-tools
 ```
 
@@ -26,7 +25,7 @@ rustup component add rustc-dev llvm-tools
 
 Without the `llvm-tools` component, you'll encounter linking errors like:
 
-```
+```text
 error: linking with `cc` failed: exit status: 1
   |
   = note: rust-lld: error: unable to find library -lLLVM-{version}
@@ -45,7 +44,7 @@ For custom-built toolchains or environments not using rustup, additional configu
 
 1. **Check LLVM installation**: Verify LLVM is installed and accessible
 2. **Configure library paths**: You may need to set environment variables:
-   ```bash
+   ```text
    export LD_LIBRARY_PATH=/path/to/llvm/lib:$LD_LIBRARY_PATH
    ```
 3. **Check version compatibility**: Ensure your LLVM version is compatible with your Rust toolchain

From 2de68a1bb180923c753e8d53d5ae913b751b860f Mon Sep 17 00:00:00 2001
From: Boxy <rust@boxyuwu.dev>
Date: Thu, 20 Mar 2025 17:30:18 +0000
Subject: [PATCH 18/39] Update `ParamEnv` section for `TypingEnv` changes

---
 src/doc/rustc-dev-guide/src/SUMMARY.md        |   5 +-
 .../src/appendix/code-index.md                |   2 +-
 src/doc/rustc-dev-guide/src/const-eval.md     |   2 +-
 .../src/param_env/param_env_acquisition.md    |  43 ----
 .../param_env_construction_internals.md       |  83 -------
 .../src/param_env/param_env_summary.md        |  18 --
 .../src/param_env/param_env_what_is_it.md     |  59 -----
 src/doc/rustc-dev-guide/src/traits/caching.md |   2 +-
 .../rustc-dev-guide/src/traits/resolution.md  |   2 +-
 .../src/typing_parameter_envs.md              | 206 ++++++++++++++++++
 10 files changed, 211 insertions(+), 211 deletions(-)
 delete mode 100644 src/doc/rustc-dev-guide/src/param_env/param_env_acquisition.md
 delete mode 100644 src/doc/rustc-dev-guide/src/param_env/param_env_construction_internals.md
 delete mode 100644 src/doc/rustc-dev-guide/src/param_env/param_env_summary.md
 delete mode 100644 src/doc/rustc-dev-guide/src/param_env/param_env_what_is_it.md
 create mode 100644 src/doc/rustc-dev-guide/src/typing_parameter_envs.md

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index 075d5af4c24a5..c5d046015d884 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -146,10 +146,7 @@
     - [ADTs and Generic Arguments](./ty_module/generic_arguments.md)
     - [Parameter types/consts/regions](./ty_module/param_ty_const_regions.md)
 - [`TypeFolder` and `TypeFoldable`](./ty-fold.md)
-- [Parameter Environments](./param_env/param_env_summary.md)
-    - [What is it?](./param_env/param_env_what_is_it.md)
-    - [How are `ParamEnv`'s constructed internally](./param_env/param_env_construction_internals.md)
-    - [Which `ParamEnv` do I use?](./param_env/param_env_acquisition.md)
+- [Typing/Param Envs](./typing_parameter_envs.md)
 - [Type inference](./type-inference.md)
 - [Trait solving](./traits/resolution.md)
     - [Higher-ranked trait bounds](./traits/hrtb.md)
diff --git a/src/doc/rustc-dev-guide/src/appendix/code-index.md b/src/doc/rustc-dev-guide/src/appendix/code-index.md
index b96ede68eab51..65fbf752d7921 100644
--- a/src/doc/rustc-dev-guide/src/appendix/code-index.md
+++ b/src/doc/rustc-dev-guide/src/appendix/code-index.md
@@ -40,5 +40,5 @@ Item            |  Kind    | Short description           | Chapter            |
 [Emitting Diagnostics]: ../diagnostics.html
 [Macro expansion]: ../macro-expansion.html
 [Name resolution]: ../name-resolution.html
-[Parameter Environment]: ../param_env/param_env_summary.html
+[Parameter Environment]: ../typing_parameter_envs.html
 [Trait Solving: Goals and Clauses]: ../traits/goals-and-clauses.html#domain-goals
diff --git a/src/doc/rustc-dev-guide/src/const-eval.md b/src/doc/rustc-dev-guide/src/const-eval.md
index 69329a3e08511..ca6a35a5e97eb 100644
--- a/src/doc/rustc-dev-guide/src/const-eval.md
+++ b/src/doc/rustc-dev-guide/src/const-eval.md
@@ -35,7 +35,7 @@ They're the wrappers of the `const_eval` query.
   Statics are special; all other functions do not represent statics correctly
   and have thus assertions preventing their use on statics.
 
-The `const_eval_*` functions use a [`ParamEnv`](./param_env/param_env_summary.html) of environment
+The `const_eval_*` functions use a [`ParamEnv`](./typing_parameter_envs.html) of environment
 in which the constant is evaluated (e.g. the function within which the constant is used)
 and a [`GlobalId`]. The `GlobalId` is made up of an `Instance` referring to a constant
 or static or of an `Instance` of a function and an index into the function's `Promoted` table.
diff --git a/src/doc/rustc-dev-guide/src/param_env/param_env_acquisition.md b/src/doc/rustc-dev-guide/src/param_env/param_env_acquisition.md
deleted file mode 100644
index f6cff2d6c63cc..0000000000000
--- a/src/doc/rustc-dev-guide/src/param_env/param_env_acquisition.md
+++ /dev/null
@@ -1,43 +0,0 @@
-
-# Which `ParamEnv` do I use?
-
-When needing a [`ParamEnv`][pe] in the compiler there are a few options for obtaining one:
-- The correct env is already in scope simply use it (or pass it down the call stack to where you are).
-- The [`tcx.param_env(def_id)` query][param_env_query]
-- Use [`ParamEnv::new`][param_env_new] to construct an env with an arbitrary set of where clauses. Then call [`traits::normalize_param_env_or_error`][normalize_env_or_error] which will handle normalizing and elaborating all the where clauses in the env for you.
-- Creating an empty environment via [`ParamEnv::reveal_all`][env_reveal_all] or [`ParamEnv::empty`][env_empty]
-
-In the large majority of cases a `ParamEnv` when required already exists somewhere in scope or above in the call stack and should be passed down. A non exhaustive list of places where you might find an existing `ParamEnv`:
-- During typeck `FnCtxt` has a [`param_env` field][fnctxt_param_env]
-- When writing late lints the `LateContext` has a [`param_env` field][latectxt_param_env]
-- During well formedness checking the `WfCheckingCtxt` has a [`param_env` field][wfckctxt_param_env]
-- The `TypeChecker` used by Mir Typeck has a [`param_env` field][mirtypeck_param_env]
-- In the next-gen trait solver all `Goal`s have a [`param_env` field][goal_param_env] specifying what environment to prove the goal in
-- When editing an existing [`TypeRelation`][typerelation] if it implements `PredicateEmittingRelation` then a [`param_env` method][typerelation_param_env] will be available.
-
-Using the `param_env` query to obtain an env is generally done at the start of some kind of analysis and then passed everywhere that a `ParamEnv` is required. For example the type checker will create a `ParamEnv` for the item it is type checking and then pass it around everywhere.
-
-Creating an env from an arbitrary set of where clauses is usually unnecessary and should only be done if the environment you need does not correspond to an actual item in the source code (i.e. [`compare_method_predicate_entailment`][method_pred_entailment] as mentioned earlier).
-
-Creating an empty environment via `ParamEnv::empty` is almost always wrong. There are very few places where we actually know that the environment should be empty. One of the only places where we do actually know this is after monomorphization, however the `ParamEnv` there should be constructed via `ParamEnv::reveal_all` instead as at this point we should be able to determine the hidden type of opaque types. Codegen/Post-mono is one of the only places that should be using `ParamEnv::reveal_all`.
-
-An additional piece of complexity here is specifying the `Reveal` (see linked docs for explanation of what reveal does) used for the `ParamEnv`. When constructing a param env using the `param_env` query it will have `Reveal::UserFacing`, if `Reveal::All` is desired then the [`tcx.param_env_reveal_all_normalized`][env_reveal_all_normalized] query can be used instead.
-
-The `ParamEnv` type has a method [`ParamEnv::with_reveal_all_normalized`][with_reveal_all] which converts an existing `ParamEnv` into one with `Reveal::All` specified. Where possible the previously mentioned query should be preferred as it is more efficient.
-
-[param_env_new]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html#method.new
-[normalize_env_or_error]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/fn.normalize_param_env_or_error.html
-[fnctxt_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn_ctxt/struct.FnCtxt.html#structfield.param_env
-[latectxt_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/context/struct.LateContext.html#structfield.param_env
-[wfckctxt_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/check/wfcheck/struct.WfCheckingCtxt.html#structfield.param_env
-[goal_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/canonical/ir/solve/struct.Goal.html#structfield.param_env
-[typerelation_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/trait.PredicateEmittingRelation.html#tymethod.param_env
-[typerelation]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/relate/trait.TypeRelation.html
-[mirtypeck_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/type_check/struct.TypeChecker.html#structfield.param_env
-[env_reveal_all_normalized]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.param_env_reveal_all_normalized
-[with_reveal_all]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html#method.with_reveal_all_normalized
-[env_reveal_all]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html#method.reveal_all
-[env_empty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html#method.empty
-[pe]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html
-[param_env_query]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn_ctxt/struct.FnCtxt.html#structfield.param_env
-[method_pred_entailment]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/check/compare_impl_item/fn.compare_method_predicate_entailment.html
diff --git a/src/doc/rustc-dev-guide/src/param_env/param_env_construction_internals.md b/src/doc/rustc-dev-guide/src/param_env/param_env_construction_internals.md
deleted file mode 100644
index 69a262a176e09..0000000000000
--- a/src/doc/rustc-dev-guide/src/param_env/param_env_construction_internals.md
+++ /dev/null
@@ -1,83 +0,0 @@
-
-# How are `ParamEnv`'s constructed internally?
-
-Creating a [`ParamEnv`][pe] is more complicated than simply using the list of where clauses defined on an item as written by the user. We need to both elaborate supertraits into the env and fully normalize all aliases. This logic is handled by [`traits::normalize_param_env_or_error`][normalize_env_or_error] (even though it does not mention anything about elaboration).
-
-## Elaborating supertraits
-
-When we have a function such as `fn foo<T: Copy>()` we would like to be able to prove `T: Clone` inside of the function as the `Copy` trait has a `Clone` supertrait. Constructing a `ParamEnv` looks at all of the trait bounds in the env and explicitly adds new where clauses to the `ParamEnv` for any supertraits found on the traits.
-
-A concrete example would be the following function:
-```rust
-trait Trait: SuperTrait {}
-trait SuperTrait: SuperSuperTrait {}
-
-// `bar`'s unelaborated `ParamEnv` would be:
-// `[T: Sized, T: Copy, T: Trait]`
-fn bar<T: Copy + Trait>(a: T) {
-    requires_impl(a);
-}
-
-fn requires_impl<T: Clone + SuperSuperTrait>(a: T) {}
-```
-
-If we did not elaborate the env then the `requires_impl` call would fail to typecheck as we would not be able to prove `T: Clone` or `T: SuperSuperTrait`. In practice we elaborate the env which means that `bar`'s `ParamEnv` is actually:
-`[T: Sized, T: Copy, T: Clone, T: Trait, T: SuperTrait, T: SuperSuperTrait]`
-This allows us to prove `T: Clone` and `T: SuperSuperTrait` when type checking `bar`.
-
-The `Clone` trait has a `Sized` supertrait however we do not end up with two `T: Sized` bounds in the env (one for the supertrait and one for the implicitly added `T: Sized` bound). This is because the elaboration process (implemented via [`util::elaborate`][elaborate]) deduplicates the where clauses to avoid this.
-
-As a side effect this also means that even if no actual elaboration of supertraits takes place, the existing where clauses in the env are _also_ deduplicated. See the following example:
-```rust
-trait Trait {}
-// The unelaborated `ParamEnv` would be:
-// `[T: Sized, T: Trait, T: Trait]`
-// but after elaboration it would be:
-// `[T: Sized, T: Trait]`
-fn foo<T: Trait + Trait>() {}
-```
-
-The [next-gen trait solver][next-gen-solver] also requires this elaboration to take place.
-
-[elaborate]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/traits/util/fn.elaborate.html
-[next-gen-solver]: ../solve/trait-solving.md
-
-## Normalizing all bounds
-
-In the old trait solver the where clauses stored in `ParamEnv` are required to be fully normalized or else the trait solver will not function correctly.  A concrete example of needing to normalize the `ParamEnv` is the following:
-```rust
-trait Trait<T> {
-    type Assoc;
-}
-
-trait Other {
-    type Bar;
-}
-
-impl<T> Other for T {
-    type Bar = u32;
-}
-
-// `foo`'s unnormalized `ParamEnv` would be:
-// `[T: Sized, U: Sized, U: Trait<T::Bar>]`
-fn foo<T, U>(a: U) 
-where
-    U: Trait<<T as Other>::Bar>,
-{
-    requires_impl(a);
-}
-
-fn requires_impl<U: Trait<u32>>(_: U) {}
-```
-
-As humans we can tell that `<T as Other>::Bar` is equal to `u32` so the trait bound on `U` is equivalent to `U: Trait<u32>`. In practice trying to prove `U: Trait<u32>` in the old solver in this environment would fail as it is unable to determine that `<T as Other>::Bar` is equal to `u32`.
-
-To work around this we normalize `ParamEnv`'s after constructing them so that `foo`'s `ParamEnv` is actually: `[T: Sized, U: Sized, U: Trait<u32>]` which means the trait solver is now able to use the `U: Trait<u32>` in the `ParamEnv` to determine that the trait bound `U: Trait<u32>` holds.
-
-This workaround does not work in all cases as normalizing associated types requires a `ParamEnv` which introduces a bootstrapping problem. We need a normalized `ParamEnv` in order for normalization to give correct results, but we need to normalize to get that `ParamEnv`. Currently we normalize the `ParamEnv` once using the unnormalized param env and it tends to give okay results in practice even though there are some examples where this breaks ([example]).
-
-In the next-gen trait solver the requirement for all where clauses in the `ParamEnv` to be fully normalized is not present and so we do not normalize when constructing `ParamEnv`s.
-
-[example]: https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=e6933265ea3e84eaa47019465739992c
-[pe]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html
-[normalize_env_or_error]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/fn.normalize_param_env_or_error.html
diff --git a/src/doc/rustc-dev-guide/src/param_env/param_env_summary.md b/src/doc/rustc-dev-guide/src/param_env/param_env_summary.md
deleted file mode 100644
index 0ff6d8fc394e2..0000000000000
--- a/src/doc/rustc-dev-guide/src/param_env/param_env_summary.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# The `ParamEnv` type
-
-## Summary
-
-The [`ParamEnv`][pe] is used to store information about the environment that we are interacting with the type system from. For example the set of in-scope where-clauses is stored in `ParamEnv` as it differs between each item whereas the list of user written impls is not stored in the `ParamEnv` as this does not change for each item.
-
-This chapter of the dev guide covers:
-- A high level summary of what a `ParamEnv` is and what it is used for
-- Technical details about what the process of constructing a `ParamEnv` involves
-- Guidance about how to acquire a `ParamEnv` when one is required
-
-## Bundling
-
-A useful API on `ParamEnv` is the [`and`][and] method which allows bundling a value with the `ParamEnv`. The `and` method produces a [`ParamEnvAnd<T>`][pea] making it clearer that using the inner value is intended to be done in that specific environment.
-
-[and]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html#method.and
-[pe]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html
-[pea]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnvAnd.html
\ No newline at end of file
diff --git a/src/doc/rustc-dev-guide/src/param_env/param_env_what_is_it.md b/src/doc/rustc-dev-guide/src/param_env/param_env_what_is_it.md
deleted file mode 100644
index 5c2f4d594052e..0000000000000
--- a/src/doc/rustc-dev-guide/src/param_env/param_env_what_is_it.md
+++ /dev/null
@@ -1,59 +0,0 @@
-
-# What is a `ParamEnv`?
-
-The type system relies on information in the environment in order for it to function correctly. This information is stored in the [`ParamEnv`][pe] type and it is important to use the correct `ParamEnv` when interacting with the type system.
-
-The information represented by `ParamEnv` is a list of in-scope where-clauses, and a `Reveal` (see linked docs for more information). A `ParamEnv` typically corresponds to a specific item's where clauses, some clauses are not explicitly written bounds and instead are implicitly added in [`predicates_of`][predicates_of] such as `ConstArgHasType` or some implied bounds.
-
-A `ParamEnv` can also be created with arbitrary data that is not derived from a specific item such as in [`compare_method_predicate_entailment`][method_pred_entailment] which creates a hybrid `ParamEnv` consisting of the impl's where clauses and the trait definition's function's where clauses. In most cases `ParamEnv`s are initially created via the [`param_env` query][query] which returns a `ParamEnv` derived from the provided item's where clauses.
-
-If we have a function such as:
-```rust
-// `foo` would have a `ParamEnv` of:
-// `[T: Sized, T: Trait, <T as Trait>::Assoc: Clone]`
-fn foo<T: Trait>()
-where
-    <T as Trait>::Assoc: Clone,
-{}
-```
-If we were conceptually inside of `foo` (for example, type-checking or linting it) we would use this `ParamEnv` everywhere that we interact with the type system. This would allow things such as normalization (TODO: write a chapter about normalization and link it), evaluating generic constants, and proving where clauses/goals, to rely on `T` being sized, implementing `Trait`, etc.
-
-A more concrete example:
-```rust
-// `foo` would have a `ParamEnv` of:
-// `[T: Sized, T: Clone]`
-fn foo<T: Clone>(a: T) {
-    // when typechecking `foo` we require all the where clauses on `bar`
-    // to hold in order for it to be legal to call. This means we have to
-    // prove `T: Clone`. As we are type checking `foo` we use `foo`'s
-    // environment when trying to check that `T: Clone` holds.
-    //
-    // Trying to prove `T: Clone` with a `ParamEnv` of `[T: Sized, T: Clone]`
-    // will trivially succeed as bound we want to prove is in our environment.
-    requires_clone(a);
-}
-```
-
-Or alternatively an example that would not compile:
-```rust
-// `foo2` would have a `ParamEnv` of:
-// `[T: Sized]`
-fn foo2<T>(a: T) {
-    // When typechecking `foo2` we attempt to prove `T: Clone`.
-    // As we are type checking `foo2` we use `foo2`'s environment
-    // when trying to prove `T: Clone`.
-    //
-    // Trying to prove `T: Clone` with a `ParamEnv` of `[T: Sized]` will
-    // fail as there is nothing in the environment telling the trait solver
-    // that `T` implements `Clone` and there exists no user written impl
-    // that could apply.
-    requires_clone(a);
-}
-```
-
-It's very important to use the correct `ParamEnv` when interacting with the type system as otherwise it can lead to ICEs or things compiling when they shouldn't (or vice versa). See [#82159](https://github.com/rust-lang/rust/pull/82159) and [#82067](https://github.com/rust-lang/rust/pull/82067) as examples of PRs that changed rustc to use the correct param env to avoid ICE. Determining how to acquire the correct `ParamEnv` is explained later in this chapter.
-
-[predicates_of]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/collect/predicates_of/fn.predicates_of.html
-[method_pred_entailment]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/check/compare_impl_item/fn.compare_method_predicate_entailment.html
-[pe]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html
-[query]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.param_env
diff --git a/src/doc/rustc-dev-guide/src/traits/caching.md b/src/doc/rustc-dev-guide/src/traits/caching.md
index a9f20969b5746..c44722a1d9a33 100644
--- a/src/doc/rustc-dev-guide/src/traits/caching.md
+++ b/src/doc/rustc-dev-guide/src/traits/caching.md
@@ -61,7 +61,7 @@ to be pretty clearly safe and also still retains a very high hit rate
 **TODO**: it looks like `pick_candidate_cache` no longer exists. In
 general, is this section still accurate at all?
 
-[`ParamEnv`]: ../param_env/param_env_summary.html
+[`ParamEnv`]: ../typing_parameter_envs.html
 [`tcx`]: ../ty.html
 [#18290]: https://github.com/rust-lang/rust/issues/18290
 [#22019]: https://github.com/rust-lang/rust/issues/22019
diff --git a/src/doc/rustc-dev-guide/src/traits/resolution.md b/src/doc/rustc-dev-guide/src/traits/resolution.md
index 26eb724588600..c62b0593694f1 100644
--- a/src/doc/rustc-dev-guide/src/traits/resolution.md
+++ b/src/doc/rustc-dev-guide/src/traits/resolution.md
@@ -183,7 +183,7 @@ in that list. If so, it is considered satisfied. More precisely, we
 want to check whether there is a where-clause obligation that is for
 the same trait (or some subtrait) and which can match against the obligation.
 
-[parameter environment]: ../param_env/param_env_summary.html
+[parameter environment]: ../typing_parameter_envs.html
 
 Consider this simple example:
 
diff --git a/src/doc/rustc-dev-guide/src/typing_parameter_envs.md b/src/doc/rustc-dev-guide/src/typing_parameter_envs.md
new file mode 100644
index 0000000000000..757296d1f6529
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/typing_parameter_envs.md
@@ -0,0 +1,206 @@
+# Typing/Parameter Environments
+
+<!-- toc -->
+
+## Typing Environments
+
+When interacting with the type system there are a few variables to consider that can affect the results of trait solving. The the set of in-scope where clauses, and what phase of the compiler type system operations are being performed in (the [`ParamEnv`][penv] and [`TypingMode`][tmode] structs respectively).
+
+When an environment to perform type system operations in has not yet been created, the [`TypingEnv`][tenv] can be used to bundle all of the external context required into a single type.
+
+Once a context to perform type system operations in has been created (e.g. an [`ObligationCtxt`][ocx] or [`FnCtxt`][fnctxt]) a `TypingEnv` is typically not stored anywhere as only the `TypingMode` is a property of the whole environment, whereas different `ParamEnv`s can be used on a per-goal basis.
+
+[ocx]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/struct.ObligationCtxt.html
+[fnctxt]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn_ctxt/struct.FnCtxt.html
+
+## Parameter Environemnts
+
+### What is a `ParamEnv`
+
+The [`ParamEnv`][penv] is a list of in-scope where-clauses, it typically corresponds to a specific item's where clauses. Some clauses are not explicitly written but are instead are implicitly added in the [`predicates_of`][predicates_of] query, such as `ConstArgHasType` or (some) implied bounds.
+
+In most cases `ParamEnv`s are initially created via the [`param_env` query][query] which returns a `ParamEnv` derived from the provided item's where clauses. A `ParamEnv` can also be created with arbitrary sets of clauses that are not derived from a specific item, such as in [`compare_method_predicate_entailment`][method_pred_entailment] where we create a hybrid `ParamEnv` consisting of the impl's where clauses and the trait definition's function's where clauses.
+
+---
+
+If we have a function such as:
+```rust
+// `foo` would have a `ParamEnv` of:
+// `[T: Sized, T: Trait, <T as Trait>::Assoc: Clone]`
+fn foo<T: Trait>()
+where
+    <T as Trait>::Assoc: Clone,
+{}
+```
+If we were conceptually inside of `foo` (for example, type-checking or linting it) we would use this `ParamEnv` everywhere that we interact with the type system. This would allow things such as normalization (TODO: write a chapter about normalization and link it), evaluating generic constants, and proving where clauses/goals, to rely on `T` being sized, implementing `Trait`, etc.
+
+A more concrete example:
+```rust
+// `foo` would have a `ParamEnv` of:
+// `[T: Sized, T: Clone]`
+fn foo<T: Clone>(a: T) {
+    // when typechecking `foo` we require all the where clauses on `requires_clone`
+    // to hold in order for it to be legal to call. This means we have to
+    // prove `T: Clone`. As we are type checking `foo` we use `foo`'s
+    // environment when trying to check that `T: Clone` holds.
+    //
+    // Trying to prove `T: Clone` with a `ParamEnv` of `[T: Sized, T: Clone]`
+    // will trivially succeed as bound we want to prove is in our environment.
+    requires_clone(a);
+}
+```
+
+Or alternatively an example that would not compile:
+```rust
+// `foo2` would have a `ParamEnv` of:
+// `[T: Sized]`
+fn foo2<T>(a: T) {
+    // When typechecking `foo2` we attempt to prove `T: Clone`.
+    // As we are type checking `foo2` we use `foo2`'s environment
+    // when trying to prove `T: Clone`.
+    //
+    // Trying to prove `T: Clone` with a `ParamEnv` of `[T: Sized]` will
+    // fail as there is nothing in the environment telling the trait solver
+    // that `T` implements `Clone` and there exists no user written impl
+    // that could apply.
+    requires_clone(a);
+}
+```
+
+[predicates_of]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/collect/predicates_of/fn.predicates_of.html
+[method_pred_entailment]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/check/compare_impl_item/fn.compare_method_predicate_entailment.html
+[query]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.param_env
+
+### Acquiring a `ParamEnv`
+
+Using the wrong [`ParamEnv`][penv] when interacting with the type system can lead to ICEs, illformed programs compiling, or erroing when we shouldn't. See [#82159](https://github.com/rust-lang/rust/pull/82159) and [#82067](https://github.com/rust-lang/rust/pull/82067) as examples of PRs that modified the compiler to use the correct param env and in the process fixed ICEs.
+
+In the large majority of cases, when a `ParamEnv` is required it either already exists somewhere in scope, or above in the call stack and should be passed down. A non exhaustive list of places where you might find an existing `ParamEnv`:
+- During typeck `FnCtxt` has a [`param_env` field][fnctxt_param_env]
+- When writing late lints the `LateContext` has a [`param_env` field][latectxt_param_env]
+- During well formedness checking the `WfCheckingCtxt` has a [`param_env` field][wfckctxt_param_env]
+- The `TypeChecker` used for MIR Typeck has a [`param_env` field][mirtypeck_param_env]
+- In the next-gen trait solver all `Goal`s have a [`param_env` field][goal_param_env] specifying what environment to prove the goal in
+- When editing an existing [`TypeRelation`][typerelation] if it implements [`PredicateEmittingRelation`][predicate_emitting_relation] then a [`param_env` method][typerelation_param_env] will be available.
+
+If you aren't sure if there's a `ParamEnv` in scope somewhere that can be used it can be worth opening a thread in the [`#t-compiler/help`][compiler_help] zulip stream where someone may be able to point out where a `ParamEnv` can be acquired from.
+
+Manually constructing a `ParamEnv` is typically only needed at the start of some kind of top level analysis (e.g. hir typeck or borrow checking). In such cases there are three ways it can be done:
+- Calling the [`tcx.param_env(def_id)` query][param_env_query] which returns the environment associated with a given definition.
+- Creating an empty environment with [`ParamEnv::empty`][env_empty].
+- Using [`ParamEnv::new`][param_env_new] to construct an env with an arbitrary set of where clauses. Then calling [`traits::normalize_param_env_or_error`][normalize_env_or_error] to handle normalizing and elaborating all the where clauses in the env.
+
+Using the `param_env` query is by far the most common way to construct a `ParamEnv` as most of the time the compiler is performing an analysis as part of some specific definition.
+
+Creating an empty environment with `ParamEnv::empty` is typically only done either in codegen (indirectly via [`TypingEnv::fully_monomorphized`][tenv_mono]), or as part of some analysis that do not expect to ever encounter generic parameters (e.g. various parts of coherence/orphan check).
+
+Creating an env from an arbitrary set of where clauses is usually unnecessary and should only be done if the environment you need does not correspond to an actual item in the source code (e.g. [`compare_method_predicate_entailment`][method_pred_entailment]).
+
+[param_env_new]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html#method.new
+[normalize_env_or_error]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/fn.normalize_param_env_or_error.html
+[fnctxt_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn_ctxt/struct.FnCtxt.html#structfield.param_env
+[latectxt_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/context/struct.LateContext.html#structfield.param_env
+[wfckctxt_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/check/wfcheck/struct.WfCheckingCtxt.html#structfield.param_env
+[goal_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/canonical/ir/solve/struct.Goal.html#structfield.param_env
+[typerelation_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/trait.PredicateEmittingRelation.html#tymethod.param_env
+[typerelation]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/relate/trait.TypeRelation.html
+[mirtypeck_param_env]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/type_check/struct.TypeChecker.html#structfield.param_env
+[env_empty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html#method.empty
+[param_env_query]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn_ctxt/struct.FnCtxt.html#structfield.param_env
+[method_pred_entailment]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/check/compare_impl_item/fn.compare_method_predicate_entailment.html
+[predicate_emitting_relation]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/relate/combine/trait.PredicateEmittingRelation.html
+[tenv_mono]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TypingEnv.html#method.fully_monomorphized
+[compiler_help]: https://rust-lang.zulipchat.com/#narrow/channel/182449-t-compiler.2Fhelp
+
+### How are `ParamEnv`s constructed
+
+Creating a [`ParamEnv`][pe] is more complicated than simply using the list of where clauses defined on an item as written by the user. We need to both elaborate supertraits into the env and fully normalize all aliases. This logic is handled by [`traits::normalize_param_env_or_error`][normalize_env_or_error] (even though it does not mention anything about elaboration).
+
+#### Elaborating supertraits
+
+When we have a function such as `fn foo<T: Copy>()` we would like to be able to prove `T: Clone` inside of the function as the `Copy` trait has a `Clone` supertrait. Constructing a `ParamEnv` looks at all of the trait bounds in the env and explicitly adds new where clauses to the `ParamEnv` for any supertraits found on the traits.
+
+A concrete example would be the following function:
+```rust
+trait Trait: SuperTrait {}
+trait SuperTrait: SuperSuperTrait {}
+
+// `bar`'s unelaborated `ParamEnv` would be:
+// `[T: Sized, T: Copy, T: Trait]`
+fn bar<T: Copy + Trait>(a: T) {
+    requires_impl(a);
+}
+
+fn requires_impl<T: Clone + SuperSuperTrait>(a: T) {}
+```
+
+If we did not elaborate the env then the `requires_impl` call would fail to typecheck as we would not be able to prove `T: Clone` or `T: SuperSuperTrait`. In practice we elaborate the env which means that `bar`'s `ParamEnv` is actually:
+`[T: Sized, T: Copy, T: Clone, T: Trait, T: SuperTrait, T: SuperSuperTrait]`
+This allows us to prove `T: Clone` and `T: SuperSuperTrait` when type checking `bar`.
+
+The `Clone` trait has a `Sized` supertrait however we do not end up with two `T: Sized` bounds in the env (one for the supertrait and one for the implicitly added `T: Sized` bound) as the elaboration process (implemented via [`util::elaborate`][elaborate]) deduplicates where clauses.
+
+A side effect of this is that even if no actual elaboration of supertraits takes place, the existing where clauses in the env are _also_ deduplicated. See the following example:
+```rust
+trait Trait {}
+// The unelaborated `ParamEnv` would be:
+// `[T: Sized, T: Trait, T: Trait]`
+// but after elaboration it would be:
+// `[T: Sized, T: Trait]`
+fn foo<T: Trait + Trait>() {}
+```
+
+The [next-gen trait solver][next-gen-solver] also requires this elaboration to take place.
+
+[elaborate]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/traits/util/fn.elaborate.html
+[next-gen-solver]: ./solve/trait-solving.md
+
+#### Normalizing all bounds
+
+In the old trait solver the where clauses stored in `ParamEnv` are required to be fully normalized as otherwise the trait solver will not function correctly. A concrete example of needing to normalize the `ParamEnv` is the following:
+```rust
+trait Trait<T> {
+    type Assoc;
+}
+
+trait Other {
+    type Bar;
+}
+
+impl<T> Other for T {
+    type Bar = u32;
+}
+
+// `foo`'s unnormalized `ParamEnv` would be:
+// `[T: Sized, U: Sized, U: Trait<T::Bar>]`
+fn foo<T, U>(a: U) 
+where
+    U: Trait<<T as Other>::Bar>,
+{
+    requires_impl(a);
+}
+
+fn requires_impl<U: Trait<u32>>(_: U) {}
+```
+
+As humans we can tell that `<T as Other>::Bar` is equal to `u32` so the trait bound on `U` is equivalent to `U: Trait<u32>`. In practice trying to prove `U: Trait<u32>` in the old solver in this environment would fail as it is unable to determine that `<T as Other>::Bar` is equal to `u32`.
+
+To work around this we normalize `ParamEnv`'s after constructing them so that `foo`'s `ParamEnv` is actually: `[T: Sized, U: Sized, U: Trait<u32>]` which means the trait solver is now able to use the `U: Trait<u32>` in the `ParamEnv` to determine that the trait bound `U: Trait<u32>` holds.
+
+This workaround does not work in all cases as normalizing associated types requires a `ParamEnv` which introduces a bootstrapping problem. We need a normalized `ParamEnv` in order for normalization to give correct results, but we need to normalize to get that `ParamEnv`. Currently we normalize the `ParamEnv` once using the unnormalized param env and it tends to give okay results in practice even though there are some examples where this breaks ([example]).
+
+In the next-gen trait solver the requirement for all where clauses in the `ParamEnv` to be fully normalized is not present and so we do not normalize when constructing `ParamEnv`s.
+
+[example]: https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=e6933265ea3e84eaa47019465739992c
+[pe]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html
+[normalize_env_or_error]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/fn.normalize_param_env_or_error.html
+
+## Typing Modes
+
+Depending on what context we are performing type system operations in, different behaviour may be required. For example during coherence there are stronger requirements about when we can consider goals to not hold or when we can consider types to be unequal.
+
+Tracking which "phase" of the compiler type system operations are being performed in is done by the [`TypingMode`][tenv] enum. The documentation on the `TypingMode` enum is quite good so instead of repeating it here verbatim we would recommend reading the API documentation directly.
+
+[penv]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html
+[tenv]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/infer_ctxt/enum.TypingMode.html
+[tmode]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/type.TypingMode.html

From 957aacd036d787e744a221e9a0d42d7811761a6e Mon Sep 17 00:00:00 2001
From: Jieyou Xu <jieyouxu@outlook.com>
Date: Fri, 21 Mar 2025 16:18:43 +0800
Subject: [PATCH 19/39] Move Fuchsia and RfL under `ecosystem-test-jobs/`
 folder

Includes redirects to avoid breaking existing links.
---
 src/doc/rustc-dev-guide/book.toml                             | 4 +++-
 src/doc/rustc-dev-guide/src/SUMMARY.md                        | 4 ++--
 src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md    | 2 +-
 .../src/tests/{ => ecosystem-test-jobs}/fuchsia.md            | 4 ++--
 .../src/tests/{ => ecosystem-test-jobs}/rust-for-linux.md     | 2 +-
 src/doc/rustc-dev-guide/src/tests/ecosystem.md                | 4 ++--
 6 files changed, 11 insertions(+), 9 deletions(-)
 rename src/doc/rustc-dev-guide/src/tests/{ => ecosystem-test-jobs}/fuchsia.md (98%)
 rename src/doc/rustc-dev-guide/src/tests/{ => ecosystem-test-jobs}/rust-for-linux.md (97%)

diff --git a/src/doc/rustc-dev-guide/book.toml b/src/doc/rustc-dev-guide/book.toml
index 67069d9930f57..eb2f6806b96fc 100644
--- a/src/doc/rustc-dev-guide/book.toml
+++ b/src/doc/rustc-dev-guide/book.toml
@@ -62,5 +62,7 @@ warning-policy = "error"
 "/diagnostics/sessiondiagnostic.html" = "diagnostic-structs.html"
 "/diagnostics/diagnostic-codes.html" = "error-codes.html"
 "/miri.html" = "const-eval/interpret.html"
-"/tests/integration.html" = "ecosystem.html"
+"/tests/fuchsia.html" = "ecosystem-test-jobs/fuchsia.html"
 "/tests/headers.html" = "directives.html"
+"/tests/integration.html" = "ecosystem.html"
+"/tests/rust-for-linux.html" = "ecosystem-test-jobs/rust-for-linux.html"
diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index 075d5af4c24a5..8fc4fd33e5a3e 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -28,8 +28,8 @@
         - [Minicore](./tests/minicore.md)
     - [Ecosystem testing](./tests/ecosystem.md)
         - [Crater](./tests/crater.md)
-        - [Fuchsia](./tests/fuchsia.md)
-        - [Rust for Linux](./tests/rust-for-linux.md)
+        - [Fuchsia](./tests/ecosystem-test-jobs/fuchsia.md)
+        - [Rust for Linux](./tests/ecosystem-test-jobs/rust-for-linux.md)
     - [Performance testing](./tests/perf.md)
     - [Suggest tests tool](./tests/suggest-tests.md)
     - [Misc info](./tests/misc.md)
diff --git a/src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md b/src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md
index a4658e0d842f9..e3c1a7148d3c7 100644
--- a/src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md
+++ b/src/doc/rustc-dev-guide/src/notification-groups/fuchsia.md
@@ -9,4 +9,4 @@ This list will be used to notify [Fuchsia][fuchsia] maintainers
 when the compiler or the standard library changes in a way that would
 break the Fuchsia integration.
 
-[fuchsia]: ../tests/fuchsia.md
+[fuchsia]: ../tests/ecosystem-test-jobs/fuchsia.md
diff --git a/src/doc/rustc-dev-guide/src/tests/fuchsia.md b/src/doc/rustc-dev-guide/src/tests/ecosystem-test-jobs/fuchsia.md
similarity index 98%
rename from src/doc/rustc-dev-guide/src/tests/fuchsia.md
rename to src/doc/rustc-dev-guide/src/tests/ecosystem-test-jobs/fuchsia.md
index 2766c362cc266..b19d94d6ff734 100644
--- a/src/doc/rustc-dev-guide/src/tests/fuchsia.md
+++ b/src/doc/rustc-dev-guide/src/tests/ecosystem-test-jobs/fuchsia.md
@@ -40,7 +40,7 @@ using your local Rust toolchain.
 src/ci/docker/run.sh x86_64-fuchsia
 ```
 
-See the [Testing with Docker](docker.md) chapter for more details on how to run
+See the [Testing with Docker](../docker.md) chapter for more details on how to run
 and debug jobs with Docker.
 
 Note that a Fuchsia checkout is *large* – as of this writing, a checkout and
@@ -170,7 +170,7 @@ rustc book][platform-support].
 [`public_configs`]: https://gn.googlesource.com/gn/+/main/docs/reference.md#var_public_configs
 [`//build/config:compiler`]: https://cs.opensource.google/fuchsia/fuchsia/+/main:build/config/BUILD.gn;l=121;drc=c26c473bef93b33117ae417893118907a026fec7
 [build system]: https://fuchsia.dev/fuchsia-src/development/build/build_system
-[fuchsia-ping]: ../notification-groups/fuchsia.md
+[fuchsia-ping]: ../../notification-groups/fuchsia.md
 
 [^loc]: As of June 2024, Fuchsia had about 2 million lines of first-party Rust
 code and a roughly equal amount of third-party code, as counted by tokei
diff --git a/src/doc/rustc-dev-guide/src/tests/rust-for-linux.md b/src/doc/rustc-dev-guide/src/tests/ecosystem-test-jobs/rust-for-linux.md
similarity index 97%
rename from src/doc/rustc-dev-guide/src/tests/rust-for-linux.md
rename to src/doc/rustc-dev-guide/src/tests/ecosystem-test-jobs/rust-for-linux.md
index bdf32ffc398db..d549ec6fca529 100644
--- a/src/doc/rustc-dev-guide/src/tests/rust-for-linux.md
+++ b/src/doc/rustc-dev-guide/src/tests/ecosystem-test-jobs/rust-for-linux.md
@@ -48,4 +48,4 @@ line to your PR description:
 Then when you `@bors try` it will pick the job that builds the Rust for Linux
 integration.
 
-[rfl-ping]: ../notification-groups/rust-for-linux.md
+[rfl-ping]: ../../notification-groups/rust-for-linux.md
diff --git a/src/doc/rustc-dev-guide/src/tests/ecosystem.md b/src/doc/rustc-dev-guide/src/tests/ecosystem.md
index 083601404255b..f4b93492e0053 100644
--- a/src/doc/rustc-dev-guide/src/tests/ecosystem.md
+++ b/src/doc/rustc-dev-guide/src/tests/ecosystem.md
@@ -24,5 +24,5 @@ there aren't any significant regressions.
 We have CI jobs that build large open-source Rust projects that are used as
 regression tests in CI. Our integration jobs build the following projects:
 
-- [Fuchsia](fuchsia.md)
-- [Rust for Linux](rust-for-linux.md)
+- [Fuchsia](./ecosystem-test-jobs/fuchsia.md)
+- [Rust for Linux](./ecosystem-test-jobs/rust-for-linux.md)

From d58ccd86c2353bcf22daee05ed44dc0780121c62 Mon Sep 17 00:00:00 2001
From: Jieyou Xu <jieyouxu@outlook.com>
Date: Fri, 21 Mar 2025 16:35:46 +0800
Subject: [PATCH 20/39] Stub out codegen backend test pages

---
 src/doc/rustc-dev-guide/src/SUMMARY.md              |  3 +++
 .../src/tests/codegen-backend-tests/cg_clif.md      |  3 +++
 .../src/tests/codegen-backend-tests/cg_gcc.md       |  3 +++
 .../src/tests/codegen-backend-tests/intro.md        | 13 +++++++++++++
 src/doc/rustc-dev-guide/src/tests/intro.md          |  8 ++++++--
 5 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_clif.md
 create mode 100644 src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md
 create mode 100644 src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index 8fc4fd33e5a3e..29085a6e85334 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -30,6 +30,9 @@
         - [Crater](./tests/crater.md)
         - [Fuchsia](./tests/ecosystem-test-jobs/fuchsia.md)
         - [Rust for Linux](./tests/ecosystem-test-jobs/rust-for-linux.md)
+    - [Codegen backend testing](./tests/codegen-backend-tests/intro.md)
+        - [Cranelift codegen backend](./tests/codegen-backend-tests/cg_clif.md)
+        - [GCC codegen backend](./tests/codegen-backend-tests/cg_gcc.md)
     - [Performance testing](./tests/perf.md)
     - [Suggest tests tool](./tests/suggest-tests.md)
     - [Misc info](./tests/misc.md)
diff --git a/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_clif.md b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_clif.md
new file mode 100644
index 0000000000000..030ddd7dff571
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_clif.md
@@ -0,0 +1,3 @@
+# Cranelift codegen backend tests
+
+TODO: please add some more information to this page.
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
new file mode 100644
index 0000000000000..4caf4c0e0eefa
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/cg_gcc.md
@@ -0,0 +1,3 @@
+# GCC codegen backend tests
+
+TODO: please add some more information to this page.
diff --git a/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md
new file mode 100644
index 0000000000000..c4bac26aba2c2
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md
@@ -0,0 +1,13 @@
+# Codegen backend testing
+
+See also the [Code generation](../../../src/backend/codegen.md) chapter.
+
+In addition to the primary LLVM codegen backend, the rust-lang/rust CI also runs tests of the [cranelift][cg_clif] and [GCC][cg_gcc] codegen backends in certain test jobs.
+
+For more details on the tests involved, see:
+
+- [Cranelift codegen backend tests](./cg_clif.md)
+- [GCC codegen backend tests](./cg_gcc.md)
+
+[cg_clif]: https://github.com/rust-lang/rustc_codegen_cranelift
+[cg_gcc]: https://github.com/rust-lang/rustc_codegen_gcc
diff --git a/src/doc/rustc-dev-guide/src/tests/intro.md b/src/doc/rustc-dev-guide/src/tests/intro.md
index ba44a969bf950..7bf30b106b43b 100644
--- a/src/doc/rustc-dev-guide/src/tests/intro.md
+++ b/src/doc/rustc-dev-guide/src/tests/intro.md
@@ -38,7 +38,7 @@ directory, and `x` will essentially run `cargo test` on that package.
 Examples:
 
 | Command                                   | Description                           |
-| ----------------------------------------- | ------------------------------------- |
+|-------------------------------------------|---------------------------------------|
 | `./x test library/std`                    | Runs tests on `std` only              |
 | `./x test library/core`                   | Runs tests on `core` only             |
 | `./x test compiler/rustc_data_structures` | Runs tests on `rustc_data_structures` |
@@ -86,7 +86,7 @@ above.
 Examples:
 
 | Command                 | Description                                                        |
-| ----------------------- | ------------------------------------------------------------------ |
+|-------------------------|--------------------------------------------------------------------|
 | `./x fmt --check`       | Checks formatting and exits with an error if formatting is needed. |
 | `./x fmt`               | Runs rustfmt across the entire codebase.                           |
 | `./x test tidy --bless` | First runs rustfmt to format the codebase, then runs tidy checks.  |
@@ -155,6 +155,10 @@ chapter](ecosystem.md) for more details.
 A separate infrastructure is used for testing and tracking performance of the
 compiler. See the [Performance testing chapter](perf.md) for more details.
 
+### Codegen backend testing
+
+See [Codegen backend testing](./codegen-backend-tests/intro.md).
+
 ## Miscellaneous information
 
 There are some other useful testing-related info at [Misc info](misc.md).

From ee6a1598268e07cf1fbecc6ad1c2d5a5db593fb4 Mon Sep 17 00:00:00 2001
From: Chiichen <chiichen@qq.com>
Date: Sun, 23 Mar 2025 12:34:41 +0800
Subject: [PATCH 21/39] doc: fix reference to #create-a-configtoml

---
 src/doc/rustc-dev-guide/src/building/prerequisites.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/building/prerequisites.md b/src/doc/rustc-dev-guide/src/building/prerequisites.md
index f49f6bb052789..6761cabac1f14 100644
--- a/src/doc/rustc-dev-guide/src/building/prerequisites.md
+++ b/src/doc/rustc-dev-guide/src/building/prerequisites.md
@@ -38,4 +38,4 @@ incremental compilation ([see here][config]). This will make compilation take
 longer (especially after a rebase), but will save a ton of space from the
 incremental caches.
 
-[config]: ./how-to-build-and-run.md#create-a-configtoml
+[config]: ./how-to-build-and-run.md#create-a-bootstraptoml

From de8b6beac8710f6391e1fe99f774ba99bb0f54ac Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <tshepang@gmail.com>
Date: Mon, 24 Mar 2025 10:40:03 +0200
Subject: [PATCH 22/39] add needed break

---
 .../src/rustdoc-internals/rustdoc-test-suite.md                | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
index c2a2e6495f82c..471dd29f74fba 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
@@ -1,6 +1,7 @@
 # The `rustdoc` test suite
 
-This page is specifically about the test suite named `rustdoc`, for other test suites used for testing rustdoc, see [Rustdoc tests](../rustdoc.md#tests).
+This page is specifically about the test suite named `rustdoc`.
+For other test suites used for testing rustdoc, see [Rustdoc tests](../rustdoc.md#tests).
 
 The `rustdoc` test suite is specifically used to test the HTML output of rustdoc.
 

From 62ec34bf5b254a3470fe74042a0ad2a53e56baed Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <tshepang@gmail.com>
Date: Mon, 24 Mar 2025 10:41:19 +0200
Subject: [PATCH 23/39] typo

---
 .../rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
index 471dd29f74fba..169b95a7e1adc 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-test-suite.md
@@ -5,7 +5,7 @@ For other test suites used for testing rustdoc, see [Rustdoc tests](../rustdoc.m
 
 The `rustdoc` test suite is specifically used to test the HTML output of rustdoc.
 
-This is achived by means of `htmldocck.py`, a custom checker script that leverages [XPath].
+This is achieved by means of `htmldocck.py`, a custom checker script that leverages [XPath].
 
 [XPath]: https://en.wikipedia.org/wiki/XPath
 

From a9a21bde85b41f19fe46b3cd06601829ed842d8f Mon Sep 17 00:00:00 2001
From: mejrs <59372212+mejrs@users.noreply.github.com>
Date: Thu, 27 Mar 2025 18:32:48 +0100
Subject: [PATCH 24/39] Delete from_method from rustc_on_unimplemented
 documentation

---
 src/doc/rustc-dev-guide/src/diagnostics.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/diagnostics.md b/src/doc/rustc-dev-guide/src/diagnostics.md
index 972309b5cd343..6f72ea902f5d6 100644
--- a/src/doc/rustc-dev-guide/src/diagnostics.md
+++ b/src/doc/rustc-dev-guide/src/diagnostics.md
@@ -954,9 +954,6 @@ application of these fields based on a variety of attributes when using
    `Self="std::iter::Iterator<char>"`. This is needed because `Self` is a
    keyword which cannot appear in attributes.
  - `direct`: user-specified rather than derived obligation.
- - `from_method`: usable both as boolean (whether the flag is present, like
-   `crate_local`) or matching against a particular method. Currently used
-   for `try`.
  - `from_desugaring`: usable both as boolean (whether the flag is present)
    or matching against a particular desugaring. The desugaring is identified
    with its variant name in the `DesugaringKind` enum.

From cdbb219f835ebb3dad05a02c48afa10c33f21f2b Mon Sep 17 00:00:00 2001
From: Santiago Pastorino <spastorino@gmail.com>
Date: Fri, 28 Mar 2025 12:38:32 -0300
Subject: [PATCH 25/39] Fix code generation link

---
 .../rustc-dev-guide/src/tests/codegen-backend-tests/intro.md    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md
index c4bac26aba2c2..6bf46ddcd21a6 100644
--- a/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md
+++ b/src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md
@@ -1,6 +1,6 @@
 # Codegen backend testing
 
-See also the [Code generation](../../../src/backend/codegen.md) chapter.
+See also the [Code generation](../../backend/codegen.md) chapter.
 
 In addition to the primary LLVM codegen backend, the rust-lang/rust CI also runs tests of the [cranelift][cg_clif] and [GCC][cg_gcc] codegen backends in certain test jobs.
 

From 40b1f4899a9081c0d8edf56072aaeb510b63a415 Mon Sep 17 00:00:00 2001
From: Mara Bos <m-ou.se@m-ou.se>
Date: Fri, 28 Mar 2025 18:32:12 +0100
Subject: [PATCH 26/39] Add the feature gate for the `super let` experiment.

---
 compiler/rustc_ast_passes/src/feature_gate.rs     |  1 +
 compiler/rustc_feature/src/unstable.rs            |  2 ++
 compiler/rustc_parse/src/parser/stmt.rs           | 15 ++++++++++++++-
 compiler/rustc_parse/src/parser/token_type.rs     |  4 ++++
 compiler/rustc_span/src/symbol.rs                 |  1 +
 tests/ui/feature-gates/feature-gate-super-let.rs  |  4 ++++
 .../feature-gates/feature-gate-super-let.stderr   | 13 +++++++++++++
 7 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 tests/ui/feature-gates/feature-gate-super-let.rs
 create mode 100644 tests/ui/feature-gates/feature-gate-super-let.stderr

diff --git a/compiler/rustc_ast_passes/src/feature_gate.rs b/compiler/rustc_ast_passes/src/feature_gate.rs
index 31ff102c127a3..4f50e21fc7d08 100644
--- a/compiler/rustc_ast_passes/src/feature_gate.rs
+++ b/compiler/rustc_ast_passes/src/feature_gate.rs
@@ -505,6 +505,7 @@ pub fn check_crate(krate: &ast::Crate, sess: &Session, features: &Features) {
     gate_all!(contracts, "contracts are incomplete");
     gate_all!(contracts_internals, "contract internal machinery is for internal use only");
     gate_all!(where_clause_attrs, "attributes in `where` clause are unstable");
+    gate_all!(super_let, "`super let` is experimental");
 
     if !visitor.features.never_patterns() {
         if let Some(spans) = spans.get(&sym::never_patterns) {
diff --git a/compiler/rustc_feature/src/unstable.rs b/compiler/rustc_feature/src/unstable.rs
index 72468dd4714d7..b4499fb2a6a41 100644
--- a/compiler/rustc_feature/src/unstable.rs
+++ b/compiler/rustc_feature/src/unstable.rs
@@ -630,6 +630,8 @@ declare_features! (
     (unstable, strict_provenance_lints, "1.61.0", Some(130351)),
     /// Allows string patterns to dereference values to match them.
     (unstable, string_deref_patterns, "1.67.0", Some(87121)),
+    /// Allows `super let` statements.
+    (unstable, super_let, "CURRENT_RUSTC_VERSION", Some(139076)),
     /// Allows subtrait items to shadow supertrait items.
     (unstable, supertrait_item_shadowing, "1.86.0", Some(89151)),
     /// Allows using `#[thread_local]` on `static` items.
diff --git a/compiler/rustc_parse/src/parser/stmt.rs b/compiler/rustc_parse/src/parser/stmt.rs
index 97cd4d2117f87..2cd09aa8959c4 100644
--- a/compiler/rustc_parse/src/parser/stmt.rs
+++ b/compiler/rustc_parse/src/parser/stmt.rs
@@ -73,7 +73,20 @@ impl<'a> Parser<'a> {
             });
         }
 
-        let stmt = if self.token.is_keyword(kw::Let) {
+        let stmt = if self.token.is_keyword(kw::Super) && self.is_keyword_ahead(1, &[kw::Let]) {
+            self.collect_tokens(None, attrs, force_collect, |this, attrs| {
+                this.expect_keyword(exp!(Super))?;
+                this.psess.gated_spans.gate(sym::super_let, this.prev_token.span);
+                this.expect_keyword(exp!(Let))?;
+                let local = this.parse_local(attrs)?; // FIXME(mara): implement super let
+                let trailing = Trailing::from(capture_semi && this.token == token::Semi);
+                Ok((
+                    this.mk_stmt(lo.to(this.prev_token.span), StmtKind::Let(local)),
+                    trailing,
+                    UsePreAttrPos::No,
+                ))
+            })?
+        } else if self.token.is_keyword(kw::Let) {
             self.collect_tokens(None, attrs, force_collect, |this, attrs| {
                 this.expect_keyword(exp!(Let))?;
                 let local = this.parse_local(attrs)?;
diff --git a/compiler/rustc_parse/src/parser/token_type.rs b/compiler/rustc_parse/src/parser/token_type.rs
index 886438fd583a3..add3c9702019c 100644
--- a/compiler/rustc_parse/src/parser/token_type.rs
+++ b/compiler/rustc_parse/src/parser/token_type.rs
@@ -114,6 +114,7 @@ pub enum TokenType {
     KwSelfUpper,
     KwStatic,
     KwStruct,
+    KwSuper,
     KwTrait,
     KwTry,
     KwType,
@@ -250,6 +251,7 @@ impl TokenType {
             KwSelfUpper,
             KwStatic,
             KwStruct,
+            KwSuper,
             KwTrait,
             KwTry,
             KwType,
@@ -324,6 +326,7 @@ impl TokenType {
             TokenType::KwSelfUpper => Some(kw::SelfUpper),
             TokenType::KwStatic => Some(kw::Static),
             TokenType::KwStruct => Some(kw::Struct),
+            TokenType::KwSuper => Some(kw::Super),
             TokenType::KwTrait => Some(kw::Trait),
             TokenType::KwTry => Some(kw::Try),
             TokenType::KwType => Some(kw::Type),
@@ -549,6 +552,7 @@ macro_rules! exp {
     (SelfUpper)      => { exp!(@kw, SelfUpper,  KwSelfUpper) };
     (Static)         => { exp!(@kw, Static,     KwStatic) };
     (Struct)         => { exp!(@kw, Struct,     KwStruct) };
+    (Super)          => { exp!(@kw, Super,      KwSuper) };
     (Trait)          => { exp!(@kw, Trait,      KwTrait) };
     (Try)            => { exp!(@kw, Try,        KwTry) };
     (Type)           => { exp!(@kw, Type,       KwType) };
diff --git a/compiler/rustc_span/src/symbol.rs b/compiler/rustc_span/src/symbol.rs
index 6807f96e712cd..cc1b324eb00d3 100644
--- a/compiler/rustc_span/src/symbol.rs
+++ b/compiler/rustc_span/src/symbol.rs
@@ -2036,6 +2036,7 @@ symbols! {
         sub_assign,
         sub_with_overflow,
         suggestion,
+        super_let,
         supertrait_item_shadowing,
         surface_async_drop_in_place,
         sym,
diff --git a/tests/ui/feature-gates/feature-gate-super-let.rs b/tests/ui/feature-gates/feature-gate-super-let.rs
new file mode 100644
index 0000000000000..cfe92a42669d1
--- /dev/null
+++ b/tests/ui/feature-gates/feature-gate-super-let.rs
@@ -0,0 +1,4 @@
+fn main() {
+    super let a = 1;
+    //~^ ERROR `super let` is experimental
+}
diff --git a/tests/ui/feature-gates/feature-gate-super-let.stderr b/tests/ui/feature-gates/feature-gate-super-let.stderr
new file mode 100644
index 0000000000000..a64e1b374f9c0
--- /dev/null
+++ b/tests/ui/feature-gates/feature-gate-super-let.stderr
@@ -0,0 +1,13 @@
+error[E0658]: `super let` is experimental
+  --> $DIR/feature-gate-super-let.rs:2:5
+   |
+LL |     super let a = 1;
+   |     ^^^^^
+   |
+   = note: see issue #139076 <https://github.com/rust-lang/rust/issues/139076> for more information
+   = help: add `#![feature(super_let)]` to the crate attributes to enable
+   = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
+
+error: aborting due to 1 previous error
+
+For more information about this error, try `rustc --explain E0658`.

From 5952f01712521d6700a58eeb0ad8b25db7c8fd68 Mon Sep 17 00:00:00 2001
From: Samuel Tardieu <sam@rfc1149.net>
Date: Fri, 28 Mar 2025 20:10:31 +0100
Subject: [PATCH 27/39] Fix trivial typo of `BoundVariableKind`

---
 src/doc/rustc-dev-guide/src/ty_module/binders.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/ty_module/binders.md b/src/doc/rustc-dev-guide/src/ty_module/binders.md
index defb7cde514a0..71157eca9b11e 100644
--- a/src/doc/rustc-dev-guide/src/ty_module/binders.md
+++ b/src/doc/rustc-dev-guide/src/ty_module/binders.md
@@ -40,7 +40,7 @@ We did not always explicitly track the set of bound vars introduced by each `Bin
 ```
 Binder(
     fn(&'^1_0 &'^1 T/#0),
-    &[BoundVariarbleKind::Region(...)],
+    &[BoundVariableKind::Region(...)],
 )
 ```
 This would cause all kinds of issues as the region `'^1_0` refers to a binder at a higher level than the outermost binder i.e. it is an escaping bound var. The `'^1` region (also writeable as `'^0_1`) is also ill formed as the binder it refers to does not introduce a second parameter. Modern day rustc will ICE when constructing this binder due to both of those regions, in the past we would have simply allowed this to work and then ran into issues in other parts of the codebase. 

From 865a5a7e164950cf728439d12efb762e29c46c2c Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <tshepang@gmail.com>
Date: Sat, 29 Mar 2025 20:02:01 +0200
Subject: [PATCH 28/39] mention that know-bug test directive takes arguments

---
 src/doc/rustc-dev-guide/src/tests/ui.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/doc/rustc-dev-guide/src/tests/ui.md b/src/doc/rustc-dev-guide/src/tests/ui.md
index c8536b0045cfd..728ea3de418a6 100644
--- a/src/doc/rustc-dev-guide/src/tests/ui.md
+++ b/src/doc/rustc-dev-guide/src/tests/ui.md
@@ -415,6 +415,14 @@ reasons, including:
    can alert the developer so they know that the associated issue has been fixed
    and can possibly be closed.
 
+This directive takes comma-separated issue numbers as arguments, or `"unknown"`:
+
+- `//@ known-bug: #123, #456` (when the issues are on rust-lang/rust)
+- `//@ known-bug: rust-lang/chalk#123456`
+  (allows arbitrary text before the `#`, which is useful when the issue is on another repo)
+- `//@ known-bug: unknown`
+  (when there is no known issue yet; preferrably open one if it does not already exist)
+
 Do not include [error annotations](#error-annotations) in a test with
 `known-bug`. The test should still include other normal directives and
 stdout/stderr files.

From 1faf7ff9a434de8995e97e7372408489ce87050e Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <tshepang@gmail.com>
Date: Sat, 29 Mar 2025 23:52:57 +0200
Subject: [PATCH 29/39] update rustc-{driver,interface} examples

---
 .../rustc-dev-guide/examples/rustc-driver-example.rs  | 11 +++++------
 .../examples/rustc-driver-interacting-with-the-ast.rs |  4 ++--
 .../examples/rustc-interface-example.rs               |  8 ++++----
 .../examples/rustc-interface-getting-diagnostics.rs   |  2 +-
 4 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
index 35dd07dd13657..fb8b13ad154ce 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
@@ -1,4 +1,4 @@
-// Tested with nightly-2025-03-08
+// Tested with nightly-2025-03-28
 
 #![feature(rustc_private)]
 
@@ -20,7 +20,7 @@ use std::path::Path;
 use std::sync::Arc;
 
 use rustc_ast_pretty::pprust::item_to_string;
-use rustc_driver::{Compilation, run_compiler};
+use rustc_driver::{run_compiler, Compilation};
 use rustc_interface::interface::{Compiler, Config};
 use rustc_middle::ty::TyCtxt;
 
@@ -71,13 +71,12 @@ impl rustc_driver::Callbacks for MyCallbacks {
 
     fn after_analysis(&mut self, _compiler: &Compiler, tcx: TyCtxt<'_>) -> Compilation {
         // Analyze the program and inspect the types of definitions.
-        for id in tcx.hir_free_items(){
+        for id in tcx.hir_free_items() {
             let item = &tcx.hir_item(id);
             match item.kind {
-                rustc_hir::ItemKind::Static(_, _, _) | rustc_hir::ItemKind::Fn { .. } => {
-                    let name = item.ident;
+                rustc_hir::ItemKind::Static(ident, ..) | rustc_hir::ItemKind::Fn { ident, .. } => {
                     let ty = tcx.type_of(item.hir_id().owner.def_id);
-                    println!("{name:?}:\t{ty:?}")
+                    println!("{ident:?}:\t{ty:?}")
                 }
                 _ => (),
             }
diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
index 2a43ba476e1ea..b0c62d5b4bbb0 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
@@ -1,4 +1,4 @@
-// Tested with nightly-2025-03-08
+// Tested with nightly-2025-03-28
 
 #![feature(rustc_private)]
 
@@ -71,7 +71,7 @@ impl rustc_driver::Callbacks for MyCallbacks {
 
     fn after_analysis(&mut self, _compiler: &Compiler, tcx: TyCtxt<'_>) -> Compilation {
         // Iterate over the top-level items in the crate, looking for the main function.
-        for id in tcx.hir_free_items(){
+        for id in tcx.hir_free_items() {
             let item = &tcx.hir_item(id);
             // Use pattern-matching to find a specific node inside the main function.
             if let rustc_hir::ItemKind::Fn { body, .. } = item.kind {
diff --git a/src/doc/rustc-dev-guide/examples/rustc-interface-example.rs b/src/doc/rustc-dev-guide/examples/rustc-interface-example.rs
index 11125caec7040..360f70c8e865a 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-interface-example.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-interface-example.rs
@@ -1,4 +1,4 @@
-// Tested with nightly-2025-03-08
+// Tested with nightly-2025-03-28
 
 #![feature(rustc_private)]
 
@@ -67,10 +67,10 @@ fn main() {
             for id in tcx.hir_free_items() {
                 let item = tcx.hir_item(id);
                 match item.kind {
-                    rustc_hir::ItemKind::Static(_, _, _) | rustc_hir::ItemKind::Fn { .. } => {
-                        let name = item.ident;
+                    rustc_hir::ItemKind::Static(ident, ..)
+                    | rustc_hir::ItemKind::Fn { ident, .. } => {
                         let ty = tcx.type_of(item.hir_id().owner.def_id);
-                        println!("{name:?}:\t{ty:?}")
+                        println!("{ident:?}:\t{ty:?}")
                     }
                     _ => (),
                 }
diff --git a/src/doc/rustc-dev-guide/examples/rustc-interface-getting-diagnostics.rs b/src/doc/rustc-dev-guide/examples/rustc-interface-getting-diagnostics.rs
index 9bb93ab495878..2512ba3c3f924 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-interface-getting-diagnostics.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-interface-getting-diagnostics.rs
@@ -1,4 +1,4 @@
-// Tested with nightly-2025-03-08
+// Tested with nightly-2025-03-28
 
 #![feature(rustc_private)]
 

From 471a2a8b87d8b5ba03a43a2c067dd322c1f5e7af Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <tshepang@gmail.com>
Date: Sun, 30 Mar 2025 00:16:39 +0200
Subject: [PATCH 30/39] example assumes a static exists

This was removed, likely by mistake, during a refactor.
---
 src/doc/rustc-dev-guide/examples/rustc-driver-example.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
index fb8b13ad154ce..0e3450086ba5b 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
@@ -34,9 +34,9 @@ impl rustc_span::source_map::FileLoader for MyFileLoader {
     fn read_file(&self, path: &Path) -> io::Result<String> {
         if path == Path::new("main.rs") {
             Ok(r#"
+static MESSAGE: &str = "Hello, World!";
 fn main() {
-    let message = "Hello, World!";
-    println!("{message}");
+    println!("{MESSAGE}");
 }
 "#
             .to_string())

From 9302f4d94f97750e84a47eaf5ac180feaaaafa3a Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <tshepang@gmail.com>
Date: Sun, 30 Mar 2025 00:31:44 +0200
Subject: [PATCH 31/39] add rustfmt settings file

---
 .../rustc-dev-guide/ci/date-check/src/main.rs | 155 ++++--------------
 .../examples/rustc-driver-example.rs          |   2 +-
 .../rustc-driver-interacting-with-the-ast.rs  |   2 +-
 src/doc/rustc-dev-guide/rustfmt.toml          |   7 +
 4 files changed, 39 insertions(+), 127 deletions(-)
 create mode 100644 src/doc/rustc-dev-guide/rustfmt.toml

diff --git a/src/doc/rustc-dev-guide/ci/date-check/src/main.rs b/src/doc/rustc-dev-guide/ci/date-check/src/main.rs
index 5ab3e6c8b65a8..9af69dbbf3f5c 100644
--- a/src/doc/rustc-dev-guide/ci/date-check/src/main.rs
+++ b/src/doc/rustc-dev-guide/ci/date-check/src/main.rs
@@ -1,11 +1,8 @@
-use std::{
-    collections::BTreeMap,
-    convert::TryInto as _,
-    env, fmt, fs,
-    path::{Path, PathBuf},
-    process,
-    str::FromStr,
-};
+use std::collections::BTreeMap;
+use std::convert::TryInto as _;
+use std::path::{Path, PathBuf};
+use std::str::FromStr;
+use std::{env, fmt, fs, process};
 
 use chrono::{Datelike as _, Month, TimeZone as _, Utc};
 use glob::glob;
@@ -19,19 +16,13 @@ struct Date {
 
 impl Date {
     fn months_since(self, other: Date) -> Option<u32> {
-        let self_chrono = Utc
-            .with_ymd_and_hms(self.year.try_into().unwrap(), self.month, 1, 0, 0, 0)
-            .unwrap();
-        let other_chrono = Utc
-            .with_ymd_and_hms(other.year.try_into().unwrap(), other.month, 1, 0, 0, 0)
-            .unwrap();
+        let self_chrono =
+            Utc.with_ymd_and_hms(self.year.try_into().unwrap(), self.month, 1, 0, 0, 0).unwrap();
+        let other_chrono =
+            Utc.with_ymd_and_hms(other.year.try_into().unwrap(), other.month, 1, 0, 0, 0).unwrap();
         let duration_since = self_chrono.signed_duration_since(other_chrono);
         let months_since = duration_since.num_days() / 30;
-        if months_since < 0 {
-            None
-        } else {
-            Some(months_since.try_into().unwrap())
-        }
+        if months_since < 0 { None } else { Some(months_since.try_into().unwrap()) }
     }
 }
 
@@ -66,26 +57,18 @@ fn collect_dates_from_file(date_regex: &Regex, text: &str) -> Vec<(usize, Date)>
     date_regex
         .captures_iter(text)
         .filter_map(|cap| {
-            if let (Some(month), Some(year), None, None) | (None, None, Some(month), Some(year)) = (
-                cap.name("m1"),
-                cap.name("y1"),
-                cap.name("m2"),
-                cap.name("y2"),
-            ) {
+            if let (Some(month), Some(year), None, None) | (None, None, Some(month), Some(year)) =
+                (cap.name("m1"), cap.name("y1"), cap.name("m2"), cap.name("y2"))
+            {
                 let year = year.as_str().parse().expect("year");
-                let month = Month::from_str(month.as_str())
-                    .expect("month")
-                    .number_from_month();
+                let month = Month::from_str(month.as_str()).expect("month").number_from_month();
                 Some((cap.get(0).expect("all").range(), Date { year, month }))
             } else {
                 None
             }
         })
         .map(|(byte_range, date)| {
-            line += text[end_of_last_cap..byte_range.end]
-                .chars()
-                .filter(|c| *c == '\n')
-                .count();
+            line += text[end_of_last_cap..byte_range.end].chars().filter(|c| *c == '\n').count();
             end_of_last_cap = byte_range.end;
             (line, date)
         })
@@ -138,10 +121,7 @@ fn main() {
     let root_dir_path = Path::new(&root_dir);
     let glob_pat = format!("{}/**/*.md", root_dir);
     let today_chrono = Utc::now().date_naive();
-    let current_month = Date {
-        year: today_chrono.year_ce().1,
-        month: today_chrono.month(),
-    };
+    let current_month = Date { year: today_chrono.year_ce().1, month: today_chrono.month() };
 
     let dates_by_file = collect_dates(glob(&glob_pat).unwrap().map(Result::unwrap));
     let dates_by_file: BTreeMap<_, _> =
@@ -173,10 +153,7 @@ fn main() {
         println!();
 
         for (path, dates) in dates_by_file {
-            println!(
-                "- {}",
-                path.strip_prefix(&root_dir_path).unwrap_or(&path).display(),
-            );
+            println!("- {}", path.strip_prefix(&root_dir_path).unwrap_or(&path).display(),);
             for (line, date) in dates {
                 println!("  - [ ] line {}: {}", line, date);
             }
@@ -191,14 +168,8 @@ mod tests {
 
     #[test]
     fn test_months_since() {
-        let date1 = Date {
-            year: 2020,
-            month: 3,
-        };
-        let date2 = Date {
-            year: 2021,
-            month: 1,
-        };
+        let date1 = Date { year: 2020, month: 3 };
+        let date2 = Date { year: 2021, month: 1 };
         assert_eq!(date2.months_since(date1), Some(10));
     }
 
@@ -273,83 +244,17 @@ Test8
         assert_eq!(
             collect_dates_from_file(&make_date_regex(), text),
             vec![
-                (
-                    3,
-                    Date {
-                        year: 2021,
-                        month: 1,
-                    }
-                ),
-                (
-                    6,
-                    Date {
-                        year: 2021,
-                        month: 2,
-                    }
-                ),
-                (
-                    9,
-                    Date {
-                        year: 2021,
-                        month: 3,
-                    }
-                ),
-                (
-                    11,
-                    Date {
-                        year: 2021,
-                        month: 4,
-                    }
-                ),
-                (
-                    17,
-                    Date {
-                        year: 2021,
-                        month: 5,
-                    }
-                ),
-                (
-                    20,
-                    Date {
-                        year: 2021,
-                        month: 1,
-                    }
-                ),
-                (
-                    23,
-                    Date {
-                        year: 2021,
-                        month: 2,
-                    }
-                ),
-                (
-                    26,
-                    Date {
-                        year: 2021,
-                        month: 3,
-                    }
-                ),
-                (
-                    28,
-                    Date {
-                        year: 2021,
-                        month: 4,
-                    }
-                ),
-                (
-                    34,
-                    Date {
-                        year: 2021,
-                        month: 5,
-                    }
-                ),
-                (
-                    38,
-                    Date {
-                        year: 2021,
-                        month: 6,
-                    }
-                ),
+                (3, Date { year: 2021, month: 1 }),
+                (6, Date { year: 2021, month: 2 }),
+                (9, Date { year: 2021, month: 3 }),
+                (11, Date { year: 2021, month: 4 }),
+                (17, Date { year: 2021, month: 5 }),
+                (20, Date { year: 2021, month: 1 }),
+                (23, Date { year: 2021, month: 2 }),
+                (26, Date { year: 2021, month: 3 }),
+                (28, Date { year: 2021, month: 4 }),
+                (34, Date { year: 2021, month: 5 }),
+                (38, Date { year: 2021, month: 6 }),
             ],
         );
     }
diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
index 0e3450086ba5b..db6ac18578542 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
@@ -20,7 +20,7 @@ use std::path::Path;
 use std::sync::Arc;
 
 use rustc_ast_pretty::pprust::item_to_string;
-use rustc_driver::{run_compiler, Compilation};
+use rustc_driver::{Compilation, run_compiler};
 use rustc_interface::interface::{Compiler, Config};
 use rustc_middle::ty::TyCtxt;
 
diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
index b0c62d5b4bbb0..c0d7f977d3500 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
@@ -20,7 +20,7 @@ use std::path::Path;
 use std::sync::Arc;
 
 use rustc_ast_pretty::pprust::item_to_string;
-use rustc_driver::{run_compiler, Compilation};
+use rustc_driver::{Compilation, run_compiler};
 use rustc_interface::interface::{Compiler, Config};
 use rustc_middle::ty::TyCtxt;
 
diff --git a/src/doc/rustc-dev-guide/rustfmt.toml b/src/doc/rustc-dev-guide/rustfmt.toml
new file mode 100644
index 0000000000000..b285329c78e61
--- /dev/null
+++ b/src/doc/rustc-dev-guide/rustfmt.toml
@@ -0,0 +1,7 @@
+# matches that of rust-lang/rust
+style_edition = "2024"
+use_small_heuristics = "Max"
+merge_derives = false
+group_imports = "StdExternalCrate"
+imports_granularity = "Module"
+use_field_init_shorthand = true

From ebae4c65a10a593b838d9c2f07f4c13e342ec03e Mon Sep 17 00:00:00 2001
From: clubby789 <jamie@hill-daniel.co.uk>
Date: Sun, 30 Mar 2025 13:21:01 +0100
Subject: [PATCH 32/39] Fix partial clone link

---
 src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
index 067e287111843..c3c1c41e3f697 100644
--- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
+++ b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
@@ -63,7 +63,7 @@ cd rust
 > **NOTE**: A shallow clone limits which `git` commands can be run.
 > If you intend to work on and contribute to the compiler, it is
 > generally recommended to fully clone the repository [as shown above](#get-the-source-code),
-> or to perform a [partial clone](#shallow-clone-the-repository) instead.
+> or to perform a [partial clone](#partial-clone-the-repository) instead.
 >
 > For example, `git bisect` and `git blame` require access to the commit history,
 > so they don't work if the repository was cloned with `--depth 1`.

From 59ca7679c7db634465b5f021060f143567824ac4 Mon Sep 17 00:00:00 2001
From: okaneco <47607823+okaneco@users.noreply.github.com>
Date: Sat, 29 Mar 2025 14:47:09 -0400
Subject: [PATCH 33/39] slice: Remove some uses of unsafe in first/last chunk
 methods

Remove unsafe `split_at_unchecked` and `split_at_mut_unchecked`
in some slice `split_first_chunk`/`split_last_chunk` methods.
Replace those calls with the safe `split_at` and `split_at_checked` where
applicable.

Add codegen tests to check for no panics when calculating the last
chunk index using `checked_sub` and `split_at`
---
 library/core/src/slice/mod.rs   | 94 ++++++++++++---------------------
 tests/codegen/slice-split-at.rs | 24 +++++++++
 2 files changed, 58 insertions(+), 60 deletions(-)
 create mode 100644 tests/codegen/slice-split-at.rs

diff --git a/library/core/src/slice/mod.rs b/library/core/src/slice/mod.rs
index 5bb7243c4491b..4e8be20643179 100644
--- a/library/core/src/slice/mod.rs
+++ b/library/core/src/slice/mod.rs
@@ -382,16 +382,11 @@ impl<T> [T] {
     #[stable(feature = "slice_first_last_chunk", since = "1.77.0")]
     #[rustc_const_stable(feature = "slice_first_last_chunk", since = "1.77.0")]
     pub const fn split_first_chunk<const N: usize>(&self) -> Option<(&[T; N], &[T])> {
-        if self.len() < N {
-            None
-        } else {
-            // SAFETY: We manually verified the bounds of the split.
-            let (first, tail) = unsafe { self.split_at_unchecked(N) };
+        let Some((first, tail)) = self.split_at_checked(N) else { return None };
 
-            // SAFETY: We explicitly check for the correct number of elements,
-            //   and do not let the references outlive the slice.
-            Some((unsafe { &*(first.as_ptr().cast::<[T; N]>()) }, tail))
-        }
+        // SAFETY: We explicitly check for the correct number of elements,
+        //   and do not let the references outlive the slice.
+        Some((unsafe { &*(first.as_ptr().cast::<[T; N]>()) }, tail))
     }
 
     /// Returns a mutable array reference to the first `N` items in the slice and the remaining
@@ -419,17 +414,12 @@ impl<T> [T] {
     pub const fn split_first_chunk_mut<const N: usize>(
         &mut self,
     ) -> Option<(&mut [T; N], &mut [T])> {
-        if self.len() < N {
-            None
-        } else {
-            // SAFETY: We manually verified the bounds of the split.
-            let (first, tail) = unsafe { self.split_at_mut_unchecked(N) };
+        let Some((first, tail)) = self.split_at_mut_checked(N) else { return None };
 
-            // SAFETY: We explicitly check for the correct number of elements,
-            //   do not let the reference outlive the slice,
-            //   and enforce exclusive mutability of the chunk by the split.
-            Some((unsafe { &mut *(first.as_mut_ptr().cast::<[T; N]>()) }, tail))
-        }
+        // SAFETY: We explicitly check for the correct number of elements,
+        //   do not let the reference outlive the slice,
+        //   and enforce exclusive mutability of the chunk by the split.
+        Some((unsafe { &mut *(first.as_mut_ptr().cast::<[T; N]>()) }, tail))
     }
 
     /// Returns an array reference to the last `N` items in the slice and the remaining slice.
@@ -452,16 +442,12 @@ impl<T> [T] {
     #[stable(feature = "slice_first_last_chunk", since = "1.77.0")]
     #[rustc_const_stable(feature = "slice_first_last_chunk", since = "1.77.0")]
     pub const fn split_last_chunk<const N: usize>(&self) -> Option<(&[T], &[T; N])> {
-        if self.len() < N {
-            None
-        } else {
-            // SAFETY: We manually verified the bounds of the split.
-            let (init, last) = unsafe { self.split_at_unchecked(self.len() - N) };
+        let Some(index) = self.len().checked_sub(N) else { return None };
+        let (init, last) = self.split_at(index);
 
-            // SAFETY: We explicitly check for the correct number of elements,
-            //   and do not let the references outlive the slice.
-            Some((init, unsafe { &*(last.as_ptr().cast::<[T; N]>()) }))
-        }
+        // SAFETY: We explicitly check for the correct number of elements,
+        //   and do not let the references outlive the slice.
+        Some((init, unsafe { &*(last.as_ptr().cast::<[T; N]>()) }))
     }
 
     /// Returns a mutable array reference to the last `N` items in the slice and the remaining
@@ -489,17 +475,13 @@ impl<T> [T] {
     pub const fn split_last_chunk_mut<const N: usize>(
         &mut self,
     ) -> Option<(&mut [T], &mut [T; N])> {
-        if self.len() < N {
-            None
-        } else {
-            // SAFETY: We manually verified the bounds of the split.
-            let (init, last) = unsafe { self.split_at_mut_unchecked(self.len() - N) };
+        let Some(index) = self.len().checked_sub(N) else { return None };
+        let (init, last) = self.split_at_mut(index);
 
-            // SAFETY: We explicitly check for the correct number of elements,
-            //   do not let the reference outlive the slice,
-            //   and enforce exclusive mutability of the chunk by the split.
-            Some((init, unsafe { &mut *(last.as_mut_ptr().cast::<[T; N]>()) }))
-        }
+        // SAFETY: We explicitly check for the correct number of elements,
+        //   do not let the reference outlive the slice,
+        //   and enforce exclusive mutability of the chunk by the split.
+        Some((init, unsafe { &mut *(last.as_mut_ptr().cast::<[T; N]>()) }))
     }
 
     /// Returns an array reference to the last `N` items in the slice.
@@ -522,17 +504,13 @@ impl<T> [T] {
     #[stable(feature = "slice_first_last_chunk", since = "1.77.0")]
     #[rustc_const_stable(feature = "const_slice_last_chunk", since = "1.80.0")]
     pub const fn last_chunk<const N: usize>(&self) -> Option<&[T; N]> {
-        if self.len() < N {
-            None
-        } else {
-            // SAFETY: We manually verified the bounds of the slice.
-            // FIXME(const-hack): Without const traits, we need this instead of `get_unchecked`.
-            let last = unsafe { self.split_at_unchecked(self.len() - N).1 };
+        // FIXME(const-hack): Without const traits, we need this instead of `get`.
+        let Some(index) = self.len().checked_sub(N) else { return None };
+        let (_, last) = self.split_at(index);
 
-            // SAFETY: We explicitly check for the correct number of elements,
-            //   and do not let the references outlive the slice.
-            Some(unsafe { &*(last.as_ptr().cast::<[T; N]>()) })
-        }
+        // SAFETY: We explicitly check for the correct number of elements,
+        //   and do not let the references outlive the slice.
+        Some(unsafe { &*(last.as_ptr().cast::<[T; N]>()) })
     }
 
     /// Returns a mutable array reference to the last `N` items in the slice.
@@ -556,18 +534,14 @@ impl<T> [T] {
     #[stable(feature = "slice_first_last_chunk", since = "1.77.0")]
     #[rustc_const_stable(feature = "const_slice_first_last_chunk", since = "1.83.0")]
     pub const fn last_chunk_mut<const N: usize>(&mut self) -> Option<&mut [T; N]> {
-        if self.len() < N {
-            None
-        } else {
-            // SAFETY: We manually verified the bounds of the slice.
-            // FIXME(const-hack): Without const traits, we need this instead of `get_unchecked`.
-            let last = unsafe { self.split_at_mut_unchecked(self.len() - N).1 };
-
-            // SAFETY: We explicitly check for the correct number of elements,
-            //   do not let the reference outlive the slice,
-            //   and require exclusive access to the entire slice to mutate the chunk.
-            Some(unsafe { &mut *(last.as_mut_ptr().cast::<[T; N]>()) })
-        }
+        // FIXME(const-hack): Without const traits, we need this instead of `get`.
+        let Some(index) = self.len().checked_sub(N) else { return None };
+        let (_, last) = self.split_at_mut(index);
+
+        // SAFETY: We explicitly check for the correct number of elements,
+        //   do not let the reference outlive the slice,
+        //   and require exclusive access to the entire slice to mutate the chunk.
+        Some(unsafe { &mut *(last.as_mut_ptr().cast::<[T; N]>()) })
     }
 
     /// Returns a reference to an element or subslice depending on the type of
diff --git a/tests/codegen/slice-split-at.rs b/tests/codegen/slice-split-at.rs
new file mode 100644
index 0000000000000..07018cf9c9171
--- /dev/null
+++ b/tests/codegen/slice-split-at.rs
@@ -0,0 +1,24 @@
+//@ compile-flags: -Copt-level=3
+#![crate_type = "lib"]
+
+// Check that no panic is generated in `split_at` when calculating the index for
+// the tail chunk using `checked_sub`.
+//
+// Tests written for refactored implementations of:
+// `<[T]>::{split_last_chunk, split_last_chunk_mut, last_chunk, last_chunk_mut}`
+
+// CHECK-LABEL: @split_at_last_chunk
+#[no_mangle]
+pub fn split_at_last_chunk(s: &[u8], chunk_size: usize) -> Option<(&[u8], &[u8])> {
+    // CHECK-NOT: panic
+    let Some(index) = s.len().checked_sub(chunk_size) else { return None };
+    Some(s.split_at(index))
+}
+
+// CHECK-LABEL: @split_at_mut_last_chunk
+#[no_mangle]
+pub fn split_at_mut_last_chunk(s: &mut [u8], chunk_size: usize) -> Option<(&mut [u8], &mut [u8])> {
+    // CHECK-NOT: panic
+    let Some(index) = s.len().checked_sub(chunk_size) else { return None };
+    Some(s.split_at_mut(index))
+}

From 39a491ada3309f47a0c8bdc41748461d00b4f735 Mon Sep 17 00:00:00 2001
From: mejrs <59372212+mejrs@users.noreply.github.com>
Date: Sun, 30 Mar 2025 23:20:04 +0200
Subject: [PATCH 34/39] unstable book: document
 import_trait_associated_functions

---
 .../import-trait-associated-functions.md      | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 src/doc/unstable-book/src/language-features/import-trait-associated-functions.md

diff --git a/src/doc/unstable-book/src/language-features/import-trait-associated-functions.md b/src/doc/unstable-book/src/language-features/import-trait-associated-functions.md
new file mode 100644
index 0000000000000..0ae5915361e51
--- /dev/null
+++ b/src/doc/unstable-book/src/language-features/import-trait-associated-functions.md
@@ -0,0 +1,22 @@
+# import_trait_associated_functions
+
+The tracking issue for this feature is: [#134691]
+
+[#134691]: https://github.com/rust-lang/rust/issues/134691
+
+------------------------
+
+This feature allows importing associated functions and constants from traits and then using them like regular items.
+
+```rust
+#![feature(import_trait_associated_functions)]
+
+use std::ops::Add::add;
+
+fn main() {
+    let numbers = vec![1, 2, 3, 4, 5, 6];
+    let sum = numbers.into_iter().reduce(add); // instead of `.reduce(Add:add)`
+
+    assert_eq!(sum, Some(21));
+}
+```

From 05d5fdadbbc5f426f2fe36b05c2b659865f2e4bb Mon Sep 17 00:00:00 2001
From: Jieyou Xu <jieyouxu@outlook.com>
Date: Wed, 2 Apr 2025 23:26:26 +0800
Subject: [PATCH 35/39] Preparing for merge from rustc

---
 src/doc/rustc-dev-guide/rust-version | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/rust-version b/src/doc/rustc-dev-guide/rust-version
index 6baf43397e881..d7c20d8ce620e 100644
--- a/src/doc/rustc-dev-guide/rust-version
+++ b/src/doc/rustc-dev-guide/rust-version
@@ -1 +1 @@
-493c38ba371929579fe136df26eccd9516347c7a
+ae9173d7dd4a31806c950c90dcc331f1508b4d17

From 072aa9e66f7c5e398d3030c8d41dc89079a4aed2 Mon Sep 17 00:00:00 2001
From: Trevor Gross <tmgross@umich.edu>
Date: Wed, 2 Apr 2025 18:15:50 +0000
Subject: [PATCH 36/39] Apply requested API changes to `cell_update`

Do the following:

* Switch to `impl FnOnce` rather than a generic `F`.
* Change `update` to return nothing.

This was discussed at a libs-api meeting [1].

Tracking issue: https://github.com/rust-lang/rust/issues/50186

[1]: https://github.com/rust-lang/rust/pull/134446#issuecomment-2770842949
---
 library/core/src/cell.rs        | 15 ++++-----------
 library/coretests/tests/cell.rs |  4 ++--
 2 files changed, 6 insertions(+), 13 deletions(-)

diff --git a/library/core/src/cell.rs b/library/core/src/cell.rs
index e789601a409af..09117e4968db6 100644
--- a/library/core/src/cell.rs
+++ b/library/core/src/cell.rs
@@ -544,7 +544,7 @@ impl<T: Copy> Cell<T> {
         unsafe { *self.value.get() }
     }
 
-    /// Updates the contained value using a function and returns the new value.
+    /// Updates the contained value using a function.
     ///
     /// # Examples
     ///
@@ -554,21 +554,14 @@ impl<T: Copy> Cell<T> {
     /// use std::cell::Cell;
     ///
     /// let c = Cell::new(5);
-    /// let new = c.update(|x| x + 1);
-    ///
-    /// assert_eq!(new, 6);
+    /// c.update(|x| x + 1);
     /// assert_eq!(c.get(), 6);
     /// ```
     #[inline]
     #[unstable(feature = "cell_update", issue = "50186")]
-    pub fn update<F>(&self, f: F) -> T
-    where
-        F: FnOnce(T) -> T,
-    {
+    pub fn update(&self, f: impl FnOnce(T) -> T) {
         let old = self.get();
-        let new = f(old);
-        self.set(new);
-        new
+        self.set(f(old));
     }
 }
 
diff --git a/library/coretests/tests/cell.rs b/library/coretests/tests/cell.rs
index d6a401c2b4d98..781a46c3744f5 100644
--- a/library/coretests/tests/cell.rs
+++ b/library/coretests/tests/cell.rs
@@ -50,10 +50,10 @@ fn smoketest_cell() {
 fn cell_update() {
     let x = Cell::new(10);
 
-    assert_eq!(x.update(|x| x + 5), 15);
+    x.update(|x| x + 5);
     assert_eq!(x.get(), 15);
 
-    assert_eq!(x.update(|x| x / 3), 5);
+    x.update(|x| x / 3);
     assert_eq!(x.get(), 5);
 }
 

From 33c1ff057983e1b32b7fe9b2eaf0253ddf9bef04 Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Wed, 2 Apr 2025 16:25:29 -0500
Subject: [PATCH 37/39] rustdoc: make settings checkboxes always square

---
 src/librustdoc/html/static/css/rustdoc.css | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css
index 0ea4d8f1e3914..aa8df35258dff 100644
--- a/src/librustdoc/html/static/css/rustdoc.css
+++ b/src/librustdoc/html/static/css/rustdoc.css
@@ -1446,6 +1446,9 @@ so that we can apply CSS-filters to change the arrow color in themes */
 	align-items: center;
 	cursor: pointer;
 }
+.setting-check input {
+	flex-shrink: 0,
+}
 
 .setting-radio input:checked {
 	box-shadow: inset 0 0 0 3px var(--main-background-color);

From 14e6a964f214e9a974a07e337e0668238d11a26c Mon Sep 17 00:00:00 2001
From: Mara Bos <m-ou.se@m-ou.se>
Date: Wed, 2 Apr 2025 23:43:41 +0200
Subject: [PATCH 38/39] Mark super_let feature as incomplete.

Co-authored-by: Travis Cross <tc@traviscross.com>
---
 compiler/rustc_feature/src/unstable.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/compiler/rustc_feature/src/unstable.rs b/compiler/rustc_feature/src/unstable.rs
index b4499fb2a6a41..0bb793e67ee2b 100644
--- a/compiler/rustc_feature/src/unstable.rs
+++ b/compiler/rustc_feature/src/unstable.rs
@@ -631,7 +631,7 @@ declare_features! (
     /// Allows string patterns to dereference values to match them.
     (unstable, string_deref_patterns, "1.67.0", Some(87121)),
     /// Allows `super let` statements.
-    (unstable, super_let, "CURRENT_RUSTC_VERSION", Some(139076)),
+    (incomplete, super_let, "CURRENT_RUSTC_VERSION", Some(139076)),
     /// Allows subtrait items to shadow supertrait items.
     (unstable, supertrait_item_shadowing, "1.86.0", Some(89151)),
     /// Allows using `#[thread_local]` on `static` items.

From 62fcb9d585723f0ab6646ba0e7dbaa72867bf8a8 Mon Sep 17 00:00:00 2001
From: beetrees <b@beetr.ee>
Date: Thu, 3 Apr 2025 01:08:41 +0100
Subject: [PATCH 39/39] Fix the `f16`/`f128` feature gate on integer literals

---
 compiler/rustc_ast_passes/src/feature_gate.rs | 22 ++++++++++---------
 .../feature-gate-f128.e2015.stderr            | 16 +++++++++++---
 .../feature-gate-f128.e2018.stderr            | 16 +++++++++++---
 tests/ui/feature-gates/feature-gate-f128.rs   |  1 +
 .../feature-gate-f16.e2015.stderr             | 16 +++++++++++---
 .../feature-gate-f16.e2018.stderr             | 16 +++++++++++---
 tests/ui/feature-gates/feature-gate-f16.rs    |  1 +
 7 files changed, 66 insertions(+), 22 deletions(-)

diff --git a/compiler/rustc_ast_passes/src/feature_gate.rs b/compiler/rustc_ast_passes/src/feature_gate.rs
index ea60e083c4ced..5745a52df71b0 100644
--- a/compiler/rustc_ast_passes/src/feature_gate.rs
+++ b/compiler/rustc_ast_passes/src/feature_gate.rs
@@ -332,17 +332,19 @@ impl<'a> Visitor<'a> for PostExpansionVisitor<'a> {
             ast::ExprKind::TryBlock(_) => {
                 gate!(&self, try_blocks, e.span, "`try` expression is experimental");
             }
-            ast::ExprKind::Lit(token::Lit { kind: token::LitKind::Float, suffix, .. }) => {
-                match suffix {
-                    Some(sym::f16) => {
-                        gate!(&self, f16, e.span, "the type `f16` is unstable")
-                    }
-                    Some(sym::f128) => {
-                        gate!(&self, f128, e.span, "the type `f128` is unstable")
-                    }
-                    _ => (),
+            ast::ExprKind::Lit(token::Lit {
+                kind: token::LitKind::Float | token::LitKind::Integer,
+                suffix,
+                ..
+            }) => match suffix {
+                Some(sym::f16) => {
+                    gate!(&self, f16, e.span, "the type `f16` is unstable")
                 }
-            }
+                Some(sym::f128) => {
+                    gate!(&self, f128, e.span, "the type `f128` is unstable")
+                }
+                _ => (),
+            },
             _ => {}
         }
         visit::walk_expr(self, e)
diff --git a/tests/ui/feature-gates/feature-gate-f128.e2015.stderr b/tests/ui/feature-gates/feature-gate-f128.e2015.stderr
index 771aee79dce16..7e8ea5e948dca 100644
--- a/tests/ui/feature-gates/feature-gate-f128.e2015.stderr
+++ b/tests/ui/feature-gates/feature-gate-f128.e2015.stderr
@@ -19,7 +19,7 @@ LL |     let a: f128 = 100.0;
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
 error[E0658]: the type `f128` is unstable
-  --> $DIR/feature-gate-f128.rs:15:11
+  --> $DIR/feature-gate-f128.rs:16:11
    |
 LL | fn foo(a: f128) {}
    |           ^^^^
@@ -29,7 +29,7 @@ LL | fn foo(a: f128) {}
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
 error[E0658]: the type `f128` is unstable
-  --> $DIR/feature-gate-f128.rs:18:8
+  --> $DIR/feature-gate-f128.rs:19:8
    |
 LL |     a: f128,
    |        ^^^^
@@ -48,6 +48,16 @@ LL |     let b = 0.0f128;
    = help: add `#![feature(f128)]` to the crate attributes to enable
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
-error: aborting due to 5 previous errors
+error[E0658]: the type `f128` is unstable
+  --> $DIR/feature-gate-f128.rs:12:13
+   |
+LL |     let c = 0f128;
+   |             ^^^^^
+   |
+   = note: see issue #116909 <https://github.com/rust-lang/rust/issues/116909> for more information
+   = help: add `#![feature(f128)]` to the crate attributes to enable
+   = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
+
+error: aborting due to 6 previous errors
 
 For more information about this error, try `rustc --explain E0658`.
diff --git a/tests/ui/feature-gates/feature-gate-f128.e2018.stderr b/tests/ui/feature-gates/feature-gate-f128.e2018.stderr
index 771aee79dce16..7e8ea5e948dca 100644
--- a/tests/ui/feature-gates/feature-gate-f128.e2018.stderr
+++ b/tests/ui/feature-gates/feature-gate-f128.e2018.stderr
@@ -19,7 +19,7 @@ LL |     let a: f128 = 100.0;
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
 error[E0658]: the type `f128` is unstable
-  --> $DIR/feature-gate-f128.rs:15:11
+  --> $DIR/feature-gate-f128.rs:16:11
    |
 LL | fn foo(a: f128) {}
    |           ^^^^
@@ -29,7 +29,7 @@ LL | fn foo(a: f128) {}
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
 error[E0658]: the type `f128` is unstable
-  --> $DIR/feature-gate-f128.rs:18:8
+  --> $DIR/feature-gate-f128.rs:19:8
    |
 LL |     a: f128,
    |        ^^^^
@@ -48,6 +48,16 @@ LL |     let b = 0.0f128;
    = help: add `#![feature(f128)]` to the crate attributes to enable
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
-error: aborting due to 5 previous errors
+error[E0658]: the type `f128` is unstable
+  --> $DIR/feature-gate-f128.rs:12:13
+   |
+LL |     let c = 0f128;
+   |             ^^^^^
+   |
+   = note: see issue #116909 <https://github.com/rust-lang/rust/issues/116909> for more information
+   = help: add `#![feature(f128)]` to the crate attributes to enable
+   = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
+
+error: aborting due to 6 previous errors
 
 For more information about this error, try `rustc --explain E0658`.
diff --git a/tests/ui/feature-gates/feature-gate-f128.rs b/tests/ui/feature-gates/feature-gate-f128.rs
index d25b6dde4ee47..dcbe60e934ae6 100644
--- a/tests/ui/feature-gates/feature-gate-f128.rs
+++ b/tests/ui/feature-gates/feature-gate-f128.rs
@@ -9,6 +9,7 @@ const A: f128 = 10.0; //~ ERROR the type `f128` is unstable
 pub fn main() {
     let a: f128 = 100.0; //~ ERROR the type `f128` is unstable
     let b = 0.0f128; //~ ERROR the type `f128` is unstable
+    let c = 0f128; //~ ERROR the type `f128` is unstable
     foo(1.23);
 }
 
diff --git a/tests/ui/feature-gates/feature-gate-f16.e2015.stderr b/tests/ui/feature-gates/feature-gate-f16.e2015.stderr
index 2bb3b59465a08..5d1ca8f6d047a 100644
--- a/tests/ui/feature-gates/feature-gate-f16.e2015.stderr
+++ b/tests/ui/feature-gates/feature-gate-f16.e2015.stderr
@@ -19,7 +19,7 @@ LL |     let a: f16 = 100.0;
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
 error[E0658]: the type `f16` is unstable
-  --> $DIR/feature-gate-f16.rs:15:11
+  --> $DIR/feature-gate-f16.rs:16:11
    |
 LL | fn foo(a: f16) {}
    |           ^^^
@@ -29,7 +29,7 @@ LL | fn foo(a: f16) {}
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
 error[E0658]: the type `f16` is unstable
-  --> $DIR/feature-gate-f16.rs:18:8
+  --> $DIR/feature-gate-f16.rs:19:8
    |
 LL |     a: f16,
    |        ^^^
@@ -48,6 +48,16 @@ LL |     let b = 0.0f16;
    = help: add `#![feature(f16)]` to the crate attributes to enable
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
-error: aborting due to 5 previous errors
+error[E0658]: the type `f16` is unstable
+  --> $DIR/feature-gate-f16.rs:12:13
+   |
+LL |     let c = 0f16;
+   |             ^^^^
+   |
+   = note: see issue #116909 <https://github.com/rust-lang/rust/issues/116909> for more information
+   = help: add `#![feature(f16)]` to the crate attributes to enable
+   = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
+
+error: aborting due to 6 previous errors
 
 For more information about this error, try `rustc --explain E0658`.
diff --git a/tests/ui/feature-gates/feature-gate-f16.e2018.stderr b/tests/ui/feature-gates/feature-gate-f16.e2018.stderr
index 2bb3b59465a08..5d1ca8f6d047a 100644
--- a/tests/ui/feature-gates/feature-gate-f16.e2018.stderr
+++ b/tests/ui/feature-gates/feature-gate-f16.e2018.stderr
@@ -19,7 +19,7 @@ LL |     let a: f16 = 100.0;
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
 error[E0658]: the type `f16` is unstable
-  --> $DIR/feature-gate-f16.rs:15:11
+  --> $DIR/feature-gate-f16.rs:16:11
    |
 LL | fn foo(a: f16) {}
    |           ^^^
@@ -29,7 +29,7 @@ LL | fn foo(a: f16) {}
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
 error[E0658]: the type `f16` is unstable
-  --> $DIR/feature-gate-f16.rs:18:8
+  --> $DIR/feature-gate-f16.rs:19:8
    |
 LL |     a: f16,
    |        ^^^
@@ -48,6 +48,16 @@ LL |     let b = 0.0f16;
    = help: add `#![feature(f16)]` to the crate attributes to enable
    = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
 
-error: aborting due to 5 previous errors
+error[E0658]: the type `f16` is unstable
+  --> $DIR/feature-gate-f16.rs:12:13
+   |
+LL |     let c = 0f16;
+   |             ^^^^
+   |
+   = note: see issue #116909 <https://github.com/rust-lang/rust/issues/116909> for more information
+   = help: add `#![feature(f16)]` to the crate attributes to enable
+   = note: this compiler was built on YYYY-MM-DD; consider upgrading it if it is out of date
+
+error: aborting due to 6 previous errors
 
 For more information about this error, try `rustc --explain E0658`.
diff --git a/tests/ui/feature-gates/feature-gate-f16.rs b/tests/ui/feature-gates/feature-gate-f16.rs
index af906d71f5fe2..f748c603efe92 100644
--- a/tests/ui/feature-gates/feature-gate-f16.rs
+++ b/tests/ui/feature-gates/feature-gate-f16.rs
@@ -9,6 +9,7 @@ const A: f16 = 10.0; //~ ERROR the type `f16` is unstable
 pub fn main() {
     let a: f16 = 100.0; //~ ERROR the type `f16` is unstable
     let b = 0.0f16; //~ ERROR the type `f16` is unstable
+    let c = 0f16; //~ ERROR the type `f16` is unstable
     foo(1.23);
 }