about summary refs log tree commit diff
path: root/src/doc/rustc-dev-guide
diff options
context:
space:
mode:
authorJakub Beránek <berykubik@gmail.com>2025-07-08 16:18:56 +0200
committerJakub Beránek <berykubik@gmail.com>2025-07-08 16:18:56 +0200
commitbdead41b65ed10d6c947b20ddb724f1ae59e2b48 (patch)
tree05a5849ce18ed88207f14d23da57a06dfc1e8126 /src/doc/rustc-dev-guide
parent3c9297c845c513a2609dd915ca9346664fe82663 (diff)
parent040e2f8b9ff2d76fbe2146d6003e297ed4532088 (diff)
downloadrust-bdead41b65ed10d6c947b20ddb724f1ae59e2b48.tar.gz
rust-bdead41b65ed10d6c947b20ddb724f1ae59e2b48.zip
Merge ref '040e2f8b9ff2' from rust-lang/rust
Pull recent changes from https://github.com/rust-lang/rust via Josh.

Upstream ref: 040e2f8b9ff2d76fbe2146d6003e297ed4532088
Filtered ref: cf4d00a666607e356e410a820ae07eeba28a9b53

This merge was created using https://github.com/rust-lang/josh-sync.
Diffstat (limited to 'src/doc/rustc-dev-guide')
-rw-r--r--src/doc/rustc-dev-guide/josh-sync.toml3
-rw-r--r--src/doc/rustc-dev-guide/rust-version2
-rw-r--r--src/doc/rustc-dev-guide/src/autodiff/internals.md4
-rw-r--r--src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md18
-rw-r--r--src/doc/rustc-dev-guide/src/contributing.md4
-rw-r--r--src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md47
-rw-r--r--src/doc/rustc-dev-guide/src/hir/lowering.md6
-rw-r--r--src/doc/rustc-dev-guide/src/solve/opaque-types.md2
-rw-r--r--src/doc/rustc-dev-guide/src/tests/ci.md11
-rw-r--r--src/doc/rustc-dev-guide/src/tests/minicore.md6
-rw-r--r--src/doc/rustc-dev-guide/src/tests/ui.md8
11 files changed, 89 insertions, 22 deletions
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/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/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