.. _packaging_android: Create a package for Android ============================ You can create a package for android using the `python-for-android `_ project. This page explains how to download and use it directly on your own machine (see :ref:`Packaging your application into APK`), use the prebuilt :ref:`testdrive` virtual machine image, or use the :ref:`buildozer` tool to automate the entire process. You can also see :ref:`Packaging your application for Kivy Launcher` to run kivy programs without compiling them. .. _Packaging your application into APK: Packaging your application into an APK -------------------------------------- This section describes how to download and use python-for-android directly. You'll need: - A linux computer or virtual machine - Java - Python 2.7 (not 2.6.) - Jinja2 (python module) - Apache ant - Android SDK Setup Python for Android ~~~~~~~~~~~~~~~~~~~~~~~~ First, install the prerequisites needed for the project: http://python-for-android.readthedocs.org/en/latest/prerequisites/ Then open a console and type:: git clone git://github.com/kivy/python-for-android Build your distribution ~~~~~~~~~~~~~~~~~~~~~~~ The distribution is a "directory" containing a specialized python compiled for Android, including only the modules you asked for. You can, from the same python-for-android, compile multiple distributions. For example: - One containing a minimal support without audio / video - Another containing audio, openssl etc. To do that, you must use the script named `distribute.sh`:: ./distribute.sh -m "kivy" The result of the compilation will be saved into `dist/default`. Here are other examples of building distributions:: ./distribute.sh -m "openssl kivy" ./distribute.sh -m "pil ffmpeg kivy" .. note:: The order of modules provided are important, as a general rule put dependencies first and then the dependent modules, C libs come first then python modules. To see the available options for distribute.sh, type:: ./distribute.sh -h .. note:: To use the latest Kivy development version to build your distribution, link "P4A_kivy_DIR" to the kivy folder environment variable to the kivy folder location. On linux you would use the export command, like this:: export P4A_kivy_DIR=/path/to/cloned/kivy/ Package your application ~~~~~~~~~~~~~~~~~~~~~~~~ Inside the distribution (`dist/default` by default), you have a tool named `build.py`. This is the script that will create the APK for you:: ./build.py --dir --name "" --package <org.of.your.app> --version <human version> --icon <path to an icon to use> --orientation <landscape|portrait> --permission <android permission like VIBRATE> (multiple allowed) <debug|release> <installd|installr|...> An example of using multiple permissions:: --permission INTERNET --permission WRITE_EXTERNAL_STORAGE Full list of available permissions are documented here: http://developer.android.com/reference/android/Manifest.permission.html For example, if we imagine that the touchtracer demo of Kivy is in the directory ~/kivy/examples/demo/touchtracer, you can do:: ./build.py --dir ~/kivy/examples/demo/touchtracer \ --package org.demo.touchtracer \ --name "Kivy Touchtracer" --version 1.1.0 debug installd You need to be aware that the default target Android SDK version for the build will be SDK v.8, which is the minimum required SDK version for kivy. You should either install this API version, or change the AndroidManifest.xml file (under dist/.../) to match your own target SDK requirements. The debug binary will be generated in bin/KivyTouchtracer-1.1.0-debug.apk. The `debug` and `installd` parameters are commands from the Android project itself. They instruct `build.py` to compile the APK in debug mode and install on the first connected device. You can then install the APK directly to your Android device as follows:: adb install -r bin/KivyTouchtracer-1.1.0-debug.apk Release on the market ~~~~~~~~~~~~~~~~~~~~~ Launch the build.py script again, with the `release` parameter. After buiding it, you must sign and zipalign the APK. Read the android documentation at: http://developer.android.com/guide/publishing/app-signing.html The release binary will be generated in bin/KivyTouchtracer-1.1.0-release-unsigned.apk (for the previous touchtracer example.) .. _testdrive: TestDrive --------- We provide a VirtualBox Image with python-for-android along with the Android SDK and NDK preinstalled to ease your installation woes. You can download it from `here <http://kivy.org/#download>`_. Once the VM is loaded, you can follow the instructions from :ref:`Packaging your application into APK`. You don't need to download with `git clone` though, as python-for-android is already installed and set up in the virtual machine home directory. .. _Buildozer: Buildozer --------- Buildozer is a tool that automates the entire build process. It downloads and sets up all the prequisites for python-for-android, including the android SDK and NDK, then builds an apk that can be automatically pushed to the device. Buildozer currently works only in Linux, and is an alpha release, but it already works well and can significantly simplify the apk build. You can get buildozer at `<https://github.com/kivy/buildozer>`_:: git clone https://github.com/kivy/buildozer.git cd buildozer sudo python2.7 setup.py install This will install buildozer in your system. Afterwards, navigate to your project directory and run:: buildozer init This creates a `buildozer.spec` file controlling your build configuration. You should edit it appropriately with your app name etc. You can set variables to control most or all of the parameters passed to python-for-android. Afterwards, plug in your android device and run:: buildozer android debug deploy run to build, push and automatically run the apk on your device. You can check the buildozer README at `<https://github.com/kivy/buildozer>`_ for more documentation of buildozer's capabilities. .. _Packaging your application for Kivy Launcher: Packaging your application for the Kivy Launcher ------------------------------------------------ The `Kivy launcher <https://play.google.com/store/apps/details?id=org.kivy.pygame&hl=en>`_ is an Android application that runs any Kivy examples stored on your SD Card. See :ref:`androidinstall`. Your application must be saved into:: /sdcard/kivy/<yourapplication> Your application directory must contain:: # Your main application file: main.py # Some info Kivy requires about your app on android: android.txt The file `android.txt` must contain:: title=<Application Title> author=<Your Name> orientation=<portrait|landscape>