gh-114099: Add documentation for iOS platform (GH-117057)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Jacob Coffee <jacob@z7x.org>
Co-authored-by: Malcolm Smith <smith@chaquo.com>
Co-authored-by: Ned Deily <nad@python.org>

1 files changed, 50 insertions, 9 deletions

diff --git a/iOS/README.rst b/iOS/README.rst
index b67199e..df429b6 100644
--- a/iOS/README.rst
+++ b/iOS/README.rst
@@ -182,7 +182,10 @@ This can be done by defining the ``LIBLZMA_CFLAGS``, ``LIBLZMA_LIBS``,
 ``BZIP2_CFLAGS``, ``BZIP2_LIBS``, ``LIBFFI_CFLAGS``, and ``LIBFFI_LIBS``
 environment variables, and the ``--with-openssl`` configure option. Versions of
 these libraries pre-compiled for iOS can be found in `this repository
-<https://github.com/beeware/cpython-apple-source-deps/releases>`__.
+<https://github.com/beeware/cpython-apple-source-deps/releases>`__. LibFFI is
+especially important, as many parts of the standard library (including the
+``platform``, ``sysconfig`` and ``webbrowser`` modules) require the use of the
+``ctypes`` module at runtime.
 
 By default, Python will be compiled with an iOS deployment target (i.e., the
 minimum supported iOS version) of 12.0. To specify a different deployment
@@ -248,16 +251,11 @@ the XCframework::
     cp path/to/iphoneos/bin Python.xcframework/ios-arm64
     cp path/to/iphoneos/lib Python.xcframework/ios-arm64
 
-    cp path/to/iphonesimulator/bin Python.xcframework/ios-arm64_x86-64-simulator
-    cp path/to/iphonesimulator/lib Python.xcframework/ios-arm64_x86-64-simulator
+    cp path/to/iphonesimulator/bin Python.xcframework/ios-arm64_x86_64-simulator
+    cp path/to/iphonesimulator/lib Python.xcframework/ios-arm64_x86_64-simulator
 
 Note that the name of the architecture-specific slice for the simulator will
-depend on the CPU architecture that you build.
-
-Then, add symbolic links to "common" platform names for each slice::
-
-    ln -si ios-arm64 Python.xcframework/iphoneos
-    ln -si ios-arm64_x86-64-simulator Python.xcframework/iphonesimulator
+depend on the CPU architecture(s) that you build.
 
 You now have a Python.xcframework that can be used in a project.
 
@@ -306,6 +304,49 @@ Debugging test failures
 The easiest way to diagnose a single test failure is to open the testbed project
 in Xcode and run the tests from there using the "Product > Test" menu item.
 
+To test in Xcode, you must ensure the testbed project has a copy of a compiled
+framework. If you've configured your build with the default install location of
+``iOS/Frameworks``, you can copy from that location into the test project. To
+test on an ARM64 simulator, run::
+
+    $ rm -rf iOS/testbed/Python.xcframework/ios-arm64_x86_64-simulator/*
+    $ cp -r iOS/Frameworks/arm64-iphonesimulator/* iOS/testbed/Python.xcframework/ios-arm64_x86_64-simulator
+
+To test on an x86-64 simulator, run::
+
+    $ rm -rf iOS/testbed/Python.xcframework/ios-arm64_x86_64-simulator/*
+    $ cp -r iOS/Frameworks/x86_64-iphonesimulator/* iOS/testbed/Python.xcframework/ios-arm64_x86_64-simulator
+
+To test on a physical device::
+
+    $ rm -rf iOS/testbed/Python.xcframework/ios-arm64/*
+    $ cp -r iOS/Frameworks/arm64-iphoneos/* iOS/testbed/Python.xcframework/ios-arm64
+
+Alternatively, you can configure your build to install directly into the
+testbed project. For a simulator, use::
+
+    --enable-framework=$(pwd)/iOS/testbed/Python.xcframework/ios-arm64_x86_64-simulator
+
+For a physical device, use::
+
+    --enable-framework=$(pwd)/iOS/testbed/Python.xcframework/ios-arm64
+
+
+Testing on an iOS device
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To test on an iOS device, the app needs to be signed with known developer
+credentials. To obtain these credentials, you must have an iOS Developer
+account, and your Xcode install will need to be logged into your account (see
+the Accounts tab of the Preferences dialog).
+
+Once the project is open, and you're signed into your Apple Developer account,
+select the root node of the project tree (labeled "iOSTestbed"), then the
+"Signing & Capabilities" tab in the details page. Select a development team
+(this will likely be your own name), and plug in a physical device to your
+macOS machine with a USB cable. You should then be able to select your physical
+device from the list of targets in the pulldown in the Xcode titlebar.
+
 Running specific tests
 ^^^^^^^^^^^^^^^^^^^^^^