Pygame Android build: missing SIMD blitter symbols cause APK crash at runtime

Open Beginner friendly
  • Is something wrong?
#3,405 0 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
62/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
c, python
Domain
build-system, mobile

Research direction

Start in pythonforandroid/recipes/pygame/init.py, where the recipe loads buildconfig/Setup.Android.SDL2.in and the surface module line is set. Compare that line with the standard SDL2 Setup template to confirm the missing simd_blitters_sse2.c and simd_blitters_avx2.c sources. Done when the Android surface module includes both files and the surface.so symbol errors no longer appear in a build.

Written by the indexing model from the issue text.

Description

Pygame Android build: missing SIMD blitter symbols cause APK crash at runtime

Summary

When building a Pygame application for Android using Buildozer and python-for-android, the APK was generated successfully but crashed immediately after startup.

The problem was caused by missing SIMD source files in the Android-specific Pygame surface module configuration.

Adding both missing source files to the surface module resolved the problem. The APK was subsequently tested successfully on a physical Android device.

I would like to share this finding and ask whether the Android-specific configuration could be updated upstream.

Environment

  • Linux (Debian 13)
  • Buildozer
  • python-for-android
  • Pygame
  • SDL2
  • Android NDK
  • Architectures: arm64-v8a and armeabi-v7a
  • Test device: Samsung Galaxy A20
  • Android version: 11

Symptoms

The first runtime error was:

ImportError: dlopen failed: cannot locate symbol
"alphablit_alpha_sse2_argb_surf_alpha"
referenced by ".../pygame/surface.so"

This was followed by:

NotImplementedError: display module not available

After adding the SSE2 source file, the first error disappeared, but another missing symbol was reported:

dlopen failed: cannot locate symbol "pg_has_avx2"
referenced by ".../pygame/surface.so"

Root cause

The Android-specific Pygame build configuration did not include two source files that are present in the standard Pygame SDL2 configuration:

  • src_c/simd_blitters_sse2.c
  • src_c/simd_blitters_avx2.c

The relevant configuration is generated by the python-for-android Pygame recipe:

pythonforandroid/recipes/pygame/__init__.py

The recipe reads the Android template using:

setup_template = open(join("buildconfig", "Setup.Android.SDL2.in")).read()

The original Android surface module configuration was:

surface src_c/surface.c src_c/alphablit.c src_c/surface_fill.c $(SDL) $(DEBUG)

The standard configuration includes the SIMD source files:

surface src_c/simd_blitters_sse2.c src_c/simd_blitters_avx2.c src_c/surface.c src_c/alphablit.c src_c/surface_fill.c $(SDL) $(DEBUG)
Why both files are required

The first missing symbol:

alphablit_alpha_sse2_argb_surf_alpha

is implemented in simd_blitters_sse2.c.

Although the filename contains SSE2, this source also provides ARM NEON support through sse2neon.h.

The second missing symbol:

pg_has_avx2

is implemented in simd_blitters_avx2.c.

Although ARM devices do not support AVX2, the function itself is still referenced by alphablit.c. Its implementation returns 0 when AVX2 is unavailable.

Therefore, the AVX2 source file must also be compiled so that the referenced symbol is available.

Working solution

The following additional line was inserted into the python-for-android Pygame recipe, immediately after loading the Android setup template:

setup_template = setup_template.replace(
    "surface src_c/surface.c",
    "surface src_c/simd_blitters_sse2.c src_c/simd_blitters_avx2.c src_c/surface.c"
)

This changes the generated surface module configuration to include both missing source files.

Reproducible repair script

To make the modification reproducible after a Buildozer clean operation, the following script can be placed in the root directory of a Buildozer project.

Filename: repair_pygame_android.sh

#!/bin/bash
set -e

RECIPE=".buildozer/android/platform/python-for-android/pythonforandroid/recipes/pygame/__init__.py"

echo "=== Pygame Android Repair ==="

if [ ! -f "$RECIPE" ]; then
    echo "ERROR: Pygame recipe not found!"
    exit 1
fi

python - "$RECIPE" <<'PY'
import sys
from pathlib import Path

path = Path(sys.argv[1])
content = path.read_text()

old = 'setup_template = open(join("buildconfig", "Setup.Android.SDL2.in")).read()'

new = old + '\n            setup_template = setup_template.replace("surface src_c/surface.c", "surface src_c/simd_blitters_sse2.c src_c/simd_blitters_avx2.c src_c/surface.c")'

if new in content:
    print("Patch already present.")
elif old in content:
    path.write_text(content.replace(old, new, 1))
    print("Pygame recipe successfully patched.")
else:
    print("ERROR: Expected code line not found. Nothing changed.")
    sys.exit(1)
PY

echo "=== Repair completed ==="

Make the script executable:

chmod +x repair_pygame_android.sh

Build procedure

The following sequence was used successfully:

# 1. Clean the Android build
buildozer android clean

# 2. Restore the Pygame recipe modification
./repair_pygame_android.sh

# 3. Build the APK
buildozer -v android debug

Important: The repair script must be executed after buildozer android clean and before building the APK. A clean operation can remove the modified python-for-android checkout.

Result

The APK was built successfully for both Android architectures:

  • arm64-v8a
  • armeabi-v7a

Buildozer reported:

# Android packaging done!
# APK ... available in the bin directory

The resulting APK was installed and tested on a Samsung Galaxy A20 running Android 11.

The application started successfully and the original Pygame import errors were resolved.

Question for the maintainers

Would it be possible to include both SIMD source files in the Android-specific Pygame surface module configuration by default?

The standard Pygame SDL2 configuration already includes these files, while the Android-specific configuration appears to omit them.

Including the required sources directly in the Android recipe could prevent other developers from encountering the same runtime errors.

Thank you for maintaining python-for-android!

Dominant language
Python
Stars
8.9k
Forks
2.1k
Avg merge
2d 16h
Merged PRs (30d)
12

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from kivy/python-for-android

All issues in kivy/python-for-android

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.