rustc-dev-guide subtree update

src/doc/rustc-dev-guide/rust-version

@@ -1 +1 @@
-390279b302ca98ae270f434100ae3730531d1246
+da86f4d0726be475afbbffe40cb2f65741c51ad3

src/doc/rustc-dev-guide/src/ast-validation.md

@@ -1,28 +1,27 @@
 # AST validation
 
 _AST validation_ is a separate AST pass that visits each
-item in the tree and performs simple checks. This pass
-doesn't perform any complex analysis, type checking or
+item in the tree and performs simple checks.
+This pass doesn't perform any complex analysis, type checking or
 name resolution.
 
-Before performing any validation, the compiler first expands
-the macros. Then this pass performs validations to check
-that each AST item is in the correct state. And when this pass
-is done, the compiler runs the crate resolution pass.
+Before performing any validation, the compiler first expands the macros.
+Then this pass performs validations to check that each AST item is in the correct state.
+And when this pass is done, the compiler runs the crate resolution pass.
 
 ## Validations
 
 Validations are defined in `AstValidator` type, which 
-itself is located in `rustc_ast_passes` crate. This
-type implements various simple checks which emit errors
+itself is located in `rustc_ast_passes` crate.
+This type implements various simple checks which emit errors
 when certain language rules are broken.
 
 In addition, `AstValidator` implements `Visitor` trait
 that defines how to visit AST items (which can be functions,
 traits, enums, etc).
 
-For each item, visitor performs specific checks. For
-example, when visiting a function declaration,
+For each item, visitor performs specific checks.
+For example, when visiting a function declaration,
 `AstValidator` checks that the function has:
 
 * no more than `u16::MAX` parameters;

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

@@ -25,6 +25,35 @@ For more information on these attributes, see the chapter about [attribute parsi
 
 [attr-parsing-chapter]: ./hir/attribute-parsing.md
 
+### Note on adding new builtin attributes
+
+<div class="warning">
+
+**Warning: Name resolution ambiguity potential when adding new builtin attributes**
+
+Please note that adding **new builtin attributes** (whose name is not reserved, i.e. a new builtin
+attribute whose name does not start with `rustc`), even if *unstable*-gated, can introduce breakage
+from name resolution ambiguity in stable code if (1) the stable code has a macro of the same name
+which gets re-exported, or (2) or a proc-macro derive helper attribute of the same name.
+
+Typically, the builtin attributes probably has to start out as `#[rustc_foo]` instead of `#[foo]` to
+avoid colliding with user-defined macros and proc-macro helper attributes.
+Then, prior to stabilization,
+a rename to `#[foo]` should be done separately with a crater run to assess fallout,
+with a deliberate breakage FCP proposal for T-lang to consider.
+
+Remember also that crater is *not* exhaustive and does not contain all existing stable code.
+
+See:
+- [Built-in attributes are treated differently vs prelude attributes, unstable built-in attributes
+  can name-collide with stable macro, and built-in attributes can break back-compat
+  #134963](https://github.com/rust-lang/rust/issues/134963) and backlinks within this issue,
+  including design discussions on how to fix this kind of breakage hazard.
+- [Broken build after updating: coverage is ambiguous; ambiguous because of a name conflict with a
+  builtin attribute #121157](https://github.com/rust-lang/rust/issues/121157).
+- [Regression: align is ambiguous #143834](https://github.com/rust-lang/rust/issues/143834).
+</div>
+
 ## 'Non-builtin'/'active' attributes
 
 These attributes are defined by a crate - either the standard library, or a proc-macro crate.

src/doc/rustc-dev-guide/src/const-eval.md

@@ -1,8 +1,9 @@
 # Constant Evaluation
 
-Constant evaluation is the process of computing values at compile time. For a
-specific item (constant/static/array length) this happens after the MIR for the
-item is borrow-checked and optimized. In many cases trying to const evaluate an
+Constant evaluation is the process of computing values at compile time.
+For a specific item (constant/static/array length) this happens after the MIR for the
+item is borrow-checked and optimized.
+In many cases trying to const evaluate an
 item will trigger the computation of its MIR for the first time.
 
 Prominent examples are:
@@ -11,14 +12,12 @@ Prominent examples are:
 * Array length
     * needs to be known to reserve stack or heap space
 * Enum variant discriminants
-    * needs to be known to prevent two variants from having the same
-      discriminant
+    * needs to be known to prevent two variants from having the same discriminant
 * Patterns
     * need to be known to check for overlapping patterns
 
 Additionally constant evaluation can be used to reduce the workload or binary
-size at runtime by precomputing complex operations at compile time and only
-storing the result.
+size at runtime by precomputing complex operations at compile time and only storing the result.
 
 All uses of constant evaluation can either be categorized as "influencing the type system"
 (array lengths, enum variant discriminants, const generic parameters), or as solely being
@@ -37,7 +36,8 @@ They're the wrappers of the `const_eval` query.
 
 The `const_eval_*` functions use a [`ParamEnv`](./typing-parameter-envs.md) 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
+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.
 
 Constant evaluation returns an [`EvalToValTreeResult`] for type system constants

src/doc/rustc-dev-guide/src/notification-groups/gpu-target.md

@@ -3,14 +3,13 @@
 **Github Label:** None <br>
 **Ping command:** `@rustbot ping gpu-target`
 
-This notification group deals with linker related issues and their integration
-within the compiler.
+This notification group deals with linker-related issues and their integration within the compiler.
 
 The group also has an associated Zulip stream ([`#t-compiler/gpgpu-backend`])
 where people can go to ask questions and discuss GPU-related topics and issues.
 
-if you're interested in participating, feel free to sign up for this group! To
-do so, open a PR against the [rust-lang/team] repository and add your GitHub
+if you're interested in participating, feel free to sign up for this group!
+To do so, open a PR against the [rust-lang/team] repository and add your GitHub
 user to [this file][gpu-target-team].
 
 [`#t-compiler/gpgpu-backend`]: https://rust-lang.zulipchat.com/#narrow/channel/422870-t-compiler.2Fgpgpu-backend

src/doc/rustc-dev-guide/src/notification-groups/wasi.md

@@ -14,8 +14,8 @@ where people can go to pose questions and discuss WASI-specific topics.
 
 So, if you are interested in participating, please sign up for the WASI group!
 To do so, open a PR against the [rust-lang/team] repository.
-Just [follow this example][eg], but change the username to your own!
+Just follow [this example], but change the username to your own!
 
 [`#t-compiler/wasm`]: https://rust-lang.zulipchat.com/#narrow/stream/463513-t-compiler.2Fwasm
 [rust-lang/team]: https://github.com/rust-lang/team
-[eg]: https://github.com/rust-lang/team/pull/1580
+[this example]: https://github.com/rust-lang/team/pull/1580

src/doc/rustc-dev-guide/src/notification-groups/wasm.md

@@ -10,14 +10,12 @@ WebAssembly-related issues as well as suggestions on how to resolve
 interesting questions regarding our WASM support.
 
 The group also has an associated Zulip channel ([`#t-compiler/wasm`])
-where people can go to pose questions and discuss WASM-specific
-topics.
+where people can go to pose questions and discuss WASM-specific topics.
 
-So, if you are interested in participating, please sign up for the
-WASM group! To do so, open a PR against the [rust-lang/team]
-repository. Just [follow this example][eg], but change the username to
-your own!
+So, if you are interested in participating, please sign up for the WASM group!
+To do so, open a PR against the [rust-lang/team] repository.
+Just follow [this example], but change the username to your own!
 
 [`#t-compiler/wasm`]: https://rust-lang.zulipchat.com/#narrow/stream/463513-t-compiler.2Fwasm
 [rust-lang/team]: https://github.com/rust-lang/team
-[eg]: https://github.com/rust-lang/team/pull/1581
+[this example]: https://github.com/rust-lang/team/pull/1581

src/doc/rustc-dev-guide/src/pat-exhaustive-checking.md

@@ -1,7 +1,7 @@
 # Pattern and exhaustiveness checking
 
-In Rust, pattern matching and bindings have a few very helpful properties. The
-compiler will check that bindings are irrefutable when made and that match arms
+In Rust, pattern matching and bindings have a few very helpful properties.
+The compiler will check that bindings are irrefutable when made and that match arms
 are exhaustive.
 
 ## Pattern usefulness
@@ -35,8 +35,7 @@ match x {
 }
 ```
 
-Thus usefulness is used for two purposes:
-detecting unreachable code (which is useful to the user),
+Thus usefulness is used for two purposes: detecting unreachable code (which is useful to the user),
 and ensuring that matches are exhaustive (which is important for soundness,
 because a match expression can return a value).
 
@@ -88,22 +87,26 @@ That file contains a detailed description of the algorithm.
 ### Constructors and fields
 
 In the value `Pair(Some(0), true)`, `Pair` is called the constructor of the value, and `Some(0)` and
-`true` are its fields. Every matchable value can be decomposed in this way. Examples of
-constructors are: `Some`, `None`, `(,)` (the 2-tuple constructor), `Foo {..}` (the constructor for
-a struct `Foo`), and `2` (the constructor for the number `2`).
-
-Each constructor takes a fixed number of fields; this is called its arity. `Pair` and `(,)` have
-arity 2, `Some` has arity 1, `None` and `42` have arity 0. Each type has a known set of
-constructors. Some types have many constructors (like `u64`) or even an infinitely many (like `&str`
-and `&[T]`).
-
-Patterns are similar: `Pair(Some(_), _)` has constructor `Pair` and two fields. The difference is
-that we get some extra pattern-only constructors, namely: the wildcard `_`, variable bindings,
-integer ranges like `0..=10`, and variable-length slices like `[_, .., _]`. We treat or-patterns
-separately.
+`true` are its fields.
+Every matchable value can be decomposed in this way.
+Examples of constructors are:
+`Some`, `None`, `(,)` (the 2-tuple constructor), `Foo {..}` (the constructor for a struct `Foo`),
+and `2` (the constructor for the number `2`).
+
+Each constructor takes a fixed number of fields; this is called its arity.
+`Pair` and `(,)` have arity 2, `Some` has arity 1, `None` and `42` have arity 0.
+Each type has a known set of constructors.
+Some types have many constructors (like `u64`) or even an infinitely many (like `&str` and `&[T]`).
+
+Patterns are similar: `Pair(Some(_), _)` has constructor `Pair` and two fields.
+The difference is that we get some extra pattern-only constructors, namely:
+the wildcard `_`, variable bindings,
+integer ranges like `0..=10`, and variable-length slices like `[_, .., _]`.
+We treat or-patterns separately.
 
 Now to check if a value `v` matches a pattern `p`, we check if `v`'s constructor matches `p`'s
-constructor, then recursively compare their fields if necessary. A few representative examples:
+constructor, then recursively compare their fields if necessary.
+A few representative examples:
 
 - `matches!(v, _) := true`
 - `matches!((v0,  v1), (p0,  p1)) := matches!(v0, p0) && matches!(v1, p1)`
@@ -114,8 +117,9 @@ constructor, then recursively compare their fields if necessary. A few represent
 - `matches!([v0], [p0, .., p1]) := false` (incompatible lengths)
 - `matches!([v0, v1, v2], [p0, .., p1]) := matches!(v0, p0) && matches!(v2, p1)`
 
-This concept is absolutely central to pattern analysis. The [`constructor`] module provides
-functions to extract, list and manipulate constructors. This is a useful enough concept that
+This concept is absolutely central to pattern analysis.
+The [`constructor`] module provides functions to extract, list, and manipulate constructors.
+This is a useful enough concept that
 variations of it can be found in other places of the compiler, like in the MIR-lowering of a match
 expression and in some clippy lints.
 
@@ -125,7 +129,8 @@ The pattern-only constructors (`_`, ranges and variable-length slices) each stan
 normal constructors, e.g. `_: Option<T>` stands for the set {`None`, `Some`} and `[_, .., _]` stands
 for the infinite set {`[,]`, `[,,]`, `[,,,]`, ...} of the slice constructors of arity >= 2.
 
-In order to manage these constructors, we keep them as grouped as possible. For example:
+In order to manage these constructors, we keep them as grouped as possible.
+For example:
 
 ```rust
 match (0, false) {
@@ -137,7 +142,8 @@ match (0, false) {
 
 In this example, all of `0`, `1`, .., `49` match the same arms, and thus can be treated as a group.
 In fact, in this match, the only ranges we need to consider are: `0..50`, `50..=100`,
-`101..=150`,`151..=200` and `201..`. Similarly:
+`101..=150`,`151..=200` and `201..`.
+Similarly:
 
 ```rust
 enum Direction { North, South, East, West }
@@ -156,10 +162,11 @@ time.
 
 ### Usefulness vs reachability in the presence of empty types
 
-This is likely the subtlest aspect of exhaustiveness. To be fully precise, a match doesn't operate
-on a value, it operates on a place. In certain unsafe circumstances, it is possible for a place to
-not contain valid data for its type. This has subtle consequences for empty types. Take the
-following:
+This is likely the subtlest aspect of exhaustiveness.
+To be fully precise, a match doesn't operate on a value; it operates on a place.
+In certain unsafe circumstances, it is possible for a place to not contain valid data for its type.
+This has subtle consequences for empty types.
+Take the following:
 
 ```rust
 enum Void {}
@@ -172,10 +179,11 @@ unsafe {
 }
 ```
 
-In this example, `ptr` is a valid pointer pointing to a place with invalid data. The `_` pattern
-does not look at the contents of the place `*ptr`, so this code is ok and the arm is taken. In other
-words, despite the place we are inspecting being of type `Void`, there is a reachable arm. If the
-arm had a binding however:
+In this example, `ptr` is a valid pointer pointing to a place with invalid data.
+The `_` pattern does not look at the contents of the place `*ptr`,
+so this code is ok and the arm is taken.
+In other words, despite the place we are inspecting being of type `Void`, there is a reachable arm.
+If the arm had a binding however:
 
 ```rust
 # #[derive(Copy, Clone)]
@@ -189,25 +197,31 @@ match *ptr {
 # }
 ```
 
-Here the binding loads the value of type `Void` from the `*ptr` place. In this example, this causes
-UB since the data is not valid. In the general case, this asserts validity of the data at `*ptr`.
+Here the binding loads the value of type `Void` from the `*ptr` place.
+In this example, this causes UB since the data is not valid.
+In the general case, this asserts validity of the data at `*ptr`.
 Either way, this arm will never be taken.
 
-Finally, let's consider the empty match `match *ptr {}`. If we consider this exhaustive, then
-having invalid data at `*ptr` is invalid. In other words, the empty match is semantically
-equivalent to the `_a => ...` match. In the interest of explicitness, we prefer the case with an
-arm, hence we won't tell the user to remove the `_a` arm. In other words, the `_a` arm is
-unreachable yet not redundant. This is why we lint on redundant arms rather than unreachable
+Finally, let's consider the empty match `match *ptr {}`.
+If we consider this exhaustive, then having invalid data at `*ptr` is invalid.
+In other words, the empty match is semantically equivalent to the `_a => ...` match.
+In the interest of explicitness, we prefer the case with an
+arm, hence we won't tell the user to remove the `_a` arm.
+In other words, the `_a` arm is unreachable yet not redundant.
+This is why we lint on redundant arms rather than unreachable
 arms, despite the fact that the lint says "unreachable".
 
 These considerations only affects certain places, namely those that can contain non-valid data
-without UB. These are: pointer dereferences, reference dereferences, and union field accesses. We
-track during exhaustiveness checking whether a given place is known to contain valid data.
+without UB.
+These are: pointer dereferences, reference dereferences, and union field accesses.
+We track during exhaustiveness checking whether a given place is known to contain valid data.
 
 Having said all that, the current implementation of exhaustiveness checking does not follow the
-above considerations. On stable, empty types are for the most part treated as non-empty. The
-[`exhaustive_patterns`] feature errs on the other end: it allows omitting arms that could be
-reachable in unsafe situations. The [`never_patterns`] experimental feature aims to fix this and
+above considerations.
+On stable, empty types are for the most part treated as non-empty.
+The [`exhaustive_patterns`] feature errs on the other end: it allows omitting arms that could be
+reachable in unsafe situations.
+The [`never_patterns`] experimental feature aims to fix this and
 permit the correct behavior of empty types in patterns.
 
 [`check_match`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_build/thir/pattern/check_match/index.html