Merge branch 'upstream_develop' into develop

Author: broccoliboy

.github/workflows/push.yml

@@ -30,9 +30,26 @@ jobs:
         pip install tox>=2.0
         tox -e pep8
 
+  spotless:
+    name: Java Spotless check
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout python-for-android
+      uses: actions/checkout@v5
+    - name: Set up Java 17
+      uses: actions/setup-java@v4
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+    - name: Set up Gradle
+      uses: gradle/actions/setup-gradle@v4
+    - name: Run Spotless check
+      working-directory: pythonforandroid/bootstraps
+      run: ./common/build/gradlew spotlessCheck
+
   test:
     name: Pytest [Python ${{ matrix.python-version }} | ${{ matrix.os }}]
-    needs: flake8
+    needs: [flake8, spotless]
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -61,9 +78,8 @@ jobs:
 
   ubuntu_build:
     name: Build test APP [ ${{ matrix.runs_on }} | ${{ matrix.bootstrap.name }} ]
-    needs: [flake8]
+    needs: [flake8, spotless]
     runs-on: ${{ matrix.runs_on }}
-    continue-on-error: true
     strategy:
       matrix:
         runs_on: [ubuntu-latest]
@@ -79,6 +95,16 @@ jobs:
           - name: qt
             target: testapps-qt
     steps:
+    - name: Maximize build space
+      uses: easimon/maximize-build-space@v10
+      with:
+        root-reserve-mb: 30720
+        swap-size-mb: 1024
+        remove-dotnet: 'true'
+        remove-android: 'true'
+        remove-haskell: 'true'
+        remove-codeql: 'true'
+        remove-docker-images: 'true'
     - name: Checkout python-for-android
       uses: actions/checkout@v5
     - name: Build python-for-android docker image
@@ -111,9 +137,8 @@ jobs:
 
   macos_build:
     name: Build test APP [ ${{ matrix.runs_on }} | ${{ matrix.bootstrap.name }} ]
-    needs: [flake8]
+    needs: [flake8, spotless]
     runs-on: ${{ matrix.runs_on }}
-    continue-on-error: true
     strategy:
       matrix:
         # macos-latest (ATM macos-15) runs on Apple Silicon,
@@ -186,28 +211,30 @@ jobs:
 
   ubuntu_rebuild_updated_recipes:
     name: Test updated recipes for arch ${{ matrix.android_arch }} [ ubuntu-latest ]
-    needs: [flake8]
+    needs: [flake8, spotless]
     runs-on: ubuntu-latest
+    # continue on error to see failures across all architectures
     continue-on-error: true
     strategy:
       matrix:
         android_arch: ["arm64-v8a", "armeabi-v7a", "x86_64", "x86"]
     env:
       REBUILD_UPDATED_RECIPES_EXTRA_ARGS: --arch=${{ matrix.android_arch }}
     steps:
+    - name: Maximize build space
+      uses: easimon/maximize-build-space@v10
+      with:
+        root-reserve-mb: 30720
+        swap-size-mb: 1024
+        remove-dotnet: 'true'
+        remove-android: 'true'
+        remove-haskell: 'true'
+        remove-codeql: 'true'
+        remove-docker-images: 'true'
     - name: Checkout python-for-android (all-history)
       uses: actions/checkout@v5
       with:
         fetch-depth: 0
-    # helps with GitHub runner getting out of space
-    - name: Free disk space
-      run: |
-        df -h
-        sudo swapoff -a
-        sudo rm -f /swapfile
-        sudo apt -y clean
-        docker images -q | xargs -r docker rmi
-        df -h
     - name: Pull docker image
       run: |
         make docker/pull
@@ -217,8 +244,9 @@ jobs:
 
   macos_rebuild_updated_recipes:
     name: Test updated recipes for arch ${{ matrix.android_arch }} [ ${{ matrix.runs_on }} ]
-    needs: [flake8]
+    needs: [flake8, spotless]
     runs-on: ${{ matrix.runs_on }}
+    # continue on error to see failures across all architectures
     continue-on-error: true
     strategy:
       matrix:

.gitignore

@@ -36,5 +36,9 @@ coverage.xml
 # testapp's build folder
 testapps/build/
 
+# Gradle build artifacts (Java linting)
+pythonforandroid/bootstraps/.gradle/
+pythonforandroid/bootstraps/build/
+
 # Dolphin (the KDE file manager autogenerates the file `.directory`)
 .directory

CONTRIBUTING.md

@@ -66,6 +66,60 @@ latest python-for-android release that supported building Python 2 was version
 On August 2021, we added support for Android App Bundle (aab). As a
 collateral benefit, we now support multi-arch apk.
 
+## Code Quality
+
+### Python Linting
+
+Python code is linted using flake8. Run it locally with:
+
+```bash
+tox -e pep8
+```
+
+### Java Linting
+
+Java source files in the bootstrap directories are linted using
+[Spotless](https://github.com/diffplug/spotless) with Google Java Format
+(AOSP style). The CI runs this check automatically.
+
+**Local execution** (requires Java 17+):
+
+```bash
+# Check for violations
+make java-lint
+
+# Auto-fix violations
+make java-lint-fix
+```
+
+The Makefile uses the Gradle wrapper (`gradlew`), which automatically downloads
+the correct Gradle version on first run. No manual Gradle installation is required.
+
+**Using Docker** (if you don't have Java 17):
+
+```bash
+# Check for violations
+make docker/java-lint
+
+# Auto-fix violations
+make docker/java-lint-fix
+```
+
+The Docker approach builds the project's Docker image (which includes Java 17)
+and runs the linting inside the container.
+
+**What gets linted:**
+
+- All `.java` files in `pythonforandroid/bootstraps/*/build/src/main/java/`
+- Excludes third-party code (`org/kamranzafar/jtar/`)
+
+**Formatting rules applied:**
+
+- Google Java Format with AOSP style (Android-friendly indentation)
+- Removal of unused imports
+- Trailing whitespace trimming
+- Files end with newline
+
 ## Creating a new release
 
 (These instructions are for core developers, not casual contributors.)

Makefile

@@ -24,6 +24,20 @@ virtualenv: $(VIRTUAL_ENV)
 test:
 	$(TOX) -- tests/ --ignore tests/test_pythonpackage.py
 
+# Java linting using Spotless (requires Java 17+, uses Gradle wrapper)
+java-lint:
+	cd pythonforandroid/bootstraps && ./common/build/gradlew spotlessCheck
+
+java-lint-fix:
+	cd pythonforandroid/bootstraps && ./common/build/gradlew spotlessApply
+
+# Java linting via Docker (no local Java required)
+docker/java-lint: docker/build
+	docker run --rm -v $(CURDIR):/home/user/app -w /home/user/app/pythonforandroid/bootstraps $(DOCKER_IMAGE) ./common/build/gradlew spotlessCheck
+
+docker/java-lint-fix: docker/build
+	docker run --rm -v $(CURDIR):/home/user/app -w /home/user/app/pythonforandroid/bootstraps $(DOCKER_IMAGE) ./common/build/gradlew spotlessApply
+
 # Also install and configure rust
 rebuild_updated_recipes: virtualenv
 	. $(ACTIVATE) && \

doc/source/apis.rst

@@ -80,6 +80,53 @@ https://developer.android.com/reference/android/Manifest.permission
 Other common tasks
 ------------------
 
+Running executables
+~~~~~~~~~~~~~~~~~~~
+
+Android restricts executing files from application data directories.
+``python-for-android`` works around this by creating symbolic links to a
+small set of supported executables inside an internal executable
+directory that is added to ``PATH``.
+
+During startup, ``start.c`` (compiled into ``libmain.so``) scans loaded
+native libraries and creates symlinks for any library matching::
+
+    lib<binary_name>bin.so
+
+Each matching library is exposed at runtime as::
+
+    <binary_name>
+
+For example::
+
+    libffmpegbin.so -> ffmpeg
+
+Recipe developers may expose additional executables by renaming them
+using the same naming convention.
+
+The following example performs a minimal FFmpeg sanity check using an
+in-memory test source and discards the output::
+
+    import subprocess
+
+    subprocess.run(
+        ["ffmpeg", "-f", "lavfi", "-i", "testsrc", "-t", "1", "-f", "null", "-"],
+        check=True
+    )
+
+This verifies that ``ffmpeg`` is available and executable on the device.
+Ensure ``ffmpeg`` is included in your ``requirements``.
+
+If video encoding is required, the following codec options must also be
+enabled in the build configuration:
+
+- ``av_codecs``
+- ``libx264``
+
+Without these, FFmpeg may be present but lack the required codec support.
+
+See also: `APK native library execution restrictions <https://github.com/agnostic-apollo/Android-Docs/blob/master/site/pages/en/projects/docs/apps/processes/app-data-file-execute-restrictions.md>`_
+
 Dismissing the splash screen
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -140,7 +187,7 @@ With Kivy, add an ``on_pause`` method to your App class, which returns True::
 
 With the webview bootstrap, pausing should work automatically.
 
-Under SDL2, you can handle the `appropriate events <https://wiki.libsdl.org/SDL_EventType>`__ (see SDL_APP_WILLENTERBACKGROUND etc.).
+Under SDL2, you can handle the `appropriate events <https://wiki.libsdl.org/SDL3/SDL_EventType>`__ (see SDL_APP_WILLENTERBACKGROUND etc.).
 
 
 Observing Activity result

doc/source/conf.py

@@ -321,3 +321,15 @@ def get_version():
     r"https://github.com/kivy/python-for-android/blob.*",
     ]
 
+# Allow redirects for URLs where we prefer to keep the original form
+linkcheck_allowed_redirects = {
+    # Kivy chat redirects to Discord invite
+    r"https://chat\.kivy\.org/": r"https://discord\.com/.*",
+    # GitHub archive URLs redirect to codeload
+    r"https://github\.com/kivy/python-for-android/archive/.*": r"https://codeload\.github\.com/.*",
+    # GitHub gist homepage redirects to starred
+    r"https://gist\.github\.com/$": r"https://gist\.github\.com/.*",
+    # Google Play Store redirects
+    r"https://play\.google\.com/store/$": r"https://play\.google\.com/store/.*",
+}
+

doc/source/index.rst

@@ -18,7 +18,7 @@ It can generate:
 
 It supports multiple CPU architectures.
 
-It supports apps developed with `Kivy framework <http://kivy.org>`_, but was
+It supports apps developed with `Kivy framework <https://kivy.org/>`_, but was
 built to be flexible about the backend libraries (through "bootstraps"), and
 also supports `PySDL2 <https://pypi.org/project/PySDL2/>`_, and a
 `WebView <https://developer.android.com/reference/android/webkit/WebView>`_ with
@@ -34,7 +34,7 @@ dependencies for Android devices, and bundling it with the app's python code
 and dependencies. The Python code is then interpreted on the Android device.
 
 It is recommended that python-for-android be used via
-`Buildozer <https://buildozer.readthedocs.io/>`_, which ensures the correct
+`Buildozer <https://buildozer.readthedocs.io/en/latest/>`_, which ensures the correct
 dependencies are pre-installed, and centralizes the configuration. However,
 python-for-android is not limited to being used with Buildozer.
 

doc/source/services.rst

@@ -64,9 +64,15 @@ The ``PATH_TO_SERVICE_PY`` is the relative path to the service entry point (like
 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
+ - :code:`:foregroundServiceType=TYPE` to specify the type of foreground service,
+   where TYPE is one of the valid Android foreground service types
+   (see `Android documentation <https://developer.android.com/develop/background-work/services/fgs/service-types>`__
+   for more details). You can specify multiple types separated by a pipe
+   character "|", e.g. :code:`:foregroundServiceType=location|mediaPlayback`. Mandatory
+   if :code:`:foreground` is used on Android 14+.
 
 Full command with all the optional parameters included would be: 
-:code:`--service=myservice:services/myservice.py:foreground:sticky`
+:code:`--service=myservice:services/myservice.py:foreground:sticky:foregroundServiceType=location`
 
 You can add multiple
 :code:`--service` arguments to include multiple services, or separate

pythonforandroid/androidndk.py

@@ -66,6 +66,10 @@ def llvm_readelf(self):
     def llvm_strip(self):
         return f"{self.llvm_binutils_prefix}strip"
 
+    @property
+    def llvm_nm(self):
+        return f"{self.llvm_binutils_prefix}nm"
+
     @property
     def sysroot(self):
         return os.path.join(self.llvm_prebuilt_dir, "sysroot")