| 1 |
# Python on iOS README |
| 2 |
|
| 3 |
**iOS support is [tier 3](https://peps.python.org/pep-0011/#tier-3).** |
| 4 |
|
| 5 |
This document provides a quick overview of some iOS specific features in the |
| 6 |
Python distribution. |
| 7 |
|
| 8 |
These instructions are only needed if you're planning to compile Python for iOS |
| 9 |
yourself. Most users should *not* need to do this. If you're looking to |
| 10 |
experiment with writing an iOS app in Python, tools such as [BeeWare's |
| 11 |
Briefcase](https://briefcase.readthedocs.io) and [Kivy's |
| 12 |
Buildozer](https://buildozer.readthedocs.io) will provide a much more |
| 13 |
approachable user experience. |
| 14 |
|
| 15 |
## Compilers for building on iOS |
| 16 |
|
| 17 |
Building for iOS requires the use of Apple's Xcode tooling. It is strongly |
| 18 |
recommended that you use the most recent stable release of Xcode. This will |
| 19 |
require the use of the most (or second-most) recently released macOS version, |
| 20 |
as Apple does not maintain Xcode for older macOS versions. The Xcode Command |
| 21 |
Line Tools are not sufficient for iOS development; you need a *full* Xcode |
| 22 |
install. |
| 23 |
|
| 24 |
If you want to run your code on the iOS simulator, you'll also need to install |
| 25 |
an iOS Simulator Platform. You should be prompted to select an iOS Simulator |
| 26 |
Platform when you first run Xcode. Alternatively, you can add an iOS Simulator |
| 27 |
Platform by selecting an open the Platforms tab of the Xcode Settings panel. |
| 28 |
|
| 29 |
## Building Python on iOS |
| 30 |
|
| 31 |
### ABIs and Architectures |
| 32 |
|
| 33 |
iOS apps can be deployed on physical devices, and on the iOS simulator. Although |
| 34 |
the API used on these devices is identical, the ABI is different - you need to |
| 35 |
link against different libraries for an iOS device build (`iphoneos`) or an |
| 36 |
iOS simulator build (`iphonesimulator`). |
| 37 |
|
| 38 |
Apple uses the `XCframework` format to allow specifying a single dependency |
| 39 |
that supports multiple ABIs. An `XCframework` is a wrapper around multiple |
| 40 |
ABI-specific frameworks that share a common API. |
| 41 |
|
| 42 |
iOS can also support different CPU architectures within each ABI. At present, |
| 43 |
there is only a single supported architecture on physical devices - ARM64. |
| 44 |
However, the *simulator* supports 2 architectures - ARM64 (for running on Apple |
| 45 |
Silicon machines), and x86_64 (for running on older Intel-based machines). |
| 46 |
|
| 47 |
To support multiple CPU architectures on a single platform, Apple uses a "fat |
| 48 |
binary" format - a single physical file that contains support for multiple |
| 49 |
architectures. It is possible to compile and use a "thin" single architecture |
| 50 |
version of a binary for testing purposes; however, the "thin" binary will not be |
| 51 |
portable to machines using other architectures. |
| 52 |
|
| 53 |
### Building a multi-architecture iOS XCframework |
| 54 |
|
| 55 |
The `Apple` subfolder of the Python repository acts as a build script that |
| 56 |
can be used to coordinate the compilation of a complete iOS XCframework. To use |
| 57 |
it, run:: |
| 58 |
|
| 59 |
python Apple build iOS |
| 60 |
|
| 61 |
This will: |
| 62 |
|
| 63 |
* Configure and compile a version of Python to run on the build machine |
| 64 |
* Download pre-compiled binary dependencies for each platform |
| 65 |
* Configure and build a `Python.framework` for each required architecture and |
| 66 |
iOS SDK |
| 67 |
* Merge the multiple `Python.framework` folders into a single `Python.xcframework` |
| 68 |
* Produce a `.tar.gz` archive in the `cross-build/dist` folder containing |
| 69 |
the `Python.xcframework`, plus a copy of the Testbed app pre-configured to |
| 70 |
use the XCframework. |
| 71 |
|
| 72 |
The `Apple` build script has other entry points that will perform the |
| 73 |
individual parts of the overall `build` target, plus targets to test the |
| 74 |
build, clean the `cross-build` folder of iOS build products, and perform a |
| 75 |
complete "build and test" CI run. The `--clean` flag can also be used on |
| 76 |
individual commands to ensure that a stale build product are removed before |
| 77 |
building. |
| 78 |
|
| 79 |
### Building a single-architecture framework |
| 80 |
|
| 81 |
If you're using the `Apple` build script, you won't need to build |
| 82 |
individual frameworks. However, if you do need to manually configure an iOS |
| 83 |
Python build for a single framework, the following options are available. |
| 84 |
|
| 85 |
#### iOS specific arguments to configure |
| 86 |
|
| 87 |
* `--enable-framework[=DIR]` |
| 88 |
|
| 89 |
This argument specifies the location where the Python.framework will be |
| 90 |
installed. If `DIR` is not specified, the framework will be installed into |
| 91 |
a subdirectory of the `iOS/Frameworks` folder. |
| 92 |
|
| 93 |
This argument *must* be provided when configuring iOS builds. iOS does not |
| 94 |
support non-framework builds. |
| 95 |
|
| 96 |
* `--with-framework-name=NAME` |
| 97 |
|
| 98 |
Specify the name for the Python framework; defaults to `Python`. |
| 99 |
|
| 100 |
> [!NOTE] |
| 101 |
> Unless you know what you're doing, changing the name of the Python |
| 102 |
> framework on iOS is not advised. If you use this option, you won't be able |
| 103 |
> to run the `Apple` build script without making significant manual |
| 104 |
> alterations, and you won't be able to use any binary packages unless you |
| 105 |
> compile them yourself using your own framework name. |
| 106 |
|
| 107 |
#### Building Python for iOS |
| 108 |
|
| 109 |
The Python build system will create a `Python.framework` that supports a |
| 110 |
*single* ABI with a *single* architecture. Unlike macOS, iOS does not allow a |
| 111 |
framework to contain non-library content, so the iOS build will produce a |
| 112 |
`bin` and `lib` folder in the same output folder as `Python.framework`. |
| 113 |
The `lib` folder will be needed at runtime to support the Python library. |
| 114 |
|
| 115 |
If you want to use Python in a real iOS project, you need to produce multiple |
| 116 |
`Python.framework` builds, one for each ABI and architecture. iOS builds of |
| 117 |
Python *must* be constructed as framework builds. To support this, you must |
| 118 |
provide the `--enable-framework` flag when configuring the build. The build |
| 119 |
also requires the use of cross-compilation. The minimal commands for building |
| 120 |
Python for the ARM64 iOS simulator will look something like: |
| 121 |
``` |
| 122 |
export PATH="$(pwd)/Apple/iOS/Resources/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin" |
| 123 |
./configure \ |
| 124 |
--enable-framework \ |
| 125 |
--host=arm64-apple-ios-simulator \ |
| 126 |
--build=arm64-apple-darwin \ |
| 127 |
--with-build-python=/path/to/python.exe |
| 128 |
make |
| 129 |
make install |
| 130 |
``` |
| 131 |
|
| 132 |
In this invocation: |
| 133 |
|
| 134 |
* `Apple/iOS/Resources/bin` has been added to the path, providing some shims for the |
| 135 |
compilers and linkers needed by the build. Xcode requires the use of `xcrun` |
| 136 |
to invoke compiler tooling. However, if `xcrun` is pre-evaluated and the |
| 137 |
result passed to `configure`, these results can embed user- and |
| 138 |
version-specific paths into the sysconfig data, which limits the portability |
| 139 |
of the compiled Python. Alternatively, if `xcrun` is used *as* the compiler, |
| 140 |
it requires that compiler variables like `CC` include spaces, which can |
| 141 |
cause significant problems with many C configuration systems which assume that |
| 142 |
`CC` will be a single executable. |
| 143 |
|
| 144 |
To work around this problem, the `Apple/iOS/Resources/bin` folder contains some |
| 145 |
wrapper scripts that present as simple compilers and linkers, but wrap |
| 146 |
underlying calls to `xcrun`. This allows configure to use a `CC` |
| 147 |
definition without spaces, and without user- or version-specific paths, while |
| 148 |
retaining the ability to adapt to the local Xcode install. These scripts are |
| 149 |
included in the `bin` directory of an iOS install. |
| 150 |
|
| 151 |
These scripts will, by default, use the currently active Xcode installation. |
| 152 |
If you want to use a different Xcode installation, you can use |
| 153 |
`xcode-select` to set a new default Xcode globally, or you can use the |
| 154 |
`DEVELOPER_DIR` environment variable to specify an Xcode install. The |
| 155 |
scripts will use the default `iphoneos`/`iphonesimulator` SDK version for |
| 156 |
the select Xcode install; if you want to use a different SDK, you can set the |
| 157 |
`IOS_SDK_VERSION` environment variable. (e.g, setting |
| 158 |
`IOS_SDK_VERSION=17.1` would cause the scripts to use the `iphoneos17.1` |
| 159 |
and `iphonesimulator17.1` SDKs, regardless of the Xcode default.) |
| 160 |
|
| 161 |
The path has also been cleared of any user customizations. A common source of |
| 162 |
bugs is for tools like Homebrew to accidentally leak macOS binaries into an iOS |
| 163 |
build. Resetting the path to a known "bare bones" value is the easiest way to |
| 164 |
avoid these problems. |
| 165 |
|
| 166 |
* `--host` is the architecture and ABI that you want to build, in GNU compiler |
| 167 |
triple format. This will be one of: |
| 168 |
|
| 169 |
- `arm64-apple-ios` for ARM64 iOS devices. |
| 170 |
- `arm64-apple-ios-simulator` for the iOS simulator running on Apple |
| 171 |
Silicon devices. |
| 172 |
- `x86_64-apple-ios-simulator` for the iOS simulator running on Intel |
| 173 |
devices. |
| 174 |
|
| 175 |
* `--build` is the GNU compiler triple for the machine that will be running |
| 176 |
the compiler. This is one of: |
| 177 |
|
| 178 |
- `arm64-apple-darwin` for Apple Silicon devices. |
| 179 |
- `x86_64-apple-darwin` for Intel devices. |
| 180 |
|
| 181 |
* `/path/to/python.exe` is the path to a Python binary on the machine that |
| 182 |
will be running the compiler. This is needed because the Python compilation |
| 183 |
process involves running some Python code. On a normal desktop build of |
| 184 |
Python, you can compile a python interpreter and then use that interpreter to |
| 185 |
run Python code. However, the binaries produced for iOS won't run on macOS, so |
| 186 |
you need to provide an external Python interpreter. This interpreter must be |
| 187 |
the same version as the Python that is being compiled. To be completely safe, |
| 188 |
this should be the *exact* same commit hash. However, the longer a Python |
| 189 |
release has been stable, the more likely it is that this constraint can be |
| 190 |
relaxed - the same micro version will often be sufficient. |
| 191 |
|
| 192 |
* The `install` target for iOS builds is slightly different to other |
| 193 |
platforms. On most platforms, `make install` will install the build into |
| 194 |
the final runtime location. This won't be the case for iOS, as the final |
| 195 |
runtime location will be on a physical device. |
| 196 |
|
| 197 |
However, you still need to run the `install` target for iOS builds, as it |
| 198 |
performs some final framework assembly steps. The location specified with |
| 199 |
`--enable-framework` will be the location where `make install` will |
| 200 |
assemble the complete iOS framework. This completed framework can then |
| 201 |
be copied and relocated as required. |
| 202 |
|
| 203 |
For a full CPython build, you also need to specify the paths to iOS builds of |
| 204 |
the binary libraries that CPython depends on (such as XZ, LibFFI and OpenSSL). |
| 205 |
This can be done by defining library specific environment variables (such as |
| 206 |
`LIBLZMA_CFLAGS`, `LIBLZMA_LIBS`), and the `--with-openssl` configure |
| 207 |
option. Versions of these libraries pre-compiled for iOS can be found in [this |
| 208 |
repository](https://github.com/beeware/cpython-apple-source-deps/releases). |
| 209 |
LibFFI is especially important, as many parts of the standard library |
| 210 |
(including the `platform`, `sysconfig` and `webbrowser` modules) require |
| 211 |
the use of the `ctypes` module at runtime. |
| 212 |
|
| 213 |
By default, Python will be compiled with an iOS deployment target (i.e., the |
| 214 |
minimum supported iOS version) of 13.0. To specify a different deployment |
| 215 |
target, provide the version number as part of the `--host` argument - for |
| 216 |
example, `--host=arm64-apple-ios15.4-simulator` would compile an ARM64 |
| 217 |
simulator build with a deployment target of 15.4. |
| 218 |
|
| 219 |
## Testing Python on iOS |
| 220 |
|
| 221 |
### Testing a multi-architecture framework |
| 222 |
|
| 223 |
Once you have a built an XCframework, you can test that framework by running: |
| 224 |
|
| 225 |
$ python Apple test iOS |
| 226 |
|
| 227 |
This test will attempt to find an "SE-class" simulator (i.e., an iPhone SE, or |
| 228 |
iPhone 16e, or similar), and run the test suite on the most recent version of |
| 229 |
iOS that is available. You can specify a simulator using the `--simulator` |
| 230 |
command line argument, providing the name of the simulator (e.g., `--simulator |
| 231 |
'iPhone 16 Pro'`). You can also use this argument to control the OS version used |
| 232 |
for testing; `--simulator 'iPhone 16 Pro,OS=18.2'` would attempt to run the |
| 233 |
tests on an iPhone 16 Pro running iOS 18.2. |
| 234 |
|
| 235 |
If the test runner is executed on GitHub Actions, the `GITHUB_ACTIONS` |
| 236 |
environment variable will be exposed to the iOS process at runtime. |
| 237 |
|
| 238 |
### Testing a single-architecture framework |
| 239 |
|
| 240 |
The `Apple/testbed` folder that contains an Xcode project that is able to run |
| 241 |
the Python test suite on Apple platforms. This project converts the Python test |
| 242 |
suite into a single test case in Xcode's XCTest framework. The single XCTest |
| 243 |
passes if the test suite passes. |
| 244 |
|
| 245 |
To run the test suite, configure a Python build for an iOS simulator (i.e., |
| 246 |
`--host=arm64-apple-ios-simulator` or `--host=x86_64-apple-ios-simulator` |
| 247 |
), specifying a framework build (i.e. `--enable-framework`). Ensure that your |
| 248 |
`PATH` has been configured to include the `Apple/iOS/Resources/bin` folder and |
| 249 |
exclude any non-iOS tools, then run: |
| 250 |
``` |
| 251 |
make all |
| 252 |
make install |
| 253 |
make testios |
| 254 |
``` |
| 255 |
|
| 256 |
This will: |
| 257 |
|
| 258 |
* Build an iOS framework for your chosen architecture; |
| 259 |
* Finalize the single-platform framework; |
| 260 |
* Make a clean copy of the testbed project; |
| 261 |
* Install the Python iOS framework into the copy of the testbed project; and |
| 262 |
* Run the test suite on an "entry-level device" simulator (i.e., an iPhone SE, |
| 263 |
iPhone 16e, or a similar). |
| 264 |
|
| 265 |
On success, the test suite will exit and report successful completion of the |
| 266 |
test suite. On a 2022 M1 MacBook Pro, the test suite takes approximately 15 |
| 267 |
minutes to run; a couple of extra minutes is required to compile the testbed |
| 268 |
project, and then boot and prepare the iOS simulator. |
| 269 |
|
| 270 |
### Debugging test failures |
| 271 |
|
| 272 |
Running `python Apple test iOS` generates a standalone version of the |
| 273 |
`Apple/testbed` project, and runs the full test suite. It does this using |
| 274 |
`Apple/testbed` itself - the folder is an executable module that can be used |
| 275 |
to create and run a clone of the testbed project. The standalone version of the |
| 276 |
testbed will be created in a directory named |
| 277 |
`cross-build/iOS-testbed.<timestamp>`. |
| 278 |
|
| 279 |
You can generate your own standalone testbed instance by running: |
| 280 |
``` |
| 281 |
python cross-build/iOS/testbed clone my-testbed |
| 282 |
``` |
| 283 |
|
| 284 |
In this invocation, `my-testbed` is the name of the folder for the new |
| 285 |
testbed clone. |
| 286 |
|
| 287 |
If you've built your own XCframework, or you only want to test a single architecture, |
| 288 |
you can construct a standalone testbed instance by running: |
| 289 |
``` |
| 290 |
python Apple/testbed clone --platform iOS --framework <path/to/framework> my-testbed |
| 291 |
``` |
| 292 |
|
| 293 |
The framework path can be the path path to a `Python.xcframework`, or the |
| 294 |
path to a folder that contains a single-platform `Python.framework`. |
| 295 |
|
| 296 |
You can then use the `my-testbed` folder to run the Python test suite, |
| 297 |
passing in any command line arguments you may require. For example, if you're |
| 298 |
trying to diagnose a failure in the `os` module, you might run: |
| 299 |
``` |
| 300 |
python my-testbed run -- test -W test_os |
| 301 |
``` |
| 302 |
|
| 303 |
This is the equivalent of running `python -m test -W test_os` on a desktop |
| 304 |
Python build. Any arguments after the `--` will be passed to testbed as if |
| 305 |
they were arguments to `python -m` on a desktop machine. |
| 306 |
|
| 307 |
### Testing in Xcode |
| 308 |
|
| 309 |
You can also open the testbed project in Xcode by running: |
| 310 |
``` |
| 311 |
open my-testbed/iOSTestbed.xcodeproj |
| 312 |
``` |
| 313 |
|
| 314 |
This will allow you to use the full Xcode suite of tools for debugging. |
| 315 |
|
| 316 |
The arguments used to run the test suite are defined as part of the test plan. |
| 317 |
To modify the test plan, select the test plan node of the project tree (it |
| 318 |
should be the first child of the root node), and select the "Configurations" |
| 319 |
tab. Modify the "Arguments Passed On Launch" value to change the testing |
| 320 |
arguments. |
| 321 |
|
| 322 |
The test plan also disables parallel testing, and specifies the use of the |
| 323 |
`Testbed.lldbinit` file for providing configuration of the debugger. The |
| 324 |
default debugger configuration disables automatic breakpoints on the |
| 325 |
`SIGINT`, `SIGUSR1`, `SIGUSR2`, and `SIGXFSZ` signals. |
| 326 |
|
| 327 |
### Testing on an iOS device |
| 328 |
|
| 329 |
To test on an iOS device, the app needs to be signed with known developer |
| 330 |
credentials. To obtain these credentials, you must have an iOS Developer |
| 331 |
account, and your Xcode install will need to be logged into your account (see |
| 332 |
the Accounts tab of the Preferences dialog). |
| 333 |
|
| 334 |
Once the project is open, and you're signed into your Apple Developer account, |
| 335 |
select the root node of the project tree (labeled "iOSTestbed"), then the |
| 336 |
"Signing & Capabilities" tab in the details page. Select a development team |
| 337 |
(this will likely be your own name), and plug in a physical device to your |
| 338 |
macOS machine with a USB cable. You should then be able to select your physical |
| 339 |
device from the list of targets in the pulldown in the Xcode titlebar. |