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

Unified 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 side-by-side diff with in-line comments
Download patch
« no previous file with comments | « configure.ac ('k') | iOS/XCode-sample/app_packages/README » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/iOS/README Wed Mar 02 00:01:35 2016 +0000
@@ -0,0 +1,165 @@
+====================
+Python on iOS README
+====================
+
+:Authors:
+ Russell Keith-Magee (2015)
+
+:Version: 3.4.2
+
+This document provides a overview of eccentricities of building and using
+Python on iOS.
+
+Build instructions
+==================
+
+The iOS build must be run on an Mac with XCode installed. To build the iOS
+framework, unpack the Python sources, move into the iOS subdirectory, and
+run ``make``. There are no configuration options to this build process -
+it will use XCode utilities to identify the location of compilers,
+resource directories, and so on.
+
+The build process will configure and build Python 6 times, producing:
+
+ * A "host" version of Python
+ * A version of Python compiled for the x86-64 iOS Simulator
+ * A version of Python compiled for the i386 iOS Simulator
+ * A version of Python compiled for ARM64 iOS devices
+ * A version of Python compiled for ARMv7s iOS devices
+ * A version of Python compiled for ARMv7 iOS devices
+
+Build products will be "installed" into iOS/build. The built products will
+then be combined into a single "fat" ``Python.framework`` that can be added to
+an XCode project. The resulting framework will be located in the root
+directory of the Python source tree.
+
+A ``make clean`` target also exists to clean out all build products;
+``make distclean`` will clean out all user-specific files from the test and
+sample projects.
+
+Test instructions
+-----------------
+
+The ``Tools`` directory contains an ``iOS-Test`` project that enables you to
+run the Python regression test suite. When you run ``make`` in the iOS
+directory, a copy of ``Python.framework`` will also be installed into this
+test project.
+
+To run the test project, load the project into XCode, and run (either on a
+device or in the simulator). The test suite takes around 20 minutes to run on
+an iPhone5S.
+
+.. note:: If you run the test project in debug mode, the XCode debugger will
+ stop whenever a signal is raised. The Python regression test suite checks
+ a number of signal handlers, and the test suite will stop mid-execution
+ when this occurs.
+
+ To disable this signal handling, set a breakpoint at the start of
+ ``main.c``; when execution stops at the breakpoint, run the following
+ commands in the debugger (at the ``(lldb)`` prompt in the console log
+ window)::
+
+ process handle SIGPIPE -n true -p true -s false
+ process handle SIGINT -n true -p true -s false
+ process handle SIGXFSZ -n true -p true -s false
+ process handle SIGUSR1 -n true -p true -s false
+ process handle SIGUSR2 -n true -p true -s false
+
+ Unfortunately, this has to be done every time the test suite is executed.
+
+iOS-specific details
+====================
+
+* ``import sys; sys.platform`` will report as "ios", regardless of whether you
+ are on a simulator or a real platform.
+
+* ``import platform; platform.machine()`` will return the device identifier.
+ For example, an iPhone 5S will return "iPhone6,2"
+
+* The following modules are not currently supported:
+
+ - ``bsddb``
+ - ``bz2``
+ - ``curses``
+ - ``dbm``
+ - ``gdbm``
+ - ``hotshot``
+ - ``idlelib``
+ - ``lzma``
+ - ``nis``
+ - ``ossaudiodev``
+ - ``readline``
+ - ``spwd``
+ - ``sqlite3``
+ - ``ssl``
+ - ``tkinter``
+ - ``turtledemo``
+ - ``wsgiref``
+
+* Due to limitations in using dynamic loading on iOS, binary Python modules must be
+ statically-linked into the executable. The framework package produced by the iOS
+ ``make install`` statically links all the supported standard library modules.
+ If you have a third-party Python binary module, you'll need to incorporate the
+ source files for that module into the sources for your own app.
+
+ If you want to add or remove a binary module from the set that is included in the
+ Python library, you can do so by providing module setup files for each platform.
+ There are three default module configuration files:
+
+ - ``Modules/Setup.ios-aarch64`` for ARM64 iOS builds
+ - ``Modules/Setup.ios-arm`` for ARMv7 iOS builds
+ - ``Modules/Setup.ios-x86_64`` for x86_64 iOS simulator builds
+
+ If you copy these files to a ``.local`` version (e.g.,
+ ``Modules/Setup.ios-aarch64.local``), the local version will override the
+ default. You can then make modifications to the modules that will be included
+ in the iOS framework, and the flags passed to the compiler when compiling those
+ modules.
+
+Adding Python to an iOS project
+===============================
+
+The iOS subdirectory contains a sample XCode 6.1 project to demonstrate how
+Python can be added to an iOS project. After building the Python iOS framework,
+copy it into the ``iOS/XCode-sample`` directory. You should end up with a directory
+structure that looks like this::
+
+ XCode-sample/
+ Python.framework/ - Manually copied into the project
+ app/
+ sample/
+ __init__.py
+ main.py - The Python script to be executed
+ app_packages/ - A directory that will be added to the `PYTHONPATH` at runtime
+ sample
+ Images.xcassets
+ en.lproj
+ main.c - The main() definition for the iOS application
+ sample-Info.plist
+ sample-Prefix.pch
+ sample.xcodeproj - The XCode project file
+
+If you open the project file is project and run it, you should get output
+similar to the following::
+
+ 2015-03-14 22:15:19.595 sample[84454:22100187] PythonHome is: /Users/rkm/Library/Developer/CoreSimulator/Devices/19FE988F-E5C3-4A6C-8752-C12DE9BF079D/data/Containers/Bundle/Application/A949B323-FD20-4C76-B370-99AFF294E9D5/sample.app
+ 2015-03-14 22:15:19.597 sample[84454:22100187] Initializing Python runtime
+ 2015-03-14 22:15:19.758 sample[84454:22100187] Running /Users/rkm/Library/Developer/CoreSimulator/Devices/19FE988F-E5C3-4A6C-8752-C12DE9BF079D/data/Containers/Bundle/Application/A949B323-FD20-4C76-B370-99AFF294E9D5/sample.app/app/sample/main.py
+ Hello, World.
+ 2015-03-14 22:15:19.792 sample[84454:22100187] Leaving
+
+You can now modify the provide Python source code, import and use
+code from the Python standard library, and add third-party modules to
+app_packages.
+
+The sample app is a console-only app, so it isn't of any real practical use.
+Python can be embedded into any Objective-C project using the normal Python
+APIs for embedding; but if you want to write a full iOS app in Python, or
+you want to access iOS services from within embedded code, you'll need to
+bridge between the Objective-C environment and the Python environment.
+This binding isn't something that Python does out of the box; you'll need
+to use a third-party library like `Rubicon ObjC`_, `Pyobjus`_ or `PyObjC`_.
+
+.. _Rubicon ObjC: http://pybee.org/rubicon
+.. _Pyobjus: http://pyobjus.readthedocs.org/
+.. _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+