diff --git a/docs/source/android.rst b/docs/source/android.rst index 98ca12ac9b..112f7e8362 100644 --- a/docs/source/android.rst +++ b/docs/source/android.rst @@ -1,11 +1,13 @@ Python API ========== -The Python for android project includes a Python module called "android". It -consists of multiple parts which are mostly there to facilitate the use of the Java API. +The Python for Android project includes a Python module called +``android`` which consists of multiple parts that are mostly there to +facilitate the use of the Java API. -This module is not designed to be comprehensive. Most of the Java API is also accessible with PyJNIus, -so if you can't find what you need here you can try using the Java API directly instead. +This module is not designed to be comprehensive. Most of the Java API +is also accessible with PyJNIus, so if you can't find what you need +here you can try using the Java API directly instead. Android (``android``) @@ -88,7 +90,7 @@ This billing module gives an access to the `In-App Billing `_ to buy. Let's say you've created a product with the id "org.kivy.gopremium" -#. In your application, you can use the billing module like this:: +#. In your application, you can use the ``billing`` module like this:: from android.billing import BillingService @@ -123,7 +125,7 @@ This billing module gives an access to the `In-App Billing [2] C JNI -> [3] Java -Think about acceleration sensors : you want to get the acceleration values in -python nothing is available natively, but you have a java API for that : the -google API is available here +Think about acceleration sensors: you want to get the acceleration +values in Python, but nothing is available natively. Lukcily you have +a Java API for that : the Google API is available here http://developer.android.com/reference/android/hardware/Sensor.html You can't use it directly, you need to do your own API to use it in python, @@ -82,14 +82,14 @@ Jni gottchas Create your own recipes ----------------------- -A recipe is a script that contain the "definition" of a module to compile. +A recipe is a script that contains the "definition" of a module to compile. The directory layout of a recipe for a is something like:: python-for-android/recipes//recipe.sh python-for-android/recipes//patches/ python-for-android/recipes//patches/fix-path.patch -When building, all the recipe build must go to:: +When building, all the recipe builds must go to:: python-for-android/build// @@ -101,5 +101,5 @@ For example, if you want to create a recipe for sdl, do:: sed -i 's#XXX#sdl#' sdl/recipe.sh Then, edit the sdl/recipe.sh to adjust other information (version, url) and -complete build function. +complete the build function. diff --git a/docs/source/example_helloworld.rst b/docs/source/example_helloworld.rst index d90a2e3944..dab760ad4b 100644 --- a/docs/source/example_helloworld.rst +++ b/docs/source/example_helloworld.rst @@ -7,9 +7,9 @@ with this project. .. note:: - Don't forget that Python for android is not Kivy only, and you might want - to use other toolkit libraries. When other toolkits will be available, this - documentation will be enhanced. + Don't forget that Python for Android is not Kivy only, and you + might want to use other toolkit libraries. When other toolkits + will be available, this documentation will be enhanced. Let's create a simple Hello world application, with one Label and one Button. @@ -55,7 +55,7 @@ Let's create a simple Hello world application, with one Label and one Button. #. Go to the ``python-for-android`` directory -#. Create a distribute with kivy:: +#. Create a distribution with kivy:: ./distribute.sh -m kivy @@ -63,7 +63,8 @@ Let's create a simple Hello world application, with one Label and one Button. cd dist/default -#. Plug your android device, and ensure you can install development application +#. Plug your android device, and ensure you can install development + application #. Build your hello world application in debug mode:: @@ -72,7 +73,7 @@ Let's create a simple Hello world application, with one Label and one Button. #. Take your device, and start the application! -#. If it's goes wrong, open the logcat by doing:: +#. If something goes wrong, open the logcat by doing:: adb logcat diff --git a/docs/source/examples.rst b/docs/source/examples.rst index b89a62e124..4d7408fa0c 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -4,11 +4,11 @@ Examples Prebuilt VirtualBox ------------------- -A good starting point to build an APK are prebuilt VirtualBox images, where -the Android NDK, the Android SDK and the Kivy Python-For-Android sources -are prebuilt in an VirtualBox image. Please search the `Download Section -`__ for -such an image. You will also need to create a device filter for the Android +A good starting point to build an APK are prebuilt VirtualBox images, +where the Android NDK, the Android SDK, and the Kivy +Python-For-Android sources are prebuilt in an VirtualBox image. Please +search the `Download Section `__ for such +an image. You will also need to create a device filter for the Android USB device using the VirtualBox OS settings. .. include:: example_helloworld.rst diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 9d0dd599cc..45202887ee 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -10,9 +10,11 @@ Android. Go to :doc:`prerequisites.rst` to see which one are working. _sqlite3.so not found --------------------- -We recently fixed sqlite3 compilation. In case of, you must: +We recently fixed sqlite3 compilation. In case of this error, you +must: -* Install development headers for sqlite3 if it's not already installed. On Ubuntu: +* Install development headers for sqlite3 if they are not already + installed. On Ubuntu: apt-get install libsqlite3-dev @@ -26,4 +28,4 @@ We recently fixed sqlite3 compilation. In case of, you must: sqlite3/* lib-dynload/_sqlite3.so -And then, sqlite3 will be compiled, and included in your APK. +Then sqlite3 will be compiled and included in your APK. diff --git a/docs/source/javaapi.rst b/docs/source/javaapi.rst index a8c44b5d5e..73fc888f8e 100644 --- a/docs/source/javaapi.rst +++ b/docs/source/javaapi.rst @@ -5,8 +5,9 @@ Using `PyJNIus `__ to access the Android API restricts the usage to a simple call of the **autoclass** constructor function and a second call to instantiate this class. -You can access through this method all Java Android API, e.g. to get the DisplayMetrics -of an Android device could fetched using the following piece of code: +You can access through this method the entire Java Android API, e.g., +the ``DisplayMetrics`` of an Android device could be fetched using the +following piece of code: .. code-block:: python @@ -15,17 +16,18 @@ of an Android device could fetched using the following piece of code: metrics.setToDefaults() self.densityDpi = metrics.densityDpi -You can access all fields and methods as described in the `Java Android -DisplayMetrics API `__ -as shown here with the method `setToDefaults()` and the field `densityDpi`. -Before you use o view a field, you should always call `setToDefaults` to initiate -to the default values of the device. - -Currently only JavaMethod, JavaStaticMethod, JavaField, JavaStaticField -and JavaMultipleMethod are built into PyJNIus, therefore such constructs like -registerListener or something like this have to be coded still in Java. -For this the Android module described below is available to access some of -the hardware in Android devices. +You can access all fields and methods as described in the `Java +Android DisplayMetrics API +`__ +as shown here with the method `setToDefaults()` and the field +`densityDpi`. Before you use a view field, you should always call +`setToDefaults` to initiate to the default values of the device. + +Currently only JavaMethod, JavaStaticMethod, JavaField, +JavaStaticField and JavaMultipleMethod are built into PyJNIus, +therefore such constructs like registerListener or something like this +must still be coded in Java. For this the Android module described +below is available to access some of the hardware on Android devices. .. module:: org.renpy.android diff --git a/docs/source/prerequisites.rst b/docs/source/prerequisites.rst index 54d9366d5e..eb5cd6dcd0 100644 --- a/docs/source/prerequisites.rst +++ b/docs/source/prerequisites.rst @@ -1,18 +1,21 @@ Prerequisites ------------- -.. note:: - There is a VirtualBox Image we provide with the prerequisites along with - Android SDK and NDK preinstalled to ease your installation woes. You can download it from `here `__. +.. note:: There is a VirtualBox Image we provide with the + prerequisites along with the Android SDK and NDK preinstalled to + ease your installation woes. You can download it from `here + `__. .. warning:: - The current version is tested only on Ubuntu oneiric (11.10) and precise - (12.04). If it doesn't work on other platforms, send us patch, not bug - report. Pyhton for Android works on Linux and Mac OSX, not Windows. + The current version is tested only on Ubuntu oneiric (11.10) and + precise (12.04). If it doesn't work on other platforms, send us a + patch, not a bug report. Python for Android works on Linux and Mac + OS X, not Windows. -You need the minimal environment for building python. Note that other libraries -might need other tools (cython is used by some recipes, and ccache to speedup the build):: +You need the minimal environment for building python. Note that other +libraries might need other tools (cython is used by some recipes, and +ccache to speedup the build):: sudo apt-get install build-essential patch git-core ccache ant python-pip python-dev @@ -24,12 +27,13 @@ On debian Squeeze amd64, those packages were found to be necessary :: sudo apt-get install lib32stdc++6 lib32z1 -Ensure you have the latest cython version:: +Ensure you have the latest Cython version:: pip install --upgrade cython -You must have android SDK and NDK. The SDK defines the Android functions you can use. -The NDK is used for compilation. Right now, it's prefered to use: +You must have android SDK and NDK. The SDK defines the Android +functions you can use. The NDK is used for compilation. Right now, +it's preferred to use: - SDK API 8 or 14 (15 will only work with a newly released NDK) - NDK r5b or r7 @@ -42,8 +46,8 @@ You can download them at:: In general, Python for Android currently works with Android 2.3 to L. -If it's your very first time into android SDK, don't forget to follow -documentation for recommended components at:: +If it's your very first time using the Android SDK, don't forget to +follow the documentation for recommended components at:: http://developer.android.com/sdk/installing/adding-packages.html @@ -55,7 +59,8 @@ documentation for recommended components at:: well, so that you can test your application on the full range of Android platform versions that your application supports. -After installing them, export both installation path, NDK version and API to use:: +After installing them, export both installation paths, NDK version, +and API to use:: export ANDROIDSDK=/path/to/android-sdk export ANDROIDNDK=/path/to/android-ndk @@ -68,7 +73,7 @@ After installing them, export both installation path, NDK version and API to use export ANDROIDNDKVER=r7 export ANDROIDAPI=14 -Also, you must configure you're PATH to add the ``android`` binary:: +Also, you must configure your PATH to add the ``android`` binary:: export PATH=$ANDROIDNDK:$ANDROIDSDK/platform-tools:$ANDROIDSDK/tools:$PATH diff --git a/docs/source/usage.rst b/docs/source/usage.rst index d5ecb0b9a0..0b55498cc3 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -4,13 +4,13 @@ Usage Step 1: compile the toolchain ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you want to compile the toolchain with only kivy module:: +If you want to compile the toolchain with only the kivy module:: ./distribute.sh -m "kivy" -After a long time, you'll get a "dist/default" directory containing all the compiled -libraries and build.py script to package your application using thoses -libraries. +After a long time, you'll get a "dist/default" directory containing +all the compiled libraries and a build.py script to package your +application using thoses libraries. You can include other modules (or "recipes") to compile using `-m`:: @@ -23,27 +23,31 @@ You can include other modules (or "recipes") to compile using `-m`:: The list of recipes we currently have is at: https://github.com/kivy/python-for-android/tree/master/recipes -You can also specify a specific version for each package. Please note that the -compilation might **break** if you don't use the default version. Most recipes -have patch to fixes android issues, and might not apply if you specify a -version. We also recommend to clean build/ before changing version.:: +You can also specify a specific version for each package. Please note +that the compilation might **break** if you don't use the default +version. Most recipes have patches to fix Android issues, and might +not apply if you specify a version. We also recommend to clean build +before changing version.:: ./distribute.sh -m "openssl kivy==master" -Python modules that don't need C extrnsions don't need a recipe and can be included this way. -From python-for-android 1.1 on, you can now specify pure-python package into the -distribution. It will use virtualenv and pip to install pure-python modules into the -distribution. Please note that compiler are deactivated, and will break any -module who try to compile something. If compilation is needed, write a recipe:: +Python modules that don't need C extrnsions don't need a recipe and +can be included this way. From python-for-android 1.1 on, you can now +specify pure-python package into the distribution. It will use +virtualenv and pip to install pure-python modules into the +distribution. Please note that the compiler is deactivated, and will +break any module which tries to compile something. If compilation is +needed, write a recipe:: ./distribute.sh -m "requests pygments kivy" .. note:: Recipes download a defined version of their needed package from the - internet, and build from it, if you know what you are doing, and want to - override that, you can export the env variable `P4A_recipe_name_DIR` and - this directory will be copied and used instead. + internet, and build from it. If you know what you are doing, and + want to override that, you can export the env variable + `P4A_recipe_name_DIR` and this directory will be copied and used + instead. Available options to `distribute.sh`:: @@ -57,7 +61,7 @@ Available options to `distribute.sh`:: Step 2: package your application ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Go fo your custom python distribution:: +Go to your custom Python distribution:: cd dist/default @@ -66,16 +70,16 @@ Use the build.py for creating the APK:: ./build.py --package org.test.touchtracer --name touchtracer \ --version 1.0 --dir ~/code/kivy/examples/demo/touchtracer debug -Then, the android package (APK) will be generated at: +Then, the Android package (APK) will be generated at: bin/touchtracer-1.0-debug.apk .. warning:: Some files and modules for python are blacklisted by default to - save a few megabytes on the final apk file, in case your + save a few megabytes on the final APK file. In case your applications doesn't find a standard python module, check the - src/blacklist.txt file remove the module you need from the list, + src/blacklist.txt file, remove the module you need from the list, and try again. Available options to `build.py`::