The SDL forums have moved to discourse.libsdl.org.
This is just a read-only archive of the previous forums, to keep old links working.


SDL Forum Index
SDL
Simple Directmedia Layer Forums
Android / SDL2: minimalistic framework / tutorial
jbikker


Joined: 01 Oct 2014
Posts: 9
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:
https://www.dropbox.com/s/8t52peh1vqec1is/minimal.rar?dl=0

And the article text:

Code:
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.
Naith


Joined: 03 Jul 2014
Posts: 158
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. Very Happy

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?
jbikker


Joined: 01 Oct 2014
Posts: 9
Naith wrote:
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?
Naith


Joined: 03 Jul 2014
Posts: 158
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.
Malapropos


Joined: 03 Jan 2015
Posts: 1
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.
GameCodingNinja


Joined: 29 Aug 2014
Posts: 32
I just want to say you are awesome for making this tutorial. I look forward to using it in the future.