Add documentation for aarch64-apple-ios-sim target

3 files changed, 58 insertions, 1 deletions

diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index b269aab9814..bc1873b6836 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/src/doc/rustc/src/SUMMARY.md
@@ -13,6 +13,7 @@
 - [JSON Output](json.md)
 - [Tests](tests/index.md)
 - [Platform Support](platform-support.md)
+    - [aarch64-apple-ios-sim](platform-support/aarch64-apple-ios-sim.md)
 - [Target Tier Policy](target-tier-policy.md)
 - [Targets](targets/index.md)
     - [Built-in Targets](targets/built-in.md)
diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md
index b3c67b84da6..53c82b73a17 100644
--- a/src/doc/rustc/src/platform-support.md
+++ b/src/doc/rustc/src/platform-support.md
@@ -196,7 +196,7 @@ host tools.
 target | std | host | notes
 -------|-----|------|-------
 `aarch64-apple-ios-macabi` | ? |  | Apple Catalyst on ARM64
-`aarch64-apple-ios-sim` | ? |  | Apple iOS Simulator on ARM64
+[`aarch64-apple-ios-sim`](platform-support/aarch64-apple-ios-sim.md) | ✓ |  | Apple iOS Simulator on ARM64
 `aarch64-apple-tvos` | * |  | ARM64 tvOS
 `aarch64-unknown-freebsd` | ✓ | ✓ | ARM64 FreeBSD
 `aarch64-unknown-hermit` | ? |  |
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
new file mode 100644
index 00000000000..9aa5db26f91
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/aarch64-apple-ios-sim.md
@@ -0,0 +1,56 @@
+# aarch64-apple-ios-sim
+
+**Tier: 3**
+
+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+.*
+
+If `rustc` has support for that target and the library artifacts are available,
+then Rust programs can be built for that target:
+
+```text
+rustc --target aarch64-apple-ios-sim your-code.rs
+```
+
+On Rust Nightly it is possible to build without the target artifacts available:
+
+```text
+cargo build -Z build-std --target aarch64-apple-ios-sim
+```
+
+There is no easy way to run simple programs in the iOS simulator.
+Static library builds can be embedded into iOS applications.