Skip to content

Commit d48b38a

Browse files
inclementinclement
committed
Added build option documentation
1 parent f7aba8a commit d48b38a

File tree

4 files changed

+139
-26
lines changed

4 files changed

+139
-26
lines changed

‎doc/source/buildoptions.rst‎

Lines changed: 123 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,11 @@
22
Build options
33
=============
44

5-
This page contains instructions for using some of the specific python-for-android build options.
5+
This page contains instructions for using different build options.
66

77

8-
Python version
9-
--------------
10-
11-
python-for-android now supports building APKs with either python2 or
12-
python3, but these have extra requirements or potential disadvantages
13-
as below.
14-
8+
Python versions
9+
---------------
1510

1611
python2
1712
~~~~~~~
@@ -52,25 +47,19 @@ there may be bugs or surprising behaviours. If you come across any,
5247
feel free to `open an issue
5348
<https://github.com/kivy/python-for-android>`__.
5449

55-
As this build is experimental, some features are missing and
56-
the build is not fully optimised so APKs are probably a little larger
57-
and slower than they need to be. This is currently being addressed,
58-
though it's not clear how the final result will compare to python2.
59-
6050
.. _bootstrap_build_options:
6151

62-
Bootstrap
63-
---------
52+
Bootstrap options
53+
-----------------
6454

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.
55+
python-for-android supports multiple app backends with different types
56+
of interface. These are called *bootstraps*.
6857

6958
Currently the following bootstraps are supported, but we hope that it
7059
it should be easy to add others if your project has different
7160
requirements. `Let us know
72-
<https://groups.google.com/forum/#!forum/python-android>`__ if there
73-
are any improvements that would help here.
61+
<https://groups.google.com/forum/#!forum/python-android>`__ if you'd
62+
like help adding a new one.
7463

7564
sdl2
7665
~~~~
@@ -89,6 +78,45 @@ and have them work with this bootstrap. It should also be possible to
8978
use e.g. pygame_sdl2, but this would need a build recipe and doesn't
9079
yet have one.
9180

81+
Build options
82+
%%%%%%%%%%%%%
83+
84+
The sdl2 bootstrap supports the following additional command line
85+
options (this list may not be exhaustive):
86+
87+
- ``--private``: The directory containing your project files.
88+
- ``--package``: The Java package name for your project. Choose e.g. ``org.example.yourapp``.
89+
- ``--name``: The app name.
90+
- ``--version``: The version number.
91+
- ``--orientation``: One of ``portait``, ``landscape`` or ``sensor``
92+
to automatically rotate according to the device orientation.
93+
- ``--icon``: A path to the png file to use as the application icon.
94+
- ``-- permission``: A permission name for the app,
95+
e.g. ``--permission VIBRATE``. For multiple permissions, add
96+
multiple ``--permission`` arguments.
97+
- ``--meta-data``: Custom key=value pairs to add in the application metadata.
98+
- ``--presplash``: A path to the image file to use as a screen while
99+
the application is loading.
100+
- ``--presplash-color``: The presplash screen background color, of the
101+
form ``#RRGGBB`` or a color name ``red``, ``green``, ``blue`` etc.
102+
- ``--wakelock``: If the argument is included, the application will
103+
prevent the device from sleeping.
104+
- ``--window``: If the argument is included, the application will not
105+
cover the Android status bar.
106+
- ``--blacklist``: The path to a file containing blacklisted patterns
107+
that will be excluded from the final APK. Defaults to ``./blacklist.txt``.
108+
- ``--whitelist``: The path to a file containing whitelisted patterns
109+
that will be included in the APK even if also blacklisted.
110+
- ``--add-jar``: The path to a .jar file to include in the APK. To
111+
include multiple jar files, pass this argument multiple times.
112+
- ``--intent-filters``: A file path containing intent filter xml to be
113+
included in AndroidManifest.xml.
114+
- ``--service``: A service name and the Python script it should
115+
run. See :ref:`arbitrary_scripts_services`.
116+
- ``--add-source``: Add a source directory to the app's Java code.
117+
- ``--no-compile-pyo``: Do not optimise .py files to .pyo.
118+
119+
92120
webview
93121
~~~~~~~
94122

@@ -112,6 +140,39 @@ present (e.g. during the short Python loading time when first
112140
started), it will instead display a loading screen until the server is
113141
ready.
114142

143+
- ``--private``: The directory containing your project files.
144+
- ``--package``: The Java package name for your project. Choose e.g. ``org.example.yourapp``.
145+
- ``--name``: The app name.
146+
- ``--version``: The version number.
147+
- ``--orientation``: One of ``portait``, ``landscape`` or ``sensor``
148+
to automatically rotate according to the device orientation.
149+
- ``--icon``: A path to the png file to use as the application icon.
150+
- ``-- permission``: A permission name for the app,
151+
e.g. ``--permission VIBRATE``. For multiple permissions, add
152+
multiple ``--permission`` arguments.
153+
- ``--meta-data``: Custom key=value pairs to add in the application metadata.
154+
- ``--presplash``: A path to the image file to use as a screen while
155+
the application is loading.
156+
- ``--presplash-color``: The presplash screen background color, of the
157+
form ``#RRGGBB`` or a color name ``red``, ``green``, ``blue`` etc.
158+
- ``--wakelock``: If the argument is included, the application will
159+
prevent the device from sleeping.
160+
- ``--window``: If the argument is included, the application will not
161+
cover the Android status bar.
162+
- ``--blacklist``: The path to a file containing blacklisted patterns
163+
that will be excluded from the final APK. Defaults to ``./blacklist.txt``.
164+
- ``--whitelist``: The path to a file containing whitelisted patterns
165+
that will be included in the APK even if also blacklisted.
166+
- ``--add-jar``: The path to a .jar file to include in the APK. To
167+
include multiple jar files, pass this argument multiple times.
168+
- ``--intent-filters``: A file path containing intent filter xml to be
169+
included in AndroidManifest.xml.
170+
- ``--service``: A service name and the Python script it should
171+
run. See :ref:`arbitrary_scripts_services`.
172+
- ``add-source``: Add a source directory to the app's Java code.
173+
- ``--port``: The port on localhost that the WebView will
174+
access. Defaults to 5000.
175+
115176

116177
pygame
117178
~~~~~~
@@ -126,3 +187,45 @@ apps, but hasn't been developed with this in mind.
126187
This bootstrap will eventually be deprecated in favour of sdl2, but
127188
not before the sdl2 bootstrap includes all the features that would be
128189
lost.
190+
191+
Build options
192+
%%%%%%%%%%%%%
193+
194+
The pygame bootstrap supports the following additional command line
195+
options (this list may not be exhaustive):
196+
197+
- ``--private``: The directory containing your project files.
198+
- ``--dir``: The directory containing your project files if you want
199+
them to be unpacked to the external storage directory rather than
200+
the app private directory.
201+
- ``--package``: The Java package name for your project. Choose e.g. ``org.example.yourapp``.
202+
- ``--name``: The app name.
203+
- ``--version``: The version number.
204+
- ``--orientation``: One of ``portait``, ``landscape`` or ``sensor``
205+
to automatically rotate according to the device orientation.
206+
- ``--icon``: A path to the png file to use as the application icon.
207+
- ``--ignore-path``: A path to ignore when including the app
208+
files. Pass multiple times to ignore multiple paths.
209+
- ``-- permission``: A permission name for the app,
210+
e.g. ``--permission VIBRATE``. For multiple permissions, add
211+
multiple ``--permission`` arguments.
212+
- ``--meta-data``: Custom key=value pairs to add in the application metadata.
213+
- ``--presplash``: A path to the image file to use as a screen while
214+
the application is loading.
215+
- ``--wakelock``: If the argument is included, the application will
216+
prevent the device from sleeping.
217+
- ``--window``: If the argument is included, the application will not
218+
cover the Android status bar.
219+
- ``--blacklist``: The path to a file containing blacklisted patterns
220+
that will be excluded from the final APK. Defaults to ``./blacklist.txt``.
221+
- ``--whitelist``: The path to a file containing whitelisted patterns
222+
that will be included in the APK even if also blacklisted.
223+
- ``--add-jar``: The path to a .jar file to include in the APK. To
224+
include multiple jar files, pass this argument multiple times.
225+
- ``--intent-filters``: A file path containing intent filter xml to be
226+
included in AndroidManifest.xml.
227+
- ``--service``: A service name and the Python script it should
228+
run. See :ref:`arbitrary_scripts_services`.
229+
- ``add-source``: Add a source directory to the app's Java code.
230+
- ``--compile-pyo``: Optimise .py files to .pyo.
231+
- ``--resource``: A key=value pair to add in the string.xml resource file.

‎doc/source/quickstart.rst‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -128,13 +128,13 @@ well as the requirements::
128128

129129
You can also replace flask with another web framework.
130130

131-
Replace ``--port=5000`` with the port your app will serve a website
132-
on. The default for Flask is 5000.
131+
Replace ``--port=5000`` with the port on which your app will serve a
132+
website. The default for Flask is 5000.
133133

134134
Build an SDL2 based application
135135
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136136

137-
This includes `Vispy <http://vispy.org/>`__ and `PySDL2
137+
This includes e.g. `PySDL2
138138
<https://pysdl2.readthedocs.io/en/latest/>`__.
139139

140140
To build your application, you need to have a name, version, a package
@@ -145,6 +145,14 @@ requirements::
145145

146146
Add your required modules in place of ``your_requirements``,
147147
e.g. ``--requirements=pysdl2`` or ``--requirements=vispy``.
148+
149+
Other options
150+
~~~~~~~~~~~~~
151+
152+
You can pass other command line arguments to control app behaviours
153+
such as orientation, wakelock and app permissions. See
154+
:ref:`bootstrap_build_options`.
155+
148156

149157

150158
Rebuild everything

‎doc/source/services.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,10 @@ you wish to use this method)::
3939
description='service description',
4040
arg='argument to service')
4141

42-
Arbitrary scripts
43-
~~~~~~~~~~~~~~~~~
42+
.. _arbitrary_scripts_services:
43+
44+
Arbitrary service scripts
45+
~~~~~~~~~~~~~~~~~~~~~~~~~
4446

4547
.. note:: This service method is *not supported* by the Pygame bootstrap.
4648

‎pythonforandroid/bootstraps/sdl2/build/build.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -425,7 +425,7 @@ def parse_args(args=None):
425425
'application is loading.'))
426426
ap.add_argument('--presplash-color', dest='presplash_color', default='#000000',
427427
help=('A string to set the loading screen background color. '
428-
'Suported formats are: #RRGGBB #AARRGGBB or color names '
428+
'Supported formats are: #RRGGBB #AARRGGBB or color names '
429429
'like red, green, blue, etc.'))
430430
ap.add_argument('--wakelock', dest='wakelock', action='store_true',
431431
help=('Indicate if the application needs the device '

0 commit comments

Comments
 (0)