In order to test a pull request, we recommend to consider the following points:

1. of course, check if the overall thing makes sense
2. is the CI passing? if not what specifically fails
3. is it working locally at compile time?
4. is it working on device at runtime?

This document will focus on the third point: is it working locally at compile time? so we will give some hints about how to proceed in order to create a local copy of the pull requests and build an apk. We expect that the contributors has enough criteria/knowledge to perform the other steps mentioned, so let's begin...

To create an apk from a python-for-android pull request we contemplate three possible scenarios:

• using python-for-android commands directly from the pull request files that we want to test, without installing it (the recommended way for most of the test cases)
• installing python-for-android using the github's branch of the pull request
• using buildozer and a custom app

We will explain the first two methods using one of the distributed python-for-android test apps and we assume that you already have the python-for-android dependencies installed. For the buildozer method we also expect that you already have a a properly working app to test and a working installation/configuration of buildozer. There is one step that it's shared with all the testing methods that we propose in here...we named it Common steps.

The first step to do it's to get a copy of the pull request, we can do it of several ways, and that it will depend of the circumstances but all the methods presented here will do the job, so...

For the example, we will use 1901 for the example) and the pull request branch that we will use is feature-fix-numpy, then you will use a variation of the following git command: git fetch origin pull/<#>/head:<local_branch_name>, eg.:

.. codeblock:: bash

    git fetch upstream pull/1901/head:feature-fix-numpy

.. codeblock:: bash

    git remote add obiwankenobi https://github.com/obiwankenobi/python-for-android.git

.. codeblock:: bash

    git fetch obiwankenobi
    git checkout obiwankenobi/feature-fix-numpy

Sometimes you may prefer to use directly the fork of the user, so you will get the nickname of the user who created the pull request, let's take the same imaginary user than before obiwankenobi:

.. codeblock:: bash

    git clone -b feature-fix-numpy \
        --single-branch \
        https://github.com/obiwankenobi/python-for-android.git \
        p4a-feature-fix-numpy

Here's the above command explained line by line:

• git clone -b feature-fix-numpy: we tell git that we want to clone the branch named feature-fix-numpy
• --single-branch: we tell git that we only want that branch
• https://github.com/obiwankenobi/python-for-android.git: noticed the nickname of the user that created the pull request: obiwankenobi in the middle of the line? that should be changed as needed for each pull request that you want to test
• p4a-feature-fix-numpy: the name of the cloned repository, so we can have multiple clones of different prs in the same folder

• Enter inside the directory of the cloned repository in the above step and run p4a command with proper args, eg:

  .. codeblock:: bash
  
      cd p4a-feature-fix-numpy
      PYTHONPATH=. python3 -m pythonforandroid.toolchain apk \
          --private=testapps/testapp_sqlite_openssl \
          --dist-name=dist_test_app_python3_libs \
          --package=org.kivy \
          --name=test_app_python3_sqlite_openssl \
          --version=0.1 \
          --requirements=requests,peewee,sdl2,pyjnius,kivy,python3 \
          --ndk-dir=/media/DEVEL/Android/android-ndk-r20 \
          --sdk-dir=/media/DEVEL/Android/android-sdk-linux \
          --android-api=27 \
          --arch=arm64-v8a \
          --permission=INTERNET \
          --debug
  

Things that you should know:

• The example above will build an testapp we will make use of the files of the testapp named testapp_sqlite_openssl.py but we don't use the setup file to build it so we must tell python-for-android what we want via arguments

• be sure to at least edit the following arguments when running the above command, since the default set in there it's unlikely that match your installation:

  • --ndk-dir: An absolute path to your android's NDK dir
  • --sdk-dir: An absolute path to your android's SDK dir
  • --debug: this one enables the debug mode of python-for-android, which will show all log messages of the build. You can omit this one but it's worth it to be mentioned, since this it's useful to us when trying to find the source of the problem when things goes wrong

• The apk generated by the above command should be located at the root of of the cloned repository, were you run the command to build the apk

• The testapps distributed with python-for-android are located at testapps folder under the main folder project

• All the builds of python-for-android are located at ~/.local/share/python-for-android

• You should have a downloaded copy of the android's NDK and SDK

• Enter inside the directory of the cloned repository mentioned in Common steps and install it via pip, eg.:

  .. codeblock:: bash
  
      cd p4a-feature-fix-numpy
      pip3 install . --upgrade --user
  

• Now, go inside the testapps directory (we assume that you still are inside the cloned repository):

  .. codeblock:: bash
  
      cd testapps
  

• Run the build of the apk via the freshly installed copy of python-for-android by running a similar command than below:

  .. code-block:: bash
  
      python3 setup_testapp_python3_sqlite_openssl.py apk \
          --ndk-dir=/media/DEVEL/Android/android-ndk-r20 \
          --sdk-dir=/media/DEVEL/Android/android-sdk-linux \
          --android-api=27 \
          --arch=arm64-v8a \
          --debug
  

Things that you should know:

• In the example above, we override some variables that are set in setup_testapp_python3_sqlite_openssl.py, you could also override them by editing this file

• be sure to at least edit the following arguments when running the above command, since the default set in there it's unlikely that match your installation:

  • --ndk-dir: An absolute path to your android's NDK dir
  • --sdk-dir: An absolute path to your android's SDK dir

• Edit your buildozer.spec file. You should search for the key p4a.source_dir and set the right value so in the example posted in Common steps it would look like this:

  p4a.source_dir = /home/user/p4a_pull_requests/p4a-feature-fix-numpy
  

• Run you buildozer command as usual, eg.:

  buildozer android debug p4a --dist-name=dist-test-feature-fix-numpy