add service_lib and aar to the docs (#2634)

* add service_lib and aar to the docs

* Update doc/source/quickstart.rst

Co-authored-by: Mirko Galimberti <[email protected]>

* Update doc/source/buildoptions.rst

Co-authored-by: Mirko Galimberti <[email protected]>

* add PATH_TO_SERVICE_PY

* Update doc/source/services.rst

Co-authored-by: Mirko Galimberti <[email protected]>

Co-authored-by: Mirko Galimberti <[email protected]>

Author: mzakharo

doc/source/buildoptions.rst

@@ -11,12 +11,10 @@ Python versions
 python-for-android supports using Python 3.7 or higher. To explicitly select a Python
 version in your requirements, use e.g. ``--requirements=python3==3.7.1,hostpython3==3.7.1``.
 
-The last python-for-android version supporting Python2 was `v2019.10.06
-          <https://github.com/kivy/python-for-android/archive/v2019.10.06.zip>`__
+The last python-for-android version supporting Python2 was `v2019.10.06 <https://github.com/kivy/python-for-android/archive/v2019.10.06.zip>`__
 
 Python-for-android no longer supports building for Python 3 using the CrystaX
-NDK. The last python-for-android version supporting CrystaX was `0.7.0.
-          <https://github.com/kivy/python-for-android/archive/0.7.0.zip>`__
+NDK. The last python-for-android version supporting CrystaX was `0.7.0 <https://github.com/kivy/python-for-android/archive/0.7.0.zip>`__
 
 .. _bootstrap_build_options:
 
@@ -156,47 +154,29 @@ ready.
   access. Defaults to 5000.
 
 
-Build options
-%%%%%%%%%%%%%
+service_library
+~~~~~~~~~~~~~~~
 
-The sdl2 bootstrap supports the following additional command line
-options (this list may not be exhaustive):
+You can use this with ``--bootstrap=service_library`` option.
+
+
+This bootstrap can be used together with ``aar`` output target to generate
+a library, containing Python services that can be used with other build 
+systems and frameworks.
 
 - ``--private``: The directory containing your project files.
-- ``--dir``: The directory containing your project files if you want
-  them to be unpacked to the external storage directory rather than
-  the app private directory.
 - ``--package``: The Java package name for your project. e.g. ``org.example.yourapp``.
-- ``--name``: The app name.
+- ``--name``: The library name.
 - ``--version``: The version number.
-- ``--orientation``: One of ``portait``, ``landscape`` or ``sensor``
-  to automatically rotate according to the device orientation.
-- ``--icon``: A path to the png file to use as the application icon.
-- ``--ignore-path``: A path to ignore when including the app
-  files. Pass multiple times to ignore multiple paths.
-- ``-- permission``: A permission name for the app,
-  e.g. ``--permission VIBRATE``. For multiple permissions, add
-  multiple ``--permission`` arguments.
-- ``--meta-data``: Custom key=value pairs to add in the application metadata.
-- ``--presplash``: A path to the image file to use as a screen while
-  the application is loading.
-- ``--wakelock``: If the argument is included, the application will
-  prevent the device from sleeping.
-- ``--window``: If the argument is included, the application will not
-  cover the Android status bar.
+- ``--service``: A service name and the Python script it should
+  run. See :ref:`arbitrary_scripts_services`.
 - ``--blacklist``: The path to a file containing blacklisted patterns
-  that will be excluded from the final APK. Defaults to ``./blacklist.txt``.
+  that will be excluded from the final AAR. Defaults to ``./blacklist.txt``.
 - ``--whitelist``: The path to a file containing whitelisted patterns
-  that will be included in the APK even if also blacklisted.
+  that will be included in the AAR even if also blacklisted.
 - ``--add-jar``: The path to a .jar file to include in the APK. To
   include multiple jar files, pass this argument multiple times.
-- ``--intent-filters``: A file path containing intent filter xml to be
-  included in AndroidManifest.xml.
-- ``--service``: A service name and the Python script it should
-  run. See :ref:`arbitrary_scripts_services`.
 - ``add-source``: Add a source directory to the app's Java code.
-- ``--compile-pyo``: Optimise .py files to .pyo.
-- ``--resource``: A key=value pair to add in the string.xml resource file.
 
 
 Requirements blacklist (APK size optimization)

doc/source/quickstart.rst

@@ -26,7 +26,7 @@ Concepts
 
 - **bootstrap:** A bootstrap is the app backend that will start your
   application. The default for graphical applications is SDL2.
-  You can also use e.g. the webview for web apps, or service_only for
+  You can also use e.g. the webview for web apps, or service_only/service_library  for
   background services. Different bootstraps have different additional
   build options.
 
@@ -213,6 +213,19 @@ You can also replace flask with another web framework.
 Replace ``--port=5000`` with the port on which your app will serve a
 website. The default for Flask is 5000.
 
+
+Build a Service library archive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To build an android archive (.aar), containing an android service , you need a name, version, package identifier, explicitly use the 
+service_library bootstrap, and declare service entry point (See :ref:`services <arbitrary_scripts_services>` for more options), as well as the requirements and arch(s)::
+
+    p4a aar --private $HOME/code/myapp --package=org.example.myapp --name "My library" --version 0.1 --bootstrap=service_library --requirements=python3 --release --service=myservice:service.py --arch=arm64-v8a --arch=armeabi-v7a
+
+
+You can then call the generated Java entrypoint(s) for your Python service(s) in other apk build frameworks.
+
+
 Exporting the Android App Bundle (aab) for distributing it on Google Play
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/services.rst

@@ -52,11 +52,23 @@ more flexible, supporting multiple services and a wider range of
 options.
 
 To create the service, create a python script with your service code
-and add a :code:`--service=myservice:/path/to/myservice.py` argument
+and add a :code:`--service=myservice:PATH_TO_SERVICE_PY` argument
 when calling python-for-android, or in buildozer.spec, a
-:code:`services = myservice:/path/to/myservice.py` [app] setting.
+:code:`services = myservice:PATH_TO_SERVICE_PY` [app] setting.
+
 The ``myservice`` name before the colon is the name of the service
-class, via which you will interact with it later. You can add multiple
+class, via which you will interact with it later. 
+
+The ``PATH_TO_SERVICE_PY`` is the relative path to the service entry point (like ``services/myservice.py``)
+
+You can optionally specify the following parameters:
+ - :code:`:foreground` for launching a service as an Android foreground service
+ - :code:`:sticky` for launching a service that gets restarted by the Android OS on exit/error
+
+Full command with all the optional parameters included would be: 
+:code:`--service=myservice:services/myservice.py:foreground:sticky`
+
+You can add multiple
 :code:`--service` arguments to include multiple services, or separate
 them with a comma in buildozer.spec, all of which you will later be
 able to stop and start from your app.