Merge from rust-lang/rust

30 files changed, 304 insertions, 114 deletions

diff --git a/src/doc/book b/src/doc/book
-Subproject 8a6d44e45b7b564eeb6bae30507e1fbac439d72
+Subproject ef1ce8f87a8b18feb1b6a9cf9a4939a79bde679
diff --git a/src/doc/embedded-book b/src/doc/embedded-book
-Subproject 10fa1e084365f23f24ad0000df541923385b73b
+Subproject 41f688a598a5022b749e23d37f3c524f6a0b28e
diff --git a/src/doc/reference b/src/doc/reference
-Subproject 50fc1628f36563958399123829c73755fa7a842
+Subproject e9fc99f107840813916f62e16b3f6d9556e1f2d
diff --git a/src/doc/rust-by-example b/src/doc/rust-by-example
-Subproject 05c7d8bae65f23a1837430c5a19be129d414f5e
+Subproject 288b4e4948add43f387cad35adc7b1c54ca6fe1
diff --git a/src/doc/rustc-dev-guide/josh-sync.toml b/src/doc/rustc-dev-guide/josh-sync.toml
new file mode 100644
index 00000000000..7882051e233
--- /dev/null
+++ b/src/doc/rustc-dev-guide/josh-sync.toml
@@ -0,0 +1,3 @@
+org = "rust-lang"
+repo = "rustc-dev-guide"
+path = "src/doc/rustc-dev-guide"
diff --git a/src/doc/rustc-dev-guide/rust-version b/src/doc/rustc-dev-guide/rust-version
index 30ba3070e1f..e444613e631 100644
--- a/src/doc/rustc-dev-guide/rust-version
+++ b/src/doc/rustc-dev-guide/rust-version
@@ -1 +1 @@
-d1d8e386c5e84c4ba857f56c3291f73c27e2d62a
+c96a69059ecc618b519da385a6ccd03155aa0237
diff --git a/src/doc/rustc-dev-guide/src/autodiff/internals.md b/src/doc/rustc-dev-guide/src/autodiff/internals.md
index 0093ef044c8..c1b31a0e4bd 100644
--- a/src/doc/rustc-dev-guide/src/autodiff/internals.md
+++ b/src/doc/rustc-dev-guide/src/autodiff/internals.md
@@ -2,11 +2,11 @@ The `std::autodiff` module in Rust allows differentiable programming:
 
 ```rust
 #![feature(autodiff)]
-use std::autodiff::autodiff;
+use std::autodiff::*;
 
 // f(x) = x * x, f'(x) = 2.0 * x
 // bar therefore returns (x * x, 2.0 * x)
-#[autodiff(bar, Reverse, Active, Active)]
+#[autodiff_reverse(bar, Active, Active)]
 fn foo(x: f32) -> f32 { x * x }
 
 fn main() {
diff --git a/src/doc/rustc-dev-guide/src/building/bootstrapping/debugging-bootstrap.md b/src/doc/rustc-dev-guide/src/building/bootstrapping/debugging-bootstrap.md
index ed267850401..c9c0d64a604 100644
--- a/src/doc/rustc-dev-guide/src/building/bootstrapping/debugging-bootstrap.md
+++ b/src/doc/rustc-dev-guide/src/building/bootstrapping/debugging-bootstrap.md
@@ -168,10 +168,17 @@ For `#[instrument]`, it's recommended to:
 
 ### Profiling bootstrap
 
-You can use the `COMMAND` tracing target to trace execution of most commands spawned by bootstrap. If you also use the `BOOTSTRAP_PROFILE=1` environment variable, bootstrap will generate a Chrome JSON trace file, which can be visualized in Chrome's `chrome://tracing` page or on https://ui.perfetto.dev.
+You can set the `BOOTSTRAP_PROFILE=1` environment variable to enable command execution profiling during bootstrap. This generates:
+
+* A Chrome trace file (for visualization in `chrome://tracing` or [Perfetto](https://ui.perfetto.dev)) if tracing is enabled via `BOOTSTRAP_TRACING=COMMAND=trace`
+* A plain-text summary file, `bootstrap-profile-{pid}.txt`, listing all commands sorted by execution time (slowest first), along with cache hits and working directories
+
+Note: the `.txt` report is always generated when `BOOTSTRAP_PROFILE=1` is set — tracing is not required.
+
+Example usage:
 
 ```bash
-$ BOOTSTRAP_TRACING=COMMAND=trace BOOTSTRAP_PROFILE=1 ./x build library
+$ BOOTSTRAP_PROFILE=1 BOOTSTRAP_TRACING=COMMAND=trace ./x build library
 ```
 
 ### rust-analyzer integration?
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 c4783002b85..d29cd144810 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
@@ -2,6 +2,24 @@
 
 <!-- toc -->
 
+<div class="warning">
+
+For `profile = "library"` users, or users who use `download-rustc = true | "if-unchanged"`, please be advised that
+the `./x test library/std` flow where `download-rustc` is active (i.e. no compiler changes) is currently broken.
+This is tracked in <https://github.com/rust-lang/rust/issues/142505>. Only the `./x test` flow is affected in this
+case, `./x {check,build} library/std` should still work.
+
+In the short-term, you may need to disable `download-rustc` for `./x test library/std`. This can be done either by:
+
+1. `./x test library/std --set rust.download-rustc=false`
+2. Or set `rust.download-rustc=false` in `bootstrap.toml`.
+
+Unfortunately that will require building the stage 1 compiler. The bootstrap team is working on this, but
+implementing a maintainable fix is taking some time.
+
+</div>
+
+
 The compiler is built using a tool called `x.py`. You will need to
 have Python installed to run it.
 
diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md
index 46d74b96734..b3fcd79ec81 100644
--- a/src/doc/rustc-dev-guide/src/contributing.md
+++ b/src/doc/rustc-dev-guide/src/contributing.md
@@ -434,6 +434,10 @@ Just a few things to keep in mind:
   it might benefit from having a Table of Contents at the beginning,
   which you can auto-generate by including the `<!-- toc -->` marker at the top.
 
+#### ⚠️ Note: Where to contribute `rustc-dev-guide` changes
+
+For detailed information about where to contribute rustc-dev-guide changes and the benefits of doing so, see [the rustc-dev-guide working group documentation](https://forge.rust-lang.org/wg-rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes).
+
 ## Issue triage
 
 Please see <https://forge.rust-lang.org/release/issue-triaging.html>.
diff --git a/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md b/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md
index e01b8f2f135..4e5c3413cb8 100644
--- a/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md
+++ b/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md
@@ -1,14 +1,18 @@
 # Diagnostic and subdiagnostic structs
 rustc has three diagnostic traits that can be used to create diagnostics:
-`Diagnostic`, `LintDiagnostic`, and `Subdiagnostic`. For simple diagnostics,
-instead of using the `Diag` API to create and emit diagnostics,
-derived impls can be used. They are only suitable for simple diagnostics that
+`Diagnostic`, `LintDiagnostic`, and `Subdiagnostic`.
+
+For simple diagnostics,
+derived impls can be used, e.g. `#[derive(Diagnostic)]`. They are only suitable for simple diagnostics that
 don't require much logic in deciding whether or not to add additional
 subdiagnostics.
 
-Such diagnostic can be translated into
-different languages and each has a slug that uniquely identifies the
-diagnostic.
+In cases where diagnostics require more complex or dynamic behavior, such as conditionally adding subdiagnostics,
+customizing the rendering logic, or selecting messages at runtime, you will need to manually implement
+the corresponding trait (`Diagnostic`, `LintDiagnostic`, or `Subdiagnostic`).
+This approach provides greater flexibility and is recommended for diagnostics that go beyond simple, static structures.
+
+Diagnostic can be translated into different languages and each has a slug that uniquely identifies the diagnostic.
 
 ## `#[derive(Diagnostic)]` and `#[derive(LintDiagnostic)]`
 
@@ -142,7 +146,7 @@ tcx.dcx().emit_err(FieldAlreadyDeclared {
 });
 ```
 
-### Reference
+### Reference for `#[derive(Diagnostic)]` and `#[derive(LintDiagnostic)]`
 `#[derive(Diagnostic)]` and `#[derive(LintDiagnostic)]` support the
 following attributes:
 
@@ -330,7 +334,34 @@ function ([example][subdiag_use_1] and [example][subdiag_use_2]) on a
 diagnostic or by assigning it to a `#[subdiagnostic]`-annotated field of a
 diagnostic struct.
 
-### Reference
+### Argument sharing and isolation
+
+Subdiagnostics add their own arguments (i.e., certain fields in their structure) to the `Diag` structure before rendering the information.
+`Diag` structure also stores the arguments from the main diagnostic, so the subdiagnostic can also use the arguments from the main diagnostic.
+
+However, when a subdiagnostic is added to a main diagnostic by implementing `#[derive(Subdiagnostic)]`,
+the following rules, introduced in [rust-lang/rust#142724](https://github.com/rust-lang/rust/pull/142724)
+apply to the handling of arguments (i.e., variables used in Fluent messages):
+
+**Argument isolation between sub diagnostics**:
+Arguments set by a subdiagnostic are only available during the rendering of that subdiagnostic.
+After the subdiagnostic is rendered, all arguments it introduced are restored from the main diagnostic.
+This ensures that multiple subdiagnostics do not pollute each other's argument scope.
+For example, when using a `Vec<Subdiag>`, it iteratively adds the same argument over and over again.
+
+**Same argument override between sub and main diagnostics**:
+If a subdiagnostic sets a argument with the same name as a arguments already in the main diagnostic,
+it will report an error at runtime unless both have exactly the same value.
+It has two benefits:
+- preserves the flexibility that arguments in the main diagnostic are allowed to appear in the attributes of the subdiagnostic.
+For example, There is an attribute `#[suggestion(code = "{new_vis}")]` in the subdiagnostic, but `new_vis` is the field in the main diagnostic struct.
+- prevents accidental overwriting or deletion of arguments required by the main diagnostic or other subdiagnostics.
+
+These rules guarantee that arguments injected by subdiagnostics are strictly scoped to their own rendering.
+The main diagnostic's arguments remain unaffected by subdiagnostic logic, even in the presence of name collisions.
+Additionally, subdiagnostics can access arguments from the main diagnostic with the same name when needed.
+
+### Reference for `#[derive(Subdiagnostic)]`
 `#[derive(Subdiagnostic)]` supports the following attributes:
 
 - `#[label(slug)]`, `#[help(slug)]`, `#[warning(slug)]` or `#[note(slug)]`
diff --git a/src/doc/rustc-dev-guide/src/hir/lowering.md b/src/doc/rustc-dev-guide/src/hir/lowering.md
index 02c69b8609f..c0057a69c10 100644
--- a/src/doc/rustc-dev-guide/src/hir/lowering.md
+++ b/src/doc/rustc-dev-guide/src/hir/lowering.md
@@ -7,10 +7,8 @@ of such structures include but are not limited to
 
 * Parenthesis
     * Removed without replacement, the tree structure makes order explicit
-* `for` loops and `while (let)` loops
-    * Converted to `loop` + `match` and some `let` bindings
-* `if let`
-    * Converted to `match`
+* `for` loops
+    * Converted to `match` + `loop` + `match`
 * Universal `impl Trait`
     * Converted to generic arguments
       (but with some flags, to know that the user didn't write them)
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 b05318ce9e6..4f44cf1701c 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
@@ -55,6 +55,9 @@ 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 `@`.
 
+Similar to compiletest directives, besides a space you can also use a colon `:` to separate
+the directive name and the arguments, however a space is preferred for HtmlDocCk directives.
+
 Use the special string `{{channel}}` in XPaths, `PATTERN` arguments and [snapshot files](#snapshot)
 if you'd like to refer to the URL `https://doc.rust-lang.org/CHANNEL` where `CHANNEL` refers to the
 current release channel (e.g, `stable` or `nightly`).
diff --git a/src/doc/rustc-dev-guide/src/solve/opaque-types.md b/src/doc/rustc-dev-guide/src/solve/opaque-types.md
index 6898ef3aa78..8880962d621 100644
--- a/src/doc/rustc-dev-guide/src/solve/opaque-types.md
+++ b/src/doc/rustc-dev-guide/src/solve/opaque-types.md
@@ -56,7 +56,7 @@ Finally, we check whether the item bounds of the opaque hold for the expected ty
 [source][item-bounds-ck].
 
 [norm]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L13
-[coherence-example]: https://github.com/rust-lang/rust/blob/master/tests/ui/type-alias-impl-trait/coherence_different_hidden_ty.rs
+[coherence-example]: https://github.com/rust-lang/rust/blob/master/tests/ui/type-alias-impl-trait/coherence/coherence_different_hidden_ty.rs
 [placeholder-ck]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L33
 [check-storage]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L51-L52
 [eq-prev]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L51-L59
diff --git a/src/doc/rustc-dev-guide/src/tests/ci.md b/src/doc/rustc-dev-guide/src/tests/ci.md
index 96e4edc17a5..750e4fa1a0f 100644
--- a/src/doc/rustc-dev-guide/src/tests/ci.md
+++ b/src/doc/rustc-dev-guide/src/tests/ci.md
@@ -66,8 +66,8 @@ kinds of builds (sets of jobs).
 ### Pull Request builds
 
 After each push to a pull request, a set of `pr` jobs are executed. Currently,
-these execute the `x86_64-gnu-llvm-X`, `x86_64-gnu-tools`, `mingw-check-1`, `mingw-check-2`
-and `mingw-check-tidy` jobs, all running on Linux. These execute a relatively short
+these execute the `x86_64-gnu-llvm-X`, `x86_64-gnu-tools`, `pr-check-1`, `pr-check-2`
+and `tidy` jobs, all running on Linux. These execute a relatively short
 (~40 minutes) and lightweight test suite that should catch common issues. More
 specifically, they run a set of lints, they try to perform a cross-compile check
 build to Windows mingw (without producing any artifacts) and they test the
@@ -148,6 +148,13 @@ for example `*msvc*` or `*-alt`. You can start at most 20 jobs in a single try b
 glob patterns, you might want to wrap them in backticks (`` ` ``) to avoid GitHub rendering
 the pattern as Markdown.
 
+The job pattern needs to match one or more jobs defined in the `auto` or `optional` sections
+of [`jobs.yml`]:
+
+- `auto` jobs are executed before a commit is merged into the `master` branch.
+- `optional` jobs are executed only when explicitly requested via a try build.
+  They are typically used for tier 2 and tier 3 targets.
+
 > **Using `try-job` PR description directives**
 >
 > 1. Identify which set of try-jobs you would like to exercise. You can
diff --git a/src/doc/rustc-dev-guide/src/tests/minicore.md b/src/doc/rustc-dev-guide/src/tests/minicore.md
index def9aaf8733..23b77279011 100644
--- a/src/doc/rustc-dev-guide/src/tests/minicore.md
+++ b/src/doc/rustc-dev-guide/src/tests/minicore.md
@@ -39,6 +39,12 @@ If you find a `core` item to be missing from the [`minicore`] stub, consider
 adding it to the test auxiliary if it's likely to be used or is already needed
 by more than one test.
 
+## Staying in sync with `core`
+
+The `minicore` items must be kept up to date with `core`. For consistent
+diagnostic output between using `core` and `minicore`, any `diagnostic`
+attributes (e.g. `on_unimplemented`) should be replicated exactly in `minicore`.
+
 ## Example codegen test that uses `minicore`
 
 ```rust,no_run
diff --git a/src/doc/rustc-dev-guide/src/tests/ui.md b/src/doc/rustc-dev-guide/src/tests/ui.md
index 09dc476d68e..4fce5838b6e 100644
--- a/src/doc/rustc-dev-guide/src/tests/ui.md
+++ b/src/doc/rustc-dev-guide/src/tests/ui.md
@@ -453,9 +453,9 @@ even run the resulting program. Just add one of the following
   - `//@ check-fail` — compilation should fail (the codegen phase is skipped).
     This is the default for UI tests.
   - `//@ build-fail` — compilation should fail during the codegen phase.
-    This will run `rustc` twice, once to verify that it compiles successfully
-    without the codegen phase, then a second time the full compile should
-    fail.
+    This will run `rustc` twice:
+    - First time is to ensure that the compile succeeds without the codegen phase
+    - Second time is to ensure that the full compile fails
   - `//@ run-fail` — compilation should succeed, but running the resulting
     binary should fail.
 
@@ -499,7 +499,7 @@ This directive takes comma-separated issue numbers as arguments, or `"unknown"`:
 - `//@ 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)
+  (when there is no known issue yet; preferably 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
diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index 201a5503079..7c688e32bc0 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/src/doc/rustc/src/SUMMARY.md
@@ -46,6 +46,7 @@
     - [\*-apple-watchos](platform-support/apple-watchos.md)
     - [\*-apple-visionos](platform-support/apple-visionos.md)
     - [aarch64-nintendo-switch-freestanding](platform-support/aarch64-nintendo-switch-freestanding.md)
+    - [aarch64-unknown-linux-musl](platform-support/aarch64-unknown-linux-musl.md)
     - [amdgcn-amd-amdhsa](platform-support/amdgcn-amd-amdhsa.md)
     - [armeb-unknown-linux-gnueabi](platform-support/armeb-unknown-linux-gnueabi.md)
     - [arm-none-eabi](platform-support/arm-none-eabi.md)
@@ -83,6 +84,7 @@
     - [m68k-unknown-linux-gnu](platform-support/m68k-unknown-linux-gnu.md)
     - [m68k-unknown-none-elf](platform-support/m68k-unknown-none-elf.md)
     - [mips64-openwrt-linux-musl](platform-support/mips64-openwrt-linux-musl.md)
+    - [mips64-unknown-linux-muslabi64](platform-support/mips64-unknown-linux-muslabi64.md)
     - [mipsel-sony-psx](platform-support/mipsel-sony-psx.md)
     - [mipsel-unknown-linux-gnu](platform-support/mipsel-unknown-linux-gnu.md)
     - [mips\*-mti-none-elf](platform-support/mips-mti-none-elf.md)
@@ -130,7 +132,7 @@
     - [\*-win7-windows-msvc](platform-support/win7-windows-msvc.md)
     - [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md)
     - [x86_64-pc-cygwin](platform-support/x86_64-pc-cygwin.md)
-    - [x86_64-unknown-linux-none.md](platform-support/x86_64-unknown-linux-none.md)
+    - [x86_64-unknown-linux-none](platform-support/x86_64-unknown-linux-none.md)
     - [x86_64-unknown-none](platform-support/x86_64-unknown-none.md)
     - [xtensa-\*-none-elf](platform-support/xtensa.md)
     - [\*-nuttx-\*](platform-support/nuttx.md)
diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md
index bb109adf76f..07eafdf4c4c 100644
--- a/src/doc/rustc/src/codegen-options/index.md
+++ b/src/doc/rustc/src/codegen-options/index.md
@@ -235,15 +235,33 @@ coverage measurement. Its use is not recommended.
 
 ## link-self-contained
 
-On `windows-gnu`, `linux-musl`, and `wasi` targets, this flag controls whether the
-linker will use libraries and objects shipped with Rust instead of those in the system.
-It takes one of the following values:
+This flag controls whether the linker will use libraries and objects shipped with Rust instead of
+those in the system.  It also controls which binary is used for the linker itself. This allows
+overriding cases when detection fails or the user wants to use shipped libraries.
+
+You can enable or disable the usage of any self-contained components using one of the following values:
 
 * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
 * `y`, `yes`, `on`, `true`: use only libraries/objects shipped with Rust.
 * `n`, `no`, `off` or `false`: rely on the user or the linker to provide non-Rust libraries/objects.
 
-This allows overriding cases when detection fails or user wants to use shipped libraries.
+It is also possible to enable or disable specific self-contained components in a more granular way.
+You can pass a comma-separated list of self-contained components, individually enabled
+(`+component`) or disabled (`-component`).
+
+Currently, only the `linker` granular option is stabilized, and only on the `x86_64-unknown-linux-gnu` target:
+- `linker`: toggle the usage of self-contained linker binaries (linker, dlltool, and their necessary libraries)
+
+Note that only the `-linker` opt-out is stable on the `x86_64-unknown-linux-gnu` target: `+linker` is
+already the default on this target.
+
+#### Implementation notes
+
+On the `x86_64-unknown-linux-gnu` target, when using the default linker flavor (using `cc` as the
+linker driver) and linker features (to try using `lld`), `rustc` will try to use the self-contained
+linker by passing a `-B /path/to/sysroot/` link argument to the driver to find `rust-lld` in the
+sysroot. For backwards-compatibility, and to limit name and `PATH` collisions, this is done using a
+shim executable (the `lld-wrapper` tool) that forwards execution to the `rust-lld` executable itself.
 
 ## linker
 
@@ -256,6 +274,39 @@ Note that on Unix-like targets (for example, `*-unknown-linux-gnu` or `*-unknown
 the C compiler (for example `cc` or `clang`) is used as the "linker" here, serving as a linker driver.
 It will invoke the actual linker with all the necessary flags to be able to link against the system libraries like libc.
 
+## linker-features
+
+The `-Clinker-features` flag allows enabling or disabling specific features used during linking.
+
+These feature flags are a flexible extension mechanism that is complementary to linker flavors,
+designed to avoid the combinatorial explosion of having to create a new set of flavors for each
+linker feature we'd want to use.
+
+The flag accepts a comma-separated list of features, individually enabled (`+feature`) or disabled
+(`-feature`).
+
+Currently only one is stable, and only on the `x86_64-unknown-linux-gnu` target:
+- `lld`: to toggle trying to use the lld linker, either the system-installed binary, or the self-contained
+  `rust-lld` linker (via the [`-Clink-self-contained=+linker`](#link-self-contained) flag).
+
+For example, use:
+- `-Clinker-features=+lld` to opt into using the `lld` linker, when possible (see the Implementation notes below)
+- `-Clinker-features=-lld` to opt out instead, for targets where it is configured as the default linker
+
+Note that only the `-lld` opt-out is stable on the `x86_64-unknown-linux-gnu` target: `+lld` is
+already the default on this target.
+
+#### Implementation notes
+
+On the `x86_64-unknown-linux-gnu` target, when using the default linker flavor (using `cc` as the
+linker driver), `rustc` will try to use lld by passing a `-fuse-ld=lld` link argument to the driver.
+`rustc` will also try to detect if that _causes_ an error during linking (for example, if GCC is too
+old to understand the flag, and returns an error) and will then retry linking without this argument,
+as a fallback.
+
+If the user _also_ passes a `-Clink-arg=-fuse-ld=$value`, both will be given to the linker
+driver but the user's will be passed last, and would generally have priority over `rustc`'s.
+
 ## linker-flavor
 
 This flag controls the linker flavor used by `rustc`. If a linker is given with
diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md
index 285b1e519b7..65b70630153 100644
--- a/src/doc/rustc/src/platform-support.md
+++ b/src/doc/rustc/src/platform-support.md
@@ -90,7 +90,7 @@ target | notes
 -------|-------
 [`aarch64-pc-windows-gnullvm`](platform-support/windows-gnullvm.md) | ARM64 MinGW (Windows 10+), LLVM ABI
 [`aarch64-pc-windows-msvc`](platform-support/windows-msvc.md) | ARM64 Windows MSVC
-`aarch64-unknown-linux-musl` | ARM64 Linux with musl 1.2.3
+[`aarch64-unknown-linux-musl`](platform-support/aarch64-unknown-linux-musl.md) | ARM64 Linux with musl 1.2.3
 [`aarch64-unknown-linux-ohos`](platform-support/openharmony.md) | ARM64 OpenHarmony
 `arm-unknown-linux-gnueabi` | Armv6 Linux (kernel 3.2+, glibc 2.17)
 `arm-unknown-linux-gnueabihf` | Armv6 Linux, hardfloat (kernel 3.2+, glibc 2.17)
@@ -333,7 +333,7 @@ target | std | host | notes
 `mips-unknown-linux-uclibc` | ✓ |  | MIPS Linux with uClibc
 [`mips64-openwrt-linux-musl`](platform-support/mips64-openwrt-linux-musl.md) | ? |  | MIPS64 for OpenWrt Linux musl 1.2.3
 `mips64-unknown-linux-gnuabi64` | ✓ | ✓ | MIPS64 Linux, N64 ABI (kernel 4.4, glibc 2.23)
-`mips64-unknown-linux-muslabi64` | ✓ |  | MIPS64 Linux, N64 ABI, musl 1.2.3
+[`mips64-unknown-linux-muslabi64`](platform-support/mips64-unknown-linux-muslabi64.md) | ✓ | ✓ | MIPS64 Linux, N64 ABI, musl 1.2.3
 `mips64el-unknown-linux-gnuabi64` | ✓ | ✓ | MIPS64 (little endian) Linux, N64 ABI (kernel 4.4, glibc 2.23)
 `mips64el-unknown-linux-muslabi64` | ✓ |  | MIPS64 (little endian) Linux, N64 ABI, musl 1.2.3
 `mipsel-sony-psp` | * |  | MIPS (LE) Sony PlayStation Portable (PSP)
diff --git a/src/doc/rustc/src/platform-support/aarch64-unknown-linux-musl.md b/src/doc/rustc/src/platform-support/aarch64-unknown-linux-musl.md
new file mode 100644
index 00000000000..5d9a552e460
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/aarch64-unknown-linux-musl.md
@@ -0,0 +1,49 @@
+# aarch64-unknown-linux-musl
+
+**Tier: 2**
+
+Target for 64-bit little endian ARMv8-A Linux programs using musl libc.
+
+## Target maintainers
+
+[@Gelbpunkt](https://github.com/Gelbpunkt)
+[@famfo](https://github.com/famfo)
+
+## Requirements
+
+Building the target itself requires a 64-bit little endian ARMv8-A compiler
+that is supported by `cc-rs`.
+
+## Building the target
+
+The target can be built by enabling it for a `rustc` build.
+
+```toml
+[build]
+target = ["aarch64-unknown-linux-musl"]
+```
+
+Make sure your C compiler is included in `$PATH`, then add it to the
+`bootstrap.toml`:
+
+```toml
+[target.aarch64-unknown-linux-musl]
+cc = "aarch64-linux-musl-gcc"
+cxx = "aarch64-linux-musl-g++"
+ar = "aarch64-linux-musl-ar"
+linker = "aarch64-linux-musl-gcc"
+```
+
+## Building Rust programs
+
+This target is distributed through `rustup`, and otherwise requires no
+special configuration.
+
+## Cross-compilation
+
+This target can be cross-compiled from any host.
+
+## Testing
+
+This target can be tested as normal with `x.py` on a 64-bit little endian
+ARMv8-A host or via QEMU emulation.
diff --git a/src/doc/rustc/src/platform-support/armv5te-unknown-linux-gnueabi.md b/src/doc/rustc/src/platform-support/armv5te-unknown-linux-gnueabi.md
index 1baf1049994..0aebbc34d40 100644
--- a/src/doc/rustc/src/platform-support/armv5te-unknown-linux-gnueabi.md
+++ b/src/doc/rustc/src/platform-support/armv5te-unknown-linux-gnueabi.md
@@ -7,7 +7,7 @@ floating-point units.
 
 ## Target maintainers
 
-[@koalatux](https://github.com/koalatux)
+There are currently no formally documented target maintainers.
 
 ## Requirements
 
diff --git a/src/doc/rustc/src/platform-support/mips64-unknown-linux-muslabi64.md b/src/doc/rustc/src/platform-support/mips64-unknown-linux-muslabi64.md
new file mode 100644
index 00000000000..60c0972bb3e
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/mips64-unknown-linux-muslabi64.md
@@ -0,0 +1,49 @@
+# mips64-unknown-linux-muslabi64
+
+**Tier: 3**
+
+Target for 64-bit big endian MIPS Linux programs using musl libc and the N64 ABI.
+
+## Target maintainers
+
+[@Gelbpunkt](https://github.com/Gelbpunkt)
+
+## Requirements
+
+Building the target itself requires a 64-bit big endian MIPS compiler that is
+supported by `cc-rs`.
+
+## Building the target
+
+The target can be built by enabling it for a `rustc` build.
+
+```toml
+[build]
+target = ["mips64-unknown-linux-muslabi64"]
+```
+
+Make sure your C compiler is included in `$PATH`, then add it to the
+`bootstrap.toml`:
+
+```toml
+[target.mips64-unknown-linux-muslabi64]
+cc = "mips64-linux-musl-gcc"
+cxx = "mips64-linux-musl-g++"
+ar = "mips64-linux-musl-ar"
+linker = "mips64-linux-musl-gcc"
+```
+
+## Building Rust programs
+
+Rust does not yet ship pre-compiled artifacts for this target. To compile for
+this target, you will first need to build Rust with the target enabled (see
+"Building the target" above).
+
+## Cross-compilation
+
+This target can be cross-compiled from any host.
+
+## Testing
+
+This target can be tested as normal with `x.py` on a 64-bit big endian MIPS
+host or via QEMU emulation.
diff --git a/src/doc/rustc/src/platform-support/netbsd.md b/src/doc/rustc/src/platform-support/netbsd.md
index 9040ef637be..e80ff85edad 100644
--- a/src/doc/rustc/src/platform-support/netbsd.md
+++ b/src/doc/rustc/src/platform-support/netbsd.md
@@ -1,7 +1,5 @@
 # \*-unknown-netbsd
 
-**Tier: 3**
-
 [NetBSD] multi-platform 4.4BSD-based UNIX-like operating system.
 
 [NetBSD]: https://www.NetBSD.org/
@@ -11,19 +9,19 @@ where `$ARCH` specifies the target processor architecture and
 `-$SUFFIX` (optional) might indicate the ABI. The following targets
 are currently defined running NetBSD:
 
-|          Target name           | NetBSD Platform |
-|--------------------------------|-----------------|
-| `x86_64-unknown-netbsd`        | [amd64 / x86_64 systems](https://wiki.netbsd.org/ports/amd64/) |
-| `armv7-unknown-netbsd-eabihf`  | [32-bit ARMv7 systems with hard-float](https://wiki.netbsd.org/ports/evbarm/) |
-| `armv6-unknown-netbsd-eabihf`  | [32-bit ARMv6 systems with hard-float](https://wiki.netbsd.org/ports/evbarm/) |
-| `aarch64-unknown-netbsd`       | [64-bit ARM systems, little-endian](https://wiki.netbsd.org/ports/evbarm/) |
-| `aarch64_be-unknown-netbsd`    | [64-bit ARM systems, big-endian](https://wiki.netbsd.org/ports/evbarm/) |
-| `i586-unknown-netbsd`          | [32-bit i386, restricted to Pentium](https://wiki.netbsd.org/ports/i386/) |
-| `i686-unknown-netbsd`          | [32-bit i386 with SSE](https://wiki.netbsd.org/ports/i386/) |
-| `mipsel-unknown-netbsd`        | [32-bit mips, requires mips32 cpu support](https://wiki.netbsd.org/ports/evbmips/) |
-| `powerpc-unknown-netbsd`       | [Various 32-bit PowerPC systems, e.g. MacPPC](https://wiki.netbsd.org/ports/macppc/) |
-| `riscv64gc-unknown-netbsd`     | [64-bit RISC-V](https://wiki.netbsd.org/ports/riscv/) |
-| `sparc64-unknown-netbsd`       | [Sun UltraSPARC systems](https://wiki.netbsd.org/ports/sparc64/) |
+| Target tier         | Target name                   | NetBSD Platform                                                                      |
+|---------------------|-------------------------------|--------------------------------------------------------------------------------------|
+| 2 (with host tools) | `x86_64-unknown-netbsd`       | [amd64 / x86_64 systems](https://wiki.netbsd.org/ports/amd64/)                       |
+| 3                   | `armv7-unknown-netbsd-eabihf` | [32-bit ARMv7 systems with hard-float](https://wiki.netbsd.org/ports/evbarm/)        |
+| 3                   | `armv6-unknown-netbsd-eabihf` | [32-bit ARMv6 systems with hard-float](https://wiki.netbsd.org/ports/evbarm/)        |
+| 3                   | `aarch64-unknown-netbsd`      | [64-bit ARM systems, little-endian](https://wiki.netbsd.org/ports/evbarm/)           |
+| 3                   | `aarch64_be-unknown-netbsd`   | [64-bit ARM systems, big-endian](https://wiki.netbsd.org/ports/evbarm/)              |
+| 3                   | `i586-unknown-netbsd`         | [32-bit i386, restricted to Pentium](https://wiki.netbsd.org/ports/i386/)            |
+| 3                   | `i686-unknown-netbsd`         | [32-bit i386 with SSE](https://wiki.netbsd.org/ports/i386/)                          |
+| 3                   | `mipsel-unknown-netbsd`       | [32-bit mips, requires mips32 cpu support](https://wiki.netbsd.org/ports/evbmips/)   |
+| 3                   | `powerpc-unknown-netbsd`      | [Various 32-bit PowerPC systems, e.g. MacPPC](https://wiki.netbsd.org/ports/macppc/) |
+| 3                   | `riscv64gc-unknown-netbsd`    | [64-bit RISC-V](https://wiki.netbsd.org/ports/riscv/)                                |
+| 3                   | `sparc64-unknown-netbsd`      | [Sun UltraSPARC systems](https://wiki.netbsd.org/ports/sparc64/)                     |
 
 All use the "native" `stdc++` library which goes along with the natively
 supplied GNU C++ compiler for the given OS version.  Many of the bootstraps
diff --git a/src/doc/rustc/src/platform-support/wasm32-wasip1.md b/src/doc/rustc/src/platform-support/wasm32-wasip1.md
index 4f065a554cf..a8a9e550581 100644
--- a/src/doc/rustc/src/platform-support/wasm32-wasip1.md
+++ b/src/doc/rustc/src/platform-support/wasm32-wasip1.md
@@ -4,37 +4,35 @@
 
 The `wasm32-wasip1` target is a WebAssembly compilation target which
 assumes that the [WASIp1] (aka "WASI preview1") set of "syscalls" are available
-for use in the standard library. Historically this target in the Rust compiler
-was one of the first for WebAssembly where Rust and C code are explicitly
-intended to interoperate as well.
-
-There's a bit of history to the target and current development which is also
-worth explaining before going much further. Historically this target was
-originally called `wasm32-wasi` in both rustc and Clang. This was first added
-to Rust in 2019. In the intervening years leading up to 2024 the WASI standard
-continued to be developed and was eventually "rebased" on top of the [Component
-Model]. This was a large change to the WASI specification and was released as
-0.2.0 ("WASIp2" colloquially) in January 2024. The previous target's name in
-rustc, `wasm32-wasi`, was then renamed to `wasm32-wasip1`, to avoid
-confusion with this new target to be added to rustc as `wasm32-wasip2`.
-Some more context can be found in these MCPs:
-
-* [Rename wasm32-wasi target to wasm32-wasip1](https://github.com/rust-lang/compiler-team/issues/607)
-* [Smooth the renaming transition of wasm32-wasi](https://github.com/rust-lang/compiler-team/issues/695)
-
-At this point the `wasm32-wasip1` target is intended for historical
-compatibility with the first version of the WASI standard. As of now (January
-2024) the 0.2.0 target of WASI ("WASIp2") is relatively new. The state of
-WASI will likely change in few years after which point this documentation will
-probably receive another update.
-
-[WASI Preview1]: https://github.com/WebAssembly/WASI/tree/main/legacy/preview1
+for use in the standard library. This target explicitly supports interop with
+non-Rust code such as C and C++.
+
+The [WASIp1] set of syscalls is standard insofar as it was written down once by
+a set of folks and has not changed since then. Additionally the [WASIp1]
+syscalls have been adapted and adopted into a number of runtimes and embeddings.
+It is not standard in the sense that there are no formal semantics for each
+syscall and APIs are no longer receiving any maintenance (e.g. no new APIs, no
+new documentation, etc). After [WASIp1] was originally developed in 2019 the
+WASI standard effort has since been "rebased" on top of the [Component Model].
+This was a large change to the WASI specification and was released as 0.2.0
+("WASIp2" colloquially) in January 2024. Current standardization efforts are
+focused on the Component Model-based definition of WASI. At this point the
+`wasm32-wasip1` Rust target is intended for historical compatibility with
+[WASIp1] set of syscalls.
+
+[WASIp1]: https://github.com/WebAssembly/WASI/tree/main/legacy/preview1
 [Component Model]: https://github.com/webassembly/component-model
 
 Today the `wasm32-wasip1` target will generate core WebAssembly modules
 which will import functions from the `wasi_snapshot_preview1` module for
 OS-related functionality (e.g. printing).
 
+> **Note**: Prior to March 2024 this target was known as `wasm32-wasi` with some
+> historical context found in old MCPs:
+>
+> * [Rename wasm32-wasi target to wasm32-wasip1](https://github.com/rust-lang/compiler-team/issues/607)
+> * [Smooth the renaming transition of wasm32-wasi](https://github.com/rust-lang/compiler-team/issues/695)
+
 ## Target maintainers
 
 When this target was added to the compiler platform-specific documentation here
@@ -44,6 +42,7 @@ said since when this document was last updated those interested in maintaining
 this target are:
 
 [@alexcrichton](https://github.com/alexcrichton)
+[@loganek](https://github.com/loganek)
 
 ## Requirements
 
diff --git a/src/doc/rustdoc.md b/src/doc/rustdoc.md
index d4a25efec17..90ce7f8b225 100644
--- a/src/doc/rustdoc.md
+++ b/src/doc/rustdoc.md
@@ -1,3 +1,3 @@
 % Rust Documentation
 
-This has been moved [into the book](book/documentation.html).
+This has been moved [into the rustdoc book](rustdoc/index.html).
diff --git a/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md b/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md
index 65e6b417427..4d7f1a4aafc 100644
--- a/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md
+++ b/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md
@@ -62,7 +62,7 @@ This form of the `doc` attribute lets you control the favicon of your docs.
 This will put `<link rel="icon" href="{}">` into your docs, where
 the string for the attribute goes into the `{}`.
 
-If you don't use this attribute, there will be no favicon.
+If you don't use this attribute, a default favicon will be used.
 
 ### `html_logo_url`
 
diff --git a/src/doc/unstable-book/src/compiler-flags/codegen-options.md b/src/doc/unstable-book/src/compiler-flags/codegen-options.md
index cc51554706d..f927e5c439c 100644
--- a/src/doc/unstable-book/src/compiler-flags/codegen-options.md
+++ b/src/doc/unstable-book/src/compiler-flags/codegen-options.md
@@ -51,10 +51,10 @@ instead of those in the system. The stable boolean values for this flag are coar
 - `mingw`: other MinGW libs and Windows import libs
 
 Out of the above self-contained linking components, `linker` is the only one currently implemented
-(beyond parsing the CLI options).
+(beyond parsing the CLI options) and stabilized.
 
 It refers to the LLD linker, built from the same LLVM revision used by rustc (named `rust-lld` to
 avoid naming conflicts), that is distributed via `rustup` with the compiler (and is used by default
-for the wasm targets). One can also opt-in to use it by combining this flag with an appropriate
-linker flavor: for example, `-Clinker-flavor=gnu-lld-cc -Clink-self-contained=+linker` will use the
-toolchain's `rust-lld` as the linker.
+for the wasm targets). One can also opt into using it by combining this flag with the appropriate
+linker feature: for example, `-Clinker-features=+lld -Clink-self-contained=+linker` will use the
+toolchain's `rust-lld` as the linker instead of the system's lld with `-Clinker-features=+lld` only.
diff --git a/src/doc/unstable-book/src/compiler-flags/linker-features.md b/src/doc/unstable-book/src/compiler-flags/linker-features.md
deleted file mode 100644
index 643fcf7c6d7..00000000000
--- a/src/doc/unstable-book/src/compiler-flags/linker-features.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# `linker-features`
-
---------------------
-
-The `-Zlinker-features` compiler flag allows enabling or disabling specific features used during
-linking, and is intended to be stabilized under the codegen options as `-Clinker-features`.
-
-These feature flags are a flexible extension mechanism that is complementary to linker flavors,
-designed to avoid the combinatorial explosion of having to create a new set of flavors for each
-linker feature we'd want to use.
-
-For example, this design allows:
-- default feature sets for principal flavors, or for specific targets.
-- flavor-specific features: for example, clang offers automatic cross-linking with `--target`, which
-  gcc-style compilers don't support. The *flavor* is still a C/C++ compiler, and we don't want to
-  multiply the number of flavors for this use-case. Instead, we can have a single `+target` feature.
-- umbrella features: for example, if clang accumulates more features in the future than just the
-  `+target` above. That could be modeled as `+clang`.
-- niche features for resolving specific issues: for example, on Apple targets the linker flag
-  implementing the `as-needed` native link modifier (#99424) is only possible on sufficiently recent
-  linker versions.
-- still allows for discovery and automation, for example via feature detection. This can be useful
-  in exotic environments/build systems.
-
-The flag accepts a comma-separated list of features, individually enabled (`+features`) or disabled
-(`-features`), though currently only one is exposed on the CLI:
-- `lld`: to toggle using the lld linker, either the system-installed binary, or the self-contained
-  `rust-lld` linker.
-
-As described above, this list is intended to grow in the future.
-
-One of the most common uses of this flag will be to toggle self-contained linking with `rust-lld` on
-and off: `-Clinker-features=+lld -Clink-self-contained=+linker` will use the toolchain's `rust-lld`
-as the linker. Inversely, `-Clinker-features=-lld` would opt out of that, if the current target had
-self-contained linking enabled by default.
diff --git a/src/doc/unstable-book/src/language-features/type-alias-impl-trait.md b/src/doc/unstable-book/src/language-features/type-alias-impl-trait.md
index a6fb25a55be..10464e500ec 100644
--- a/src/doc/unstable-book/src/language-features/type-alias-impl-trait.md
+++ b/src/doc/unstable-book/src/language-features/type-alias-impl-trait.md
@@ -64,7 +64,7 @@ struct HaveAlias {
 
 In this example, the concrete type referred to by `Alias` is guaranteed to be the same wherever `Alias` occurs.
 
-> Orginally this feature included type aliases as an associated type of a trait. In [#110237] this was split off to [`impl_trait_in_assoc_type`].
+> Originally this feature included type aliases as an associated type of a trait. In [#110237] this was split off to [`impl_trait_in_assoc_type`].
 
 ### `type_alias_impl_trait` in argument position.