151 lines
4.8 KiB
ReStructuredText
151 lines
4.8 KiB
ReStructuredText
|
|
distutils/setuptools integration
|
|
================================
|
|
|
|
Have `p4a apk` run setup.py (replaces ``--requirements``)
|
|
---------------------------------------------------------
|
|
|
|
If your project has a `setup.py` file, then it can be executed by
|
|
`p4a` when your app is packaged such that your app properly ends up
|
|
in the packaged site-packages. (Use ``--use-setup-py`` to enable this,
|
|
``--ignore-setup-py`` to prevent it)
|
|
|
|
This is functionality to run **setup.py INSIDE `p4a apk`,** as opposed
|
|
to the other section below, which is about running
|
|
*p4a inside setup.py*.
|
|
|
|
This however has these caveats:
|
|
|
|
- **Only your ``main.py`` from your app's ``--private`` data is copied
|
|
into the .apk!** Everything else needs to be installed by your
|
|
``setup.py`` into the site-packages, or it won't be packaged.
|
|
|
|
- All dependencies that map to recipes can only be pinned to exact
|
|
versions, all other constraints will either just plain not work
|
|
or even cause build errors. (Sorry, our internal processing is
|
|
just not smart enough to honor them properly at this point)
|
|
|
|
- The dependency analysis at the start may be quite slow and delay
|
|
your build
|
|
|
|
Reasons why you would want to use a `setup.py` to be processed (and
|
|
omit specifying ``--requirements``):
|
|
|
|
- You want to use a more standard mechanism to specify dependencies
|
|
instead of ``--requirements``
|
|
|
|
- You already use a `setup.py` for other platforms
|
|
|
|
- Your application imports itself
|
|
in a way that won't work unless installed to site-packages)
|
|
|
|
|
|
Reasons **not** to use a `setup.py` (that is to use the usual
|
|
``--requirements`` mechanism instead):
|
|
|
|
- You don't use a `setup.py` yet, and prefer the simplicity of
|
|
just specifying ``--requirements``
|
|
|
|
- Your `setup.py` assumes a desktop platform and pulls in
|
|
Android-incompatible dependencies, and you are not willing
|
|
to change this, or you want to keep it separate from Android
|
|
deployment for other organizational reasons
|
|
|
|
- You need data files to be around that aren't installed by
|
|
your `setup.py` into the site-packages folder
|
|
|
|
|
|
Use your setup.py to call p4a
|
|
-----------------------------
|
|
|
|
Instead of running p4a via the command line, you can call it via
|
|
`setup.py` instead, by it integrating with distutils and setup.py.
|
|
|
|
This is functionality to run **p4a INSIDE setup.py,** as opposed
|
|
to the other section above, which is about running
|
|
*setup.py inside `p4a apk`*.
|
|
|
|
The base command is::
|
|
|
|
python setup.py apk
|
|
|
|
The files included in the APK will be all those specified in the
|
|
``package_data`` argument to setup. For instance, the following
|
|
example will include all .py and .png files in the ``testapp``
|
|
folder::
|
|
|
|
from distutils.core import setup
|
|
from setuptools import find_packages
|
|
|
|
setup(
|
|
name='testapp_setup',
|
|
version='1.1',
|
|
description='p4a setup.py example',
|
|
author='Your Name',
|
|
author_email='youremail@address.com',
|
|
packages=find_packages(),
|
|
options=options,
|
|
package_data={'testapp': ['*.py', '*.png']}
|
|
)
|
|
|
|
The app name and version will also be read automatically from the
|
|
setup.py.
|
|
|
|
The Android package name uses ``org.test.lowercaseappname``
|
|
if not set explicitly.
|
|
|
|
The ``--private`` argument is set automatically using the
|
|
package_data. You should *not* set this manually.
|
|
|
|
The target architecture defaults to ``--armeabi``.
|
|
|
|
All of these automatic arguments can be overridden by passing them manually on the command line, e.g.::
|
|
|
|
python setup.py apk --name="Testapp Setup" --version=2.5
|
|
|
|
Adding p4a arguments in setup.py
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Instead of providing extra arguments on the command line, you can
|
|
store them in setup.py by passing the ``options`` parameter to
|
|
:code:`setup`. For instance::
|
|
|
|
from distutils.core import setup
|
|
from setuptools import find_packages
|
|
|
|
options = {'apk': {'debug': None, # use None for arguments that don't pass a value
|
|
'requirements': 'sdl2,pyjnius,kivy,python3',
|
|
'android-api': 19,
|
|
'ndk-dir': '/path/to/ndk',
|
|
'dist-name': 'bdisttest',
|
|
}}
|
|
|
|
packages = find_packages()
|
|
print('packages are', packages)
|
|
|
|
setup(
|
|
name='testapp_setup',
|
|
version='1.1',
|
|
description='p4a setup.py example',
|
|
author='Your Name',
|
|
author_email='youremail@address.com',
|
|
packages=find_packages(),
|
|
options=options,
|
|
package_data={'testapp': ['*.py', '*.png']}
|
|
)
|
|
|
|
These options will be automatically included when you run ``python
|
|
setup.py apk``. Any options passed on the command line will override
|
|
these values.
|
|
|
|
Adding p4a arguments in setup.cfg
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can also provide p4a arguments in the setup.cfg file, as normal
|
|
for distutils. The syntax is::
|
|
|
|
[apk]
|
|
|
|
argument=value
|
|
|
|
requirements=sdl2,kivy
|