Debian Codegraph @

Apple/iOS/README.md

raw
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.