Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in

Side by Side Diff: iOS/README

Issue 23670: Modifications to support iOS as a development platform
Patch Set: Created 3 years, 8 months ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « configure.ac ('k') | iOS/XCode-sample/app_packages/README » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
1 ====================
2 Python on iOS README
3 ====================
5 :Authors:
6 Russell Keith-Magee (2015)
8 :Version: 3.4.2
10 This document provides a overview of eccentricities of building and using
11 Python on iOS.
13 Build instructions
14 ==================
16 The iOS build must be run on an Mac with XCode installed. To build the iOS
17 framework, unpack the Python sources, move into the iOS subdirectory, and
18 run ``make``. There are no configuration options to this build process -
19 it will use XCode utilities to identify the location of compilers,
20 resource directories, and so on.
22 The build process will configure and build Python 6 times, producing:
24 * A "host" version of Python
25 * A version of Python compiled for the x86-64 iOS Simulator
26 * A version of Python compiled for the i386 iOS Simulator
27 * A version of Python compiled for ARM64 iOS devices
28 * A version of Python compiled for ARMv7s iOS devices
29 * A version of Python compiled for ARMv7 iOS devices
31 Build products will be "installed" into iOS/build. The built products will
32 then be combined into a single "fat" ``Python.framework`` that can be added to
33 an XCode project. The resulting framework will be located in the root
34 directory of the Python source tree.
36 A ``make clean`` target also exists to clean out all build products;
37 ``make distclean`` will clean out all user-specific files from the test and
38 sample projects.
40 Test instructions
41 -----------------
43 The ``Tools`` directory contains an ``iOS-Test`` project that enables you to
44 run the Python regression test suite. When you run ``make`` in the iOS
45 directory, a copy of ``Python.framework`` will also be installed into this
46 test project.
48 To run the test project, load the project into XCode, and run (either on a
49 device or in the simulator). The test suite takes around 20 minutes to run on
50 an iPhone5S.
52 .. note:: If you run the test project in debug mode, the XCode debugger will
53 stop whenever a signal is raised. The Python regression test suite checks
54 a number of signal handlers, and the test suite will stop mid-execution
55 when this occurs.
57 To disable this signal handling, set a breakpoint at the start of
58 ``main.c``; when execution stops at the breakpoint, run the following
59 commands in the debugger (at the ``(lldb)`` prompt in the console log
60 window)::
62 process handle SIGPIPE -n true -p true -s false
63 process handle SIGINT -n true -p true -s false
64 process handle SIGXFSZ -n true -p true -s false
65 process handle SIGUSR1 -n true -p true -s false
66 process handle SIGUSR2 -n true -p true -s false
68 Unfortunately, this has to be done every time the test suite is executed.
70 iOS-specific details
71 ====================
73 * ``import sys; sys.platform`` will report as "ios", regardless of whether you
74 are on a simulator or a real platform.
76 * ``import platform; platform.machine()`` will return the device identifier.
77 For example, an iPhone 5S will return "iPhone6,2"
79 * The following modules are not currently supported:
81 - ``bsddb``
82 - ``bz2``
83 - ``curses``
84 - ``dbm``
85 - ``gdbm``
86 - ``hotshot``
87 - ``idlelib``
88 - ``lzma``
89 - ``nis``
90 - ``ossaudiodev``
91 - ``readline``
92 - ``spwd``
93 - ``sqlite3``
94 - ``ssl``
95 - ``tkinter``
96 - ``turtledemo``
97 - ``wsgiref``
99 * Due to limitations in using dynamic loading on iOS, binary Python modules must be
100 statically-linked into the executable. The framework package produced by the i OS
101 ``make install`` statically links all the supported standard library modules.
102 If you have a third-party Python binary module, you'll need to incorporate the
103 source files for that module into the sources for your own app.
105 If you want to add or remove a binary module from the set that is included in the
106 Python library, you can do so by providing module setup files for each platfor m.
107 There are three default module configuration files:
109 - ``Modules/Setup.ios-aarch64`` for ARM64 iOS builds
110 - ``Modules/Setup.ios-arm`` for ARMv7 iOS builds
111 - ``Modules/Setup.ios-x86_64`` for x86_64 iOS simulator builds
113 If you copy these files to a ``.local`` version (e.g.,
114 ``Modules/Setup.ios-aarch64.local``), the local version will override the
115 default. You can then make modifications to the modules that will be included
116 in the iOS framework, and the flags passed to the compiler when compiling thos e
117 modules.
119 Adding Python to an iOS project
120 ===============================
122 The iOS subdirectory contains a sample XCode 6.1 project to demonstrate how
123 Python can be added to an iOS project. After building the Python iOS framework,
124 copy it into the ``iOS/XCode-sample`` directory. You should end up with a direct ory
125 structure that looks like this::
127 XCode-sample/
128 Python.framework/ - Manually copied into the project
129 app/
130 sample/
131 __init__.py
132 main.py - The Python script to be executed
133 app_packages/ - A directory that will be added to the `PYTHONP ATH` at runtime
134 sample
135 Images.xcassets
136 en.lproj
137 main.c - The main() definition for the iOS application
138 sample-Info.plist
139 sample-Prefix.pch
140 sample.xcodeproj - The XCode project file
142 If you open the project file is project and run it, you should get output
143 similar to the following::
145 2015-03-14 22:15:19.595 sample[84454:22100187] PythonHome is: /Users/rkm/Lib rary/Developer/CoreSimulator/Devices/19FE988F-E5C3-4A6C-8752-C12DE9BF079D/data/C ontainers/Bundle/Application/A949B323-FD20-4C76-B370-99AFF294E9D5/sample.app
146 2015-03-14 22:15:19.597 sample[84454:22100187] Initializing Python runtime
147 2015-03-14 22:15:19.758 sample[84454:22100187] Running /Users/rkm/Library/De veloper/CoreSimulator/Devices/19FE988F-E5C3-4A6C-8752-C12DE9BF079D/data/Containe rs/Bundle/Application/A949B323-FD20-4C76-B370-99AFF294E9D5/sample.app/app/sample /main.py
148 Hello, World.
149 2015-03-14 22:15:19.792 sample[84454:22100187] Leaving
151 You can now modify the provide Python source code, import and use
152 code from the Python standard library, and add third-party modules to
153 app_packages.
155 The sample app is a console-only app, so it isn't of any real practical use.
156 Python can be embedded into any Objective-C project using the normal Python
157 APIs for embedding; but if you want to write a full iOS app in Python, or
158 you want to access iOS services from within embedded code, you'll need to
159 bridge between the Objective-C environment and the Python environment.
160 This binding isn't something that Python does out of the box; you'll need
161 to use a third-party library like `Rubicon ObjC`_, `Pyobjus`_ or `PyObjC`_.
163 .. _Rubicon ObjC: http://pybee.org/rubicon
164 .. _Pyobjus: http://pyobjus.readthedocs.org/
165 .. _PyObjC: https://pythonhosted.org/pyobjc/
« no previous file with comments | « configure.ac ('k') | iOS/XCode-sample/app_packages/README » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+