Build ‐ Android

Check Build for generic instructions.

Building for Android depends on the cmake toolchain file in cmake/android.toolchain, and having cmake and Oracle Java 8 or newer JRE and JDK packages for your OS installed. (OpenJDK does NOT work for building!)

In addition configuring the EE build, this toolchain file does a few additional things:

• Downloads and installs the android SDK + NDK with all required tools. This requires accepting a license.
• Downloads and compiles SDL2 with requirements and installs those in the NDK folder.
• Builds an APK from the compiled sources.

Build for 32-bit ARM v7

Building 32-bit EE for Android should be as easy as running from the repo root:

mkdir _build_android
cd _build_android
cmake .. -G Ninja -DSERIOUS_PROTON_DIR=../../SeriousProton -DCMAKE_TOOLCHAIN_FILE=../cmake/android.toolchain
ninja

Build for 64-bit ARM v8

Some newer devices, such as the Pixel 7 series, won't run 32-bit Android apps.

To build 64-bit EE for Android, add the -DANDROID_ABI=arm64-v8a flag:

mkdir _build_android_64
cd _build_android_64
cmake .. -G Ninja -DSERIOUS_PROTON_DIR=../../SeriousProton -DCMAKE_TOOLCHAIN_FILE=../cmake/android.toolchain -DANDROID_ABI=arm64-v8a
ninja

This might fail with an error due to a missing __builtin_rotateleft64 (zeux/meshoptimizer#534, zeux/meshoptimizer#540). If so, try setting ANDROID_NDK_VERSION in cmake/android.toolchain to a newer version, such as NDK 23c:

-set(ANDROID_NDK_VERSION "19.2.5345600" CACHE STRING "NDK version to use. Be mindful, this is brittle across SDL2/CMake/NDK configurations.")
+set(ANDROID_NDK_VERSION "23.2.8568313" CACHE STRING "NDK version to use. Be mindful, this is brittle across SDL2/CMake/NDK configurations.")

Build for x86

Similar to ARM v8, pass the appropriate ANDROID_ABI flags for your architecture.

For 32-bit x86, pass x86:

mkdir _build_android_x86_32
cd _build_android_x86_32
cmake .. -G Ninja -DSERIOUS_PROTON_DIR=../../SeriousProton -DCMAKE_TOOLCHAIN_FILE=../cmake/android.toolchain -DANDROID_ABI=x86
ninja

For 64-bit x86, pass x86_64:

mkdir _build_android_x86_64
cd _build_android_x86_64
cmake .. -G Ninja -DSERIOUS_PROTON_DIR=../../SeriousProton -DCMAKE_TOOLCHAIN_FILE=../cmake/android.toolchain -DANDROID_ABI=x86_64
ninja

Troubleshooting

Testing Android ARM builds on x86 devices

The official Android Emulator supports ARM ABIs on system images for Android 11 and newer, which allows you to install and test the APKs built by these processes without an Android device. For details, see the Android Developers Blog. Note that the emulator will not necessarily match the behavior of a real device, especially regarding OpenGL ES limitations.

"CMAKE_MAKE_PROGRAM is not set"

If you encounter a CMAKE_MAKE_PROGRAM is not set error, make sure you've installed make. If you've installed it, ensure it's in your $PATH/%PATH%; if it is and it still fails, add -DCMAKE_MAKE_PROGRAM=$(which make) to manually specify its location.

"jarsigner error"

If you encounter a jarsigner error: java.lang.RuntimeException: keystore load: ... (No such file or directory) error, you need to create a keystore. The Android build script uses:

keytool -genkey -alias ${ANDROID_SIGN_KEY_NAME} -keyalg RSA -keysize 2048 -validity 10000

where the default ANDROID_SIGN_KEY_NAME is "Android" and the default password is password, and the command generates the keystore file at ~/.keystore.

"Invalid keystore format"

If you have a keystore but get a keystore load: Invalid keystore format error, ensure that the keystore conforms to the above command's flags and is at the specified location. See cmake/android.toolchain for details.

Note that this only works on Linux. Building for Android from Windows is not supported at the moment.