Rollup merge of #124772 - madsmtm:apple-platform-support-docs, r=oli-obk

Refactor documentation for Apple targets

Refactor the documentation for Apple targets in `rustc`'s platform support page to make it clear what the supported OS version is and which environment variables are being read (`*_DEPLOYMENT_TARGET` and `SDKROOT`). This fixes #124215.

Note that I've expanded the `aarch64-apple-ios-sim` maintainers `@badboy` and `@deg4uss3r` to include being maintainer of all `*-apple-ios-*` targets. If you do not wish to be so, please state that, then I'll explicitly note that in the docs.

Additionally, I've added myself as co-maintainer of most of these targets.

r? `@thomcc`

I think the documentation you've previously written on tvOS is great, have mostly modified it to have a more consistent formatting with the rest of the Apple target.

I recognize that there's quite a few changes here, feel free to ask about any of them!

---

CC `@simlay` `@Nilstrieb`

`@rustbot` label O-apple

Author: matthiaskrgr

compiler/rustc_target/src/spec/base/apple/mod.rs

@@ -272,6 +272,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))
 }
@@ -320,6 +321,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.
@@ -352,6 +354,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))
 }
 
@@ -367,6 +370,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))
 }
 
@@ -382,6 +386,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))
 }
 

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)
@@ -76,7 +80,6 @@
     - [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md)
     - [x86_64-unknown-linux-none.md](platform-support/x86_64-unknown-linux-none.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)

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

src/doc/rustc/src/platform-support/aarch64-apple-ios-sim.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.

src/doc/rustc/src/platform-support/apple-darwin.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.