|
| 1 | +# Python Apple Support |
| 2 | + |
| 3 | +This is a meta-package for building a version of Python that can be |
| 4 | +embedded into a macOS, iOS, tvOS, or watchOS project. |
| 5 | + |
| 6 | +**This branch builds a packaged version of Python 3.13**. Other Python |
| 7 | +versions are available by cloning other branches of the main repository: |
| 8 | + |
| 9 | +- [Python 3.9](https://github.com/beeware/Python-Apple-support/tree/3.9) |
| 10 | +- [Python |
| 11 | + 3.10](https://github.com/beeware/Python-Apple-support/tree/3.10) |
| 12 | +- [Python |
| 13 | + 3.11](https://github.com/beeware/Python-Apple-support/tree/3.11) |
| 14 | +- [Python |
| 15 | + 3.12](https://github.com/beeware/Python-Apple-support/tree/3.12) |
| 16 | +- [Python |
| 17 | + 3.14](https://github.com/beeware/Python-Apple-support/tree/3.14) |
| 18 | + |
| 19 | +It works by downloading, patching, and building a fat binary of Python |
| 20 | +and selected pre-requisites, and packaging them as frameworks that can |
| 21 | +be incorporated into an Xcode project. The binary modules in the Python |
| 22 | +standard library are distributed as binaries that can be dynamically |
| 23 | +loaded at runtime. |
| 24 | + |
| 25 | +The macOS package is a re-bundling of the official macOS binary, |
| 26 | +modified so that it is relocatable, with the IDLE, Tkinter and turtle |
| 27 | +packages removed, and the App Store compliance patch applied. |
| 28 | + |
| 29 | +The iOS, tvOS, and watchOS packages compiled by this project |
| 30 | +use the official [PEP 730](https://peps.python.org/pep-0730/) code that |
| 31 | +is part of Python 3.13 to provide iOS support; the relevant patches have |
| 32 | +been backported to 3.9-3.12. Additional patches have been applied to add |
| 33 | +tvOS, and watchOS support. |
| 34 | + |
| 35 | +The binaries support x86_64 and arm64 for macOS; arm64 for iOS and |
| 36 | +appleTV devices; and arm64_32 for watchOS devices. |
| 37 | +It also supports device simulators on both x86_64 and M1 |
| 38 | +hardware. This should enable the code to run on: |
| 39 | + |
| 40 | +- macOS 11 (Big Sur) or later, on: |
| 41 | + - MacBook (including MacBooks using Apple Silicon) |
| 42 | + - iMac (including iMacs using Apple Silicon) |
| 43 | + - Mac Mini (including Apple Silicon Mac minis) |
| 44 | + - Mac Studio (all models) |
| 45 | + - Mac Pro (all models) |
| 46 | + |
| 47 | +- iOS 13.0 or later, on: |
| 48 | + - iPhone (6s or later) |
| 49 | + - iPad (5th gen or later) |
| 50 | + - iPad Air (all models) |
| 51 | + - iPad Mini (2 or later) |
| 52 | + - iPad Pro (all models) |
| 53 | + - iPod Touch (7th gen or later) |
| 54 | + |
| 55 | +- tvOS 12.0 or later, on: |
| 56 | + - Apple TV (4th gen or later) |
| 57 | + |
| 58 | +- watchOS 4.0 or later, on: |
| 59 | + - Apple Watch (4th gen or later) |
| 60 | + |
| 61 | +## Quickstart |
| 62 | + |
| 63 | +The easist way to use these packages is by creating a project with |
| 64 | +[Briefcase](https://github.com/beeware/briefcase). Briefcase will |
| 65 | +download pre-compiled versions of these support packages, and add them |
| 66 | +to an Xcode project (or pre-build stub application, in the case of |
| 67 | +macOS). |
| 68 | + |
| 69 | +Pre-built versions of the frameworks can be downloaded from the [Github |
| 70 | +releases page](https://github.com/beeware/Python-Apple-support/releases) |
| 71 | +and added to your project. |
| 72 | + |
| 73 | +Alternatively, to build the frameworks on your own, download/clone this |
| 74 | +repository, and then in the root directory, and run: |
| 75 | + |
| 76 | +- `make` (or `make all`) to build everything. |
| 77 | +- `make macOS` to build everything for macOS. |
| 78 | +- `make iOS` to build everything for iOS. |
| 79 | +- `make tvOS` to build everything for tvOS. |
| 80 | +- `make watchOS` to build everything for watchOS. |
| 81 | + |
| 82 | +This should: |
| 83 | + |
| 84 | +1. Download the original source packages |
| 85 | +2. Patch them as required for compatibility with the selected OS |
| 86 | +3. Build the packages as Xcode-compatible XCFrameworks. |
| 87 | + |
| 88 | +The resulting support packages will be packaged as `.tar.gz` files in |
| 89 | +the `dist` folder. |
| 90 | + |
| 91 | +Each support package contains: |
| 92 | + |
| 93 | +- `VERSIONS`, a text file describing the specific versions of code used |
| 94 | + to build the support package; |
| 95 | +- `Python.xcframework`, a multi-architecture build of the Python runtime |
| 96 | + library. |
| 97 | + |
| 98 | +On iOS/tvOS/watchOS, the `Python.xcframework` contains a slice |
| 99 | +for each supported ABI (device and simulator). The folder containing the |
| 100 | +slice can also be used as a `PYTHONHOME`, as it contains a `bin`, |
| 101 | +`include` and `lib` directory. |
| 102 | + |
| 103 | +The `bin` folder does not contain Python executables (as they can't be |
| 104 | +invoked). However, it *does* contain shell aliases for the compilers |
| 105 | +that are needed to build packages. This is required because Xcode uses |
| 106 | +the `xcrun` alias to dynamically generate the name of binaries, but a |
| 107 | +lot of C tooling expects that `CC` will not contain spaces. |
| 108 | + |
| 109 | +Each slice of an iOS/tvOS/watchOS XCframework also contains a |
| 110 | +`platform-config` folder with a subfolder for each supported |
| 111 | +architecture in that slice. These subfolders can be used to make a macOS |
| 112 | +Python environment behave as if it were on an iOS/tvOS/watchOS |
| 113 | +device. This works in one of two ways: |
| 114 | + |
| 115 | +1. **A sitecustomize.py script**. If the `platform-config` subfolder is |
| 116 | + on your `PYTHONPATH` when a Python interpreter is started, a site |
| 117 | + customization will be applied that patches methods in `sys`, |
| 118 | + `sysconfig` and `platform` that are used to identify the system. |
| 119 | +2. **A make_cross_venv.py script**. If you call `make_cross_venv.py`, |
| 120 | + providing the location of a virtual environment, the script will add |
| 121 | + some files to the `site-packages` folder of that environment that |
| 122 | + will automatically apply the same set of patches as the |
| 123 | + `sitecustomize.py` script whenever the environment is activated, |
| 124 | + without any need to modify `PYTHONPATH`. If you use `build` to |
| 125 | + create an isolated PEP 517 environment to build a wheel, these |
| 126 | + patches will also be applied to the isolated build environment that |
| 127 | + is created. |
| 128 | + |
| 129 | +iOS distributions also contain a copy of the iOS |
| 130 | +`testbed` project - an Xcode project that can be used to run |
| 131 | +test suites of Python code. See the [CPython documentation on testing |
| 132 | +packages](https://docs.python.org/3/using/ios.html#testing-a-python-package) |
| 133 | +for details on how to use this testbed. |
| 134 | + |
| 135 | +For a detailed instructions on using the support package in your own |
| 136 | +project, see the [usage guide](./USAGE.md) |
| 137 | + |
| 138 | +## Building binary wheels |
| 139 | + |
| 140 | +This project packages the Python standard library, but does not address |
| 141 | +building binary wheels. Binary wheels for macOS can be obtained from |
| 142 | +PyPI. [Mobile Forge](https://github.com/beeware/mobile-forge) is a |
| 143 | +project that provides the tooling to build build binary wheels for iOS |
| 144 | +(and potentially for tvOS, and watchOS, although that hasn't |
| 145 | +been tested). |
| 146 | + |
| 147 | +## Historical support |
| 148 | + |
| 149 | +The following versions were supported in the past, but are no longer |
| 150 | +maintained: |
| 151 | + |
| 152 | +- [Python 2.7](https://github.com/beeware/Python-Apple-support/tree/2.7) |
| 153 | + (EOL January 2020) |
| 154 | +- [Python 3.4](https://github.com/beeware/Python-Apple-support/tree/3.4) |
| 155 | + (EOL March 2019) |
| 156 | +- [Python 3.5](https://github.com/beeware/Python-Apple-support/tree/3.5) |
| 157 | + (EOL February 2021) |
| 158 | +- [Python 3.6](https://github.com/beeware/Python-Apple-support/tree/3.6) |
| 159 | + (EOL December 2021) |
| 160 | +- [Python 3.7](https://github.com/beeware/Python-Apple-support/tree/3.7) |
| 161 | + (EOL September 2022) |
| 162 | +- [Python 3.8](https://github.com/beeware/Python-Apple-support/tree/3.8) |
| 163 | + (EOL October 2024) |
0 commit comments