Contents:

.. toctree::

:maxdepth: 2

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 all the files of your 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 :)

Prerequisites

.. warning::

The current version is tested only on Ubuntu oneiric (11.10). If it doesn't

work on another platform, send us patch, not bug report.

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)::

You must have android SDK and NDK. You can download them at::

If it's your very first time into android SDK, don't forget to follow

documentation for recommended components at::

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

Usage

Step 1: compile the toolchain

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

After a long time, you'll get a "dist/default" directory containing all the compiled

libraries and build.py script to package your application using thoses

libraries.

You can include other libraries to compile using `-m`::

Available options to `distribute.sh`::

Step 2: package your application

Go fo your custom python distribution::

Use the build.py for creating the APK::

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

bin/touchtracer-1.0-debug.apk

Available options to `build.py`::

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

Customize your distribution

The basic layout of a distribution is::

Available modules

List of available modules: jpeg pil png sdl sqlite3 pygame kivy android

libxml2 libxslt lxml ffmpeg openssl chipmunk

The up-to-date list is available at:

https://github.com/kivy/python-for-android/tree/master/recipes

Only hostpython and python are 2 mandatory recipes, used for building

hostpython / target python libraries.

Create your own recipes

A recipe is a script that contain the "definition" of a module to compile.

The directory layout of a recipe for a <modulename> is something like::

When building, all the recipe build must go to::

For example, if you want to create a recipe for sdl, do::

Then, edit the sdl/recipe.sh to adjust other information (version, url) and

complete build function.

Related project

- PGS4A: http://pygame.renpy.org/

- Android scripting: http://code.google.com/p/android-scripting/

- Python on a chip: http://code.google.com/p/python-on-a-chip/

TODO

- jni/Android.mk must not include ttf/image/mixer if not asked by the user

- Python try always to import name.so, namemodule.so, name.py, name.pyo ?

- restore libpymodules.so loading to reduce the number of dlopen.