Update docs describing the framework build and usage.

Author: freakboy3742

README.rst

@@ -19,24 +19,24 @@ pre-requisites, and packaging them as static libraries that can be incorporated
 XCode project. The binary modules in the Python standard library are statically
 compiled, but are distributed as objects that can be dynamically loaded at runtime.
 
-It exposes *almost* all the modules in the Python standard library except for:
+The macOS package is a re-bundling of the official macOS binary, modified so that
+it is relocatable.
 
-* ``dbm.gnu``
-* ``tkinter``
-* ``readline``
-* ``nis`` (Deprecated by PEP594)
-* ``ossaudiodev`` (Deprecated by PEP594)
-* ``spwd`` (Deprecated by PEP594)
-
-The following standard library modules are available on macOS, but not the other
-Apple platforms:
+The iOS, tvOS and watchOS packages are compiled by this project. They expose
+*almost* all the modules in the Python standard library except for:
 
 * ``curses``
+* ``dbm.gnu``
 * ``grp``
 * ``multiprocessing``
+* ``nis`` (Deprecated by PEP594)
+* ``ossaudiodev`` (Deprecated by PEP594)
 * ``posixshmem``
 * ``posixsubprocess``
+* ``readline``
+* ``spwd`` (Deprecated by PEP594)
 * ``syslog``
+* ``tkinter``
 
 The binaries support x86_64 and arm64 for macOS; arm64 for iOS and appleTV
 devices; and arm64_32 for watchOS. It also supports device simulators on both
@@ -93,10 +93,6 @@ Each support package contains:
 
 * ``VERSIONS``, a text file describing the specific versions of code used to build the
   support package;
-* ``bin``, a folder containing shell aliases for the compilers that are needed
-  to build packages. This is required because Xcode uses the ``xcrun`` alias to
-  dynamically generate the name of binaries, but a lot of C tooling expects that ``CC``
-  will not contain spaces.
 * ``platform-site``, a folder that contains site customization scripts that can be used
   to make your local Python install look like it is an on-device install for each of the
   underlying target architectures supported by the platform. This is needed because when
@@ -107,10 +103,17 @@ Each support package contains:
   return ``platform`` and ``sysconfig`` responses consistent with on-device behavior,
   which will cause ``pip`` to install platform-appropriate packages.
 * ``Python.xcframework``, a multi-architecture build of the Python runtime library
-* ``python-stdlib``, the code and binary modules comprising the Python standard library.
-  On iOS, tvOS and watchOS, there are 2 copies of every binary module - one for physical
-  devices, and one for the simulator. The simulator binaries are "fat", containing code
-  for both x86_64 and arm64.
+
+On iOS/tvOS/watchOS, the ``Python.xcframework`` contains a
+slice for each supported ABI (device and simulator). The folder containing the
+slice can also be used as a ``PYTHONHOME``, as it contains a ``bin``, ``include``
+and ``lib`` directory.
+
+The ``bin`` folder does not contain Python executables (as they can't be
+invoked). However, it *does* contain shell aliases for the compilers that are
+needed to build packages. This is required because Xcode uses the ``xcrun``
+alias to dynamically generate the name of binaries, but a lot of C tooling
+expects that ``CC`` will not contain spaces.
 
 For a detailed instructions on using the support package in your own project,
 see the `usage guide <./USAGE.md>`__

USAGE.md

@@ -23,31 +23,42 @@ To add this support package to your own project:
 1. [Download a release tarball for your desired Python version and Apple
    platform](https://github.com/beeware/Python-Apple-support/releases)
 
-2. Add the `python-stdlib` and `Python.xcframework` to your Xcode project. Both
-   the `python-stdlib` folder and the `Python.xcframework` should be members of
-   any target that needs to use Python.
+2. Add `Python.xcframework` to your Xcode project. You can put it anywhere in your
+   project that you want; the following instructions assume it has been put in a
+   folder named "Support".
 
 3. In Xcode, select the root node of the project tree, and select the target you
    want to build.
 
 4. Select "General" -> "Frameworks, Libraries and Embedded Content", and ensure
    that `Python.xcframework` is on the list of frameworks. It should be marked
-   "Do not embed".
+   "Embed and sign".
 
-5. Select "General" -> "Build Phases", and ensure that the `python-stdlib` folder
-   is listed in the "Copy Bundle Resources" step.
+5. Select "General" -> "Build Settings", and set the following values:
+   - Linking - General:
+     - `@executable_path/Frameworks`
+   - Search paths:
+     - Framework Search paths: `"$(PROJECT_DIR)/Support"`
+     - Header Search paths: `"$(BUILT_PRODUCTS_DIR)/Python.framework/Headers"`
 
-6. If you're on iOS, Add a new "Run script" build phase named "Purge Python Binary
-   Modules for Non-Target Platforms". This script will purge any dynamic module for the
-   platform you are *not* targeting. The script should have the following content:
+6. Add a new "Run script" build phase named "Install target specific Python
+   Modules". This script will install the standard library for your target. The
+   script should have the following content:
 
 ```bash
+set -e
+
+mkdir -p "$CODESIGNING_FOLDER_PATH/python/lib"
 if [ "$EFFECTIVE_PLATFORM_NAME" = "-iphonesimulator" ]; then
-    echo "Purging Python modules for iOS Device"
-    find "$CODESIGNING_FOLDER_PATH/python-stdlib" -name "*.*-iphoneos.dylib" -exec rm -f "{}" \;
+    echo "Installing Python modules for iOS Simulator"
+    rsync -au --delete "$PROJECT_DIR/Support/Python.xcframework/iphonesimulator/lib/" "$CODESIGNING_FOLDER_PATH/python/lib/"
+    # Also install any user-provided modules
+    # rsync -au --delete "$PROJECT_DIR/Testbed/app_packages.iphonesimulator/" "$CODESIGNING_FOLDER_PATH/app_packages"
 else
-    echo "Purging Python modules for iOS Simulator"
-    find "$CODESIGNING_FOLDER_PATH" -name "*.*-iphonesimulator.dylib" -exec rm -f "{}" \;
+    echo "Installing Python modules for iOS Device"
+    rsync -au --delete "$PROJECT_DIR/Support/Python.xcframework/iphoneos/lib/" "$CODESIGNING_FOLDER_PATH/python/lib"
+    # Also install any user-provided modules
+    # rsync -au --delete "$PROJECT_DIR/Testbed/app_packages.iphoneos/" "$CODESIGNING_FOLDER_PATH/app_packages"
 fi
 ```
 
@@ -69,13 +80,12 @@ install_dylib () {
     DYLIB=$(basename "$FULL_DYLIB")
     # The name of the .dylib file, relative to the install base
     RELATIVE_DYLIB=${FULL_DYLIB#$CODESIGNING_FOLDER_PATH/$INSTALL_BASE/}
-    # The (hopefully unique) name of the framework, constructed by replacing path
-    # separators in the relative name with underscores.
-    FRAMEWORK_NAME=$(echo $RELATIVE_DYLIB | cut -d "." -f 1 | tr "/" "_");
+    # The full dotted name of the binary module, constructed from the file path.
+    FULL_MODULE_NAME=$(echo $RELATIVE_DYLIB | cut -d "." -f 1 | tr "/" ".");
     # A bundle identifier; not actually used, but required by Xcode framework packaging
-    FRAMEWORK_BUNDLE_ID=$(echo $PRODUCT_BUNDLE_IDENTIFIER.$FRAMEWORK_NAME | tr "_" "-")
+    FRAMEWORK_BUNDLE_ID=$(echo $PRODUCT_BUNDLE_IDENTIFIER.$FULL_MODULE_NAME | tr "_" "-")
     # The name of the framework folder.
-    FRAMEWORK_FOLDER="Frameworks/$FRAMEWORK_NAME.framework"
+    FRAMEWORK_FOLDER="Frameworks/$FULL_MODULE_NAME.framework"
 
     # If the framework folder doesn't exist, create it.
     if [ ! -d "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER" ]; then
@@ -91,10 +101,16 @@ install_dylib () {
     mv "$FULL_DYLIB" "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER"
 }
 
+# Make sure to update the Python version version reference here
 echo "Install standard library dylibs..."
-find "$CODESIGNING_FOLDER_PATH/python-stdlib/lib-dynload" -name "*.dylib" | while read FULL_DYLIB; do
-    install_dylib python-stdlib/lib-dynload "$FULL_DYLIB"
+find "$CODESIGNING_FOLDER_PATH/python/lib/python3.13/lib-dynload" -name "*.dylib" | while read FULL_DYLIB; do
+    install_dylib python/lib/python3.13/lib-dynload "$FULL_DYLIB"
 done
+# Also install any user-provided dynamic modules; e.g.,
+# echo "Install app package dylibs..."
+# find "$CODESIGNING_FOLDER_PATH/app_packages" -name "*.dylib" | while read FULL_DYLIB; do
+#     install_dylib app_packages "$FULL_DYLIB"
+# done
 
 # Clean up dylib template
 rm -f "$CODESIGNING_FOLDER_PATH/dylib-Info-template.plist"
@@ -103,6 +119,11 @@ echo "Signing frameworks as $EXPANDED_CODE_SIGN_IDENTITY_NAME ($EXPANDED_CODE_SI
 find "$CODESIGNING_FOLDER_PATH/Frameworks" -name "*.framework" -exec /usr/bin/codesign --force --sign "$EXPANDED_CODE_SIGN_IDENTITY" ${OTHER_CODE_SIGN_FLAGS:-} -o runtime --timestamp=none --preserve-metadata=identifier,entitlements,flags --generate-entitlement-der "{}" \;
 ```
 
+   Make sure that you update these scripts to update the references to the
+   Python version, and include any user-provided code that you want to bundle.
+   If you use the ``rsync`` approach above, user-provided code should *not* be
+   included as part of the "Copy Bundle Resources" step.
+
    You'll also need to add a file named `dylib-Info-template.plist` to your Xcode
    project, and make it a member of any target that needs to use Python. The template
    should have the following content: