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.