From 350eadadd27e596e06eb80ed098f348d0d71bebd Mon Sep 17 00:00:00 2001 From: Alexander Taylor Date: Sun, 4 Dec 2016 22:56:16 +0000 Subject: [PATCH 1/2] Added APK unpacking instructions --- doc/source/troubleshooting.rst | 45 ++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst index d24abf11ae..b67550ec6c 100644 --- a/doc/source/troubleshooting.rst +++ b/doc/source/troubleshooting.rst @@ -69,6 +69,51 @@ on `logcat `_ in particular. +Unpacking an APK +---------------- + +It is sometimes useful to unpack a pacakged APK to see what is inside, +especially when debugging python-for-android itself. + +APKs are just zip files, so you can extract the contents easily:: + + unzip YourApk.apk + +At the top level, this will always contain the same set of files:: + + $ ls + AndroidManifest.xml classes.dex META-INF res +assets lib PyonicPython2interpreter-0.9-debug.apk resources.arsc + +The Python distribution is in the assets folder:: + + $ cd assets + $ ls + private.mp3 + +``private.mp3`` is actually a tarball containing all your packaged +data, and the Python distribution. Extract it:: + + $ tar xf private.mp3 + +This will reveal all the Python-related files:: + + $ ls + android_runnable.pyo include interpreter_subprocess main.kv pipinterface.kv settings.pyo + assets __init__.pyo interpreterwrapper.pyo main.pyo pipinterface.pyo utils.pyo + editor.kv interpreter.kv lib menu.kv private.mp3 widgets.pyo + editor.pyo interpreter.pyo libpymodules.so menu.pyo settings.kv + +Most of these files have been included by the user (in this case, they +come from one of my own apps), the rest relate to the python +distribution. + +With Python 2, the Python installation can mostly be found in the +``lib`` folder. With Python 3 (using the ``python3crystax`` recipe), +the Python installation can be found in a folder named +``crystax_python``. + + Common errors ------------- From 0c245ddeb52aabedebd89e318bda46ea332e0781 Mon Sep 17 00:00:00 2001 From: Alexander Taylor Date: Sun, 4 Dec 2016 22:44:24 +0000 Subject: [PATCH 2/2] Improved build options doc --- doc/source/buildoptions.rst | 46 +++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 25 deletions(-) diff --git a/doc/source/buildoptions.rst b/doc/source/buildoptions.rst index db54fd8291..ce21ee8806 100644 --- a/doc/source/buildoptions.rst +++ b/doc/source/buildoptions.rst @@ -2,9 +2,7 @@ Build options ============= -python-for-android provides several major choices for build -components. This page describes the advantages and drawbacks, and -extra technical details or requirements, in each case. +This page contains instructions for using some of the specific python-for-android build options. Python version @@ -20,9 +18,9 @@ python2 Select this by adding it in your requirements, e.g. ``--requirements=python2``. -This option builds Python 2.7.2 for your selected Android architecture, and -includes it in the APK. There are no special requirements, all the -building is done locally. +This option builds Python 2.7.2 for your selected Android +architecture. There are no special requirements, all the building is +done locally. The python2 build is also the way python-for-android originally worked, even in the old toolchain. @@ -35,23 +33,26 @@ python3 Python3 support is experimental, and some of these details may change as it is improved and fully stabilised. +.. note:: You must manually download the `CrystaX NDK + `__ and tell + python-for-android to use it with ``--ndk-dir /path/to/NDK``. + Select this by adding the ``python3crystax`` recipe to your requirements, e.g. ``--requirements=python3crystax``. This uses the prebuilt Python from the `CrystaX NDK `__, a drop-in replacement for -Google's official NDK which includes many improvements. As such, you +Google's official NDK which includes many improvements. You *must* use the CrystaX NDK 10.3.0 or higher when building with python3. You can get it `here `__. -python3 inclusion should work fine, including all existing -recipes, but internally this is handled quite differently to the -locally built python2 so there may be bugs or surprising -behaviours. If you come across any, feel free to `open an issue +The python3crystax build is is handled quite differently to python2 so +there may be bugs or surprising behaviours. If you come across any, +feel free to `open an issue `__. -The experimental status also means that some features are missing and +As this build is experimental, some features are missing and the build is not fully optimised so APKs are probably a little larger and slower than they need to be. This is currently being addressed, 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. Bootstrap --------- -python-for-android supports multiple bootstraps, the Java and JNI code -that starts the app and the python interpreter, then handles -interactions with the Android OS. +python-for-android supports multiple bootstraps, which contain the app +backend that starts the app and the python interpreter, then +handles interactions with the Android OS. Currently the following bootstraps are supported, but we hope that it it should be easy to add others if your project has different @@ -74,8 +75,8 @@ are any improvements that would help here. sdl2 ~~~~ -You can use this with ``--bootstrap=sdl2``, or simply include the -``sdl2`` recipe in your ``--requirements``. +Use this with ``--bootstrap=sdl2``, or just include the +``sdl2`` recipe, e.g. ``--requirements=sdl2,python2``. SDL2 is a popular cross-platform depelopment library, particularly for games. It has its own Android project support, which @@ -83,21 +84,16 @@ python-for-android uses as a bootstrap, and to which it adds the Python build and JNI code to start it. From the point of view of a Python program, SDL2 should behave as -normal. For instance, you can build apps with Kivy, Vispy, or PySDL2 +normal. For instance, you can build apps with Kivy or PySDL2 and have them work with this bootstrap. It should also be possible to use e.g. pygame_sdl2, but this would need a build recipe and doesn't yet have one. -.. note:: - The SDL2 bootstrap is newer, and does not support all the old - features of the Pygame one. It is under active development to fix - these omissions. - webview ~~~~~~~ -You can use this with ``--bootstrap=webview``, or simply include the -``webviewjni`` recipe in your ``--requirements``. +You can use this with ``--bootstrap=webview``, or include the +``webviewjni`` recipe, e.g. ``--requirements=webviewjni,python2``. The webview bootstrap gui is, per the name, a WebView displaying a webpage, but this page is hosted on the device via a Python