Skip to content

Commit 72431ea

Browse files
inclementinclement
committed
Updated quickstart doc
1 parent c78a21d commit 72431ea

File tree

1 file changed

+53
-20
lines changed

1 file changed

+53
-20
lines changed

‎doc/source/quickstart.rst‎

Lines changed: 53 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -32,45 +32,78 @@ Or by direct download::
3232
unzip master.zip
3333
cd python-for-android-revamp-master
3434
35-
Then in both cases run `python setup.py install``.
35+
Then in both cases run ``python setup.py install``.
3636

3737

3838
Basic use
3939
---------
4040

41+
python-for-android provides two executables, ``python-for-android``
42+
and ``p4a``. These are identical and interchangeable, you can
43+
substitute either one for the other. These instructions all use
44+
``python-for-android``.
45+
4146
You can test that p4a was installed correctly by running
4247
``python-for-android recipes``. This should print a list of all the
4348
recipes available to be built into your APKs.
4449

45-
.. warning:: The below instructions are out of date, if you installed
46-
with pip you can replace ``python2 toolchain.py`` with
47-
``python-for-android``.
48-
49-
Navigate to the ``pythonforandroid`` directory within the downloaded package.
50+
Before running any apk packaging or distribution creation, it is
51+
essential to set some env vars. First install the Android SDK and NDK, then:
52+
53+
- Set the ``ANDROIDSDK`` env var to the ``/path/to/the/sdk``
54+
- Set the ``ANDROIDNDK`` env var to the ``/path/to/the/ndk``
55+
- Set the ``ANDROIDAPI`` to the targeted API version (or leave it
56+
unset to use the default of ``14``.
57+
- Set the ``ANDROIDNDKVER`` env var to the version of the NDK
58+
downloaded, e.g. the current NDK is ``r10e`` (or leave it unset to
59+
use the default of ``r9``.
5060

51-
.. note:: This will soon be replaced with a normal call to setup.py,
52-
but this hasn't been finished and tested yet.
53-
54-
You need to set ANDROIDSDK and ANDROIDNDK env vars to point to these.
61+
The process of setting these variables should be streamlined in the
62+
future, these options are preliminary.
5563

5664
To create a basic distribution, run .e.g::
5765

58-
python2 toolchain.py create --name=testproject --bootstrap=pygame --recipes=sdl,python2
66+
python-for-android create --dist_name=testproject --bootstrap=pygame --requirements=sdl,python2
67+
68+
This will compile the distribution, which will take a few minutes, but
69+
will keep you informed about its progress. The arguments relate to the
70+
properties of the created distribution; the dist_name is an (optional)
71+
unique identifier, and the requirements is a list of any pure Python
72+
pypi modules, or dependencies with recipes available, that your app
73+
depends on. The full list of builtin internal recipes can be seen with
74+
``python-for-android recipes``.
5975

60-
These arguments relate to the old python-for-android; ``name`` is the
61-
dist name, and ``recipes`` is a list of recipes to use. The build
62-
should proceed and eventually finish, and will print the location of
63-
the dist.
64-
6576
.. note:: Compiled dists are not located in the same place as with old
6677
python-for-android, but instead in an OS-dependent
6778
location. The build process will print this location when it
68-
finishes.
79+
finishes, but you no longer need to navigate there manually
80+
(see below).
6981

70-
To build an APK, navigate to the dist dir and run build.py just as with old p4a.
82+
To build an APK, use the ``apk`` command::
83+
84+
python-for-android apk --private /path/to/your/app --package=org.example.packagename --name="Your app name" --version=0.1
85+
86+
The arguments to ``apk`` can be anything accepted by the old
87+
python-for-android build.py; the above is a minimal set to create a
88+
basic app. You can see the list with ``python-for-android apk help``.
89+
90+
A new feature of python-for-android is that you can do all of this with just one command::
91+
92+
python-for-android apk --private /home/asandy/devel/planewave_frozen/ --package=net.inclem.planewavessdl2 --name="planewavessdl2" --version=0.5 --bootstrap=sdl2 --requirements=sdl,python2 --dist_name=testproject
93+
94+
This combines the previous ``apk`` command with the arguments to
95+
``create``, and works in exactly the same way; if no internal
96+
distribution exists with these requirements then one is first built,
97+
before being used to package the APK. When the command is run again,
98+
the build step is skipped and the previous dist re-used.
99+
100+
Using this method you don't have to worry about whether a dist exists,
101+
though it is recommended to use a different ``dist_name`` for each
102+
project unless they have precisely the same requirements.
71103

72-
You can build an SDL2 APK similarly, first making a dist::
104+
You can build an SDL2 APK similarly, creating a dist as follows::
73105

74106
python2 toolchain.py create --name=testsdl2 --bootstrap=sdl2 --recipes=sdl2,python2
75107

76-
This will have a build.py in the same way, but currently doesn't support many options.
108+
You can then make an APK in the same way, but this is more
109+
experimental and doesn't support as much customisation yet.

0 commit comments

Comments
 (0)