Getting Started
===============

Getting up and running on python-for-android (p4a) is a simple process
and should only take you a couple of minutes. We'll refer to Python
for android as p4a in this documentation.

Concepts
--------

*Basic:*

- **requirements:** For p4a, all your app's dependencies must be specified
  via ``--requirements`` similar to the standard `requirements.txt`.
  (Unless you specify them via a `setup.py`/`install_requires`)
  All dependencies will be mapped to "recipes" if any exist, so that
  many common libraries will just work. See "recipe" below for details.

- **distribution:** A distribution is the final "build" of your
  compiled project + requirements, as an Android project assembled by
  p4a that can be turned directly into an APK. p4a can contain multiple
  distributions with different sets of requirements.

- **build:** A build refers to a compiled recipe or distribution.

- **bootstrap:** A bootstrap is the app backend that will start your
  application. The default for graphical applications is SDL2.
  You can also use e.g. the webview for web apps, or service_only for
  background services. Different bootstraps have different additional
  build options.

*Advanced:*

- **recipe:**
  A recipe is a file telling p4a how to install a requirement
  that isn't by default fully Android compatible.
  This is often necessary for Cython or C/C++-using python extensions.
  p4a has recipes for many common libraries already included, and any
  dependency you specified will be automatically mapped to its recipe.
  If a dependency doesn't work and has no recipe included in p4a,
  then it may need one to work.


Installation
------------

Installing p4a
~~~~~~~~~~~~~~

p4a is now available on Pypi, so you can install it using pip::

    pip install python-for-android

You can also test the master branch from Github using::

    pip install git+https://github.com/kivy/python-for-android.git

Installing Dependencies
~~~~~~~~~~~~~~~~~~~~~~~

p4a has several dependencies that must be installed:

- git
- ant
- python2
- cython (can be installed via pip)
- a Java JDK (e.g. openjdk-8)
- zlib (including 32 bit)
- libncurses (including 32 bit)
- unzip
- virtualenv (can be installed via pip)
- ccache (optional)
- autoconf (for ffpyplayer_codecs recipe)
- libtool (for ffpyplayer_codecs recipe)
- cmake (required for some native code recipes like jpeg's recipe)

On recent versions of Ubuntu and its derivatives you may be able to
install most of these with::

    sudo dpkg --add-architecture i386
    sudo apt-get update
    sudo apt-get install -y build-essential ccache git zlib1g-dev python2.7 python2.7-dev libncurses5:i386 libstdc++6:i386 zlib1g:i386 openjdk-8-jdk unzip ant ccache autoconf libtool

On Arch Linux (64 bit) you should be able to run the following to
install most of the dependencies (note: this list may not be
complete). gcc-multilib will conflict with (and replace) gcc if not
already installed::

    sudo pacman -S jdk7-openjdk python2 python2-pip python2-kivy mesa-libgl lib32-mesa-libgl lib32-sdl2 lib32-sdl2_image lib32-sdl2_mixer sdl2_ttf unzip gcc-multilib gcc-libs-multilib

Installing Android SDK
~~~~~~~~~~~~~~~~~~~~~~

.. warning::
   python-for-android is often picky about the **SDK/NDK versions.**
   Pick the recommended ones from below to avoid problems.

Basic SDK install
`````````````````

You need to download and unpack the Android SDK and NDK to a directory (let's say $HOME/Documents/):

- `Android SDK <https://developer.android.com/studio/index.html>`_
- `Android NDK <https://developer.android.com/ndk/downloads/index.html>`_

For the Android SDK, you can download 'just the command line
tools'. When you have extracted these you'll see only a directory
named ``tools``, and you will need to run extra commands to install
the SDK packages needed. 

For Android NDK, note that modern releases will only work on a 64-bit
operating system. **The minimal, and recommended, NDK version to use is r17c:**

 - `Go to ndk downloads page <https://developer.android.com/ndk/downloads/>`_
 - Windows users should create a virtual machine with an GNU Linux os
   installed, and then you can follow the described instructions from within
   your virtual machine.


Platform and build tools
````````````````````````

First, install an API platform to targ