Main page

Setting up SDL3 for Android

Usage of the prebuild SDL3-x.y.z.aar

• CMake, MinGW, Android SDK, NDK 23, JDK must be installed
• Download the "sdlcross-SDL3" template example here: https://github.com/madebr/sdlcross (choose the SDL3 branch and select: Code > Download ZIP). Unzip somewhere
• Go to this link. Download the "android" archive in the Artifacts section. Unzip it
• You will find the "SDL3-3.1.2.aar" file there
• Note. You can find the "INSTALL.md" guide in the "SDL3-3.1.2.aar" archive but you don't need to study it for the current tutorial
• As the "INSTALL.md" guide says to copy "SDL3-3.1.2.aar" to "sdlcross-SDL3/app/libs" folder
• Open the "sdlcross-SDL3/app/build.gradle". Choose what ABI you want to use. For example, "arm64-v8a" for new devices, "armeabi-v7a" is for an old ones, "x86" and "x86_64" - for the Android emulator:

cmake {
    arguments '-DANDROID_STL=c++_shared', '-DWITH_IMAGE=OFF', '-DWITH_MIXER=OFF'
    // abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
    abiFilters 'armeabi-v7a'
}

• Open the command line inside of the "sdlcross-SDL3" template root folder
• Copy and paste the following command: gradlew assembleDebug
• It requires 6m 52s for the first build and 7 seconds for the next builds when you change a code in the "main.c" file
• The generated APK file will be here: "sdlcross-SDL3/app/build/outputs/apk/debug/app-debug.apk" - 3.8 MB
• The following command is for installing APK-file that connected via USB-cable: gradlew installDebug
• Important! If you changed a project name inside of the "CMakeLists.txt" here:

# Declare the project
project(sdlcross)

• then you should write the same name here in the .java file that is located here "app\src\main\java\com\example\sdlcross" inside of the "getLibraries()" method:

package com.example.sdlcross;

import org.libsdl.app.SDLActivity;

public class MyActivity extends SDLActivity {
    protected String[] getLibraries() {
        return new String[] { "my_project" };
    }
}

Based on the Discord discussion

How to build SDL3-x.y.z.aar yourself from SDL3 sources

• The newest Python version must be installed. I use Python 3.12. Maybe you can use 3.10 and 3.11 but 3.8 cannot be used. I now nothing about 3.9
• Note. You can use a few versions of Python on your computer. For example, I use Python 3.8 because PyBox2D cannot work with 3.9 at this moment. I downloaded Windows embeddable package. I download the "Window embeddable package", renamed python.exe to python312.exe and added it to the Path. I can use the "python312" command in the console
• Open the console terminal
• Clone SDL source: git clone https://github.com/libsdl-org/SDL.git
• Note. I used this commit: 8bcfdb0 from Aug 23, 2024. You can read how to use the specific commit here on the Stack Overflow I used it: git reset --hard 8bcfdb0
• Note. You can disable the ABI's that you don't need in the "build-release.py". It allows to build in 4m 25s. SDL3-3.1.2.aar will have 3.30 MB (download):

ANDROID_AVAILABLE_ABIS = [
    "armeabi-v7a"
    #"arm64-v8a",
    #"x86",
    #"x86_64",
]

• Go to the root of the SDL folder: cd SDL
• Run: python build-scripts/build-release.py --create android --project SDL3 --force
• The "aar" file will be generated here: SDL/dist/SDL3-3.1.2.aar'. The size of it is 11.7 MB (download)
• Note. You can disable "fresh" in the "build-scripts/build-release.py" by comment it for faster turn-a-round, and forcing a build:

cmake_args = [
    "cmake",
    "-S", str(self.root),
    "-B", str(build_dir),
    #"--fresh",
    f'''-DCMAKE_C_FLAGS="-ffile-prefix-map={self.root}=/src/{self.

Based on the Discord discussion