Skip to content

Commit 8fe4f43

Browse files
inclementinclement
authored
Merge pull request kivy#950 from inclement/doc_fixes
Doc fixes
2 parents 599ed2e + 0c245dd commit 8fe4f43

File tree

2 files changed

+66
-25
lines changed

2 files changed

+66
-25
lines changed

‎doc/source/buildoptions.rst‎

Lines changed: 21 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,7 @@
22
Build options
33
=============
44

5-
python-for-android provides several major choices for build
6-
components. This page describes the advantages and drawbacks, and
7-
extra technical details or requirements, in each case.
5+
This page contains instructions for using some of the specific python-for-android build options.
86

97

108
Python version
@@ -20,9 +18,9 @@ python2
2018

2119
Select this by adding it in your requirements, e.g. ``--requirements=python2``.
2220

23-
This option builds Python 2.7.2 for your selected Android architecture, and
24-
includes it in the APK. There are no special requirements, all the
25-
building is done locally.
21+
This option builds Python 2.7.2 for your selected Android
22+
architecture. There are no special requirements, all the building is
23+
done locally.
2624

2725
The python2 build is also the way python-for-android originally
2826
worked, even in the old toolchain.
@@ -35,23 +33,26 @@ python3
3533
Python3 support is experimental, and some of these details
3634
may change as it is improved and fully stabilised.
3735

36+
.. note:: You must manually download the `CrystaX NDK
37+
<https://www.crystax.net/android/ndk>`__ and tell
38+
python-for-android to use it with ``--ndk-dir /path/to/NDK``.
39+
3840
Select this by adding the ``python3crystax`` recipe to your
3941
requirements, e.g. ``--requirements=python3crystax``.
4042

4143
This uses the prebuilt Python from the `CrystaX NDK
4244
<https://www.crystax.net/android/ndk>`__, a drop-in replacement for
43-
Google's official NDK which includes many improvements. As such, you
45+
Google's official NDK which includes many improvements. You
4446
*must* use the CrystaX NDK 10.3.0 or higher when building with
4547
python3. You can get it `here
4648
<https://www.crystax.net/en/download>`__.
4749

48-
python3 inclusion should work fine, including all existing
49-
recipes, but internally this is handled quite differently to the
50-
locally built python2 so there may be bugs or surprising
51-
behaviours. If you come across any, feel free to `open an issue
50+
The python3crystax build is is handled quite differently to python2 so
51+
there may be bugs or surprising behaviours. If you come across any,
52+
feel free to `open an issue
5253
<https://github.com/kivy/python-for-android>`__.
5354

54-
The experimental status also means that some features are missing and
55+
As this build is experimental, some features are missing and
5556
the build is not fully optimised so APKs are probably a little larger
5657
and slower than they need to be. This is currently being addressed,
5758
though it's not clear how the final result will compare to python2.
@@ -61,9 +62,9 @@ though it's not clear how the final result will compare to python2.
6162
Bootstrap
6263
---------
6364

64-
python-for-android supports multiple bootstraps, the Java and JNI code
65-
that starts the app and the python interpreter, then handles
66-
interactions with the Android OS.
65+
python-for-android supports multiple bootstraps, which contain the app
66+
backend that starts the app and the python interpreter, then
67+
handles interactions with the Android OS.
6768

6869
Currently the following bootstraps are supported, but we hope that it
6970
it should be easy to add others if your project has different
@@ -74,30 +75,25 @@ are any improvements that would help here.
7475
sdl2
7576
~~~~
7677

77-
You can use this with ``--bootstrap=sdl2``, or simply include the
78-
``sdl2`` recipe in your ``--requirements``.
78+
Use this with ``--bootstrap=sdl2``, or just include the
79+
``sdl2`` recipe, e.g. ``--requirements=sdl2,python2``.
7980

8081
SDL2 is a popular cross-platform depelopment library, particularly for
8182
games. It has its own Android project support, which
8283
python-for-android uses as a bootstrap, and to which it adds the
8384
Python build and JNI code to start it.
8485

8586
From the point of view of a Python program, SDL2 should behave as
86-
normal. For instance, you can build apps with Kivy, Vispy, or PySDL2
87+
normal. For instance, you can build apps with Kivy or PySDL2
8788
and have them work with this bootstrap. It should also be possible to
8889
use e.g. pygame_sdl2, but this would need a build recipe and doesn't
8990
yet have one.
9091

91-
.. note::
92-
The SDL2 bootstrap is newer, and does not support all the old
93-
features of the Pygame one. It is under active development to fix
94-
these omissions.
95-
9692
webview
9793
~~~~~~~
9894

99-
You can use this with ``--bootstrap=webview``, or simply include the
100-
``webviewjni`` recipe in your ``--requirements``.
95+
You can use this with ``--bootstrap=webview``, or include the
96+
``webviewjni`` recipe, e.g. ``--requirements=webviewjni,python2``.
10197

10298
The webview bootstrap gui is, per the name, a WebView displaying a
10399
webpage, but this page is hosted on the device via a Python

‎doc/source/troubleshooting.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,51 @@ on `logcat
6969
<http://developer.android.com/intl/zh-cn/tools/help/logcat.html>`_ in
7070
particular.
7171

72+
Unpacking an APK
73+
----------------
74+
75+
It is sometimes useful to unpack a pacakged APK to see what is inside,
76+
especially when debugging python-for-android itself.
77+
78+
APKs are just zip files, so you can extract the contents easily::
79+
80+
unzip YourApk.apk
81+
82+
At the top level, this will always contain the same set of files::
83+
84+
$ ls
85+
AndroidManifest.xml classes.dex META-INF res
86+
assets lib PyonicPython2interpreter-0.9-debug.apk resources.arsc
87+
88+
The Python distribution is in the assets folder::
89+
90+
$ cd assets
91+
$ ls
92+
private.mp3
93+
94+
``private.mp3`` is actually a tarball containing all your packaged
95+
data, and the Python distribution. Extract it::
96+
97+
$ tar xf private.mp3
98+
99+
This will reveal all the Python-related files::
100+
101+
$ ls
102+
android_runnable.pyo include interpreter_subprocess main.kv pipinterface.kv settings.pyo
103+
assets __init__.pyo interpreterwrapper.pyo main.pyo pipinterface.pyo utils.pyo
104+
editor.kv interpreter.kv lib menu.kv private.mp3 widgets.pyo
105+
editor.pyo interpreter.pyo libpymodules.so menu.pyo settings.kv
106+
107+
Most of these files have been included by the user (in this case, they
108+
come from one of my own apps), the rest relate to the python
109+
distribution.
110+
111+
With Python 2, the Python installation can mostly be found in the
112+
``lib`` folder. With Python 3 (using the ``python3crystax`` recipe),
113+
the Python installation can be found in a folder named
114+
``crystax_python``.
115+
116+
72117
Common errors
73118
-------------
74119

0 commit comments

Comments
 (0)