Document how to test with iOS/tvOS/watchOS/visionOS simulator

Author: madsmtm

src/doc/rustc-dev-guide/src/tests/running.md

@@ -339,9 +339,34 @@ results.  The Docker image is set up to launch `remote-test-server` and the
 build tools use `remote-test-client` to communicate with the server to
 coordinate running tests (see [src/bootstrap/src/core/build_steps/test.rs]).
 
-> **TODO**
->
-> - Is there any support for using an iOS emulator?
+To run on the iOS/tvOS/watchOS/visionOS simulator, we can similarly treat it as
+a "remote" machine. A curious detail here is that the network is shared between
+the simulator instance and the host macOS, so we can use the local loopback
+address `127.0.0.1`. Something like the following should work:
+
+```sh
+# Build the test server for the iOS simulator:
+./x build src/tools/remote-test-server --target aarch64-apple-ios-sim
+
+# If you already have a simulator instance open, copy the device UUID from:
+xcrun simctl list devices booted
+UDID=01234567-89AB-CDEF-0123-456789ABCDEF
+
+# Alternatively, create and boot a new simulator instance:
+xcrun simctl list runtimes
+xcrun simctl list devicetypes
+UDID=$(xcrun simctl create $CHOSEN_DEVICE_TYPE $CHOSEN_RUNTIME)
+xcrun simctl boot $UDID
+# See https://nshipster.com/simctl/ for details.
+
+# Spawn the runner on port 12345:
+xcrun simctl spawn $UDID ./build/host/stage2-tools/aarch64-apple-ios-sim/release/remote-test-server -v --bind 127.0.0.1:12345
+
+# In a new terminal, run tests via the runner:
+export TEST_DEVICE_ADDR="127.0.0.1:12345"
+./x test --host='' --target aarch64-apple-ios-sim --skip tests/debuginfo
+# FIXME(madsmtm): Allow debuginfo tests to work (maybe needs `.dSYM` folder to be copied to the target?).
+```
 
 [armhf-gnu]: https://github.com/rust-lang/rust/tree/master/src/ci/docker/host-x86_64/armhf-gnu/Dockerfile
 [QEMU]: https://www.qemu.org/

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

@@ -66,14 +66,19 @@ Rust programs can be built for these targets by specifying `--target`, if
 $ rustc --target aarch64-apple-ios your-code.rs
 ```
 
+Or if using Cargo and `-Zbuild-std`:
+```console
+$ cargo +nightly build -Zbuild-std --target armv7s-apple-ios
+```
+
 The simulator variants can be differentiated from the variants running
 on-device with the `target_env = "sim"` cfg (or `target_abi = "sim"` before
 Rust CURRENT_RUSTC_VERSION).
 
 ```rust
 if cfg!(all(target_vendor = "apple", target_env = "sim")) {
     // Do something on the iOS/tvOS/visionOS/watchOS Simulator.
-} {
+} else {
     // Everything else, like Windows and non-Simulator iOS.
 }
 ```
@@ -82,8 +87,15 @@ This is similar to the `TARGET_OS_SIMULATOR` define in C code.
 
 ## 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.
+Running and testing your code naturally requires either an actual device
+running iOS, or the equivalent Xcode simulator environment. There exists
+several tools in the ecosystem for running a Cargo project on one of these.
+One of these tools is [`cargo-dinghy`]. [madsmtm/objc2#459] contains a more
+exhaustive list.
+
+See also [testing on emulators in the `rustc-dev-guide`][test-sim] for
+instructions on running the standard library's test suite.
 
-It hopefully will be possible to improve this in the future.
+[`cargo-dinghy`]: https://github.com/sonos/dinghy
+[madsmtm/objc2#459]: https://github.com/madsmtm/objc2/issues/459
+[test-sim]: https://rustc-dev-guide.rust-lang.org/tests/running.html#testing-on-emulators

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

@@ -65,17 +65,8 @@ 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-tvos your-code.rs
-```
+See [the instructions for iOS](./apple-ios.md#building-rust-programs).
 
 ## 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.
+See [the instructions for iOS](./apple-ios.md#testing).

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

@@ -46,20 +46,11 @@ be fixed in [#124560](https://github.com/rust-lang/rust/pull/124560).
 
 ## 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-visionos-sim your-code.rs
-```
+See [the instructions for iOS](./apple-ios.md#building-rust-programs).
 
 ## 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.
+See [the instructions for iOS](./apple-ios.md#testing).
 
 ## Cross-compilation toolchains and C code
 

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

@@ -50,17 +50,8 @@ 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-watchos-sim your-code.rs
-```
+See [the instructions for iOS](./apple-ios.md#building-rust-programs).
 
 ## 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.
+See [the instructions for iOS](./apple-ios.md#testing).