Debian Codegraph @

Doc/using/ios.rst

raw
1 .. _using-ios:
2
3 ===================
4 Using Python on iOS
5 ===================
6
7 :Authors:
8 Russell Keith-Magee (2024-03)
9
10 Python on iOS is unlike Python on desktop platforms. On a desktop platform,
11 Python is generally installed as a system resource that can be used by any user
12 of that computer. Users then interact with Python by running a :program:`python`
13 executable and entering commands at an interactive prompt, or by running a
14 Python script.
15
16 On iOS, there is no concept of installing as a system resource. The only unit
17 of software distribution is an "app". There is also no console where you could
18 run a :program:`python` executable, or interact with a Python REPL.
19
20 As a result, the only way you can use Python on iOS is in embedded mode - that
21 is, by writing a native iOS application, and embedding a Python interpreter
22 using ``libPython``, and invoking Python code using the :ref:`Python embedding
23 API <embedding>`. The full Python interpreter, the standard library, and all
24 your Python code is then packaged as a standalone bundle that can be
25 distributed via the iOS App Store.
26
27 If you're looking to experiment for the first time with writing an iOS app in
28 Python, projects such as `BeeWare <https://beeware.org>`__ and `Kivy
29 <https://kivy.org>`__ will provide a much more approachable user experience.
30 These projects manage the complexities associated with getting an iOS project
31 running, so you only need to deal with the Python code itself.
32
33 Python at runtime on iOS
34 ========================
35
36 iOS version compatibility
37 -------------------------
38
39 The minimum supported iOS version is specified at compile time, using the
40 :option:`--host` option to ``configure``. By default, when compiled for iOS,
41 Python will be compiled with a minimum supported iOS version of 13.0. To use a
42 different minimum iOS version, provide the version number as part of the
43 :option:`!--host` argument - for example,
44 ``--host=arm64-apple-ios15.4-simulator`` would compile an ARM64 simulator build
45 with a deployment target of 15.4.
46
47 Platform identification
48 -----------------------
49
50 When executing on iOS, ``sys.platform`` will report as ``ios``. This value will
51 be returned on an iPhone or iPad, regardless of whether the app is running on
52 the simulator or a physical device.
53
54 Information about the specific runtime environment, including the iOS version,
55 device model, and whether the device is a simulator, can be obtained using
56 :func:`platform.ios_ver`. :func:`platform.system` will report ``iOS`` or
57 ``iPadOS``, depending on the device.
58
59 :func:`os.uname` reports kernel-level details; it will report a name of
60 ``Darwin``.
61
62 Standard library availability
63 -----------------------------
64
65 The Python standard library has some notable omissions and restrictions on
66 iOS. See the :ref:`API availability guide for iOS <mobile-availability>` for
67 details.
68
69 Binary extension modules
70 ------------------------
71
72 One notable difference about iOS as a platform is that App Store distribution
73 imposes hard requirements on the packaging of an application. One of these
74 requirements governs how binary extension modules are distributed.
75
76 The iOS App Store requires that *all* binary modules in an iOS app must be
77 dynamic libraries, contained in a framework with appropriate metadata, stored
78 in the ``Frameworks`` folder of the packaged app. There can be only a single
79 binary per framework, and there can be no executable binary material outside
80 the ``Frameworks`` folder.
81
82 This conflicts with the usual Python approach for distributing binaries, which
83 allows a binary extension module to be loaded from any location on
84 ``sys.path``. To ensure compliance with App Store policies, an iOS project must
85 post-process any Python packages, converting ``.so`` binary modules into
86 individual standalone frameworks with appropriate metadata and signing. For
87 details on how to perform this post-processing, see the guide for :ref:`adding
88 Python to your project <adding-ios>`.
89
90 To help Python discover binaries in their new location, the original ``.so``
91 file on ``sys.path`` is replaced with a ``.fwork`` file. This file is a text
92 file containing the location of the framework binary, relative to the app
93 bundle. To allow the framework to resolve back to the original location, the
94 framework must contain a ``.origin`` file that contains the location of the
95 ``.fwork`` file, relative to the app bundle.
96
97 For example, consider the case of an import ``from foo.bar import _whiz``,
98 where ``_whiz`` is implemented with the binary module
99 ``sources/foo/bar/_whiz.abi3.so``, with ``sources`` being the location
100 registered on ``sys.path``, relative to the application bundle. This module
101 *must* be distributed as ``Frameworks/foo.bar._whiz.framework/foo.bar._whiz``
102 (creating the framework name from the full import path of the module), with an
103 ``Info.plist`` file in the ``.framework`` directory identifying the binary as a
104 framework. The ``foo.bar._whiz`` module would be represented in the original
105 location with a ``sources/foo/bar/_whiz.abi3.fwork`` marker file, containing
106 the path ``Frameworks/foo.bar._whiz/foo.bar._whiz``. The framework would also
107 contain ``Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin``, containing
108 the path to the ``.fwork`` file.
109
110 When running on iOS, the Python interpreter will install an
111 :class:`~importlib.machinery.AppleFrameworkLoader` that is able to read and
112 import ``.fwork`` files. Once imported, the ``__file__`` attribute of the
113 binary module will report as the location of the ``.fwork`` file. However, the
114 :class:`~importlib.machinery.ModuleSpec` for the loaded module will report the
115 ``origin`` as the location of the binary in the framework folder.
116
117 Compiler stub binaries
118 ----------------------
119
120 Xcode doesn't expose explicit compilers for iOS; instead, it uses an ``xcrun``
121 script that resolves to a full compiler path (e.g., ``xcrun --sdk iphoneos
122 clang`` to get the ``clang`` for an iPhone device). However, using this script
123 poses two problems:
124
125 * The output of ``xcrun`` includes paths that are machine specific, resulting
126 in a sysconfig module that cannot be shared between users; and
127
128 * It results in ``CC``/``CPP``/``LD``/``AR`` definitions that include spaces.
129 There is a lot of C ecosystem tooling that assumes that you can split a
130 command line at the first space to get the path to the compiler executable;
131 this isn't the case when using ``xcrun``.
132
133 To avoid these problems, Python provided stubs for these tools. These stubs are
134 shell script wrappers around the underingly ``xcrun`` tools, distributed in a
135 ``bin`` folder distributed alongside the compiled iOS framework. These scripts
136 are relocatable, and will always resolve to the appropriate local system paths.
137 By including these scripts in the bin folder that accompanies a framework, the
138 contents of the ``sysconfig`` module becomes useful for end-users to compile
139 their own modules. When compiling third-party Python modules for iOS, you
140 should ensure these stub binaries are on your path.
141
142 Installing Python on iOS
143 ========================
144
145 Tools for building iOS apps
146 ---------------------------
147
148 Building for iOS requires the use of Apple's Xcode tooling. It is strongly
149 recommended that you use the most recent stable release of Xcode. This will
150 require the use of the most (or second-most) recently released macOS version,
151 as Apple does not maintain Xcode for older macOS versions. The Xcode Command
152 Line Tools are not sufficient for iOS development; you need a *full* Xcode
153 install.
154
155 If you want to run your code on the iOS simulator, you'll also need to install
156 an iOS Simulator Platform. You should be prompted to select an iOS Simulator
157 Platform when you first run Xcode. Alternatively, you can add an iOS Simulator
158 Platform by selecting from the Platforms tab of the Xcode Settings panel.
159
160 .. _adding-ios:
161
162 Adding Python to an iOS project
163 -------------------------------
164
165 Python can be added to any iOS project, using either Swift or Objective C. The
166 following examples will use Objective C; if you are using Swift, you may find a
167 library like `PythonKit <https://github.com/pvieito/PythonKit>`__ to be
168 helpful.
169
170 To add Python to an iOS Xcode project:
171
172 1. Build or obtain a Python ``XCFramework``. See the instructions in
173 :source:`Apple/iOS/README.md` (in the CPython source distribution) for details on
174 how to build a Python ``XCFramework``. At a minimum, you will need a build
175 that supports ``arm64-apple-ios``, plus one of either
176 ``arm64-apple-ios-simulator`` or ``x86_64-apple-ios-simulator``.
177
178 2. Drag the ``XCframework`` into your iOS project. In the following
179 instructions, we'll assume you've dropped the ``XCframework`` into the root
180 of your project; however, you can use any other location that you want by
181 adjusting paths as needed.
182
183 3. Add your application code as a folder in your Xcode project. In the
184 following instructions, we'll assume that your user code is in a folder
185 named ``app`` in the root of your project; you can use any other location by
186 adjusting paths as needed. Ensure that this folder is associated with your
187 app target.
188
189 4. Select the app target by selecting the root node of your Xcode project, then
190 the target name in the sidebar that appears.
191
192 5. In the "General" settings, under "Frameworks, Libraries and Embedded
193 Content", add ``Python.xcframework``, with "Embed & Sign" selected.
194
195 6. In the "Build Settings" tab, modify the following:
196
197 - Build Options
198
199 * User Script Sandboxing: No
200 * Enable Testability: Yes
201
202 - Search Paths
203
204 * Framework Search Paths: ``$(PROJECT_DIR)``
205 * Header Search Paths: ``"$(BUILT_PRODUCTS_DIR)/Python.framework/Headers"``
206
207 - Apple Clang - Warnings - All languages
208
209 * Quoted Include In Framework Header: No
210
211 7. Add a build step that processes the Python standard library, and your own
212 Python binary dependencies. In the "Build Phases" tab, add a new "Run
213 Script" build step *before* the "Embed Frameworks" step, but *after* the
214 "Copy Bundle Resources" step. Name the step "Process Python libraries",
215 disable the "Based on dependency analysis" checkbox, and set the script
216 content to:
217
218 .. code-block:: bash
219
220 set -e
221 source $PROJECT_DIR/Python.xcframework/build/build_utils.sh
222 install_python Python.xcframework app
223
224 If you have placed your XCframework somewhere other than the root of your
225 project, modify the path to the first argument.
226
227 8. Add Objective C code to initialize and use a Python interpreter in embedded
228 mode. You should ensure that:
229
230 * UTF-8 mode (:c:member:`PyPreConfig.utf8_mode`) is *enabled*;
231 * Buffered stdio (:c:member:`PyConfig.buffered_stdio`) is *disabled*;
232 * Writing bytecode (:c:member:`PyConfig.write_bytecode`) is *disabled*;
233 * Signal handlers (:c:member:`PyConfig.install_signal_handlers`) are *enabled*;
234 * System logging (:c:member:`PyConfig.use_system_logger`) is *enabled*
235 (optional, but strongly recommended; this is enabled by default);
236 * :envvar:`PYTHONHOME` for the interpreter is configured to point at the
237 ``python`` subfolder of your app's bundle; and
238 * The :envvar:`PYTHONPATH` for the interpreter includes:
239
240 - the ``python/lib/python3.X`` subfolder of your app's bundle,
241 - the ``python/lib/python3.X/lib-dynload`` subfolder of your app's bundle, and
242 - the ``app`` subfolder of your app's bundle
243
244 Your app's bundle location can be determined using ``[[NSBundle mainBundle]
245 resourcePath]``.
246
247 Steps 7 and 8 of these instructions assume that you have a single folder of
248 pure Python application code, named ``app``. If you have third-party binary
249 modules in your app, some additional steps will be required:
250
251 * You need to ensure that any folders containing third-party binaries are
252 either associated with the app target, or are explicitly copied as part of
253 step 7. Step 7 should also purge any binaries that are not appropriate for
254 the platform a specific build is targeting (i.e., delete any device binaries
255 if you're building an app targeting the simulator).
256
257 * If you're using a separate folder for third-party packages, ensure that
258 folder is added to the end of the call to ``install_python`` in step 7, and
259 as part of the :envvar:`PYTHONPATH` configuration in step 8.
260
261 * If any of the folders that contain third-party packages will contain ``.pth``
262 files, you should add that folder as a *site directory* (using
263 :meth:`site.addsitedir`), rather than adding to :envvar:`PYTHONPATH` or
264 :attr:`sys.path` directly.
265
266 Testing a Python package
267 ------------------------
268
269 The CPython source tree contains :source:`a testbed project <Apple/iOS/testbed>` that
270 is used to run the CPython test suite on the iOS simulator. This testbed can also
271 be used as a testbed project for running your Python library's test suite on iOS.
272
273 After building or obtaining an iOS XCFramework (see :source:`Apple/iOS/README.md`
274 for details), create a clone of the Python iOS testbed project. If you used the
275 ``Apple`` build script to build the XCframework, you can run:
276
277 .. code-block:: bash
278
279 $ python cross-build/iOS/testbed clone --app <path/to/module1> --app <path/to/module2> app-testbed
280
281 Or, if you've sourced your own XCframework, by running:
282
283 .. code-block:: bash
284
285 $ python Apple/testbed clone --platform iOS --framework <path/to/Python.xcframework> --app <path/to/module1> --app <path/to/module2> app-testbed
286
287 Any folders specified with the ``--app`` flag will be copied into the cloned
288 testbed project. The resulting testbed will be created in the ``app-testbed``
289 folder. In this example, the ``module1`` and ``module2`` would be importable
290 modules at runtime. If your project has additional dependencies, they can be
291 installed into the ``app-testbed/Testbed/app_packages`` folder (using ``pip
292 install --target app-testbed/Testbed/app_packages`` or similar).
293
294 You can then use the ``app-testbed`` folder to run the test suite for your app,
295 For example, if ``module1.tests`` was the entry point to your test suite, you
296 could run:
297
298 .. code-block:: bash
299
300 $ python app-testbed run -- module1.tests
301
302 This is the equivalent of running ``python -m module1.tests`` on a desktop
303 Python build. Any arguments after the ``--`` will be passed to the testbed as
304 if they were arguments to ``python -m`` on a desktop machine.
305
306 You can also open the testbed project in Xcode by running:
307
308 .. code-block:: bash
309
310 $ open app-testbed/iOSTestbed.xcodeproj
311
312 This will allow you to use the full Xcode suite of tools for debugging.
313
314 The arguments used to run the test suite are defined as part of the test plan.
315 To modify the test plan, select the test plan node of the project tree (it
316 should be the first child of the root node), and select the "Configurations"
317 tab. Modify the "Arguments Passed On Launch" value to change the testing
318 arguments.
319
320 The test plan also disables parallel testing, and specifies the use of the
321 ``Testbed.lldbinit`` file for providing configuration of the debugger. The
322 default debugger configuration disables automatic breakpoints on the
323 ``SIGINT``, ``SIGUSR1``, ``SIGUSR2``, and ``SIGXFSZ`` signals.
324
325 App Store Compliance
326 ====================
327
328 The only mechanism for distributing apps to third-party iOS devices is to
329 submit the app to the iOS App Store; apps submitted for distribution must pass
330 Apple's app review process. This process includes a set of automated validation
331 rules that inspect the submitted application bundle for problematic code. There
332 are some steps that must be taken to ensure that your app will be able to pass
333 these validation steps.
334
335 Incompatible code in the standard library
336 -----------------------------------------
337
338 The Python standard library contains some code that is known to violate these
339 automated rules. While these violations appear to be false positives, Apple's
340 review rules cannot be challenged; so, it is necessary to modify the Python
341 standard library for an app to pass App Store review.
342
343 The Python source tree contains
344 :source:`a patch file <Mac/Resources/app-store-compliance.patch>` that will remove
345 all code that is known to cause issues with the App Store review process. This
346 patch is applied automatically when building for iOS.
347
348 Privacy manifests
349 -----------------
350
351 In April 2025, Apple introduced a requirement for `certain third-party
352 libraries to provide a Privacy Manifest
353 <https://developer.apple.com/support/third-party-SDK-requirements>`__.
354 As a result, if you have a binary module that uses one of the affected
355 libraries, you must provide an ``.xcprivacy`` file for that library.
356 OpenSSL is one library affected by this requirement, but there are others.
357
358 If you produce a binary module named ``mymodule.so``, and use you the Xcode
359 build script described in step 7 above, you can place a ``mymodule.xcprivacy``
360 file next to ``mymodule.so``, and the privacy manifest will be installed into
361 the required location when the binary module is converted into a framework.