Skip to content

Commit 048a734

Browse files
inclementinclement
committed
Merge branch 'docs_launcher' of https://github.com/KeyWeeUsr/python-for-android into KeyWeeUsr-docs_launcher
2 parents 70b324b + fa93bc8 commit 048a734

File tree

2 files changed

+155
-0
lines changed

2 files changed

+155
-0
lines changed

‎doc/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Contents
3232
recipes
3333
bootstraps
3434
services
35+
launcher
3536
apis
3637
troubleshooting
3738
contribute

‎doc/source/launcher.rst

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
.. _launcher:
2+
3+
Launcher
4+
========
5+
6+
.. note::
7+
8+
This form of packaging creates an APK that allows quick and dirty testing
9+
of your android applications. Do not use in production!
10+
11+
.. warning::
12+
13+
Using the launcher in production gives the end-user easy access to your
14+
source code.
15+
16+
The Kivy Launcher is an Android application that can run any Kivy app
17+
stored in `kivy` folder on SD Card. You can download the latest stable
18+
version for your android device from the
19+
`Play Store <https://play.google.com/store/apps/details?id=org.kivy.pygame>`_.
20+
21+
The stable launcher comes with various packages usually listed in the
22+
description in the store. Those aren't always enough for an application to run
23+
or even launch if you work with other dependencies that are not packaged.
24+
25+
Permissions
26+
-----------
27+
28+
The stable launcher has these permissions:
29+
30+
- ACCESS_COARSE_LOCATION
31+
- ACCESS_FINE_LOCATION
32+
- BLUETOOTH
33+
- INTERNET
34+
- READ_EXTERNAL_STORAGE
35+
- RECORD_AUDIO
36+
- VIBRATE
37+
- WRITE_EXTERNAL_STORAGE
38+
39+
.. |perm_docs| replace:: android documentation
40+
41+
.. _perm_docs:
42+
https://developer.android.com/guide/topics/security/permissions.html
43+
44+
Check the other available permissions in the |perm_docs|_.
45+
46+
Packages
47+
--------
48+
49+
The launcher by default provides access to these packages:
50+
51+
- audiostream
52+
- cymunk
53+
- docutils
54+
- ffmpeg
55+
- kivy
56+
- lxml
57+
- openssl
58+
- pil
59+
- plyer
60+
- pygments
61+
- pyjnius
62+
- pyopenssl
63+
- sqlite3
64+
- twisted
65+
66+
Building
67+
--------
68+
69+
To keep up with the most recent Kivy and be able to run more than one app
70+
without building over and over a launcher with kivy `master` branch together
71+
with additional packager most of your apps use are necessary. To build it
72+
you'll need pygame bootstrap (launcher is not available in sdl2 yet). To get
73+
the most recent versions of packages you need to clean them first, so that
74+
the packager won't grab an old package instead of fresh one.
75+
76+
.. highlight:: none
77+
78+
::
79+
80+
p4a clean_dists
81+
p4a clean_builds
82+
p4a apk --requirements=requirements \
83+
--permission PERMISSION \
84+
--package=the.package.name \
85+
--name="App name" \
86+
--version=x.y.z \
87+
--android_api XY \
88+
--bootstrap=pygame \
89+
--launcher \
90+
--minsdk 13
91+
92+
.. note::
93+
94+
`--minsdk 13` is necessary for the new toolchain, otherwise you'll be able
95+
to run apps only in `landscape` orientation.
96+
97+
.. warning::
98+
99+
Do not use any of `--private`, `--public`, `--dir` or other arguments for
100+
adding `main.py` or `main.pyo` to the app. The argument `--launcher` is
101+
above them and tells the p4a to build the launcher version of the APK.
102+
103+
The power of the launcher is in its capability to run multiple apps from
104+
source, which means the more packages you include, the more stable your
105+
installation will be and the less times you'll need to update it or do anything
106+
else with it except running apps. The necessary stuff is about 6 - 8MB big and
107+
additional packages won't increase the size that much, which is definitelly
108+
an advantage if there are more than two apps for testing.
109+
110+
Usage
111+
-----
112+
113+
Once the launcher is installed, you need to create a folder on your sdcard
114+
(`/sdcard/kivy`). Each new folder inside `kivy` represents a separate
115+
application.
116+
117+
::
118+
119+
/sdcard/kivy/<yourapplication>
120+
121+
To tell the launcher to even see your application you have to have
122+
`android.txt` file in your app's folder. The file has to contain three basic
123+
lines::
124+
125+
title=<Application Title>
126+
author=<Your Name>
127+
orientation=<portrait|landscape>
128+
129+
The file is editable so you can change for example orientation or name. You
130+
aren't allowed to change permissions however, so before building the launcher
131+
decide carefully what permissions do you need.
132+
133+
After you set your `android.txt` file, you can now run the launcher and start
134+
any available app from the list.
135+
136+
Release on the market
137+
---------------------
138+
139+
Launcher is released on Google Play with each new Kivy stable branch. Master
140+
branch is not suitable for a regular user because it changes quickly and needs
141+
testing.
142+
143+
Source code
144+
-----------
145+
146+
.. |renpy| replace:: pygame org.renpy.android
147+
148+
.. _renpy:
149+
https://github.com/kivy/python-for-android/tree/master/\
150+
pythonforandroid/bootstraps/pygame/build/src/org/renpy/android
151+
152+
If you feel confident, feel free to improve the launcher. You can find the
153+
source code at |renpy|_. Change the link if you want to contribute to other
154+
than pygame bootstrap.

0 commit comments

Comments
 (0)