DEV Community

Cover image for Porting a Pygame Game from Arch (BTW) to Android (By losing my mind so you don’t have to)
A. Ababa
A. Ababa

Posted on

Porting a Pygame Game from Arch (BTW) to Android (By losing my mind so you don’t have to)

#python #android #archlinux #gamedev

Introduction

If you have ever tried to run buildozer android debug on a rolling-release distribution like Arch Linux, you probably know the pain. It usually starts with a simple command and ends with you staring at gcc compiler logs at 3 AM, wondering why longintrepr.h is missing.

Table of Contents

The Golden Stack (TL;DR)

Android cross-compilation is fragile. If you mix the wrong versions of Python, Cython, and Java, the build fails. Here is the exact combination that works in 2026:

Tool Version The Why
Python 3.11 3.12+ removed distutils, breaking many Android recipes.
Cython < 3.0.0 Cython 3.0 removed longintrepr.h, breaking Kivy/Pygame recipes.
Java JDK 17 Required by the latest Android SDK/Gradle.

Step 1: System Prerequisites

Arch is "bare bones," so we need to manually fetch the headers that python-for-android (p4a) needs to compile the recipes.

Run the following in your terminal to install the build toolchain and headers:

# Update everything first
sudo pacman -Syu


# Install the build toolchain and headers
# We need jdk17-openjdk for Gradle and base-devel for gcc/make
sudo pacman -S git zip unzip jdk17-openjdk python pip python-virtualenv \
    base-devel autoconf libtool pkg-config zlib ncurses cmake libffi openssl
Enter fullscreen mode Exit fullscreen mode

Step 2: The Virtual Environment (DO NOT SKIP THIS)

Never install Buildozer or Cython globally on Arch. System updates will break your build toolchain. We need an isolated environment where we can pin older versions of Cython without messing up the system.

# 1. Create the venv with Python 3.11
python3.11 -m venv .venv


# 2. Activate it
source .venv/bin/activate


# 3. Install the specific versions
# We pin Cython < 3.0 to fix the "longintrepr.h" error
pip install "Cython<3.0" "setuptools<71.0.0" buildozer
Enter fullscreen mode Exit fullscreen mode

Step 3: The "Flag Sanitization" Patch

This was the hardest bug to track down.

On Arch Linux, the system compilers are configured with aggressive security and optimization flags like -fcf-protection (Intel Control-flow enforcement) and -march=x86-64.

When Buildozer runs, it sometimes leaks these Host Flags into the Target (Android) build process. The Android NDK compiler sees -march=x86-64, panics because it's trying to build for ARM, and crashes with cryptic errors.

The Fix: We need to "sanitize" the environment variables in the recipe before the build starts.

  • Navigate to the pygame recipe inside your hidden .buildozer directory. It is usually located here: .buildozer/android/platform/python-for-android/pythonforandroid/recipes/pygame/__init__.py
  • Locate the build_armeabi_v7a method and inject this sanitation logic: 
import re


# ... inside the build_armeabi_v7a method ...
env = self.get_recipe_env(arch)


# 🧹 THE SANITIZER
# Strip flags that break ARM builds (like x86 specific protections)
bad_flags = [
    r'-m(arch|tune|cpu)=\S+',      # e.g., -march=x86-64
    r'-fcf-protection(=\S+)?',     # Intel specific
    r'-fno-plt'                    # PLT hardening
]


for var in ['CFLAGS', 'LDFLAGS']:
    if var in env:
        for pattern in bad_flags:
            env[var] = re.sub(pattern, '', env[var])


# ... proceed with the build ...
Enter fullscreen mode Exit fullscreen mode

This simple script strips the x86 flags before they reach the NDK.

Step 4: Building the APK

Now that our environment is clean and our flags are sanitized, we can build.

CRITICAL: You must export your local venv path before building. If you don't, Buildozer might use the system Cython (v3.0+) and fail.

# Force the build to use our local venv tools
export PATH="$(pwd)/.venv/bin:$PATH"


# Build the debug APK
buildozer android debug
Enter fullscreen mode Exit fullscreen mode

This will:

  • Download the Android SDK/NDK (takes a while the first time).
  • Compile Python 3.11 for ARM.
  • Package your Pygame app.

If everything goes well, you’ll see the glorious Application pushed. message.

Troubleshooting Cheatsheet

If (when) things break, here is your rescue kit.

1. The "longintrepr.h not found" Error

  • Cause: You are using Cython 3.0+.
  • Fix: Run pip install "Cython<3.0" and check your PATH.

2. The App Crashes Immediately

Buildozer hides the Python errors. You need logcat to see why your game crashed.

# Filter specifically for Python crashes
adb logcat -s python studio.flappybird.game
Enter fullscreen mode Exit fullscreen mode

3. "Get Android SDK" Hangs

  • Cause: You need to accept a license agreement.
  • Fix: Run the command in the foreground first, or check your internet connection.

Final Thoughts

Porting to Android doesn't have to be a nightmare, but on Linux (Arch BTW), you have to respect the toolchain. By pinning your dependencies and sanitizing your compiler flags, you can build reliable APKs even on a bleeding-edge distro like Arch.

Happy Coding!

Top comments (0)