SDL2 application for Android built by Gradle 4

SDL2 is a well known library for making games or interactive application for Linux, Windows or macOS. The library has also support for mobile devices. Building application for Android requires a little bit more effort than build for desktops.

Let’s go step-by-step.

First of all download Gradle 4 and add bin directory with gradle to your PATH environment variable.

Download and install Android Studio.

Clone sdl2-android-example project from GitHub.

Open the repo in Android Studio and open SDK Manager. Go to Tools, select menu Android, and select item SDK Manager.

In the lower right corner check option Show Package Details. Install Android SDK Build Tool e.g. version 25.0.3 and NDK.

When you open the sdl2-android-example you will see following structure. There are two gradle files in the top level directory. The first is build.gradle. The file contains a dependency on gradle-experimental plugin which is recommended for NDK builds for Android.

buildscript {
    repositories {
    dependencies {
        // Android native build plugin compatible with Gradle 4
        classpath ''

allprojects {
    repositories {

The second Gradle file is settings.gradle. The file contains a list of modules which are in the project. One module is SDL2 library. Then there are two further modules app and main. The app module is the bridge between Java and SDL2. The main module contains C code for the application.

gradle.ext.sdkVersion = 21

include ':app'
include ':SDL2'
include ':main'

These two files provide a skeleton for the build of the application. Each module SDL2, app and main are stored in the directory that matches the name a of module. Each module contains its own build.gradle which describes how to build the module.

The module file SDL2/build.gradle is interesting because it contains many excludes. It does not make sense to build all C files from SDL2 for Android.

The module file main/build.gradle contains information for linking the C application with SDL2 library.

The module file app/build.gradle contains information how to wrap all the C source code into final application.

First of all, it is necessary to build the libraries (.so files):

gradle distributeLib

If you want to build just one library, you can type:

gradle :SDL2:distributeLib

Gradle will build all flavors. If you’re experiencing problems with Android Studio, just sync the project after executing this command from command line.

Now you can deploy the application to a device or an emulator. Go to Gradle projects, expand :app module, expand Tasks, expand install and double click installDebug target.

We will discuss how to use further SDL2 libraries in next articles. You can find more under topic SDL2.

Note: the sample projet at GitHub already contains reference to other libraries like PNG. Please follow instructions described in the article SDL2_image for Android with PNG image format. The other option is to clone older version of application without PNG.

No votes yet.
Please wait...

5. July 2017 at 21:28 - Development (Tags: , , , , , , ).

  • Alain De Feyter

    looks veryinteresting, but I keep getting the following error before being able to run the app:
    Gradle ‘sdl2-android-example’ project refresh failed
    Error:Exception thrown while executing model rule: NdkComponentModelPlugin.Rules#createNativeBuildModel(NativeBuildConfig, ModelMap, ModelMap, NdkHandler) > create(debug-arm64-v8a)
    Shared library runtime files /home/alaindef/Android/sdl2-android-example/distribution/png/lib/arm64-v8a/ does not exist for prebuilt shared library ‘png:arm64-v8aDebugShared’.

    can you help?

    No votes yet.
    Please wait...
  • Hi Alain,

    thank you for the question. The issue is caused by missing libpng. All ‘.so’ libraries must be build using distributeLib target.
    This is described in the next article:

    To fix your problem, just type:
    gradle :zip:distributeLib
    gradle :png:distributeLib
    gradle :SDL2_image:distributeLib

    I will update the article and add a pointer to the article about PNG.

    Please try it and let me know whether it works for you.

    No votes yet.
    Please wait...
  • Alain De Feyter

    Hi Juraj,
    Thank you so much for your work and your quick support. Thanks to that I got where I wanted to be!
    of course, if I had read your, I should have found out for myself, but wtf reads the readme files? 🙂
    I have put my cpp files in the right directory, and after a few hickups it worked fantastically. Our Android app now shows a map of the world, in which you can zoom and pan. the assets dir contains now more than 200Mb of data.
    the final project should handle more than 800 files. right now the java heap size limit is a problem, but I did it already with the old ANT tool, so it should work with gradle too.
    next challenge is to put the assets in an obb file (which worked with the old ant system). If you have any suggestions on how to do that with the gradle tool, I will be most happy to hear from you!

    Thanks again for your great contribution to the community!

    alain de feyter

    No votes yet.
    Please wait...
  • Hi Alain,

    I’m glad that it worked for you.

    Yesterday I’ve published an update to the sdl2-android-example with JPEG support. Maybe it could be useful also for your app:

    Here is hint how to increase heap size:

    Private assets on Android might look like a common file system, but they’re not. All assets are compressed and Android creates virtual FS which is accessible only by the application. I would recommend storing big amounts of assets in External Storage. This will speed up the build and application will be smaller.

    Here you can find more information about app-private data storage:

    No votes yet.
    Please wait...
  • Hi Alain,

    I have important update for you. If you’d like to target API level 19 in your application then you can find here some hints how to make SDL2 works with API level 19:

    The source code of sdl2-android-example has been already updated.

    No votes yet.
    Please wait...