Merge branch 'master' of https://github.com/rust-lang/reference into c-unwind-documentation

Author: BatmanAoD

.github/workflows/main.yml

@@ -1,5 +1,7 @@
 name: CI
-on: [push, pull_request]
+on:
+  pull_request:
+  merge_group:
 
 jobs:
   test:

src/SUMMARY.md

@@ -44,6 +44,7 @@
     - [Code generation](attributes/codegen.md)
     - [Limits](attributes/limits.md)
     - [Type System](attributes/type_system.md)
+    - [Debugger](attributes/debugger.md)
 
 - [Statements and expressions](statements-and-expressions.md)
     - [Statements](statements.md)

src/attributes.md

@@ -271,6 +271,8 @@ The following is an index of all built-in attributes.
 - Type System
   - [`non_exhaustive`] — Indicate that a type will have more fields/variants
     added in future.
+- Debugger
+  - [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type.
 
 [Doc comments]: comments.md#doc-comments
 [ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
@@ -291,6 +293,7 @@ The following is an index of all built-in attributes.
 [`cold`]: attributes/codegen.md#the-cold-attribute
 [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
 [`crate_type`]: linkage.md
+[`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute
 [`deny`]: attributes/diagnostics.md#lint-check-attributes
 [`deprecated`]: attributes/diagnostics.md#the-deprecated-attribute
 [`derive`]: attributes/derive.md

src/attributes/codegen.md

@@ -89,9 +89,11 @@ Feature     | Implicitly Enables | Description
 `bmi1`      |          | [BMI1] — Bit Manipulation Instruction Sets
 `bmi2`      |          | [BMI2] — Bit Manipulation Instruction Sets 2
 `cmpxchg16b`|          | [`cmpxchg16b`] - Compares and exchange 16 bytes (128 bits) of data atomically
+`f16c`      | `avx`    | [F16C] — 16-bit floating point conversion instructions
 `fma`       | `avx`    | [FMA3] — Three-operand fused multiply-add
 `fxsr`      |          | [`fxsave`] and [`fxrstor`] — Save and restore x87 FPU, MMX Technology, and SSE State
 `lzcnt`     |          | [`lzcnt`] — Leading zeros count
+`movbe`     |          | [`movbe`] - Move data after swapping bytes
 `pclmulqdq` | `sse2`   | [`pclmulqdq`] — Packed carry-less multiplication quadword
 `popcnt`    |          | [`popcnt`] — Count of bits set to 1
 `rdrand`    |          | [`rdrand`] — Read random number
@@ -117,10 +119,12 @@ Feature     | Implicitly Enables | Description
 [BMI1]: https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets
 [BMI2]: https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets#BMI2
 [`cmpxchg16b`]: https://www.felixcloutier.com/x86/cmpxchg8b:cmpxchg16b
+[F16C]: https://en.wikipedia.org/wiki/F16C
 [FMA3]: https://en.wikipedia.org/wiki/FMA_instruction_set
 [`fxsave`]: https://www.felixcloutier.com/x86/fxsave
 [`fxrstor`]: https://www.felixcloutier.com/x86/fxrstor
 [`lzcnt`]: https://www.felixcloutier.com/x86/lzcnt
+[`movbe`]: https://www.felixcloutier.com/x86/movbe
 [`pclmulqdq`]: https://www.felixcloutier.com/x86/pclmulqdq
 [`popcnt`]: https://www.felixcloutier.com/x86/popcnt
 [`rdrand`]: https://en.wikipedia.org/wiki/RdRand
@@ -357,15 +361,20 @@ trait object whose methods are attributed.
 
 ## The `instruction_set` attribute
 
-The *`instruction_set` attribute* may be applied to a function to enable code generation for a specific
-instruction set supported by the target architecture. It uses the [_MetaListPath_] syntax and a path
-comprised of the architecture and instruction set to specify how to generate the code for
-architectures where a single program may utilize multiple instruction sets.
+The *`instruction_set` [attribute]* may be applied to a function to control which instruction set the function will be generated for.
+This allows mixing more than one instruction set in a single program on CPU architectures that support it.
+It uses the [_MetaListPath_] syntax, and a path comprised of the architecture family name and instruction set name.
 
-The following values are available on targets for the `ARMv4` and `ARMv5te` architectures:
+[_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax
+
+It is a compilation error to use the `instruction_set` attribute on a target that does not support it.
+
+### On ARM
 
-* `arm::a32` - Uses ARM code.
-* `arm::t32` - Uses Thumb code.
+For the `ARMv4T` and `ARMv5te` architectures, the following are supported:
+
+* `arm::a32` - Generate the function as A32 "ARM" code.
+* `arm::t32` - Generate the function as T32 "Thumb" code.
 
 <!-- ignore: arm-only -->
 ```rust,ignore
@@ -376,4 +385,7 @@ fn foo_arm_code() {}
 fn bar_thumb_code() {}
 ```
 
-[_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax
+Using the `instruction_set` attribute has the following effects:
+
+* If the address of the function is taken as a function pointer, the low bit of the address will be set to 0 (arm) or 1 (thumb) depending on the instruction set.
+* Any inline assembly in the function must use the specified instruction set instead of the target default.

src/attributes/debugger.md

@@ -0,0 +1,141 @@
+# Debugger attributes
+
+The following [attributes] are used for enhancing the debugging experience when using third-party debuggers like GDB or WinDbg.
+
+## The `debugger_visualizer` attribute
+
+The *`debugger_visualizer` attribute* can be used to embed a debugger visualizer file into the debug information.
+This enables an improved debugger experience for displaying values in the debugger.
+It uses the [_MetaListNameValueStr_] syntax to specify its inputs, and must be specified as a crate attribute.
+
+### Using `debugger_visualizer` with Natvis
+
+Natvis is an XML-based framework for Microsoft debuggers (such as Visual Studio and WinDbg) that uses declarative rules to customize the display of types.
+For detailed information on the Natvis format, refer to Microsoft's [Natvis documentation].
+
+This attribute only supports embedding Natvis files on `-windows-msvc` targets.
+
+The path to the Natvis file is specified with the `natvis_file` key, which is a path relative to the crate source file:
+
+<!-- ignore: requires external files, and msvc -->
+```rust ignore
+#![debugger_visualizer(natvis_file = "Rectangle.natvis")]
+
+struct FancyRect {
+    x: f32,
+    y: f32,
+    dx: f32,
+    dy: f32,
+}
+
+fn main() {
+    let fancy_rect = FancyRect { x: 10.0, y: 10.0, dx: 5.0, dy: 5.0 };
+    println!("set breakpoint here");
+}
+```
+
+and `Rectangle.natvis` contains:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
+    <Type Name="foo::FancyRect">
+      <DisplayString>({x},{y}) + ({dx}, {dy})</DisplayString>
+      <Expand>
+        <Synthetic Name="LowerLeft">
+          <DisplayString>({x}, {y})</DisplayString>
+        </Synthetic>
+        <Synthetic Name="UpperLeft">
+          <DisplayString>({x}, {y + dy})</DisplayString>
+        </Synthetic>
+        <Synthetic Name="UpperRight">
+          <DisplayString>({x + dx}, {y + dy})</DisplayString>
+        </Synthetic>
+        <Synthetic Name="LowerRight">
+          <DisplayString>({x + dx}, {y})</DisplayString>
+        </Synthetic>
+      </Expand>
+    </Type>
+</AutoVisualizer>
+```
+
+When viewed under WinDbg, the `fancy_rect` variable would be shown as follows:
+
+```text
+> Variables:
+  > fancy_rect: (10.0, 10.0) + (5.0, 5.0)
+    > LowerLeft: (10.0, 10.0)
+    > UpperLeft: (10.0, 15.0)
+    > UpperRight: (15.0, 15.0)
+    > LowerRight: (15.0, 10.0)
+```
+
+### Using `debugger_visualizer` with GDB
+
+GDB supports the use of a structured Python script, called a *pretty printer*, that describes how a type should be visualized in the debugger view.
+For detailed information on pretty printers, refer to GDB's [pretty printing documentation].
+
+Embedded pretty printers are not automatically loaded when debugging a binary under GDB.
+There are two ways to enable auto-loading embedded pretty printers:
+1. Launch GDB with extra arguments to explicitly add a directory or binary to the auto-load safe path: `gdb -iex "add-auto-load-safe-path safe-path path/to/binary" path/to/binary`
+ For more information, see GDB's [auto-loading documentation].
+1. Create a file named `gdbinit` under `$HOME/.config/gdb` (you may need to create the directory if it doesn't already exist). Add the following line to that file: `add-auto-load-safe-path path/to/binary`.
+
+These scripts are embedded using the `gdb_script_file` key, which is a path relative to the crate source file.
+
+<!-- ignore: requires external files -->
+```rust ignore
+#![debugger_visualizer(gdb_script_file = "printer.py")]
+
+struct Person {
+    name: String,
+    age: i32,
+}
+
+fn main() {
+    let bob = Person { name: String::from("Bob"), age: 10 };
+    println!("set breakpoint here");
+}
+```
+
+and `printer.py` contains:
+
+```python
+import gdb
+
+class PersonPrinter:
+    "Print a Person"
+
+    def __init__(self, val):
+        self.val = val
+        self.name = val["name"]
+        self.age = int(val["age"])
+
+    def to_string(self):
+        return "{} is {} years old.".format(self.name, self.age)
+
+def lookup(val):
+    lookup_tag = val.type.tag
+    if lookup_tag is None:
+        return None
+    if "foo::Person" == lookup_tag:
+        return PersonPrinter(val)
+
+    return None
+
+gdb.current_objfile().pretty_printers.append(lookup)
+```
+
+When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` will display:
+
+```text
+"Bob" is 10 years old.
+```
+
+[^rust-gdb]: Note: This assumes you are using the `rust-gdb` script which configures pretty-printers for standard library types like `String`.
+
+[auto-loading documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Auto_002dloading-safe-path.html
+[attributes]: ../attributes.md
+[Natvis documentation]: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects
+[pretty printing documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
+[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax

src/attributes/diagnostics.md

@@ -49,7 +49,7 @@ check on and off:
 
 ```rust
 #[warn(missing_docs)]
-pub mod m2{
+pub mod m2 {
     #[allow(missing_docs)]
     pub mod nested {
         // Missing documentation is ignored here

src/behavior-considered-undefined.md

@@ -42,9 +42,12 @@ code.
   All this also applies when values of these
   types are passed in a (nested) field of a compound type, but not behind
   pointer indirections.
-* Mutating immutable data. All data inside a [`const`] item is immutable. Moreover, all
-  data reached through a shared reference or data owned by an immutable binding
-  is immutable, unless that data is contained within an [`UnsafeCell<U>`].
+* Mutating immutable bytes. All bytes inside a [`const`] item are immutable.
+  The bytes owned by an immutable binding are immutable, unless those bytes are part of an [`UnsafeCell<U>`].
+
+  Moreover, the bytes [pointed to] by a shared reference, including transitively through other references (both shared and mutable) and `Box`es, are immutable; transitivity includes those references stored in fields of compound types.
+
+  A mutation is any write of more than 0 bytes which overlaps with any of the relevant bytes (even if that write does not change the memory contents).
 * Invoking undefined behavior via compiler intrinsics.
 * Executing code compiled with platform features that the current platform
   does not support (see [`target_feature`]), *except* if the platform explicitly documents this to be safe.
@@ -79,6 +82,11 @@ code.
     > `rustc_layout_scalar_valid_range_*` attributes.
 * Incorrect use of inline assembly. For more details, refer to the [rules] to
   follow when writing code that uses inline assembly.
+* **In [const context](const_eval.md#const-context)**: transmuting or otherwise
+  reinterpreting a pointer (reference, raw pointer, or function pointer) into
+  some allocated object as a non-pointer type (such as integers).
+  'Reinterpreting' refers to loading the pointer value at integer type without a
+  cast, e.g. by doing raw pointer casts or using a union.
 
 **Note:** Uninitialized memory is also implicitly invalid for any type that has
 a restricted set of valid values. In other words, the only cases in which
@@ -91,13 +99,16 @@ reading uninitialized memory is permitted are inside `union`s and in "padding"
 > vice versa, undefined behavior in Rust can cause adverse affects on code
 > executed by any FFI calls to other languages.
 
+### Pointed-to bytes
+
+The span of bytes a pointer or reference "points to" is determined by the pointer value and the size of the pointee type (using `size_of_val`).
+
 ### Dangling pointers
 [dangling]: #dangling-pointers
 
 A reference/pointer is "dangling" if it is null or not all of the bytes it
-points to are part of the same live allocation (so in particular they all have to be
-part of *some* allocation). The span of bytes it points to is determined by the
-pointer value and the size of the pointee type (using `size_of_val`).
+[points to] are part of the same live allocation (so in particular they all have to be
+part of *some* allocation).
 
 If the size is 0, then the pointer must either point inside of a live allocation
 (including pointing just after the last byte of the allocation), or it must be
@@ -121,3 +132,5 @@ must never exceed `isize::MAX`.
 [dereference expression]: expressions/operator-expr.md#the-dereference-operator
 [place expression context]: expressions.md#place-expressions-and-value-expressions
 [rules]: inline-assembly.md#rules-for-inline-assembly
+[points to]: #pointed-to-bytes
+[pointed to]: #pointed-to-bytes

src/comments.md

@@ -42,7 +42,7 @@ Non-doc comments are interpreted as a form of whitespace.
 ## Doc comments
 
 Line doc comments beginning with exactly _three_ slashes (`///`), and block
-doc comments (`/** ... */`), both inner doc comments, are interpreted as a
+doc comments (`/** ... */`), both outer doc comments, are interpreted as a
 special syntax for [`doc` attributes]. That is, they are equivalent to writing
 `#[doc="..."]` around the body of the comment, i.e., `/// Foo` turns into
 `#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`.

src/conditional-compilation.md

@@ -129,6 +129,7 @@ Example values:
 * `"dragonfly"`
 * `"openbsd"`
 * `"netbsd"`
+* `"none"` (typical for embedded targets)
 
 ### `target_family`
 
@@ -254,6 +255,12 @@ It is written as `cfg`, `(`, a configuration predicate, and finally `)`.
 If the predicate is true, the thing is rewritten to not have the `cfg` attribute
 on it. If the predicate is false, the thing is removed from the source code.
 
+When a crate-level `cfg` has a false predicate, the behavior is slightly
+different: any crate attributes preceding the `cfg` are kept, and any crate
+attributes following the `cfg` are removed. This allows `#![no_std]` and
+`#![no_core]` crates to avoid linking `std`/`core` even if a `#![cfg(...)]` has
+removed the entire crate.
+
 Some examples on functions:
 
 ```rust

src/destructors.md

@@ -285,7 +285,7 @@ An *extending pattern* is either
 * An [identifier pattern] that binds by reference or mutable reference.
 * A [struct][struct pattern], [tuple][tuple pattern], [tuple struct][tuple
   struct pattern], or [slice][slice pattern] pattern where at least one of the
-  direct subpatterns is a extending pattern.
+  direct subpatterns is an extending pattern.
 
 So `ref x`, `V(ref x)` and `[ref x, y]` are all extending patterns, but `x`,
 `&ref x` and `&(ref x,)` are not.

src/expressions.md

@@ -162,7 +162,7 @@ Explicitly, the assignee expressions are:
 - Place expressions.
 - [Underscores][_UnderscoreExpression_].
 - [Tuples][_TupleExpression_] of assignee expressions.
-- [Slices][_ArrayExpression_] of assingee expressions.
+- [Slices][_ArrayExpression_] of assignee expressions.
 - [Tuple structs][_StructExpression_] of assignee expressions.
 - [Structs][_StructExpression_] of assignee expressions (with optionally named
   fields).

src/expressions/call-expr.md

@@ -48,7 +48,7 @@ trait Pretty {
 }
 
 trait Ugly {
-  fn print(&self);
+    fn print(&self);
 }
 
 struct Foo;

src/expressions/loop-expr.md

@@ -249,8 +249,27 @@ A `break` expression is only permitted in the body of a loop, and has one of the
 >    [_BlockExpression_]
 
 Labelled block expressions are exactly like block expressions, except that they allow using `break` expressions within the block.
-Unlike other loops, `break` expressions within a label expression *must* have a label (i.e. the label is not optional).
-Unlike other loops, labelled block expressions *must* begin with a label.
+Unlike loops, `break` expressions within a labelled block expression *must* have a label (i.e. the label is not optional).
+Similarly, labelled block expressions *must* begin with a label.
+
+```rust
+# fn do_thing() {}
+# fn condition_not_met() -> bool { true }
+# fn do_next_thing() {}
+# fn do_last_thing() {}
+let result = 'block: {
+    do_thing();
+    if condition_not_met() {
+        break 'block 1;
+    }
+    do_next_thing();
+    if condition_not_met() {
+        break 'block 2;
+    }
+    do_last_thing();
+    3
+};
+```
 
 ## `continue` expressions