Author's Note: The following gives a detailed overview for everything needed in order to build a RapidGame project for Android. Most of this README is about what is required for Android development in general. As such, there will be redundant information for those who are already familiar with the topic. If that is the case, it is still recommended that you still skim through this README. - Samuel Ørsnæs
Run rapidgame prebuild android in a Cygwin shell to make sure the Android libraries are prebuilt.
cd [APPNAME]/Projects/android && makemake runYou can create, delete, and edit source files under [APPNAME]/Projects and assets under [APPNAME]/Assets as you wish. Changes in these folders will be included in the Android build automatically.
As the Android NDK and Ant are compressed folders (not something you install), you choose where you want to unpack them. According to the NDK, the path to it may not contain any spaces (e.g. /path to my/ndk is not allowed).
After downloading Android Studio, you will need to download the APIs for the OS version that you want to target. You could for example choose Android 4.3.1 (API 18) as your target OS. It turns out that the template project that comes with RapidGame targets API 18, while cocos2d-x/js itself targets API 10. This means that you must download these particular APIs before you can build the template project. In order to do so, you go to Android Studio > Configure > SDK Manager > [Select and install appropriate packages]. If you had previously created a project in Android Studio, then launching Android Studio will open up directly to the IDE. To navigate to the SDK Manager from there, you go to Tools > Android > SDK Manager.
(Windows only) Cygwin must be installed for all users (this is the recommended option in Cygwin's setup), which installs Cygwin in your root directory (C:\Cygwin or C:\Cygwin64). You should of course install the 64-bit version if you have a 64-bit machine. After you download the setup program found on their front page, you should keep this file stored somewhere safe in case you want to add packages or update Cygwin later. It is recommended that you use a Cygwin shell anytime you need to interact with the command line for your project. When you create a cocos2d-x/js project with RapidGame (rapidgame create), you must run Cygwin as administrator (right-click on `Cygwin Terminal` > `Run as administrator`). This is to ensure that the lib symlink is properly created. If you find installing Cygwin to be a bit intimidating, check out the Help!
Before building your first project, you should make sure all the necessary environment variables are set. If you don't know what that means, refer to Environment Variables Intro.
ANDROID_SDK_ROOT = /path/to/sdk
ANT_HOME = /path/to/ant
ANT_ROOT = /path/to/ant/bin
JAVA_HOME = /path/to/jdk
NDK_ROOT = /path/to/ndk
PATH = $PATH,
/path/to/python,
/path/to/jdk/bin,
/path/to/ndk,
/path/to/sdk/build-tools/[VERSION],
/path/to/sdk/platform-tools,
/path/to/sdk/tools
The above is a generic representation of the environment variables and not proper syntax. It up to you to format the information for your system.
(Windows only) In addition to setting the above environment variables for your host OS, you must also set ANDROID_SDK_ROOT and NDK_ROOT in Cygwin's ~/.bash_profile as you would on Mac. The formatting should be as follows:
export ANDROID_SDK_ROOT=C:/path/to/sdk
export NDK_ROOT=C:/path/to/ndk
Windows defaults:
C:\PythonXXC:\Program Files\Java\jdk1.XC:\Users\[USERNAME]\AppData\Local\Android\sdkMyGame = example root project directoryMyGame/Projects and your assets in MyGame/Assets.cd) to MyGame/Projects/android.make, your entire project will be built and packaged into an .apk file (the file that goes on your Android device).make will intelligently keep track of new and deleted files, so you don't have to.make will only keep track of the C and C++ (.c, .cpp, .cc, .cxx) source files in MyGame/Projects. This means if you have Objective-C (.m, .mm) files specific to iOS and Mac, make will ignore them when building your Android project.MyGame/Projects/android/makeignore.my cpp file.cpp is not allowed).make (such as what sort of output is logged to the console) by editing MyGame/Projects/android/makefile. Be careful of your changes, as they could adversely affect the build process or prevent you from building your project.make: Builds the debug version of your game and signs the .apk with the debug key (produces APPNAME-debug.apk). If you have never signed an Android application before and are prompted to enter information pertaining to the debug key, here is the info you need:
Absolute path:
(Mac) /Users/[USERNAME]/.android/debug.keystore
(Win) C:/Users/[USERNAME]/.android/debug.keystore
Keystore name: debug.keystore
Keystore password: android
Key alias: androiddebugkey
Key password: android
CN: CN=Android Debug,0=Android,C=US
make release: Builds the release version of your game but creates the .apk file using the debug key (produces APPNAME-debug.apk).make distribution: Builds the release version of your game and signs the .apk with the release key (produces APPNAME-release-aligned.apk). For info on how to create a release key and sign your app, refer to this page. If you prefer to do everything on the command line, take a look here. The commands are OS-agnostic, so they are the same on Mac and Windows.make run: You need to have run one of the above commands first. Your Android device must also have USB debugging enabled and be plugged in via USB. Installs APPNAME-debug.apk on your Android device and begins printing log output to the console. make run does not launch your app after installing it. As for the log output, the default settings--specified in the makefile--print debug output from your app and fatal errors from everywhere else. For more about how logging works, refer to this page. If you want all future projects to keep a particular setting, you can create your own RapidGame template.make run-relase: Installs APPNAME-debug.apk on your device and logs output to the console, exactly as make run does. However, you can modify the makefile to change what kind of logs you will see when you execute one command versus the other.make run-distribution: Installs APPNAME-release-aligned.apk on your device and logs output to the console. You need to have run make distribution first.make clean: Removes all the files and folders that are created when you build your game. Run this to clean up your Android project before you rebuild it.make start-emulator: You will first need to create an Android Virtual Device (AVD) using AVD Manager, which can be found at $ANDROID_SDK_ROOT/AVD Manager, or by opening Android Studio and navigating to Tools > Android > AVD Manager. The AVD you create should be set to use the ARM architecture, because 1) RapidGame Android projects can only build for ARM, and 2) an emulated x86 device requires you to download and configure several things before you can emulate that architecture. You will then need open the makefile and uncomment #emulator -avd [device_name] by removing the # and then replacing [device_name] with the name of the AVD you want to use for testing. In addition, uncomment the lines under run-emulator. Although the emulator is useful for testing your game in different environments, you should thoroughly test your game on at least a few physical Android devices before you release it. Take a look here as well if you want to try a faster Android emulation solution.make run-emulator: Installs APPNAME-debug.apk on your chosen AVD. The selected AVD must already be running (make start-emulator).If you are new to Android development, you may have questions about all the files that are in MyGame/Projects/android. First off, these files do not need to be changed in any way in order to get the template project running. However, they are needed in order to specify the metadata of your game, such as what the target Android OS version is, or whether your game starts in portrait or landscape, or what kind of permissions you want access to and what kind of hardware features your game requires. The following is a summary of the files you may want to modify for some reason or another in order to fit your needs. If you want a good starting point for better understanding of Android metadata files, this page is a place to start.
.identifier: The package identifier for your game..name: The name of your game.AndroidManifest.xml: This is the main file you will need to muck around with if you want to change any metadata about your game. Refer to the page mentioned above to see what's contained in the file itself and how to modify it.ant.properties: Add your keystore information to this file so that you are automatically prompted for the release key's password when you run make distribution. Refer here if you don't know what a keystore is or how to make one.makefile: Tells make what to do to build your project for each of the possible targets. You could for example change how verbose you want adb logcat to be when printing output to the console.makeignore: The list of C/C++ source files under MyGame/Projects that you don't want included in the Android build of your game.As your app is built using what Android considers native code (C++), your final .apk will contain code compiled for a specific architecture. If you were writing a pure Java app, that app would run on any device without needing to compile for each architecture thanks to the JVM. By default, your Android game is set to build for the ARM (armeabi) architecture, which a huge majority of Android devices use (think the equivalent to Intel's dominance in desktop computing). However, there is another version of ARM known as ARMv7, which is an architecture that is backwards compatitable with ARM, so you can just build your app for ARM and it will run on newer ARMv7 devices just fine. The main advantage of ARMv7 is faster floating point operations, so you may find your game performs better on newer devices. For more specific info on the different architectures, refer here. You can find out much more extensive documentation about the NDK in general by going to $NDK_ROOT/docs/Start_Here.html.
In order to actually get your project to compile for both ARM and ARMv7, you can edit APP_ABI in MyGame/Projects/android/Application.mk to read APP_ABI := armeabi armeabi-v7a. When you rebuild your project with make, the .apk will now contain the files for both ARM and ARMv7, and when the .apk is installed on a device, the necessary files will be used depending on the processor. One thing that must be noted is that when you build for ARMv7, you will get a long list of warning messages, and these messages will continue scrolling on the screen for several minutes until finally your game finishes building. There is nothing that can be done to prevent these warning messages (if you discover a way, please let us know on RapidGame's issues page (requires a Github account)), but they are harmless. Your game will still compile and run without issue. However, to speed up build time, you should only build for ARM during the development stage of your game. If your .apk gets to be over 50MB and you are considering submitting multiple .apk's for your game, then there are certain rules you must be aware of.
If you're not familiar with environment variables, they are variables that are accessible by any program on your computer, which makes them very powerful and important. One example of this usefulness is that when you type a command like python in your console, your computer doesn't automatically know where to find it. However, all major operating systems have a variable called PATH, that is a list of directories, which your computer searches in to find if there's something related to what you typed on the command line. So when you type python in your shell, the OS looks in all the directories listed in PATH and when it finds an executable named python, it executes that program. The following will explain how to properly set environment variables for your particular OS.
Environment variables can be set in a plain text file known as ~/.bash_profile (~ signifies your home directory, which is /Users/[USERNAME] on Mac). You can check that the file exists by running cd ~ && ls -a. To open the file, use your preferred text editor, such as nano .bash_profile. You will find other code written in the file already, which you should ignore. Go to the bottom of the file to add your specific environment variables. The format is as follows:
export var1=/path/to/var1
export var2=/path/to/var2
# We want to keep the original variable and append new paths to it
export PATH=$PATH:/path/to/something/else:/path/to/another/thing
When you are done editing the file, save and close it and then run cd ~ && source .bash_profile and you're good to go. If you want to double-check that the variable has the correct value, you can type echo $VAR, which will print the value of VAR back to you.
For Windows, the easiest way to edit your environment variables is by pressing the Windows button, searching "environment variables", and clicking on the link that comes up. A window should open that is divided into user and system variables, and we are only interested in editing user variables. Be sure to check if the variable already exists before trying to create a new one. Each variable has a name and a value, so if we were setting ANDROID_SDK_ROOT, then that would be the name, and the value might be C:\Users\John\AppData\Local\Android\sdk. If you want to add to an already existing variable, then you add the path to add to the beginning of the value and then place a ; between the path you added and the rest of the value, e.g. we want to add Python's path to some other paths, so the final result would look like: C:\Python27;C:\Program Files\Directory Containing MyProgram;C:\other\things.
MyGame = example root project directoryYou save your source files in MyGame/Projects and your assets in MyGame/Assets. You can see what goes into the .apk by running unzip -l MyGame/Projects/android/bin/[APKNAME].
Move the NDK folder to a path without any spaces.
make run and all I get is `waiting for device`!Have you enabled USB debugging for your device? Is your device plugged in via USB? Type adb devices to see if your device has been recognized. If you don't see your device, close the shell you are using and open a new one. Type adb devices one more time and your device should appear. Now you can execute make run.
Here. You need a GitHub account first.