Toolchain¶

Introduction¶

In terms of comparaison, you can check how Python for android can be useful compared to other projects.

Project	Native Python	GUI libraries	APK generation	Custom build
Python for android	Yes	Yes	Yes	Yes
PGS4A	Yes	Yes	Yes	No
Android scripting	No	No	No	No
Python on a chip	No	No	No	No

Note

For the moment, we are shipping only one “java bootstrap” (needed for decompressing your packaged zip file project, create an OpenGL ES 2.0 surface, handle touch input and manage an audio thread).

If you want to use it without kivy module (an opengl es 2.0 ui toolkit), then you might want a lighter java bootstrap, that we don’t have right now. Help is welcome :)

So for the moment, Python for Android can only be used with the kivy GUI toolkit: http://kivy.org/#home

How does it work ?¶

To be able to run Python on android, you need to compile it for android. And you need to compile all the libraries you want for android too. Since Python is a language, not a toolkit, you cannot draw any user interface with it: you need to use a toolkit for it. Kivy can be one of them.

So for a simple ui project, the first step is to compile Python + Kivy + all others libraries. Then you’ll have what we call a “distribution”. A distribution is composed of:

Python
Python libraries
All selected libraries (kivy, pygame, pil...)
A java bootstrap
A build script

You’ll use the build script for create an “apk”: an android package.

Prerequisites¶

Note

There is a VirtualBox Image we provide with the prerequisites along with the Android SDK and NDK preinstalled to ease your installation woes. You can download it from here.

Warning

The current version is tested only on Ubuntu oneiric (11.10) and precise (12.04). If it doesn’t work on other platforms, send us a patch, not a bug report. Python for Android works on Linux and Mac OS X, not Windows.

You need the minimal environment for building python. Note that other libraries might need other tools (cython is used by some recipes, and ccache to speedup the build):

sudo apt-get install build-essential patch git-core ccache ant python-pip python-dev

If you are on a 64 bit distro, you should install these packages too :

sudo apt-get install ia32-libs  libc6-dev-i386

On debian Squeeze amd64, those packages were found to be necessary :

sudo apt-get install lib32stdc++6 lib32z1

Ensure you have the latest Cython version:

pip install --upgrade cython

You must have android SDK and NDK. The SDK defines the Android functions you can use. The NDK is used for compilation. Right now, it’s preferred to use:

SDK API 8 or 14 (15 will only work with a newly released NDK)
NDK r5b or r7

You can download them at:

http://developer.android.com/sdk/index.html
http://developer.android.com/sdk/ndk/index.html

In general, Python for Android currently works with Android 2.3 to L.

If it’s your very first time using the Android SDK, don’t forget to follow the documentation for recommended components at:

http://developer.android.com/sdk/installing/adding-packages.html

    You need to download at least one platform into your environment, so
    that you will be able to compile your application and set up an Android
    Virtual Device (AVD) to run it on (in the emulator). To start with,
    just download the latest version of the platform. Later, if you plan to
    publish your application, you will want to download other platforms as
    well, so that you can test your application on the full range of
    Android platform versions that your application supports.

After installing them, export both installation paths, NDK version, and API to use:

export ANDROIDSDK=/path/to/android-sdk
export ANDROIDNDK=/path/to/android-ndk
export ANDROIDNDKVER=rX
export ANDROIDAPI=X

# example
export ANDROIDSDK="/home/tito/code/android/android-sdk-linux_86"
export ANDROIDNDK="/home/tito/code/android/android-ndk-r7"
export ANDROIDNDKVER=r7
export ANDROIDAPI=14

Also, you must configure your PATH to add the android binary:

export PATH=$ANDROIDNDK:$ANDROIDSDK/platform-tools:$ANDROIDSDK/tools:$PATH

Usage¶

Step 1: compile the toolchain¶

If you want to compile the toolchain with only the kivy module:

./distribute.sh -m "kivy"

Warning

Do not run the above command from within a virtual enviroment.

After a long time, you’ll get a “dist/default” directory containing all the compiled libraries and a build.py script to package your application using thoses libraries.

You can include other modules (or “recipes”) to compile using -m:

./distribute.sh -m "openssl kivy"
./distribute.sh -m "pil ffmpeg kivy"

Note

Recipes are instructions for compiling Python modules that require C extensions. The list of recipes we currently have is at: https://github.com/kivy/python-for-android/tree/master/recipes

You can also specify a specific version for each package. Please note that the compilation might break if you don’t use the default version. Most recipes have patches to fix Android issues, and might not apply if you specify a version. We also recommend to clean build before changing version.:

./distribute.sh -m "openssl kivy==master"

Python modules that don’t need C extensions don’t need a recipe and can be included this way. From python-for-android 1.1 on, you can now specify pure-python package into the distribution. It will use virtualenv and pip to install pure-python modules into the distribution. Please note that the compiler is deactivated, and will break any module which tries to compile something. If compilation is needed, write a recipe:

./distribute.sh -m "requests pygments kivy"

Note

Recipes download a defined version of their needed package from the internet, and build from it. If you know what you are doing, and want to override that, you can export the env variable P4A_recipe_name_DIR and this directory will be copied and used instead.

Available options to distribute.sh:

-d directory           Name of the distribution directory
-h                     Show this help
-l                     Show a list of available modules
-m 'mod1 mod2'         Modules to include
-f                     Restart from scratch (remove the current build)
-u 'mod1 mod2'         Modules to update (if already compiled)

Step 2: package your application¶

Go to your custom Python distribution:

cd dist/default

Use the build.py for creating the APK:

./build.py --package org.test.touchtracer --name touchtracer \
--version 1.0 --dir ~/code/kivy/examples/demo/touchtracer debug

Then, the Android package (APK) will be generated at:

bin/touchtracer-1.0-debug.apk

Warning

Some files and modules for python are blacklisted by default to save a few megabytes on the final APK file. In case your applications doesn’t find a standard python module, check the src/blacklist.txt file, remove the module you need from the list, and try again.

Available options to build.py:

-h, --help            show this help message and exit
--package PACKAGE     The name of the java package the project will be
                      packaged under.
--name NAME           The human-readable name of the project.
--version VERSION     The version number of the project. This should consist
                      of numbers and dots, and should have the same number
                      of groups of numbers as previous versions.
--numeric-version NUMERIC_VERSION
                      The numeric version number of the project. If not
                      given, this is automatically computed from the
                      version.
--dir DIR             The directory containing public files for the project.
--private PRIVATE     The directory containing additional private files for
                      the project.
--launcher            Provide this argument to build a multi-app launcher,
                      rather than a single app.
--icon-name ICON_NAME
                      The name of the project's launcher icon.
--orientation ORIENTATION
                      The orientation that the game will display in. Usually
                      one of "landscape", "portrait" or "sensor".
--permission PERMISSIONS
                      The permissions to give this app.
--ignore-path IGNORE_PATH
                      Ignore path when building the app
--icon ICON           A png file to use as the icon for the application.
--presplash PRESPLASH
                      A jpeg file to use as a screen while the application
                      is loading.
--install-location INSTALL_LOCATION
                      The default install location. Should be "auto",
                      "preferExternal" or "internalOnly".
--compile-pyo         Compile all .py files to .pyo, and only distribute the
                      compiled bytecode.
--intent-filters INTENT_FILTERS
                      Add intent-filters xml rules to AndroidManifest.xml
--blacklist BLACKLIST
                      Use a blacklist file to match unwanted file in the
                      final APK
--sdk SDK_VERSION     Android SDK version to use. Default to 8
--minsdk MIN_SDK_VERSION
                      Minimum Android SDK version to use. Default to 8
--window              Indicate if the application will be windowed

Meta-data¶

New in version 1.3.

You can extend the AndroidManifest.xml with application meta-data. If you are using external toolkits like Google Maps, you might want to set your API key in the meta-data. You could do it like this:

./build.py ... --meta-data com.google.android.maps.v2.API_KEY=YOURAPIKEY

Some meta-data can be used to interact with the behavior of our internal component.

Token	Description
surface.transparent	If set to 1, the created surface will be transparent (can be used to add background Android widget in the background, or use accelerated widgets)
surface.depth	Size of the depth component, default to 0. 0 means automatic, but you can force it to a specific value. Be warned, some old phone might not support the depth you want.
surface.stencil	Size of the stencil component, default to 8.
android.background_color	Color (32bits RGBA color), used for the background window. Usually, the background is covered by the OpenGL Background, unless surface.transparent is set.

Customize your distribution¶

The basic layout of a distribution is:

AndroidManifest.xml     - (*) android manifest (generated from templates)
assets/
    private.mp3         - (*) fake package that will contain all the python installation
    public.mp3          - (*) fake package that will contain your application
bin/                    - contain all the apk generated from build.py
blacklist.txt           - list of file patterns to not include in the APK
buildlib/               - internals libraries for build.py
build.py                - build script to use for packaging your application
build.xml               - (*) build settings (generated from templates)
default.properties      - settings generated from your distribute.sh
libs/                   - contain all the compiled libraries
local.properties        - settings generated from your distribute.sh
private/                - private directory containing all the python files
    lib/                  this is where you can remove or add python libs.
        python2.7/        by default, some modules are already removed (tests, idlelib, ...)
project.properties      - settings generated from your distribute.sh
python-install/         - the whole python installation, generated from distribute.sh
                          not included in the final package.
res/                    - (*) android resource (generated from build.py)
src/                    - Java bootstrap
templates/              - Templates used by build.py

(*): Theses files are automatically generated from build.py, don't change them directly !