Lazy Foo' Productions

Setting up SDL 2 on Windows Android Studio 3.0.1

Last Updated: Jun 10th, 2019

1) Get ready to download. A lot. Like over a gigabyte of data. If you have a limited connection, I'm sorry the android SDK is huge and it's just the way things are. I recommend having a movie or TV show to watch ready if a gigabyte takes a long time for you to download.

First, download the Java Development Kit (JDK) on this page. I am assuming you're running 64bit windows, so download the 64bit version:
download jdk

2) Download Android Studio on this page.
download android studio

3) Download the SDL2 source. Not just the development libraries you use for desktop development, the full source. You can find the full source on this page.
download sdl source

4) Install the JDK. This should be a simple next, next, next,... finish installation.

5) Install the Android Studio. It's mostly a next, next, and finish installation but make sure to change a couple things. In the configurations setting menu make sure to set the android sdk path to some place accessible. For this tutorial we are placing it at C:\androidsdk.
android sdk location

6) Start Android Studio. The first time you start Android Studio it will run a set up wizard. Make sure to select the Custom Install.
custom install

In the SDK Components Setup, make sure it pointed to the sdk directory we set when installing (which was at C:\androidsdk).
sdk components
Keep going through the installation and hit finish so it can start downloading.

7) Starting Android Studio again, open up the sdk manager:
configure sdk manager

Check Show Package Details, select Android version 16, and hit Apply to install:
install android 16

8) Click on SDK Tools and make sure to install:
  • CMake
  • Google USB Driver
  • NDK
sdk tools

9) Extract the SDL2 source code to some accessable directory that is ideally dedicated to containing Android libraries. For this tutorial we will put them in the directory C:\androidlib. After extracting the SDL2 source code you should have an Android makefile at C:\androidlib\SDL2-2.0.5\ Depending on your version of SDL, it could be at C:\androidlib\SDL2-2.0.4\ or C:\androidlib\SDL2-2.0.6\ and so on.

10) Start up Android Studio again and import the android project from the SDL2 source code which should be at C:\androidlib\SDL2-2.0.5\android-project
import project

11) Set the destination to a new folder inside of some accessable directory that is ideally dedicated to containing Android projects. For this tutorial we will put the project in C:\androidprojects\SDL.
project destination
Select the directory and import the project with the default settings.

12) If you try to hit Build -> Make Project you'll get the following error: Minimum supported Gradle version is 4.1. Current version is 2.14.1.

This means our project is set to use the wrong version of Gradle. To fix this, set the Project window to project mode, open C:\androidprojects\SDL\gradle\wrapper\ and change distributionUrl=https\:// to distributionUrl=https\://

Make project again (it may take a while to download Gradle 4.1) and you'll get a new error: cannot find symbol class Objects

13) That error was due to the fact that Android Studio cannot find the Java Objects class. It can't find it because it is pointed at an old JDK. To make sure it compiles against the latest version of Java, go to File -> Project Structure.
project structure

Select app under Modules and the set the Source/Target Compatibility to the latest version (currently 1.8):

Build again and you should get a new error.

14) The new error will say:
Error:Execution failed for task ':app:compileDebugNdk'. > Error: Your project contains C++ files but it is not using a supported native build system. Consider using CMake or ndk-build integration with the stable Android Gradle plugin: or use the experimental plugin:

This is complaining that the NDK setup is broken for our project.

Let's back up a bit and talk about how SDL 2 on Android works. Android development is mostly Java based and SDL is a C based library. The Native Development Kit that allows Java to interface with native C/C++ code using the Java Native Interface. With the NDK, we'll build SDL2 as a shared object that will interface with Java, and we'll build our game as another shared object that will interface with SDL 2.

What we need to do is tell gradle (the build tool used by Android Studio) to use the Android make file for our project. Open up the project window, right click on app and select "Link C++ with Gradle".
link with gradle

Set the Build System to ndk-build and set the project path to point to the Android make file which should be at C:\androidprojects\SDL\app\src\main\jni\
select android mk
Hit Build -> Make Project and you'll get a bunch of new errors saying something like Error:(688) Android NDK: Module main depends on undefined modules: SDL2

15) What the previous error was complaining about was that it can't find the SDL 2 module. What we need to do is set up a symbolic link to the SDL 2 source we extracted.

Next, go to the start menu and run cmd as administrator:
cmd as admin

Go to the JNI directory inside the project using this command: cd "C:\androidprojects\SDL\app\src\main\jni"

And create a symbolic link directory to the SDL 2 source directory we extracted (REMEMBER: This path will vary depending on your version of SDL 2): mklink /D SDL2 C:\androidlib\SDL2-2.0.5

You should get the following message back symbolic link created for SDL2 <<===>> C:\androidlib\SDL2-2.0.5

Try to rebuild the project. You'll new a new error:
Error:A problem occurred configuring project ':app'. > executing external native build for ndkBuild C:\androidprojects\SDL\app\src\main\jni\

but at least now you'll see symbolic link in the project:

16) That gradle error didn't tell us much so we'll have to open up the gradle console:
open gradle console
Scroll up a bit and you'll see some errors from the ndk-build: `C:/androidprojects/SDL/app/src/main/jni/src/YourSourceHere.c', needed by `C:/androidprojects/SDL/app/build/intermediates/ndkBuild/debug/obj/local/armeabi/objs-debug/main/YourSourceHere.o'. Stop.

In this case, the error "No rule to make target" actually means it can't find the file you're asking to compile. It's trying to compile C:/androidprojects/SDL/app/src/main/jni/src/YourSourceHere.c but can't find it which makes sense because it doesn't exist. YourSourceHere.c is a place holder for our application source file so we need to replace it with ours.

Download the source for lesson 52 and place 52_hello_mobile.cpp at C:\androidprojects\SDL\app\src\main\jni\src\52_hello_mobile.cpp. Open up C:\androidprojects\SDL\app\src\main\jni\src\ and change YourSourceHere.c to 52_hello_mobile.cpp. Build and you should get a new error in the gradle build menu.

17) The error Error:(7, 10) fatal error: 'string' file not found is due to the fact that the project is not set up to use the standard C++ library. To fix this, open up C:\androidprojects\SDL\app\src\main\jni\ and change # APP_STL := stlport_static to APP_STL := stlport_static so it's no longer commmented out. Build again and you should get no errors.

18) Open C:\androidprojects\SDL\app\src\main\res\values\strings.xml and change <string name="app_name">SDL App</string> to <string name="app_name">SDL Tutorial</string>

This will change the name under the App's icon from "SDL App" to "SDL Tutorial".

19) At this point the app will run our code but it will fail because it can't load the media files for the tutorial. Media files go in the asset directory. Create a folder called assets at C:\androidprojects\SDL\app\src\main\assets. Copy the directory inside of the zip we downloaded and place it in the assets directory. If the application needs to open 52_hello_mobile\hello.bmp, it needs to be at C:\androidprojects\SDL\app\src\main\assets\52_hello_mobile\hello.bmp when building.

20) Our SDL application is ready to build and run, but first we need to set up our device. You can use an Android emulator, but the emulator is can be really, really slow so I recommend getting an Android device if you can.

First you'll need to enable USB debugging on your device. That is version/device specific which is why I won't go over it here. Google search "android enable usb debugging" with your device name and they'll show you how to do it.

Make sure you have the device drivers installed on your Windows machine. The driver you downloaded from Android Studio should be located at C:\androidsdk\extras\google\usb_driver which may work with your device or your device may require a driver from the manufacturer. Either way, make sure to check in the Windows Device Manager that your device has its drivers installed. Without the drivers, ADB (Android Debug Bridge) won't connect and you won't be able to deploy and debug on your device.

After you set up your Android device, go to Run -> run App.
run app

If you want to see the console output of the app, you can see it in the Android Monitor:
android monitor
The Android Monitor can also show you if there are any ADB errors.

Now that you have SDL 2 running on your device, it's time to go onto part 2 of the tutorial.