Auto merge of #133193 - fmease:rollup-v38ayvk, r=fmease

Rollup of 9 pull requests

Successful merges:

 - #132758 (Improve `{BTreeMap,HashMap}::get_key_value` docs.)
 - #133180 ([rustdoc] Fix items with generics not having their jump to def link generated)
 - #133181 (Update books)
 - #133182 (const_panic: inline in bootstrap builds to avoid f16/f128 crashes)
 - #133185 (rustdoc-search: use smart binary search in bitmaps)
 - #133186 (Document s390x-unknown-linux targets)
 - #133187 (Add reference annotations for diagnostic attributes)
 - #133191 (rustdoc book: Move `--test-builder(--wrapper)?` docs to unstable section.)
 - #133192 (RELEASES.md: Don't document unstable `--test-build-wrapper`)

r? `@ghost`
`@rustbot` modify labels: rollup

RELEASES.md

@@ -670,13 +670,6 @@ Cargo
 - [Support `target.<triple>.rustdocflags` officially](https://github.com/rust-lang/cargo/pull/13197/)
 - [Stabilize global cache data tracking](https://github.com/rust-lang/cargo/pull/13492/)
 
-<a id="1.78.0-Misc"></a>
-
-Misc
-----
-
-- [rustdoc: add `--test-builder-wrapper` arg to support wrappers such as RUSTC_WRAPPER when building doctests](https://github.com/rust-lang/rust/pull/114651/)
-
 <a id="1.78.0-Compatibility-Notes"></a>
 
 Compatibility Notes

library/alloc/src/collections/btree/map.rs

@@ -677,20 +677,58 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
         }
     }
 
-    /// Returns the key-value pair corresponding to the supplied key.
+    /// Returns the key-value pair corresponding to the supplied key. This is
+    /// potentially useful:
+    /// - for key types where non-identical keys can be considered equal;
+    /// - for getting the `&K` stored key value from a borrowed `&Q` lookup key; or
+    /// - for getting a reference to a key with the same lifetime as the collection.
     ///
     /// The supplied key may be any borrowed form of the map's key type, but the ordering
     /// on the borrowed form *must* match the ordering on the key type.
     ///
     /// # Examples
     ///
     /// ```
+    /// use std::cmp::Ordering;
     /// use std::collections::BTreeMap;
     ///
+    /// #[derive(Clone, Copy, Debug)]
+    /// struct S {
+    ///     id: u32,
+    /// #   #[allow(unused)] // prevents a "field `name` is never read" error
+    ///     name: &'static str, // ignored by equality and ordering operations
+    /// }
+    ///
+    /// impl PartialEq for S {
+    ///     fn eq(&self, other: &S) -> bool {
+    ///         self.id == other.id
+    ///     }
+    /// }
+    ///
+    /// impl Eq for S {}
+    ///
+    /// impl PartialOrd for S {
+    ///     fn partial_cmp(&self, other: &S) -> Option<Ordering> {
+    ///         self.id.partial_cmp(&other.id)
+    ///     }
+    /// }
+    ///
+    /// impl Ord for S {
+    ///     fn cmp(&self, other: &S) -> Ordering {
+    ///         self.id.cmp(&other.id)
+    ///     }
+    /// }
+    ///
+    /// let j_a = S { id: 1, name: "Jessica" };
+    /// let j_b = S { id: 1, name: "Jess" };
+    /// let p = S { id: 2, name: "Paul" };
+    /// assert_eq!(j_a, j_b);
+    ///
     /// let mut map = BTreeMap::new();
-    /// map.insert(1, "a");
-    /// assert_eq!(map.get_key_value(&1), Some((&1, &"a")));
-    /// assert_eq!(map.get_key_value(&2), None);
+    /// map.insert(j_a, "Paris");
+    /// assert_eq!(map.get_key_value(&j_a), Some((&j_a, &"Paris")));
+    /// assert_eq!(map.get_key_value(&j_b), Some((&j_a, &"Paris"))); // the notable case
+    /// assert_eq!(map.get_key_value(&p), None);
     /// ```
     #[stable(feature = "map_get_key_value", since = "1.40.0")]
     pub fn get_key_value<Q: ?Sized>(&self, k: &Q) -> Option<(&K, &V)>

library/core/src/panic.rs

@@ -215,7 +215,7 @@ pub macro const_panic {
                 #[noinline]
                 if const #[track_caller] #[inline] { // Inline this, to prevent codegen
                     $crate::panic!($const_msg)
-                } else #[track_caller] { // Do not inline this, it makes perf worse
+                } else #[track_caller] #[cfg_attr(bootstrap, inline)] { // Do not inline this, it makes perf worse
                     $crate::panic!($runtime_msg)
                 }
             )

library/std/src/collections/hash/map.rs

@@ -880,7 +880,11 @@ where
         self.base.get(k)
     }
 
-    /// Returns the key-value pair corresponding to the supplied key.
+    /// Returns the key-value pair corresponding to the supplied key. This is
+    /// potentially useful:
+    /// - for key types where non-identical keys can be considered equal;
+    /// - for getting the `&K` stored key value from a borrowed `&Q` lookup key; or
+    /// - for getting a reference to a key with the same lifetime as the collection.
     ///
     /// The supplied key may be any borrowed form of the map's key type, but
     /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
@@ -890,11 +894,39 @@ where
     ///
     /// ```
     /// use std::collections::HashMap;
+    /// use std::hash::{Hash, Hasher};
+    ///
+    /// #[derive(Clone, Copy, Debug)]
+    /// struct S {
+    ///     id: u32,
+    /// #   #[allow(unused)] // prevents a "field `name` is never read" error
+    ///     name: &'static str, // ignored by equality and hashing operations
+    /// }
+    ///
+    /// impl PartialEq for S {
+    ///     fn eq(&self, other: &S) -> bool {
+    ///         self.id == other.id
+    ///     }
+    /// }
+    ///
+    /// impl Eq for S {}
+    ///
+    /// impl Hash for S {
+    ///     fn hash<H: Hasher>(&self, state: &mut H) {
+    ///         self.id.hash(state);
+    ///     }
+    /// }
+    ///
+    /// let j_a = S { id: 1, name: "Jessica" };
+    /// let j_b = S { id: 1, name: "Jess" };
+    /// let p = S { id: 2, name: "Paul" };
+    /// assert_eq!(j_a, j_b);
     ///
     /// let mut map = HashMap::new();
-    /// map.insert(1, "a");
-    /// assert_eq!(map.get_key_value(&1), Some((&1, &"a")));
-    /// assert_eq!(map.get_key_value(&2), None);
+    /// map.insert(j_a, "Paris");
+    /// assert_eq!(map.get_key_value(&j_a), Some((&j_a, &"Paris")));
+    /// assert_eq!(map.get_key_value(&j_b), Some((&j_a, &"Paris"))); // the notable case
+    /// assert_eq!(map.get_key_value(&p), None);
     /// ```
     #[inline]
     #[stable(feature = "map_get_key_value", since = "1.40.0")]

src/doc/rustc/src/SUMMARY.md

@@ -72,6 +72,8 @@
     - [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md)
     - [riscv64gc-unknown-linux-gnu](platform-support/riscv64gc-unknown-linux-gnu.md)
     - [riscv64gc-unknown-linux-musl](platform-support/riscv64gc-unknown-linux-musl.md)
+    - [s390x-unknown-linux-gnu](platform-support/s390x-unknown-linux-gnu.md)
+    - [s390x-unknown-linux-musl](platform-support/s390x-unknown-linux-musl.md)
     - [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md)
     - [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md)
     - [\*-nto-qnx-\*](platform-support/nto-qnx.md)

src/doc/rustc/src/platform-support.md

@@ -99,7 +99,7 @@ target | notes
 `powerpc64le-unknown-linux-gnu` | PPC64LE Linux (kernel 3.10, glibc 2.17)
 [`riscv64gc-unknown-linux-gnu`](platform-support/riscv64gc-unknown-linux-gnu.md) | RISC-V Linux (kernel 4.20, glibc 2.29)
 [`riscv64gc-unknown-linux-musl`](platform-support/riscv64gc-unknown-linux-musl.md) | RISC-V Linux (kernel 4.20, musl 1.2.3)
-`s390x-unknown-linux-gnu` | S390x Linux (kernel 3.2, glibc 2.17)
+[`s390x-unknown-linux-gnu`](platform-support/s390x-unknown-linux-gnu.md) | S390x Linux (kernel 3.2, glibc 2.17)
 `x86_64-unknown-freebsd` | 64-bit FreeBSD
 `x86_64-unknown-illumos` | illumos
 `x86_64-unknown-linux-musl` | 64-bit Linux with musl 1.2.3
@@ -367,7 +367,7 @@ target | std | host | notes
 [`riscv64gc-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | OpenBSD/riscv64
 [`riscv64-linux-android`](platform-support/android.md) |   |   | RISC-V 64-bit Android
 [`riscv64-wrs-vxworks`](platform-support/vxworks.md) | ✓ |  |
-`s390x-unknown-linux-musl` |  |  | S390x Linux (kernel 3.2, musl 1.2.3)
+[`s390x-unknown-linux-musl`](platform-support/s390x-unknown-linux-musl.md) |  |  | S390x Linux (kernel 3.2, musl 1.2.3)
 `sparc-unknown-linux-gnu` | ✓ |  | 32-bit SPARC Linux
 [`sparc-unknown-none-elf`](./platform-support/sparc-unknown-none-elf.md) | * |  | Bare 32-bit SPARC V7+
 [`sparc64-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | NetBSD/sparc64

src/doc/rustc/src/platform-support/s390x-unknown-linux-gnu.md

@@ -0,0 +1,113 @@
+# `s390x-unknown-linux-gnu`
+
+**Tier: 2 (with Host Tools)**
+
+IBM z/Architecture (s390x) targets (including IBM Z and LinuxONE) running Linux.
+
+## Target maintainers
+
+- Ulrich Weigand, <ulrich.weigand@de.ibm.com>, [@uweigand](https://github.com/uweigand)
+- Josh Stone, <jistone@redhat.com>, [@cuviper](https://github.com/cuviper)
+
+## Requirements
+
+This target requires:
+
+* Linux Kernel version 3.2 or later
+* glibc 2.17 or later
+
+Code generated by the target uses the z/Architecture ISA assuming a minimum
+architecture level of z10 (Eighth Edition of the z/Architecture Principles
+of Operation), and is compliant with the s390x ELF ABI.
+
+Reference material:
+
+* [z/Architecture Principles of Operation][s390x-isa]
+* [z/Architecture ELF Application Binary Interface][s390x-abi]
+
+[s390x-isa]: https://publibfp.dhe.ibm.com/epubs/pdf/a227832d.pdf
+[s390x-abi]: https://github.com/IBM/s390x-abi
+
+## Building the target
+
+This target is distributed through `rustup`, and otherwise requires no
+special configuration.
+
+If you need to build your own Rust for some reason though, the target can be
+enabled in `config.toml`. For example:
+
+```toml
+[build]
+target = ["s390x-unknown-linux-gnu"]
+```
+
+## Building Rust programs
+
+On a s390x Linux host, the `s390x-unknown-linux-gnu` target should be
+automatically installed and used by default.
+
+On a non-s390x host, add the target:
+
+```bash
+rustup target add s390x-unknown-linux-gnu
+```
+
+Then cross compile crates with:
+
+```bash
+cargo build --target s390x-unknown-linux-gnu
+```
+
+## Testing
+
+There are no special requirements for testing and running the target.
+For testing cross builds on the host, please refer to the "Cross-compilation
+toolchains and C code" section below.
+
+## Cross-compilation toolchains and C code
+
+Rust code built using the target is compatible with C code compiled with
+GCC or Clang using the `s390x-unknown-linux-gnu` target triple (via either
+native or cross-compilation).
+
+On Ubuntu, a s390x cross-toolchain can be installed with:
+
+```bash
+apt install gcc-s390x-linux-gnu g++-s390x-linux-gnu libc6-dev-s390x-cross
+```
+
+Depending on your system, you may need to configure the target to use the GNU
+GCC linker. To use it, add the following to your `.cargo/config.toml`:
+
+```toml
+[target.s390x-unknown-linux-gnu]
+linker = "s390x-linux-gnu-gcc"
+```
+
+If your `s390x-linux-gnu-*` toolchain is not in your `PATH` you may need to
+configure additional settings:
+
+```toml
+[target.s390x-unknown-linux-gnu]
+# Adjust the paths to point at your toolchain
+cc = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-gcc"
+cxx = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-g++"
+ar = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-ar"
+ranlib = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-ranlib"
+linker = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-gcc"
+```
+
+To test cross compiled binaries on a non-s390x host, you can use
+[`qemu`](https://www.qemu.org/docs/master/system/target-s390x.html).
+On Ubuntu, a s390x emulator can be obtained with:
+
+```bash
+apt install qemu-system-s390x
+```
+
+Then, in `.cargo/config.toml` set the `runner`:
+
+```toml
+[target.s390x-unknown-linux-gnu]
+runner = "qemu-s390x-static -L /usr/s390x-linux-gnu"
+```

src/doc/rustc/src/platform-support/s390x-unknown-linux-musl.md

@@ -0,0 +1,83 @@
+# `s390x-unknown-linux-musl`
+
+**Tier: 3**
+
+IBM z/Architecture (s390x) targets (including IBM Z and LinuxONE) running Linux.
+
+## Target maintainers
+
+- Ulrich Weigand, <ulrich.weigand@de.ibm.com>, [@uweigand](https://github.com/uweigand)
+
+## Requirements
+
+This target requires:
+
+* Linux Kernel version 3.2 or later
+* musl 1.2.3 or later
+
+Code generated by the target uses the z/Architecture ISA assuming a minimum
+architecture level of z10 (Eighth Edition of the z/Architecture Principles
+of Operation), and is compliant with the s390x ELF ABI.
+
+Reference material:
+
+* [z/Architecture Principles of Operation][s390x-isa]
+* [z/Architecture ELF Application Binary Interface][s390x-abi]
+
+[s390x-isa]: https://publibfp.dhe.ibm.com/epubs/pdf/a227832d.pdf
+[s390x-abi]: https://github.com/IBM/s390x-abi
+
+## Building the target
+
+Because it is Tier 3, Rust does not yet ship pre-compiled artifacts for this
+target.
+
+Therefore, you can build Rust with support for the target by adding it to the
+target list in `config.toml`, a sample configuration is shown below.
+
+```toml
+[build]
+target = ["s390x-unknown-linux-musl"]
+```
+
+## 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).
+
+## Testing
+
+There are no special requirements for testing and running the target.
+For testing cross builds on the host, please refer to the "Cross-compilation
+toolchains and C code" section below.
+
+## Cross-compilation toolchains and C code
+
+Rust code built using the target is compatible with C code compiled with
+GCC or Clang using the `s390x-unknown-linux-musl` target triple (via either
+native or cross-compilation).
+
+Depending on your system, you may need to configure the target to use the GNU
+GCC linker. To use it, add the following to your `.cargo/config.toml`:
+
+```toml
+[target.s390x-unknown-linux-musl]
+linker = "s390x-linux-musl-gcc"
+```
+
+If your `s390x-linux-musl-*` toolchain is not in your `PATH` you may need to
+configure additional settings:
+
+```toml
+[target.s390x-unknown-linux-musl]
+# Adjust the paths to point at your toolchain
+cc = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-gcc"
+cxx = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-g++"
+ar = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-ar"
+ranlib = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-ranlib"
+linker = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-gcc"
+```
+
+To test cross compiled binaries on a non-s390x host, you can use
+[`qemu`](https://www.qemu.org/docs/master/system/target-s390x.html).