255 lines
8.1 KiB
ReStructuredText
255 lines
8.1 KiB
ReStructuredText
|
|
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
|
|
--------
|
|
|
|
- requirements: For p4a, your applications dependencies are
|
|
requirements similar to the standard `requirements.txt`, but with
|
|
one difference: p4a will search for a recipe first instead of
|
|
installing requirements with pip.
|
|
|
|
- recipe: A recipe is a file that defines how to compile a
|
|
requirement. Any libraries that have a Python extension *must* have
|
|
a recipe in p4a, or compilation will fail. If there is no recipe for
|
|
a requirement, it will be downloaded using pip.
|
|
|
|
- build: A build refers to a compiled recipe.
|
|
|
|
- distribution: A distribution is the final "build" of all your
|
|
compiled requirements, as an Android project that can be turned
|
|
directly into an APK. p4a can contain multiple distributions with
|
|
different sets of requirements.
|
|
|
|
- bootstrap: A bootstrap is the app backend that will start your
|
|
application. Your application could use SDL2 as a base, or Pygame,
|
|
or a web backend like Flask with a WebView bootstrap. Different
|
|
bootstraps can have different build options.
|
|
|
|
|
|
Installation
|
|
------------
|
|
|
|
Installing p4a
|
|
~~~~~~~~~~~~~~
|
|
|
|
p4a is now available on 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-7)
|
|
- 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)
|
|
|
|
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-7-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. If your installation is already 32-bit, install the
|
|
same packages but without ``lib32-`` or ``-multilib``::
|
|
|
|
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
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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/sdk/index.html#Other>`_
|
|
- `Android NDK <https://developer.android.com/ndk/downloads/index.html>`_
|
|
|
|
Then, you can edit your ``~/.bashrc`` or other favorite shell to include new environment variables necessary for building on android::
|
|
|
|
# Adjust the paths!
|
|
export ANDROIDSDK="$HOME/Documents/android-sdk-21"
|
|
export ANDROIDNDK="$HOME/Documents/android-ndk-r10e"
|
|
export ANDROIDAPI="14" # Minimum API version your application require
|
|
export ANDROIDNDKVER="r10e" # Version of the NDK you installed
|
|
|
|
You have the possibility to configure on any command the PATH to the SDK, NDK and Android API using:
|
|
|
|
- :code:`--sdk_dir PATH` as an equivalent of `$ANDROIDSDK`
|
|
- :code:`--ndk_dir PATH` as an equivalent of `$ANDROIDNDK`
|
|
- :code:`--android_api VERSION` as an equivalent of `$ANDROIDAPI`
|
|
- :code:`--ndk_ver PATH` as an equivalent of `$ANDROIDNDKVER`
|
|
|
|
|
|
Usage
|
|
-----
|
|
|
|
Build a Kivy application
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To build your application, you need to have a name, version, a package
|
|
identifier, and explicitly write the bootstrap you want to use, as
|
|
well as the requirements::
|
|
|
|
p4a apk --private $HOME/code/myapp --package=org.example.myapp --name "My application" --version 0.1 --bootstrap=sdl2 --requirements=python2,kivy
|
|
|
|
This will first build a distribution that contains `python2` and `kivy`, and using a SDL2 bootstrap. Python2 is here explicitely written as kivy can work with python2 or python3.
|
|
|
|
You can also use ``--bootstrap=pygame``, but this bootstrap is deprecated for use with Kivy and SDL2 is preferred.
|
|
|
|
Build a WebView application
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To build your application, you need to have a name, version, a package
|
|
identifier, and explicitly use the webview bootstrap, as
|
|
well as the requirements::
|
|
|
|
p4a apk --private $HOME/code/myapp --package=org.example.myapp --name "My WebView Application" --version 0.1 --bootstrap=webview --requirements=flask --port=5000
|
|
|
|
You can also replace flask with another web framework.
|
|
|
|
Replace ``--port=5000`` with the port on which your app will serve a
|
|
website. The default for Flask is 5000.
|
|
|
|
Build an SDL2 based application
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This includes e.g. `PySDL2
|
|
<https://pysdl2.readthedocs.io/en/latest/>`__.
|
|
|
|
To build your application, you need to have a name, version, a package
|
|
identifier, and explicitly write the sdl2 bootstrap, as well as the
|
|
requirements::
|
|
|
|
p4a apk --private $HOME/code/myapp --package=org.example.myapp --name "My SDL2 application" --version 0.1 --bootstrap=sdl2 --requirements=your_requirements
|
|
|
|
Add your required modules in place of ``your_requirements``,
|
|
e.g. ``--requirements=pysdl2`` or ``--requirements=vispy``.
|
|
|
|
Other options
|
|
~~~~~~~~~~~~~
|
|
|
|
You can pass other command line arguments to control app behaviours
|
|
such as orientation, wakelock and app permissions. See
|
|
:ref:`bootstrap_build_options`.
|
|
|
|
|
|
|
|
Rebuild everything
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
If anything goes wrong and you want to clean the downloads and builds to retry everything, run::
|
|
|
|
p4a clean_all
|
|
|
|
If you just want to clean the builds to avoid redownloading dependencies, run::
|
|
|
|
p4a clean_builds && p4a clean_dists
|
|
|
|
Getting help
|
|
~~~~~~~~~~~~
|
|
|
|
If something goes wrong and you don't know how to fix it, add the
|
|
``--debug`` option and post the output log to the `kivy-users Google
|
|
group <https://groups.google.com/forum/#!forum/kivy-users>`__ or irc
|
|
channel #kivy at irc.freenode.net .
|
|
|
|
See :doc:`troubleshooting` for more information.
|
|
|
|
|
|
Advanced usage
|
|
--------------
|
|
|
|
Recipe management
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
You can see the list of the available recipes with::
|
|
|
|
p4a recipes
|
|
|
|
If you are contributing to p4a and want to test a recipes again,
|
|
you need to clean the build and rebuild your distribution::
|
|
|
|
p4a clean_recipe_build RECIPENAME
|
|
p4a clean_dists
|
|
# then rebuild your distribution
|
|
|
|
You can write "private" recipes for your application, just create a
|
|
``p4a-recipes`` folder in your build directory, and place a recipe in
|
|
it (edit the ``__init__.py``)::
|
|
|
|
mkdir -p p4a-recipes/myrecipe
|
|
touch p4a-recipes/myrecipe/__init__.py
|
|
|
|
|
|
Distribution management
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Every time you start a new project, python-for-android will internally
|
|
create a new distribution (an Android build project including Python
|
|
and your other dependencies compiled for Android), according to the
|
|
requirements you added on the command line. You can force the reuse of
|
|
an existing distribution by adding::
|
|
|
|
p4a apk --dist_name=myproject ...
|
|
|
|
This will ensure your distribution will always be built in the same
|
|
directory, and avoids using more disk space every time you adjust a
|
|
requirement.
|
|
|
|
You can list the available distributions::
|
|
|
|
p4a distributions
|
|
|
|
And clean all of them::
|
|
|
|
p4a clean_dists
|
|
|
|
Configuration file
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
python-for-android checks in the current directory for a configuration
|
|
file named ``.p4a``. If found, it adds all the lines as options to the
|
|
command line. For example, you can add the options you would always
|
|
include such as::
|
|
|
|
--dist_name my_example
|
|
--android_api 19
|
|
--requirements kivy,openssl
|
|
|
|
|
|
Going further
|
|
~~~~~~~~~~~~~
|
|
|
|
See the other pages of this doc for more information on specific topics:
|
|
|
|
- :doc:`buildoptions`
|
|
- :doc:`commands`
|
|
- :doc:`recipes`
|
|
- :doc:`bootstraps`
|
|
- :doc:`apis`
|
|
- :doc:`troubleshooting`
|
|
- :doc:`launcher`
|
|
- :doc:`contribute`
|