Android / SDL2: minimalistic framework / tutorial

Hi all,

(sorry for the repost, post title didn’t mention Android, now it does)

As requested here: https://forums.libsdl.org/viewtopic.php?t=10748 , I’m preparing a little tutorial + framework for developing an SDL2 / Android app on the windows desktop and deploying it to the emulator and device. I want to submit this as an article to GameDev, but since it’s a large number of steps, it would be nice if someone could ‘playtest’ it first and let me know if it’s OK.

Here’s the accompanying code:

And the article text:

STEPS 

PART A - One-time Preparations / installing a new development machine 

1. Get the Android SDK. 
   Currently at: https://developer.android.com/sdk/index.html?hl=i#download 
   Note: you don't need the Eclipse stuff; get the 'stand-alone Android SDK 
   Tools for Windows' instead. To get to this file, expand the 'Get the SDK 
   for an existing IDE' thing. 
   The file is 90MB. 
2. Get the NDK. 
   Currently at: https://developer.android.com/tools/sdk/ndk/index.html 
   Note: if you have a 64-bit OS, you can get either the 32-bit or 64-bit 
   version, both should work fine. I picked the 64-bit version. 
   This file is 507MB, so you'll need some patience if you're on a slow 
   connection. 
3. Get the JDK. 
   Currently at: 
   http://www.oracle.com/technetwork/java/javase/downloads/index.html 
   Note: Get the JDK package, not one of the JRE versions. 
   The current version is 8u25. Like the NDK, I got the 64-bit version: 
   jdk-8u25-windows-x64.exe. This is a 157MB download. 
   The 64-bit version should be fine as well if you're on a 64-bit OS. 
4. Install the JDK. 
5. Install the SDK. This requires the JDK, which it should find for you: 
   On my machine, the SDK installer found JDK version 1.8.0_25 in 
   c:\Program Files\Java\jdk1.8.0_25\bin. 
   Like in step 1, I'm going to diverge from the defaults Google 
   recommends: instead of installing to the default install directory 
   C:\Program Files (x86)\Android\android-sdk 
   we'll install to a place that is easier to find later: 
   D:\ANDROID\android-sdk 
   Don't start the SDK manager yet. We'll take care of that later. 
6. Install the NDK. It's just a zip, containing a folder 
   'android-ndk-r10b', which you can unpack to the ANDROID folder. 
7. Add the NDK and SDK folders to your system path: 
   D:\ANDROID\android-ndk-r10b 
   D:\ANDROID\android-sdk\tools 
   D:\ANDROID\android-sdk\platform-tools 
   You can do this in the Windows control panel, system, advanced system 
   properties, environment variables. 
8. Get WinAnt. 
   Currently at: 
   https://code.google.com/p/winant/ 
   Install it; it will ask you for a JDK directory, which is on my system: 
   C:\Program Files\Java\jdk1.8.0_25 

Your ANDROID folder now contains two directories: 

android-ndk-r10b 
android-sdk 

PART B - Setting up emulation 

1. Go into the android-sdk folder and start "SDK Manager.exe". 
   It's time to make some decisions about what versions of Android you want 
   to support: I picked 4.0 and up, but SDL2 supports lower versions as 
   well. Keep in mind that pre-4.0 devices may not have the processing 
   power to run your creations; to be safe from complaining users, I 
   decided to simply limit availability to 4.x. 
   In the SDK Manager, select the following: 
   Tools 
   - Android SDK Tools 
   - Android SDK Platform-tools 
   - Android SDK Build-tools 
   Android 4.0 (API 14): 
   - SDK Platform 
   - ARM EABI v7a System Image 
   Android 4.1.2 (API 16): 
   - SDK Platform 
   - ARM EABI v7a System Image 
   - Intel x86 Atom System Image 
   - MIPS System Image 
   Hit the button saying "Install 11 packages", and wait for the tool to 
   download the selected items. 
   About the two API levels selected here: 
   API level 14 represents Android 4.0, which is the minimum version of 
   the OS I want to support. Level 16 seems to be required to run the 
   emulator with GPU emulation, which is why that is installed as well. 
2. Now start "AVD Manager.exe". This lets you setup an emulator, which is 
   useful during development. 
   Create a new device, using the "Create" button. Then fill out the form      that pops up. I used 

the NexusOne as a template. Don't forget to 
   enable 'Use Host GPU'; SDL2 will badly need this to get decent 
   performance. 
   You can now start the emulator if you want (fun to see an Android 
   device on your desktop). 

PART C - Getting the app running under Windows 

1. Download the package linked to this tutorial, and unzip it to your 
   ANDROID folder. This adds the folder 'minimal'. 
2. Inside this folder, you will find a folder 'win32', which contains 
   a VS2013 solution file, 'minimal.sln'. Open this file. 
   This project should run out-of-the-box. The application runs natively on 
   Windows, and you can use it as a starting point for your own 
   application. 

PART D - Building for Android 

1. Open a command prompt, and go to your ANDROID directory: 
   D: 
   cd \ANDROID\minimal 
2. Compile the C/C++ code by executing 
   ndk-build 
   on the command prompt. This will take a while, but should conclude 
   without errors. 
3. Build the final apk by executing 
   ant release 
   You now have a valid, signed apk file, ready for deployment on the 
   emulator or an actual device. You can find the apk in the bin folder, 
   its name is 'Minimal-release.apk'. 
4. Run the apk file on the emulator, by executing 
   ant release install 
   This requires that the emulator is running, obviously. 

At this point, you can run your app in three possible ways: 
- Natively, in Windows; 
- In the emulator; 
- On your device. 
>From this point, there's a number of things to take care of if you want to 
do any development beyond 'very basic' (i.e., modifying game.cpp and 
recompiling): 

- Adding source files to the project; 
- Changing application icons; 
- Changing the application name. 

These are detailed below. 

PART E - Expanding the project 

1. When you add a source file to the project, you need to notify the 
   Android build system of this. This is done through the Android.mk file 
   in minimal\jni\src. In this file, you'll find a section that reads 
   # Add your application source files here... 
   LOCAL_SRC_FILES := $(SDL_PATH)/src/main/android/SDL_android_main.c \ 
   main.cpp \ 
   ../../win32/game.cpp 
   Add a backslash to the last line, and then add your new file: 
   # Add your application source files here... 
   LOCAL_SRC_FILES := $(SDL_PATH)/src/main/android/SDL_android_main.c \ 
   main.cpp \ 
   ../../win32/game.cpp \ 
        ../../win32/tools.cpp 
   Header files will be picked up automatically, as long as they are in 
   the same folder (win32). 
2. The application icons are stored in the 'res' folder, in four sizes. You 
   can overwrite these files with new icons. After rebuilding the apk, 
   the new icons will appear in the emulator and on your device. 

PART F - Changing the application name 

This is a massive undertaking, that deserves its own section. Renaming is 
required, if you decide to take your application to Google Play: your app 
must have a unique name before you can upload it. So, here we go. 

The full ID of the app as it is is com.bik5.minimal. Let's assume we want 
to change it to org.test.myapp. 

1. Start by deleting (the contents of) the following folders: 
   - bin 
   - gen 
2. Rename the minimal folder itself to myapp. 
3. In src\com\bik5\minimal you will find a file called Minimal.java. We 
   need to make the following changes: 
   - change the names of the directories to org\test\myapp 
   - change the name of the java file to Myapp.java 
   - edit Myapp.java, and replace the first line with: 
     package org.test.Myapp; 
   - do a global replace in this file of 'Minimal' to 'Myapp' (mind the 
     case!) 
   - save the file. 
4. Open myapp\AndroidManifest.xml. The third line reads: 
   package="com.bik5.minimal" 
   Change this to 
   package="org.test.myapp" 
   A few lines below that, you'll find: 
   <activity android:name="Minimal" 
   Change this to 
   <activity android:name="Myapp" 
5. In res\values, you will find strings.xml. Open the file with notepad, 
   and replace 'Minimal' with 'Myapp'. 
6. Open myapp\ant.properties. Replace 'minimal' by 'myapp'. 
7. Open myapp\build.properties. Replace 'minimal' by 'myapp'. 
8. Open myapp\build.xml. Replace 'Minimal' by 'Myapp'. 
9. Generate a new keystore. Execute the following command using the command 
   prompt: 
   keytool -genkey -v -keystore myapp.keystore -alias myapp 
   -keyalg RSA -keysize 2048 -validity 10000 
   This will prompt you for all sorts of information, which allows you to 
   further personalize the keystore. 
10. Edit myapp\jni\SDL\Android.mk. Replace 
    'com_bik5_minimal_Minimal' by 'org_test_myapp_Myapp'. 
11. Edit myapp\jni\SDL\src\core\SDL_android.c. 
    Replace 'com_bik5_minimal_Minimal' by 'org_test_myapp_Myapp'. 
    Replace 'com_bik5_minimal' by 'org_test_myapp'. 
12. Edit myapp\jni\SDL\src\main\android\SDL_android_main.c. 
    Replace 'com_bik5_minimal_Minimal' by 'org_test_myapp_Myapp'. 
13. Edit myapp\jni\SDL\src\video\android\SDL_androidevents.c. 
    Replace 'com_bik5_minimal_Minimal' by 'org_test_myapp_Myapp'. 
14. And finally, run ndk-build to recompile the modified SDL files; then 
    run ant release to recompile the Java code and build the APK. Then, 
    test the APK: if it crashes right away, one of the steps above went 
    wrong. The easiest way to fix this is to search the relevant files 
    for remnants of the old name. 

You now have an APK with a unique name, signed with your own generated 
keystore. This file is ready to go to Google Play.

This has been written after my experiences writing “Hatched!” (available from Google Play: https://play.google.com/store/apps/details?id=com.bik5.hatched and https://play.google.com/store/apps/details?id=com.bik5.hatchedfull). I hope this helps others to more easily write games in C++ for Android using SDL2.

Big thanks for the tutorial! I’ve followed it and have succesfully created- and tested the android application and it works on both an emulator and on an actual device. :smiley:

One thing that I had problem with was in the PART F - Changing the application name - part, where a keystore should be generated. I realized I had to go into the java directory on the C-drive to find the keytool, start a command prompt and execute the “keytool -genkey …” command for it to generate a key. I think you should write in your tutorial that the user should go into the java directory, and so on, before executing the command in the command prompt (instead of executing the command inside the MyApp directory like I did).

Or maybe I did something wrong that caused me to not be able to execute the command inside the MyApp directory?

One thing that I had problem with was in the PART F - Changing the application name - part, where a keystore should be generated. I realized I had to go into the java directory on the C-drive to find the keytool, start a command prompt and execute the “keytool -genkey …” command for it to generate a key. I think you should write in your tutorial that the user should go into the java directory, and so on, before executing the command in the command prompt (instead of executing the command inside the MyApp directory like I did).

You should have executed the command listed in section F from the command prompt. The ‘keytool’ executable should be in your path if you executed step A7 correctly. Could you verify that?

Sorry for the late answer.

I incorrectly added the path’s (in part A, 7) to the system path and after made it correctly I can verify that it works the way it’s supposed to.

Dropbox link gives me 404. Is there any way you could put it up again? I’m trying to get my SDL2 application running on Android but I’m having hard time finding any good resources.

I just want to say you are awesome for making this tutorial. I look forward to using it in the future.