From fa93bc843767a9748ec8c0c4bc8fef0ee791ef30 Mon Sep 17 00:00:00 2001 From: Peter Badida Date: Tue, 5 Jul 2016 09:22:59 +0200 Subject: [PATCH] Add docs for launcher --- doc/source/index.rst | 1 + doc/source/launcher.rst | 154 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 doc/source/launcher.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index c7ec2cf922..670a3c24ea 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -32,6 +32,7 @@ Contents recipes bootstraps services + launcher apis troubleshooting contribute diff --git a/doc/source/launcher.rst b/doc/source/launcher.rst new file mode 100644 index 0000000000..634448fea7 --- /dev/null +++ b/doc/source/launcher.rst @@ -0,0 +1,154 @@ +.. _launcher: + +Launcher +======== + +.. note:: + + This form of packaging creates an APK that allows quick and dirty testing + of your android applications. Do not use in production! + +.. warning:: + + Using the launcher in production gives the end-user easy access to your + source code. + +The Kivy Launcher is an Android application that can run any Kivy app +stored in `kivy` folder on SD Card. You can download the latest stable +version for your android device from the +`Play Store `_. + +The stable launcher comes with various packages usually listed in the +description in the store. Those aren't always enough for an application to run +or even launch if you work with other dependencies that are not packaged. + +Permissions +----------- + +The stable launcher has these permissions: + + - ACCESS_COARSE_LOCATION + - ACCESS_FINE_LOCATION + - BLUETOOTH + - INTERNET + - READ_EXTERNAL_STORAGE + - RECORD_AUDIO + - VIBRATE + - WRITE_EXTERNAL_STORAGE + +.. |perm_docs| replace:: android documentation + +.. _perm_docs: + https://developer.android.com/guide/topics/security/permissions.html + +Check the other available permissions in the |perm_docs|_. + +Packages +-------- + +The launcher by default provides access to these packages: + + - audiostream + - cymunk + - docutils + - ffmpeg + - kivy + - lxml + - openssl + - pil + - plyer + - pygments + - pyjnius + - pyopenssl + - sqlite3 + - twisted + +Building +-------- + +To keep up with the most recent Kivy and be able to run more than one app +without building over and over a launcher with kivy `master` branch together +with additional packager most of your apps use are necessary. To build it +you'll need pygame bootstrap (launcher is not available in sdl2 yet). To get +the most recent versions of packages you need to clean them first, so that +the packager won't grab an old package instead of fresh one. + +.. highlight:: none + +:: + + p4a clean_dists + p4a clean_builds + p4a apk --requirements=requirements \ + --permission PERMISSION \ + --package=the.package.name \ + --name="App name" \ + --version=x.y.z \ + --android_api XY \ + --bootstrap=pygame \ + --launcher \ + --minsdk 13 + +.. note:: + + `--minsdk 13` is necessary for the new toolchain, otherwise you'll be able + to run apps only in `landscape` orientation. + +.. warning:: + + Do not use any of `--private`, `--public`, `--dir` or other arguments for + adding `main.py` or `main.pyo` to the app. The argument `--launcher` is + above them and tells the p4a to build the launcher version of the APK. + +The power of the launcher is in its capability to run multiple apps from +source, which means the more packages you include, the more stable your +installation will be and the less times you'll need to update it or do anything +else with it except running apps. The necessary stuff is about 6 - 8MB big and +additional packages won't increase the size that much, which is definitelly +an advantage if there are more than two apps for testing. + +Usage +----- + +Once the launcher is installed, you need to create a folder on your sdcard +(`/sdcard/kivy`). Each new folder inside `kivy` represents a separate +application. + +:: + + /sdcard/kivy/ + +To tell the launcher to even see your application you have to have +`android.txt` file in your app's folder. The file has to contain three basic +lines:: + + title= + author= + orientation= + +The file is editable so you can change for example orientation or name. You +aren't allowed to change permissions however, so before building the launcher +decide carefully what permissions do you need. + +After you set your `android.txt` file, you can now run the launcher and start +any available app from the list. + +Release on the market +--------------------- + +Launcher is released on Google Play with each new Kivy stable branch. Master +branch is not suitable for a regular user because it changes quickly and needs +testing. + +Source code +----------- + +.. |renpy| replace:: pygame org.renpy.android + +.. _renpy: + https://github.com/kivy/python-for-android/tree/master/\ + pythonforandroid/bootstraps/pygame/build/src/org/renpy/android + +If you feel confident, feel free to improve the launcher. You can find the +source code at |renpy|_. Change the link if you want to contribute to other +than pygame bootstrap.