(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.