Document all Apple targets in rustc's platform support

- Fixed std support in top-level docs.
- Added `*-apple-darwin` docs.
- Added `i686-apple-darwin` docs.
- Moved `aarch64-apple-ios-sim` to `*-apple-ios` and document all the
  iOS targets there.
- Added `*-apple-ios-macabi` docs.
- Add myself (madsmtm) as co-maintainer of most of these targets.

14 files changed, 376 insertions, 177 deletions

diff --git a/compiler/rustc_target/src/spec/base/apple/mod.rs b/compiler/rustc_target/src/spec/base/apple/mod.rs
index d667bad44e3..b12d3f22d8d 100644
--- a/compiler/rustc_target/src/spec/base/apple/mod.rs
+++ b/compiler/rustc_target/src/spec/base/apple/mod.rs
@@ -271,6 +271,7 @@ fn macos_default_deployment_target(arch: Arch) -> (u32, u32) {
 
 fn macos_deployment_target(arch: Arch) -> (u32, u32) {
     // If you are looking for the default deployment target, prefer `rustc --print deployment-target`.
+    // Note: If bumping this version, remember to update it in the rustc/platform-support docs.
     from_set_deployment_target("MACOSX_DEPLOYMENT_TARGET")
         .unwrap_or_else(|| macos_default_deployment_target(arch))
 }
@@ -319,6 +320,7 @@ fn link_env_remove(os: &'static str) -> StaticCow<[StaticCow<str>]> {
 
 fn ios_deployment_target(arch: Arch, abi: &str) -> (u32, u32) {
     // If you are looking for the default deployment target, prefer `rustc --print deployment-target`.
+    // Note: If bumping this version, remember to update it in the rustc/platform-support docs.
     let (major, minor) = match (arch, abi) {
         (Arm64e, _) => (14, 0),
         // Mac Catalyst defaults to 13.1 in Clang.
@@ -351,6 +353,7 @@ pub fn ios_sim_llvm_target(arch: Arch) -> String {
 
 fn tvos_deployment_target() -> (u32, u32) {
     // If you are looking for the default deployment target, prefer `rustc --print deployment-target`.
+    // Note: If bumping this version, remember to update it in the rustc platform-support docs.
     from_set_deployment_target("TVOS_DEPLOYMENT_TARGET").unwrap_or((10, 0))
 }
 
@@ -366,6 +369,7 @@ pub fn tvos_sim_llvm_target(arch: Arch) -> String {
 
 fn watchos_deployment_target() -> (u32, u32) {
     // If you are looking for the default deployment target, prefer `rustc --print deployment-target`.
+    // Note: If bumping this version, remember to update it in the rustc platform-support docs.
     from_set_deployment_target("WATCHOS_DEPLOYMENT_TARGET").unwrap_or((5, 0))
 }
 
@@ -381,6 +385,7 @@ pub fn watchos_sim_llvm_target(arch: Arch) -> String {
 
 fn visionos_deployment_target() -> (u32, u32) {
     // If you are looking for the default deployment target, prefer `rustc --print deployment-target`.
+    // Note: If bumping this version, remember to update it in the rustc platform-support docs.
     from_set_deployment_target("XROS_DEPLOYMENT_TARGET").unwrap_or((1, 0))
 }
 
diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index c9c0ee4067f..a309110e875 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/src/doc/rustc/src/SUMMARY.md
@@ -16,13 +16,17 @@
 - [Platform Support](platform-support.md)
     - [Target Tier Policy](target-tier-policy.md)
     - [Template for Target-specific Documentation](platform-support/TEMPLATE.md)
-    - [arm64e-apple-ios.md](platform-support/arm64e-apple-ios.md)
-    - [arm64e-apple-darwin.md](platform-support/arm64e-apple-darwin.md)
-    - [aarch64-apple-ios-sim](platform-support/aarch64-apple-ios-sim.md)
     - [arm64ec-pc-windows-msvc](platform-support/arm64ec-pc-windows-msvc.md)
+    - [\*-apple-darwin](platform-support/apple-darwin.md)
+        - [i686-apple-darwin](platform-support/i686-apple-darwin.md)
+        - [x86_64h-apple-darwin](platform-support/x86_64h-apple-darwin.md)
+        - [arm64e-apple-darwin.md](platform-support/arm64e-apple-darwin.md)
+    - [\*-apple-ios](platform-support/apple-ios.md)
+        - [\*-apple-ios-macabi](platform-support/apple-ios-macabi.md)
+        - [arm64e-apple-ios.md](platform-support/arm64e-apple-ios.md)
     - [\*-apple-tvos](platform-support/apple-tvos.md)
-    - [\*-apple-watchos\*](platform-support/apple-watchos.md)
-    - [aarch64-apple-visionos\*](platform-support/apple-visionos.md)
+    - [\*-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)
     - [armeb-unknown-linux-gnueabi](platform-support/armeb-unknown-linux-gnueabi.md)
     - [arm-none-eabi](platform-support/arm-none-eabi.md)
@@ -75,7 +79,6 @@
     - [\*-win7-windows-msvc](platform-support/win7-windows-msvc.md)
     - [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md)
     - [x86_64-unknown-none](platform-support/x86_64-unknown-none.md)
-    - [x86_64h-apple-darwin](platform-support/x86_64h-apple-darwin.md)
 - [Targets](targets/index.md)
     - [Built-in Targets](targets/built-in.md)
     - [Custom Targets](targets/custom.md)
diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md
index 764798a80e6..5c8789d03df 100644
--- a/src/doc/rustc/src/platform-support.md
+++ b/src/doc/rustc/src/platform-support.md
@@ -36,7 +36,7 @@ target | notes
 `i686-pc-windows-gnu` | 32-bit MinGW (Windows 10+) [^x86_32-floats-return-ABI]
 `i686-pc-windows-msvc` | 32-bit MSVC (Windows 10+) [^x86_32-floats-return-ABI]
 `i686-unknown-linux-gnu` | 32-bit Linux (kernel 3.2+, glibc 2.17+) [^x86_32-floats-return-ABI]
-`x86_64-apple-darwin` | 64-bit macOS (10.12+, Sierra+)
+[`x86_64-apple-darwin`](platform-support/apple-darwin.md) | 64-bit macOS (10.12+, Sierra+)
 `x86_64-pc-windows-gnu` | 64-bit MinGW (Windows 10+)
 `x86_64-pc-windows-msvc` | 64-bit MSVC (Windows 10+)
 `x86_64-unknown-linux-gnu` | 64-bit Linux (kernel 3.2+, glibc 2.17+)
@@ -86,7 +86,7 @@ so Rustup may install the documentation for a similar tier 1 target instead.
 
 target | notes
 -------|-------
-`aarch64-apple-darwin` | ARM64 macOS (11.0+, Big Sur+)
+[`aarch64-apple-darwin`](platform-support/apple-darwin.md) | ARM64 macOS (11.0+, Big Sur+)
 `aarch64-pc-windows-msvc` | ARM64 Windows MSVC
 `aarch64-unknown-linux-musl` | ARM64 Linux with musl 1.2.3
 `arm-unknown-linux-gnueabi` | Armv6 Linux (kernel 3.2, glibc 2.17)
@@ -133,8 +133,8 @@ so Rustup may install the documentation for a similar tier 1 target instead.
 
 target | std | notes
 -------|:---:|-------
-`aarch64-apple-ios` | ✓ | ARM64 iOS
-[`aarch64-apple-ios-sim`](platform-support/aarch64-apple-ios-sim.md) | ✓ | Apple iOS Simulator on ARM64
+[`aarch64-apple-ios`](platform-support/apple-ios.md) | ✓ | ARM64 iOS
+[`aarch64-apple-ios-sim`](platform-support/apple-ios.md) | ✓ | Apple iOS Simulator on ARM64
 `aarch64-fuchsia` | ✓ | Alias for `aarch64-unknown-fuchsia`
 [`aarch64-unknown-fuchsia`](platform-support/fuchsia.md) | ✓ | ARM64 Fuchsia
 [`aarch64-linux-android`](platform-support/android.md) | ✓ | ARM64 Android
@@ -192,7 +192,7 @@ target | std | notes
 `wasm32-wasi` | ✓ | WebAssembly with WASI (undergoing a [rename to `wasm32-wasip1`][wasi-rename])
 [`wasm32-wasip1`](platform-support/wasm32-wasip1.md) | ✓ | WebAssembly with WASI
 [`wasm32-wasip1-threads`](platform-support/wasm32-wasip1-threads.md) | ✓ |  | WebAssembly with WASI Preview 1 and threads
-`x86_64-apple-ios` | ✓ | 64-bit x86 iOS
+[`x86_64-apple-ios`](platform-support/apple-ios.md) | ✓ | 64-bit x86 iOS
 [`x86_64-fortanix-unknown-sgx`](platform-support/x86_64-fortanix-unknown-sgx.md) | ✓ | [Fortanix ABI] for 64-bit Intel SGX
 `x86_64-fuchsia` | ✓ | Alias for `x86_64-unknown-fuchsia`
 [`x86_64-unknown-fuchsia`](platform-support/fuchsia.md) | ✓ | 64-bit x86 Fuchsia
@@ -241,9 +241,9 @@ target | std | host | notes
 [`arm64e-apple-ios`](platform-support/arm64e-apple-ios.md) | ✓ | | ARM64e Apple iOS
 [`arm64e-apple-darwin`](platform-support/arm64e-apple-darwin.md)  | ✓ | ✓ | ARM64e Apple Darwin
 [`arm64ec-pc-windows-msvc`](platform-support/arm64ec-pc-windows-msvc.md) | ? | | Arm64EC Windows MSVC
-`aarch64-apple-ios-macabi` | ? |  | Apple Catalyst on ARM64
-[`aarch64-apple-tvos`](platform-support/apple-tvos.md) | ? |  | ARM64 tvOS
-[`aarch64-apple-tvos-sim`](platform-support/apple-tvos.md) | ? |  | ARM64 tvOS Simulator
+[`aarch64-apple-ios-macabi`](platform-support/apple-ios-macabi.md) | ✓ |  | Apple Catalyst on ARM64
+[`aarch64-apple-tvos`](platform-support/apple-tvos.md) | ✓ |  | ARM64 tvOS
+[`aarch64-apple-tvos-sim`](platform-support/apple-tvos.md) | ✓ |  | ARM64 tvOS Simulator
 [`aarch64-apple-watchos`](platform-support/apple-watchos.md) | ✓ |  | ARM64 Apple WatchOS
 [`aarch64-apple-watchos-sim`](platform-support/apple-watchos.md) | ✓ |  | ARM64 Apple WatchOS Simulator
 [`aarch64-apple-visionos`](platform-support/apple-visionos.md) | ✓ |  | ARM64 Apple visionOS
@@ -283,7 +283,7 @@ target | std | host | notes
 [`armv7a-kmc-solid_asp3-eabihf`](platform-support/kmc-solid.md) | ✓ |  | ARM SOLID with TOPPERS/ASP3, hardfloat
 [`armv7a-none-eabihf`](platform-support/arm-none-eabi.md) | * |  | Bare Armv7-A, hardfloat
 [`armv7k-apple-watchos`](platform-support/apple-watchos.md) | ✓ |  | Armv7-A Apple WatchOS
-`armv7s-apple-ios` | ✓ |  | Armv7-A Apple-A6 Apple iOS
+[`armv7s-apple-ios`](platform-support/apple-ios.md) | ✓ |  | Armv7-A Apple-A6 Apple iOS
 [`armv8r-none-eabihf`](platform-support/armv8r-none-eabihf.md) | * |  | Bare Armv8-R, hardfloat
 `avr-unknown-gnu-atmega328` | * |  | AVR. Requires `-Z build-std=core`
 `bpfeb-unknown-none` | * |  | BPF (big endian)
@@ -292,10 +292,10 @@ target | std | host | notes
 `csky-unknown-linux-gnuabiv2hf` | ✓ |  | C-SKY abiv2 Linux, hardfloat (little endian)
 [`hexagon-unknown-none-elf`](platform-support/hexagon-unknown-none-elf.md)| * | | Bare Hexagon (v60+, HVX)
 [`hexagon-unknown-linux-musl`](platform-support/hexagon-unknown-linux-musl.md) | ✓ | | Hexagon Linux with musl 1.2.3
-`i386-apple-ios` | ✓ |  | 32-bit x86 iOS [^x86_32-floats-return-ABI]
+[`i386-apple-ios`](platform-support/apple-ios.md) | ✓ |  | 32-bit x86 iOS [^x86_32-floats-return-ABI]
 [`i586-pc-nto-qnx700`](platform-support/nto-qnx.md) | * |  | 32-bit x86 QNX Neutrino 7.0 RTOS  [^x86_32-floats-return-ABI]
 [`i586-unknown-netbsd`](platform-support/netbsd.md) | ✓ |  | 32-bit x86, restricted to Pentium
-`i686-apple-darwin` | ✓ | ✓ | 32-bit macOS (10.12+, Sierra+) [^x86_32-floats-return-ABI]
+[`i686-apple-darwin`](platform-support/apple-darwin.md) | ✓ | ✓ | 32-bit macOS (10.12+, Sierra+) [^x86_32-floats-return-ABI]
 `i686-unknown-haiku` | ✓ | ✓ | 32-bit Haiku [^x86_32-floats-return-ABI]
 [`i686-unknown-hurd-gnu`](platform-support/hurd.md) | ✓ | ✓ | 32-bit GNU/Hurd [^x86_32-floats-return-ABI]
 [`i686-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | NetBSD/i386 with SSE2 [^x86_32-floats-return-ABI]
@@ -367,8 +367,8 @@ target | std | host | notes
 `thumbv7neon-unknown-linux-musleabihf` | ? |  | Thumb2-mode Armv7-A Linux with NEON, musl 1.2.3
 [`wasm32-wasip2`](platform-support/wasm32-wasip2.md) | ✓ |  | WebAssembly
 [`wasm64-unknown-unknown`](platform-support/wasm64-unknown-unknown.md) | ? |  | WebAssembly
-`x86_64-apple-ios-macabi` | ✓ |  | Apple Catalyst on x86_64
-[`x86_64-apple-tvos`](platform-support/apple-tvos.md) | ? |  | x86 64-bit tvOS
+[`x86_64-apple-ios-macabi`](platform-support/apple-ios-macabi.md) | ✓ |  | Apple Catalyst on x86_64
+[`x86_64-apple-tvos`](platform-support/apple-tvos.md) | ✓ |  | x86 64-bit tvOS
 [`x86_64-apple-watchos-sim`](platform-support/apple-watchos.md) | ✓ |  | x86 64-bit Apple WatchOS simulator
 [`x86_64-pc-nto-qnx710`](platform-support/nto-qnx.md) | ✓ |  | x86 64-bit QNX Neutrino 7.1 RTOS |
 [`x86_64-unikraft-linux-musl`](platform-support/unikraft-linux-musl.md) | ✓ |   | 64-bit Unikraft with musl 1.2.3
diff --git a/src/doc/rustc/src/platform-support/aarch64-apple-ios-sim.md b/src/doc/rustc/src/platform-support/aarch64-apple-ios-sim.md
deleted file mode 100644
index 3f29e2c5e1f..00000000000
--- a/src/doc/rustc/src/platform-support/aarch64-apple-ios-sim.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# aarch64-apple-ios-sim
-
-**Tier: 2**
-
-Apple iOS Simulator on ARM64.
-
-## Designated Developers
-
-* [@badboy](https://github.com/badboy)
-* [@deg4uss3r](https://github.com/deg4uss3r)
-
-## Requirements
-
-This target is cross-compiled.
-To build this target Xcode 12 or higher on macOS is required.
-
-## Building
-
-The target can be built by enabling it for a `rustc` build:
-
-```toml
-[build]
-build-stage = 1
-target = ["aarch64-apple-ios-sim"]
-```
-
-## Cross-compilation
-
-This target can be cross-compiled from `x86_64` or `aarch64` macOS hosts.
-
-Other hosts are not supported for cross-compilation, but might work when also providing the required Xcode SDK.
-
-## Testing
-
-Currently there is no support to run the rustc test suite for this target.
-
-
-## Building Rust programs
-
-*Note: Building for this target requires the corresponding iOS SDK, as provided by Xcode 12+.*
-
-From Rust Nightly 1.56.0 (2021-08-03) on the artifacts are shipped pre-compiled:
-
-```text
-rustup target add aarch64-apple-ios-sim --toolchain nightly
-```
-
-Rust programs can be built for that target:
-
-```text
-rustc --target aarch64-apple-ios-sim your-code.rs
-```
-
-There is no easy way to run simple programs in the iOS simulator.
-Static library builds can be embedded into iOS applications.
diff --git a/src/doc/rustc/src/platform-support/apple-darwin.md b/src/doc/rustc/src/platform-support/apple-darwin.md
new file mode 100644
index 00000000000..0fb86949a4b
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/apple-darwin.md
@@ -0,0 +1,59 @@
+# `*-apple-darwin`
+
+Apple macOS targets.
+
+**Tier: 1**
+
+- `x86_64-apple-darwin`: macOS on 64-bit x86.
+
+**Tier: 2 (with Host Tools)**
+
+- `aarch64-apple-darwin`: macOS on ARM64 (M1-family or later Apple Silicon CPUs).
+
+## Target maintainers
+
+- [@thomcc](https://github.com/thomcc)
+- [@madsmtm](https://github.com/madsmtm)
+
+## Requirements
+
+### OS version
+
+The minimum supported version is macOS 10.12 Sierra on x86, and macOS 11.0 Big
+Sur on ARM64.
+
+This version can be raised per-binary by changing the [deployment target],
+which might yield more performance optimizations. `rustc` respects the common
+environment variables used by Xcode to do so, in this case
+`MACOSX_DEPLOYMENT_TARGET`.
+
+The current default deployment target for `rustc` can be retrieved with
+[`rustc --print=deployment-target`][rustc-print].
+
+[deployment target]: https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/cross_development/Configuring/configuring.html
+[rustc-print]: ../command-line-arguments.md#option-print
+
+### Binary format
+
+The default binary format is Mach-O, the executable format used on Apple's
+platforms.
+
+## Building
+
+These targets are distributed through `rustup`, and otherwise require no
+special configuration.
+
+## Testing
+
+There are no special requirements for testing and running this target.
+
+x86 binaries can be run on Apple Silicon by using Rosetta.
+
+## Cross-compilation toolchains and C code
+
+Cross-compilation of these targets are supported using Clang, but may require
+Xcode or the macOS SDK (`MacOSX.sdk`) to be available to compile C code and
+to link.
+
+The path to the SDK can be passed to `rustc` using the common `SDKROOT`
+environment variable.
diff --git a/src/doc/rustc/src/platform-support/apple-ios-macabi.md b/src/doc/rustc/src/platform-support/apple-ios-macabi.md
new file mode 100644
index 00000000000..278ee94b6d4
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/apple-ios-macabi.md
@@ -0,0 +1,58 @@
+# `*-apple-ios-macabi`
+
+Apple Mac Catalyst targets.
+
+**Tier: 3**
+
+- `aarch64-apple-ios-macabi`: Mac Catalyst on ARM64.
+- `x86_64-apple-ios-macabi`: Mac Catalyst on 64-bit x86.
+
+## Target maintainers
+
+- [@madsmtm](https://github.com/madsmtm)
+
+## Requirements
+
+These targets are cross-compiled, and require the corresponding macOS SDK
+(`MacOSX.sdk`) which contain `./System/iOSSupport` headers to allow linking to
+iOS-specific headers, as provided by Xcode 11 or higher.
+
+The path to the SDK can be passed to `rustc` using the common `SDKROOT`
+environment variable.
+
+### OS version
+
+The minimum supported version is iOS 13.1.
+
+This can be raised per-binary by changing the deployment target. `rustc`
+respects the common environment variables used by Xcode to do so, in this
+case `IPHONEOS_DEPLOYMENT_TARGET`.
+
+## Building the target
+
+The targets can be built by enabling them for a `rustc` build in
+`config.toml`, by adding, for example:
+
+```toml
+[build]
+target = ["aarch64-apple-ios-macabi", "x86_64-apple-ios-macabi"]
+```
+
+Using the unstable `-Zbuild-std` with a nightly Cargo may also work.
+
+## Building Rust programs
+
+Rust programs can be built for these targets by specifying `--target`, if
+`rustc` has been built with support for them. For example:
+
+```console
+$ rustc --target aarch64-apple-ios-macabi your-code.rs
+```
+
+## Testing
+
+Mac Catalyst binaries can be run directly on macOS 10.15 Catalina or newer.
+
+x86 binaries can be run on Apple Silicon by using Rosetta.
+
+Note that using certain UIKit functionality requires the binary to be bundled.
diff --git a/src/doc/rustc/src/platform-support/apple-ios.md b/src/doc/rustc/src/platform-support/apple-ios.md
new file mode 100644
index 00000000000..5045f810400
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/apple-ios.md
@@ -0,0 +1,74 @@
+# `*-apple-ios`
+
+Apple iOS / iPadOS targets.
+
+**Tier: 2 (without Host Tools)**
+
+- `aarch64-apple-ios`: Apple iOS on ARM64.
+- `aarch64-apple-ios-sim`: Apple iOS Simulator on ARM64.
+- `x86_64-apple-ios`: Apple iOS Simulator on 64-bit x86.
+
+**Tier: 3**
+
+- `armv7s-apple-ios`: Apple iOS on Armv7-A.
+- `i386-apple-ios`: Apple iOS Simulator on 32-bit x86.
+
+## Target maintainers
+
+- [@badboy](https://github.com/badboy)
+- [@deg4uss3r](https://github.com/deg4uss3r)
+- [@madsmtm](https://github.com/madsmtm)
+
+## Requirements
+
+These targets are cross-compiled, and require the corresponding iOS SDK
+(`iPhoneOS.sdk` or `iPhoneSimulator.sdk`), as provided by Xcode. To build the
+ARM64 targets, Xcode 12 or higher is required.
+
+The path to the SDK can be passed to `rustc` using the common `SDKROOT`
+environment variable.
+
+### OS version
+
+The minimum supported version is iOS 10.0.
+
+This can be raised per-binary by changing the deployment target. `rustc`
+respects the common environment variables used by Xcode to do so, in this
+case `IPHONEOS_DEPLOYMENT_TARGET`.
+
+## Building the target
+
+The tier 2 targets are distributed through `rustup`, and can be installed
+using one of:
+```console
+$ rustup target add aarch64-apple-ios
+$ rustup target add aarch64-apple-ios-sim
+$ rustup target add x86_64-apple-ios
+```
+
+The tier 3 targets can be built by enabling them for a `rustc` build in
+`config.toml`, by adding, for example:
+
+```toml
+[build]
+target = ["armv7s-apple-ios", "i386-apple-ios"]
+```
+
+Using the unstable `-Zbuild-std` with a nightly Cargo may also work.
+
+## Building Rust programs
+
+Rust programs can be built for these targets by specifying `--target`, if
+`rustc` has been built with support for them. For example:
+
+```console
+$ rustc --target aarch64-apple-ios your-code.rs
+```
+
+## Testing
+
+There is no support for running the Rust or standard library testsuite at the
+moment. Testing has mostly been done manually with builds of static libraries
+embedded into applications called from Xcode or a simulator.
+
+It hopefully will be possible to improve this in the future.
diff --git a/src/doc/rustc/src/platform-support/apple-tvos.md b/src/doc/rustc/src/platform-support/apple-tvos.md
index e7ea109df1b..7a3b601579a 100644
--- a/src/doc/rustc/src/platform-support/apple-tvos.md
+++ b/src/doc/rustc/src/platform-support/apple-tvos.md
@@ -1,40 +1,44 @@
 # `*-apple-tvos`
-- aarch64-apple-tvos
-- x86_64-apple-tvos
+
+Apple tvOS targets.
 
 **Tier: 3**
 
-Apple tvOS targets:
-- Apple tvOS on aarch64
-- Apple tvOS Simulator on x86_64
+- `aarch64-apple-tvos`: Apple tvOS on ARM64.
+- `aarch64-apple-tvos-sim`: Apple tvOS Simulator on ARM64.
+- `x86_64-apple-tvos`: Apple tvOS Simulator on x86_64.
 
 ## Target maintainers
 
-* [@thomcc](https://github.com/thomcc)
+- [@thomcc](https://github.com/thomcc)
+- [@madsmtm](https://github.com/madsmtm)
 
 ## Requirements
 
-These targets are cross-compiled. You will need appropriate versions of Xcode
-and the SDKs for tvOS (`AppleTVOS.sdk`) and/or the tvOS Simulator
-(`AppleTVSimulator.sdk`) to build a toolchain and target these platforms.
+These targets are cross-compiled, and require the corresponding tvOS SDK
+(`AppleTVOS.sdk` or `AppleTVSimulator.sdk`), as provided by Xcode. To build the
+ARM64 targets, Xcode 12 or higher is required.
+
+The path to the SDK can be passed to `rustc` using the common `SDKROOT`
+environment variable.
 
-The targets support most (see below) of the standard library including the
-allocator to the best of my knowledge, however they are very new, not yet
-well-tested, and it is possible that there are various bugs.
+### OS version
 
-In theory we support back to tvOS version 7.0, although the actual minimum
-version you can target may be newer than this, for example due to the versions
-of Xcode and your SDKs.
+The minimum supported version is tvOS 10.0, although the actual minimum version
+you can target may be newer than this, for example due to the versions of Xcode
+and your SDKs.
 
-As with the other Apple targets, `rustc` respects the common environment
-variables used by Xcode to configure this, in this case
-`TVOS_DEPLOYMENT_TARGET`.
+The version can be raised per-binary by changing the deployment target. `rustc`
+respects the common environment variables used by Xcode to do so, in this
+case `TVOS_DEPLOYMENT_TARGET`.
 
-#### Incompletely supported library functionality
+### Incompletely supported library functionality
 
-As mentioned, "most" of the standard library is supported, which means that some portions
-are known to be unsupported. The following APIs are currently known to have
-missing or incomplete support:
+The targets support most of the standard library including the allocator to the
+best of my knowledge, however they are very new, not yet well-tested, and it is
+possible that there are various bugs.
+
+The following APIs are currently known to have missing or incomplete support:
 
 - `std::process::Command`'s API will return an error if it is configured in a
   manner which cannot be performed using `posix_spawn` -- this is because the
@@ -47,41 +51,30 @@ missing or incomplete support:
 
 ## Building the target
 
-The targets can be built by enabling them for a `rustc` build in `config.toml`, by adding, for example:
+The targets can be built by enabling them for a `rustc` build in
+`config.toml`, by adding, for example:
 
 ```toml
 [build]
 build-stage = 1
-target = ["aarch64-apple-tvos", "x86_64-apple-tvos", "aarch64-apple-tvos-sim"]
+target = ["aarch64-apple-tvos", "aarch64-apple-tvos-sim"]
 ```
 
-It's possible that cargo under `-Zbuild-std` may also be used to target them.
+Using the unstable `-Zbuild-std` with a nightly Cargo may also work.
 
 ## Building Rust programs
 
-*Note: Building for this target requires the corresponding TVOS SDK, as provided by Xcode.*
-
-Rust programs can be built for these targets
+Rust programs can be built for these targets by specifying `--target`, if
+`rustc` has been built with support for them. For example:
 
-```text
+```console
 $ rustc --target aarch64-apple-tvos your-code.rs
-...
-$ rustc --target x86_64-apple-tvos your-code.rs
-...
-$ rustc --target aarch64-apple-tvos-sim your-code.rs
 ```
 
 ## Testing
 
-There is no support for running the Rust or standard library testsuite on tvOS
-or the simulators at the moment. Testing has mostly been done manually with
-builds of static libraries called from Xcode or a simulator.
+There is no support for running the Rust or standard library testsuite at the
+moment. Testing has mostly been done manually with builds of static libraries
+embedded into applications called from Xcode or a simulator.
 
 It hopefully will be possible to improve this in the future.
-
-## Cross-compilation toolchains and C code
-
-This target can be cross-compiled from x86_64 or aarch64 macOS hosts.
-
-Other hosts are not supported for cross-compilation, but might work when also
-providing the required Xcode SDK.
diff --git a/src/doc/rustc/src/platform-support/apple-visionos.md b/src/doc/rustc/src/platform-support/apple-visionos.md
index 9874126e42f..56224d7e20d 100644
--- a/src/doc/rustc/src/platform-support/apple-visionos.md
+++ b/src/doc/rustc/src/platform-support/apple-visionos.md
@@ -1,53 +1,67 @@
-# aarch64-apple-visionos\*
+# `*-apple-visionos`
 
--   aarch64-apple-visionos
--   aarch64-apple-visionos-sim
+Apple visionOS / xrOS targets.
 
 **Tier: 3**
 
-Apple visionOS targets:
-
--   Apple visionOS on arm64
--   Apple visionOS Simulator on arm64
+- `aarch64-apple-visionos`: Apple visionOS on arm64.
+- `aarch64-apple-visionos-sim`: Apple visionOS Simulator on arm64.
 
 ## Target maintainers
 
--   [@agg23](https://github.com/agg23)
--   [@madsmtm](https://github.com/madsmtm)
+- [@agg23](https://github.com/agg23)
+- [@madsmtm](https://github.com/madsmtm)
 
 ## Requirements
 
-These targets are cross-compiled.
-To build these targets Xcode 15 or higher on macOS is required, along with LLVM 18.
+These targets are cross-compiled, and require the corresponding visionOS SDK
+(`XROS.sdk` or `XRSimulator.sdk`), as provided by Xcode 15 or newer.
+
+The path to the SDK can be passed to `rustc` using the common `SDKROOT`
+environment variable.
+
+### OS version
+
+The minimum supported version is visionOS 1.0.
+
+This can be raised per-binary by changing the deployment target. `rustc`
+respects the common environment variables used by Xcode to do so, in this
+case `XROS_DEPLOYMENT_TARGET`.
 
 ## Building the target
 
-The targets can be built by enabling them for a `rustc` build, for example:
+The targets can be built by enabling them for a `rustc` build in
+`config.toml`, by adding, for example:
 
 ```toml
 [build]
-build-stage = 1
-target = ["aarch64-apple-visionos-sim"]
+target = ["aarch64-apple-visionos", "aarch64-apple-visionos-sim"]
 ```
 
-## Building Rust programs
+Using the unstable `-Zbuild-std` with a nightly Cargo may also work.
 
-_Note: Building for this target requires the corresponding visionOS SDK, as provided by Xcode 15+._
+Note: Currently, a newer version of `libc` and `cc` may be required, this will
+be fixed in [#124560](https://github.com/rust-lang/rust/pull/124560).
+
+## Building Rust programs
 
-Rust programs can be built for these targets, if `rustc` has been built with support for them, for example:
+Rust programs can be built for these targets by specifying `--target`, if
+`rustc` has been built with support for them. For example:
 
-```text
-rustc --target aarch64-apple-visionos-sim your-code.rs
+```console
+$ rustc --target aarch64-apple-visionos-sim your-code.rs
 ```
 
 ## Testing
 
-There is no support for running the Rust testsuite on visionOS or the simulators.
+There is no support for running the Rust or standard library testsuite at the
+moment. Testing has mostly been done manually with builds of static libraries
+embedded into applications called from Xcode or a simulator.
 
-There is no easy way to run simple programs on visionOS or the visionOS simulators. Static library builds can be embedded into visionOS applications.
+It hopefully will be possible to improve this in the future.
 
 ## Cross-compilation toolchains and C code
 
-This target can be cross-compiled from x86_64 or aarch64 macOS hosts.
+The Clang target is suffixed with `-xros` for historical reasons.
 
-Other hosts are not supported for cross-compilation, but might work when also providing the required Xcode SDK.
+LLVM 18 or newer is required to build this target.
diff --git a/src/doc/rustc/src/platform-support/apple-watchos.md b/src/doc/rustc/src/platform-support/apple-watchos.md
index 7be2467352c..8ba35f70b85 100644
--- a/src/doc/rustc/src/platform-support/apple-watchos.md
+++ b/src/doc/rustc/src/platform-support/apple-watchos.md
@@ -1,58 +1,65 @@
-# *-apple-watchos
-- arm64_32-apple-watchos
-- armv7k-apple-watchos
-- aarch64-apple-watchos
-- aarch64-apple-watchos-sim
-- x86_64-apple-watchos-sim
+# `*-apple-watchos`
+
+Apple watchOS targets.
 
 **Tier: 3**
 
-Apple WatchOS targets:
-- Apple WatchOS on Arm 64_32
-- Apple WatchOS on Arm v7k
-- Apple WatchOS on Arm 64
-- Apple WatchOS Simulator on arm64
-- Apple WatchOS Simulator on x86_64
+- `aarch64-apple-watchos`: Apple WatchOS on ARM64.
+- `aarch64-apple-watchos-sim`: Apple WatchOS Simulator on ARM64.
+- `x86_64-apple-watchos-sim`: Apple WatchOS Simulator on 64-bit x86.
+- `arm64_32-apple-watchos`: Apple WatchOS on Arm 64_32.
+- `armv7k-apple-watchos`: Apple WatchOS on Armv7k.
 
 ## Target maintainers
 
-* [@deg4uss3r](https://github.com/deg4uss3r)
-* [@vladimir-ea](https://github.com/vladimir-ea)
-* [@leohowell](https://github.com/leohowell)
+- [@deg4uss3r](https://github.com/deg4uss3r)
+- [@vladimir-ea](https://github.com/vladimir-ea)
+- [@leohowell](https://github.com/leohowell)
+- [@madsmtm](https://github.com/madsmtm)
 
 ## Requirements
 
-These targets are cross-compiled.
-To build these targets Xcode 12 or higher on macOS is required.
+These targets are cross-compiled, and require the corresponding watchOS SDK
+(`WatchOS.sdk` or `WatchSimulator.sdk`), as provided by Xcode. To build the
+ARM64 targets, Xcode 12 or higher is required.
+
+The path to the SDK can be passed to `rustc` using the common `SDKROOT`
+environment variable.
+
+### OS version
+
+The minimum supported version is watchOS 5.0.
+
+This can be raised per-binary by changing the deployment target. `rustc`
+respects the common environment variables used by Xcode to do so, in this
+case `WATCHOS_DEPLOYMENT_TARGET`.
 
 ## Building the target
 
-The targets can be built by enabling them for a `rustc` build, for example:
+The targets can be built by enabling them for a `rustc` build in
+`config.toml`, by adding, for example:
 
 ```toml
 [build]
 build-stage = 1
-target = ["aarch64-apple-watchos-sim"]
+target = ["aarch64-apple-watchos", "aarch64-apple-watchos-sim"]
 ```
 
-## Building Rust programs
+Using the unstable `-Zbuild-std` with a nightly Cargo may also work.
 
-*Note: Building for this target requires the corresponding WatchOS SDK, as provided by Xcode 12+.*
+## Building Rust programs
 
-Rust programs can be built for these targets, if `rustc` has been built with support for them, for example:
+Rust programs can be built for these targets by specifying `--target`, if
+`rustc` has been built with support for them. For example:
 
-```text
-rustc --target aarch64-apple-watchos-sim your-code.rs
+```console
+$ rustc --target aarch64-apple-watchos-sim your-code.rs
 ```
 
 ## Testing
 
-There is no support for running the Rust testsuite on WatchOS or the simulators.
-
-There is no easy way to run simple programs on WatchOS or the WatchOS simulators. Static library builds can be embedded into WatchOS applications.
-
-## Cross-compilation toolchains and C code
-
-This target can be cross-compiled from x86_64 or aarch64 macOS hosts.
+There is no support for running the Rust or standard library testsuite at the
+moment. Testing has mostly been done manually with builds of static libraries
+embedded into applications called from Xcode or a simulator.
 
-Other hosts are not supported for cross-compilation, but might work when also providing the required Xcode SDK.
+It hopefully will be possible to improve this in the future.
diff --git a/src/doc/rustc/src/platform-support/arm64e-apple-darwin.md b/src/doc/rustc/src/platform-support/arm64e-apple-darwin.md
index d9b9aeae1ae..4d98b3a6098 100644
--- a/src/doc/rustc/src/platform-support/arm64e-apple-darwin.md
+++ b/src/doc/rustc/src/platform-support/arm64e-apple-darwin.md
@@ -12,6 +12,8 @@ ARM64e macOS (11.0+, Big Sur+)
 
 Target for `macOS` on late-generation `M` series Apple chips.
 
+See the docs on [`*-apple-darwin`](apple-darwin.md) for general macOS requirements.
+
 ## Building the target
 
 You can build Rust with support for the targets by adding it to the `target` list in `config.toml`:
diff --git a/src/doc/rustc/src/platform-support/arm64e-apple-ios.md b/src/doc/rustc/src/platform-support/arm64e-apple-ios.md
index 0215621be3d..3c878f7250e 100644
--- a/src/doc/rustc/src/platform-support/arm64e-apple-ios.md
+++ b/src/doc/rustc/src/platform-support/arm64e-apple-ios.md
@@ -10,8 +10,7 @@ ARM64e iOS (12.0+)
 
 ## Requirements
 
-These targets only support cross-compilation.
-The targets do support `std`.
+See the docs on [`*-apple-ios`](apple-ios.md) for general iOS requirements.
 
 ## Building the target
 
diff --git a/src/doc/rustc/src/platform-support/i686-apple-darwin.md b/src/doc/rustc/src/platform-support/i686-apple-darwin.md
new file mode 100644
index 00000000000..d69fa97ce63
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/i686-apple-darwin.md
@@ -0,0 +1,41 @@
+# `i686-apple-darwin`
+
+Apple macOS on 32-bit x86.
+
+## Target maintainers
+
+- [@thomcc](https://github.com/thomcc)
+- [@madsmtm](https://github.com/madsmtm)
+
+## Requirements
+
+See the docs on [`*-apple-darwin`](apple-darwin.md) for general macOS requirements.
+
+## Building the target
+
+You'll need the macOS 10.13 SDK shipped with Xcode 9. The location of the SDK
+can be passed to `rustc` using the common `SDKROOT` environment variable.
+
+Once you have that, you can build Rust with support for the target by adding
+it to the `target` list in `config.toml`:
+
+```toml
+[build]
+target = ["i686-apple-darwin"]
+```
+
+Using the unstable `-Zbuild-std` with a nightly Cargo may also work.
+
+## Building Rust programs
+
+Rust [no longer] ships pre-compiled artifacts for this target. To compile for
+this target, you will either need to build Rust with the target enabled (see
+"Building the target" above), or build your own copy using `build-std` or
+similar.
+
+[no longer]: https://blog.rust-lang.org/2020/01/03/reducing-support-for-32-bit-apple-targets.html
+
+## Testing
+
+Running this target requires an Intel Macbook running macOS 10.14 or earlier,
+as later versions removed support for running 32-bit binaries.
diff --git a/src/doc/rustc/src/platform-support/x86_64h-apple-darwin.md b/src/doc/rustc/src/platform-support/x86_64h-apple-darwin.md
index 0fe9d4edaca..6c2a6a41101 100644
--- a/src/doc/rustc/src/platform-support/x86_64h-apple-darwin.md
+++ b/src/doc/rustc/src/platform-support/x86_64h-apple-darwin.md
@@ -23,9 +23,8 @@ default or user-defined allocators). This target is probably most useful when
 targeted via cross-compilation (including from `x86_64-apple-darwin`), but if
 built manually, the host tools work.
 
-It is similar to `x86_64-apple-darwin` in nearly all respects, although the
-minimum supported OS version is slightly higher (it requires 10.8 rather than
-`x86_64-apple-darwin`'s 10.7).
+It is similar to [`x86_64-apple-darwin`](apple-darwin.md) in nearly all
+respects.
 
 ## Building the target