diff --git a/doc/Makefile b/doc/Makefile index c2fadd0e6f..6152500cb6 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = sphinx-build2 +SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build diff --git a/doc/source/apis.rst b/doc/source/apis.rst index 1003b4a1fe..4f292d8676 100644 --- a/doc/source/apis.rst +++ b/doc/source/apis.rst @@ -3,42 +3,36 @@ Accessing Android APIs ====================== When writing an Android application you may want to access the normal -Android APIs, which are available in Java. It is by calling these that -you would normally accomplish everything from vibration, to opening -other applications, to accessing sensor data, to controlling settings -like screen orientation and wakelocks. - -These APIs can be accessed from Python to perform all of these tasks -and many more. This is made possible by the `Pyjnius -`_ module, a Python -library for automatically wrapping Java and making it callable from -Python code. This is fairly simple to use, though not very Pythonic -and inherits Java's verbosity. For this reason the Kivy organisation -also created `Plyer `_, -which further wraps specific APIs in a Pythonic and cross-platform -way - so in fact you can call the same code in Python but have it do -the right thing also on platforms other than Android. - -These are both independent projects whose documentation is linked -above, and you can check this to learn about all the things they can -do. The following sections give some simple introductory examples, -along with explanation of how to include these modules in your APKs. +Android Java APIs, in order to control your application's appearance +(fullscreen, orientation etc.), interact with other apps or use +hardware like vibration and sensors. + +You can access these with `Pyjnius +`_, a Python library for +automatically wrapping Java and making it callable from Python +code. Pyjnius is fairly simple to use, but not very Pythonic and it +inherits Java's verbosity. For this reason the Kivy organisation also +created `Plyer `_, which +further wraps specific APIs in a Pythonic and cross-platform way; you +can call the same code in Python but have it do the right thing also +on platforms other than Android. + +Pyjnius and Plyer are independent projects whose documentation is +linked above. See below for some simple introductory examples, and +explanation of how to include these modules in your APKs. Using Pyjnius ------------- -Pyjnius lets you call the Android API directly from Python; this let's -you do almost everything you can (and probably would) do in a Java -app. Pyjnius is works by dynamically wrapping Java classes, so you -don't have to wait for any particular feature to be pre-supported. +Pyjnius lets you call the Android API directly from Python Pyjnius is +works by dynamically wrapping Java classes, so you don't have to wait +for any particular feature to be pre-supported. -You can include Pyjnius in your APKs by adding the `pyjnius` or -`pyjniussdl2` recipes to your build requirements (the former works -with Pygame/SDL1, the latter with SDL2, the need to make this choice -will be removed later when pyjnius internally supports multiple -Android backends). It is automatically included in any APK containing -Kivy, in which case you don't need to specify it manually. +You can include Pyjnius in your APKs by adding `pyjnius` to your build +requirements, e.g. :code:`--requirements=flask,pyjnius`. It is +automatically included in any APK containing Kivy, in which case you +don't need to specify it manually. The basic mechanism of Pyjnius is the `autoclass` command, which wraps a Java class. For instance, here is the code to vibrate your device:: @@ -87,17 +81,16 @@ You can check the `Pyjnius documentation `_ for further details. Using Plyer ----------- -Plyer aims to provide a much less verbose, Pythonic wrapper to -platform-specific APIs. Android is a supported platform, but it also -supports iOS and desktop operating systems, with the idea that the -same Plyer code would do the right thing on any of them, though Plyer -is a work in progress and not all platforms support all Plyer calls -yet. This is the disadvantage of Plyer, it does not support all APIs -yet, but you can always Pyjnius to call anything that is currently -missing. +Plyer provides a much less verbose, Pythonic wrapper to +platform-specific APIs. It supports Android as well as iOS and desktop +operating systems, though plyer is a work in progress and not all +platforms support all Plyer calls yet. + +Plyer does not support all APIs yet, but you can always Pyjnius to +call anything that is currently missing. You can include Plyer in your APKs by adding the `Plyer` recipe to -your build requirements. It is not included automatically. +your build requirements, e.g. :code:`--requirements=plyer`. You should check the `Plyer documentation `_ for details of all supported facades (platform APIs), but as an example the following is how you @@ -106,8 +99,4 @@ would achieve vibration as described in the Pyjnius section above:: from plyer.vibrator import vibrate vibrate(10) # in Plyer, the argument is in seconds -This is obviously *much* less verbose! - -.. warning:: At the time of writing, the Plyer recipe is not yet - ported, and Plyer doesn't support SDL2. These issues will - be fixed soon. +This is obviously *much* less verbose than with Pyjnius! diff --git a/doc/source/bootstraps.rst b/doc/source/bootstraps.rst index 17b36a3387..c522933316 100644 --- a/doc/source/bootstraps.rst +++ b/doc/source/bootstraps.rst @@ -2,18 +2,16 @@ Bootstraps ========== +This page is about creating new bootstrap backends. For build options +of existing bootstraps (i.e. with SDL2, Pygame, Webview etc.), see +:ref:`build options `. + python-for-android (p4a) supports multiple *bootstraps*. These fulfill a similar role to recipes, but instead of describing how to compile a specific module they describe how a full Android project may be put together from a combination of individual recipes and other components such as Android source code and various build files. -If you do not want to modify p4a, you don't need to worry about -bootstraps, just make sure you specify what modules you want to use -(or specify an existing bootstrap manually), and p4a will -automatically build everything appropriately. The existing choices are -explained on the :ref:`build options ` page. - This page describes the basics of how bootstraps work so that you can create and use your own if you like, making it easy to build new kinds of Python project for Android. diff --git a/doc/source/index.rst b/doc/source/index.rst index 451999e02c..f393be3596 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -28,7 +28,6 @@ Contents quickstart buildoptions - installation commands recipes bootstraps @@ -44,4 +43,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index cabe41aefb..079f31115d 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -1,50 +1,56 @@ -Quickstart -========== +Getting Started +=============== -These simple steps run through the most simple procedure to create an -APK with some simple default parameters. See the :doc:`commands -documentation ` for all the different commands and build -options available. +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. -.. warning:: These instructions are quite preliminary. The - installation and use process will become more standard in - the near future. +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. -Installation ------------- +- 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. -The easiest way to install is with pip. You need to have setuptools installed, then run:: +- build: A build refers to a compiled recipe. - pip install git+https://github.com/kivy/python-for-android.git +- 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. -This should install python-for-android (though you may need to run as root or add --user). +- 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. -You could also install python-for-android manually, either via git:: - git clone https://github.com/kivy/python-for-android.git - cd python-for-android +Installation +------------ -Or by direct download:: +Installing p4a +~~~~~~~~~~~~~~ - wget https://github.com/kivy/python-for-android/archive/master.zip - unzip revamp.zip - cd python-for-android-revamp +p4a is not yet released on Pypi, but you can install it using pip:: -Then in both cases run ``python setup.py install``. + pip install git+https://github.com/kivy/python-for-android.git -Dependencies ------------- +Installing Dependencies +~~~~~~~~~~~~~~~~~~~~~~~ -python-for-android has several dependencies that must be installed, -via your package manager or otherwise. These include: +p4a has several dependencies that must be installed: - git - ant - python2 - cython (can be installed via pip) -- the Android `SDK `_ and `NDK `_ (see below) - a Java JDK (e.g. openjdk-7) - zlib (including 32 bit) - libncurses (including 32 bit) @@ -57,205 +63,148 @@ 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 + 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 -When installing the Android SDK and NDK, note the filepaths where they -may be found, and the version of the NDK installed. You may need to -set environment variables pointing to these later. +Installing Android SDK +~~~~~~~~~~~~~~~~~~~~~~ -.. _basic_use: +You need to download and unpack to a directory (let's say $HOME/Documents/): -Basic use ---------- +- `Android SDK `_ +- `Android NDK `_ -python-for-android provides two executables, ``python-for-android`` -and ``p4a``. These are identical and interchangeable, you can -substitute either one for the other. These instructions all use -``python-for-android``. +Then, you can edit your `~/.bashrc` or others favorite shell to include new environment variables necessary for building on android:: -You can test that p4a was installed correctly by running -``python-for-android recipes``. This should print a list of all the -recipes available to be built into your APKs. + # 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 -Before running any apk packaging or distribution creation, it is -essential to set some env vars. Make sure you have installed the -Android SDK and NDK, then: +You have the possibility to configure on any command the PATH to the SDK, NDK and Android API using: -- Set the ``ANDROIDSDK`` env var to the ``/path/to/the/sdk`` -- Set the ``ANDROIDNDK`` env var to the ``/path/to/the/ndk`` -- Set the ``ANDROIDAPI`` to the targeted API version (or leave it - unset to use the default of ``14``). -- Set the ``ANDROIDNDKVER`` env var to the version of the NDK - downloaded, e.g. the current NDK is ``r10e`` (or leave it unset to - use the default of ``r9``. +- `--sdk_dir PATH` as an equivalent of `$ANDROIDSDK` +- `--ndk_dir PATH` as an equivalent of `$ANDROIDNDK` +- `--android_api VERSION` as an equivalent of `$ANDROIDAPI` +- `--ndk_ver PATH` as an equivalent of `$ANDROIDNDKVER` -This is **NOT** the only way to set these variables, see the `setting -SDK/NDK paths `_ section for other options and their -details. -To create a basic distribution, run .e.g:: +Usage +----- - python-for-android create --dist_name=testproject --bootstrap=pygame \ - --requirements=sdl,python2 +Build a Kivy application +~~~~~~~~~~~~~~~~~~~~~~~~ -This will compile the distribution, which will take a few minutes, but -will keep you informed about its progress. The arguments relate to the -properties of the created distribution; the dist_name is an (optional) -unique identifier, and the requirements is a list of any pure Python -pypi modules, or dependencies with recipes available, that your app -depends on. The full list of builtin internal recipes can be seen with -``python-for-android recipes``. +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:: -.. note:: Compiled dists are not located in the same place as with old - python-for-android, but instead in an OS-dependent - location. The build process will print this location when it - finishes, but you no longer need to navigate there manually - (see below). + p4a apk --private $HOME/code/myapp --package=org.example.myapp --name "My application" --version 0.1 --bootstrap=sdl2 --requirements=python2,kivy -To build an APK, use the ``apk`` command:: +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. - python-for-android apk --private /path/to/your/app --package=org.example.packagename \ - --name="Your app name" --version=0.1 +You can also use ``--bootstrap=pygame``, but this bootstrap is deprecated for use with Kivy and SDL2 is preferred. -The arguments to ``apk`` can be anything accepted by the old -python-for-android build.py; the above is a minimal set to create a -basic app. You can see the list with ``python-for-android apk help``. - -A new feature of python-for-android is that you can do all of this with just one command:: - - python-for-android apk --private /path/to/your/app \ - --package=org.example.packagename --name="Your app name" --version=0.5 - --bootstrap=pygame --requirements=sdl,python2 --dist_name=testproject - -This combines the previous ``apk`` command with the arguments to -``create``, and works in exactly the same way; if no internal -distribution exists with these requirements then one is first built, -before being used to package the APK. When the command is run again, -the build step is skipped and the previous dist re-used. - -Using this method you don't have to worry about whether a dist exists, -though it is recommended to use a different ``dist_name`` for each -project unless they have precisely the same requirements. +Build a WebView application +~~~~~~~~~~~~~~~~~~~~~~~~~ -You can build an SDL2 APK similarly, creating a dist as follows:: +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:: - python-for-android create --dist_name=testsdl2 --bootstrap=sdl2 --requirements=sdl2,python2,kivy + p4a apk --private $HOME/code/myapp --package=org.example.myapp --name "My WebView Application" --version 0.1 --bootstrap=webview --requirements=flask --port=5000 -Note that you must now explicitly add ``kivy`` to the requirements, as -its presence is now optional (you can alternatively use SDL2 in other -ways, such as with PySDL2). +You can also replace flask with another web framework. -You can then make an APK in the same way, but this is more -experimental and doesn't support as much customisation yet. +Replace ``--port=5000`` with the port your app will serve a website +on. The default for Flask is 5000. -Your APKs are not limited to Kivy, for instance you can create apps -using Vispy, or using PySDL2 directly. The basic command for this -would be e.g.:: +Build an SDL2 based application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - python-for-android create --dist_name=testvispy --bootstrap=sdl2 --requirements=vispy +This includes `Vispy `__ and `PySDL2 +`__. -python-for-android also has commands to list internal information -about distributions available, to export or symlink these (they come -with a standalone APK build script), and in future will also support -features including binary download to avoid the manual compilation -step. +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:: -See the :doc:`commands` documentation for full details of available -functionality. + p4a apk --private $HOME/code/myapp --package=org.example.myapp --name "My SDL2 application" --version 0.1 --bootstrap=sdl2 --requirements=your_requirements -.. _setting_paths: +Add your required modules in place of ``your_requirements``, +e.g. ``--requirements=pysdl2`` or ``--requirements=vispy``. + -Setting paths to the the SDK and NDK ------------------------------------- +Rebuild everything +~~~~~~~~~~~~~~~~~~ -If building your own dists it is necessary to have installed the -Android SDK and NDK, and to make Kivy aware of their locations. The -instructions in `basic use `_ use environment variables -for this, but this is not the only option. The different possibilities -for each setting are given below. +If anything goes wrong and you want to clean the downloads and builds to retry everything, run:: -Path to the Android SDK -~~~~~~~~~~~~~~~~~~~~~~~ + p4a clean_all + +If you just want to clean the builds to avoid redownloading dependencies, run:: -python-for-android searches in the following places for this path, in -order; setting any of these variables overrides all the later ones: + p4a clean_builds && p4a clean_dists + +Getting help +~~~~~~~~~~~~ -- The ``--sdk_dir`` argument to any python-for-android command. -- The ``ANDROIDSDK`` environment variable. -- The ``ANDROID_HOME`` environment variable (this may be used or set - by other tools). -- By using buildozer and letting it download the SDK; - python-for-android automatically checks the default buildozer - download directory. This is intended to make testing - python-for-android easy. +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 `__ or irc +channel #kivy at irc.freenode.net . -If none of these is set, python-for-android will raise an error and exit. +See :ref:`Troubleshooting ` for more information. -The Android API to target -~~~~~~~~~~~~~~~~~~~~~~~~~ -When building for Android it is necessary to target an API number -corresponding to a specific version of Android. Whatever you choose, -your APK will probably not work in earlier versions, but you also -cannot use features introduced in later versions. +Advanced usage +-------------- -You must download specific platform tools for the SDK for any given -target, it does not come with any. Do this by running -``/path/to/android/sdk/tools/android``, which will give a gui -interface, and select the 'platform tools' option under your chosen -target. +Recipe management +~~~~~~~~~~~~~~~~~~ -The default target of python-for-android is 14, corresponding to -Android 4.0. This may be changed in the near future. +You can see the list of the available recipes with:: -You must pass the target API to python-for-android, and can do this in -several ways. Each choice overrides all the later ones: + 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:: -- The ``--android_api`` argument to any python-for-android command. -- The ``ANDROIDAPI`` environment variables. -- If neither of the above, the default target is used (currently 14). + p4a clean_recipe_build RECIPENAME + p4a clean_dists + # then rebuild your distribution -python-for-android checks if the target you select is available, and -gives an error if not, so it's easy to test if you passed this -variable correctly. +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``):: -Path to the Android NDK -~~~~~~~~~~~~~~~~~~~~~~~ + mkdir -p p4a-recipes/myrecipe + touch p4a-recipes/myrecipe/__init__.py + -python-for-android searches in the following places for this path, in -order; setting any of these variables overrides all the later ones: +Distribution management +~~~~~~~~~~~~~~~~~~~~~~~~ -- The ``--ndk_dir`` argument to any python-for-android command. -- The ``ANDROIDNDK`` environment variable. -- The ``NDK_HOME`` environment variable (this may be used or set - by other tools). -- The ``ANDROID_NDK_HOME`` environment variable (this may be used or set -- By using buildozer and letting it download the NDK; - python-for-android automatically checks the default buildozer - download directory. This is intended to make testing - python-for-android easy. - by other tools). +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:: -If none of these is set, python-for-android will raise an error and exit. + p4a apk --dist_name=myproject ... -The Android NDK version -~~~~~~~~~~~~~~~~~~~~~~~ +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. -python-for-android needs to know what version of the NDK is installed, -in order to properly resolve its internal filepaths. You can set this -with any of the following methods - note that the first is preferred, -and means that you probably do *not* have to manually set this. +You can list the available distributions:: -- The ``RELEASE.TXT`` file in the NDK directory. If this exists and - contains the version (which it probably does automatically), you do - not need to set it manually. -- The ``--ndk_ver`` argument to any python-for-android command. -- The ``ANDROIDNDKVER`` environment variable. + p4a distributions -If ``RELEASE.TXT`` exists but you manually set a different version, -python-for-android will warn you about it, but will assume you are -correct and try to continue the build. +And clean all of them:: + p4a clean_dists + Configuration file ~~~~~~~~~~~~~~~~~~ @@ -267,3 +216,20 @@ 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: + +.. toctree:: + :maxdepth: 1 + + More detailed build options + Command line arguments + Creating and editing recipes + Creating and editing bootstraps + Using the Android Java APIs + Troubleshooting + Contributing diff --git a/doc/source/recipes.rst b/doc/source/recipes.rst index 5a1212a111..ab2f5d0c50 100644 --- a/doc/source/recipes.rst +++ b/doc/source/recipes.rst @@ -2,17 +2,18 @@ Recipes ======= -This documentation describes how python-for-android (p4a) recipes -work. These are special scripts for installing different programs +This page describes how python-for-android (p4a) compilation recipes +work, and how to build your own. If you just want to build an APK, +ignore this and jump straight to the :doc:`quickstart`. + +Recipes are special scripts for compiling and installing different programs (including Python modules) into a p4a distribution. They are necessary to take care of compilation for any compiled components, as these must be compiled for Android with the correct architecture. -python-for-android comes with many recipes for popular modules, and no -recipe is necessary at all for the use of Python modules with no -compiled components; if you just want to build an APK, you can jump -straight to the :doc:`quickstart` or :doc:`commands` documentation, or -can use the :code:`recipes` command to list available recipes. +python-for-android comes with many recipes for popular modules. No +recipe is necessary to use of Python modules with no +compiled components; these are installed automaticaly via pip. If you are new to building recipes, it is recommended that you first read all of this page, at least up to the Recipe reference @@ -23,8 +24,7 @@ examples of how recipes are built or overridden for specific purposes. Creating your own Recipe ------------------------ -This documentation jumps straight to the practicalities of creating -your own recipe. The formal reference documentation of the Recipe +The formal reference documentation of the Recipe class can be found in the `Recipe class `_ section and below. Check the `recipe template section `_ for a template @@ -52,9 +52,8 @@ information about each parameter. These core options are vital for all recipes, though the url may be omitted if the source is somehow loaded from elsewhere. -The ``recipe = YourRecipe()`` is also vital. This variable is used -when the recipe is imported as the recipe instance to build with. If -it is omitted, your recipe won't work. +You must include ``recipe = YourRecipe()``. This variable is accessed +when the recipe is imported. .. note:: The url includes the ``{version}`` tag. You should only access the url with the ``versioned_url`` property, which @@ -74,9 +73,8 @@ The actual build process takes place via three core methods:: super(YourRecipe, self).build_arch(arch) # Do any clearing up -The prebuild of every recipe is run before the build of any recipe, -and likewise the build of every recipe is run before the postbuild of -any. This lets you strictly order the build process. +These methods are always run in the listed order; prebuild, then +build, then postbuild. If you defined an url for your recipe, you do *not* need to manually download it, this is handled automatically. @@ -412,7 +410,7 @@ A Recipe template ----------------- The following template includes all the recipe sections you might -use. Note that none are compulsory, feel free to delete method +use. None are compulsory, feel free to delete method overrides if you do not use them:: from pythonforandroid.toolchain import Recipe, shprint, current_directory @@ -427,6 +425,7 @@ overrides if you do not use them:: version = 'some_version_string' url = 'http://example.com/example-{version}.tar.gz' + # {version} will be replaced with self.version when downloading depends = ['python2', 'numpy'] # A list of any other recipe names # that must be built before this @@ -469,13 +468,11 @@ overrides if you do not use them:: Examples of recipes ------------------- -The above documentation has included a number of snippets -demonstrating different behaviour. Together, these cover most of what -is ever necessary to make a recipe work. - -python-for-android includes many recipes for popular modules, which -are an excellent resource to find out how to add your own. You can -find these in the `python-for-android Github page +This documentation covers most of what is ever necessary to make a +recipe work. For further examples, python-for-android includes many +recipes for popular modules, which are an excellent resource to find +out how to add your own. You can find these in the `python-for-android +Github page `__.