From 16378982174051e996bb89cfa15a4381037c0142 Mon Sep 17 00:00:00 2001 From: Nat Weiss Date: Wed, 27 Jan 2016 01:35:27 -0800 Subject: [PATCH] Simplified Android prebuild no longer requires cygwin. --- .gitignore | 2 + CHANGELOG.txt | 10 +- README.md | 29 +- rapidgame.js | 146 +-- src/proj.android/build.sh | 155 --- src/proj.android/makefile | 26 - .../TwoScene/Projects/android/README.html | 1138 ----------------- 7 files changed, 90 insertions(+), 1416 deletions(-) delete mode 100755 src/proj.android/build.sh delete mode 100644 src/proj.android/makefile delete mode 100644 templates/cocos2dx/TwoScene/Projects/android/README.html diff --git a/.gitignore b/.gitignore index f1108dd..c2a54d8 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,5 @@ libexepath.txt msbuildpath.txt vctargetspath.txt RapidGame.xcodeproj +/current + diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 5e7ceba..6d95a1c 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -1,9 +1,15 @@ -Version 0.9.14 - January 12, 2015 +Version 1.0.0 - January 26, 2016 + + Linux support. + Can specify cocos2d-x source folder. + Simplified Android prebuild so it doesn't require cygwin on Windows. + +Version 0.9.14 - January 12, 2016 Fixed prebuild on Windows. Started automatic detection of whether to prebuild Javascript bindings by checking cocos/base/ccConfig.h. -Version 0.9.13 - January 10, 2015 +Version 0.9.13 - January 10, 2016 Updated to cocos2d-x 3.9. diff --git a/README.md b/README.md index 7276b3a..c5b239b 100644 --- a/README.md +++ b/README.md @@ -117,13 +117,21 @@ Windows: [Visual Studio](https://www.visualstudio.com/en-us/products/free-develo Linux: run `cocos2d-x/build/install-deps-linux.sh` and that [Git](http://git-scm.com/downloads) and [Node.js](https://nodejs.org/en/download/) are installed. -Android (any platform): please read the [Android README](http://htmlpreview.github.io/?https://github.com/NatWeiss/RapidGame/blob/master/templates/cocos2dx/TwoScene/Projects/android/README.html) or [watch the video](https://www.youtube.com/watch?v=5PWEtjvhX1k) to find out what you will need for Android development. +Android (any platform): you'll need to install the Android [SDK](http://developer.android.com/sdk/installing/) and [NDK](http://developer.android.com/tools/sdk/ndk/), then run the SDK Manager and install the latest *Tools*, *Platform Tools* and *Build-tools*. Finally, make sure that the environment variable `NDK_ROOT` is the path to the NDK. + + +Windows Notes +------------- + +1. **The `rapidgame create` or `rapidgame prebuild` command must be run as administrator.** This allows symlinks to be properly created. +2. If you have freshly installed Visual Studio, then you will need to run it once in order for it to download the necessary build tools. +3. To prebuild Android libraries, please set the `NDK_ROOT` environment variable. You can do this permanently for all command prompt sessions by going: Computer > Properties > Advanced System Settings > Environment System Variables. Confirm this with `echo %PATH%` or just try to run `ndk-build` from any directory. Updates ------- -* Coming soon: Linux support. Also can specify cocos2d-x source folder. +* Jan 27, 2016: Linux support. Can specify cocos2d-x source folder. Simplified Android prebuild so it doesn't require cygwin on Windows. * Jan 10, 2016: Updated to cocos2d-x 3.9. * Aug 17, 2015: Fixes for Visual Studio 2015. * Aug 11, 2015: On Windows, the path to MSBuild.exe, Lib.exe and VCTargetsPath can be set manually in case they cannot be automatically located. @@ -138,23 +146,6 @@ Updates * Aug 14, 2014: Prebuilder updated for cocos2d-js 3.0 rc2 / cocos2d-x 3.2. -Windows Notes -------------- - -1. **The `rapidgame create` or `rapidgame prebuild` command must be run as administrator.** This allows symlinks to be properly created. -2. If you have freshly installed Visual Studio, then you will need to run it once in order for it to download the necessary build tools. -3. To compile the Android libraries successfully, `rapidgame prebuild` must be run via [Cygwin](https://www.cygwin.com). Read about all the specific requirements in the [Android README](http://htmlpreview.github.io/?https://github.com/NatWeiss/RapidGame/blob/master/templates/cocos2dx/TwoScene/Projects/android/README.html), or [watch the video](https://www.youtube.com/watch?v=5PWEtjvhX1k) instead. -4. Windows cannot build the cocos2d-x libraries or cocos2d-js bindings for iOS and Mac. If you want to use RapidGame to develop for these platforms, you must use a Mac. - -Thanks to [Samuel Ørsnæs](https://github.com/samoersnaes) for originally getting the Android build working in Windows. - - -Android Notes -------------- - -A detailed guide has been written specifically for how to build Android projects using RapidGame. You can read it [here](http://htmlpreview.github.io/?https://github.com/NatWeiss/RapidGame/blob/master/templates/cocos2dx/TwoScene/Projects/android/README.html), or alternatively find it in your cocos2d-x/js project as `[APPNAME]/Projects/android/README.html`. - - Eliminate Grunt Work -------------------- diff --git a/rapidgame.js b/rapidgame.js index 1eafd8f..ff8124b 100644 --- a/rapidgame.js +++ b/rapidgame.js @@ -1080,16 +1080,11 @@ var linkWin = function(config, callback) { // prebuild android // var prebuildAndroid = function(platform, config, arch, callback) { - var i, j, src, dest, command, args = [], func, funcArg, + var i, j, src, dest, command, args = [], func, funcArg, ndkToolchainVersion = "", configs = (config ? [config] : (cmd.minimal ? ["Debug"] : ["Debug", "Release"])), - archs = (cmd.minimal ? ["armeabi"] : ["armeabi", "armeabi-v7a", "x86"]); + archs = (cmd.minimal ? ["armeabi"] : ["armeabi", "armeabi-v7a", "x86"]), + toolchains = ["4.9", "4.8", "4.7"]; - // Windows requires TERM environment variable (means running from cygwin) - if (process.platform === "win32" && !("TERM" in process.env)) { - logBuild("Can only build Android on Windows using a cygwin terminal", true); - callback(); - return; - } // All platforms require NDK_ROOT environment variable. if (!("NDK_ROOT" in process.env)) { logBuild("Can only build Android with a proper SDK and NDK installation.", true); @@ -1098,6 +1093,20 @@ var prebuildAndroid = function(platform, config, arch, callback) { callback(); return; } + + // Determine which toolchain to use. + for (i = 0; i < toolchains.length; i += 1) { + if (dirExists(path.join(process.env["NDK_ROOT"], "toolchains", "arm-linux-androideabi-" + toolchains[i]))) { + ndkToolchainVersion = toolchains[i]; + break; + } + } + if (ndkToolchainVersion.length <= 0) { + logBuild("No suitable toolchain version found in: " + path.join(process.env["NDK_ROOT"], "toolchains"), true); + logBuild("Acceptable versions: " + toolchains.join(", "), true); + callback(); + return; + } // create builds array builds = []; @@ -1106,61 +1115,30 @@ var prebuildAndroid = function(platform, config, arch, callback) { src = path.join(cmd.prefix, "src", "proj.android"); dest = path.join(cmd.src, "build", configs[i] + "-Android"); - // Always copy latest jni and build.sh and makefile. + // Always copy latest Android build files. logBuild("Copying " + src + " to " + dest, true); wrench.mkdirSyncRecursive(dest); - copyGlobbed(src, dest, "build.sh"); - copyGlobbed(src, dest, "makefile"); + //copyGlobbed(src, dest, "build.sh"); + //copyGlobbed(src, dest, "makefile"); copyGlobbed(path.join(src, "jni"), path.join(dest, "jni"), "*"); // Set func. func = linkAndroid; - funcArg = configs[i]; - if (process.platform === "win32") { - // win32 uses make - command = "make"; - args = []; - if (cmd.minimal) { - args.push(cmd.nostrip ? ["minimal-nostrip"] : ["minimal"]); - } else { - args.push(cmd.nostrip ? ["nostrip"] : []); - } - if (!doJSB) { - args.push("nojs"); - } + for (j = 0; j < archs.length; j += 1) { + // Run the ndk-build. + command = path.join(process.env["NDK_ROOT"], "ndk-build" + (process.platform === "win32" ? ".cmd" : "")); + args = [ + "-C", dest, + "NDK_TOOLCHAIN_VERSION=" + ndkToolchainVersion, + "NDK_MODULE_PATH=" + cmd.src, + "APP_PLATFORM=" + "android-18", + "APP_ABI=" + archs[j], + "CONFIG=" + configs[i], + "DO_JS=" + (doJSB ? "1" : "0") + ]; + funcArg = configs[i] + "-" + archs[j]; builds.push([configs[i], command, dest, args, func, funcArg]); - - //if (cmd.minimal) { - // if (cmd.nostrip) { - // builds.push([command, "non-stripped minimal (Debug armeabi)"]); - // } else { - // builds.push(["minimal (Debug armeabi)"]); - // } - //} else { - // if (cmd.nostrip) { - // builds.push(["non-stripped libraries for all platforms"]); - // } else { - // builds.push(["libraries for all platforms"]); - // } - //} - } else { - for (j = 0; j < archs.length; j += 1) { - // Mac and Linux use build.sh - command = path.join(dest, "build.sh"); - args = [ - archs[j], - configs[i] - ]; - if (cmd.nostrip) { - args.push("nostrip"); - } - if (!doJSB) { - args.push("nojs"); - } - - builds.push([configs[i], command, dest, args, func, funcArg]); - } } } nextBuild("Android", callback); @@ -1169,16 +1147,48 @@ var prebuildAndroid = function(platform, config, arch, callback) { // // link android // -var linkAndroid = function(config, callback) { - var dest; +var linkAndroid = function(configArch, callback) { + var a, src, dest, config = "", arch = ""; + // Copy these prebuilt files. + a = configArch.split("-"); + if (a.length >= 2) { + config = a[0]; + arch = a[1]; + + src = path.join(cmd.src, "build", config + "-Android", "obj", "local", arch); + dest = path.join(cmd.dest, "cocos2d", "x", "lib", config + "-Android", arch); + + logBuild("Copying Android libraries from " + src + " to " + dest, true); + copyGlobbed(src, dest, "*.a"); + } else { + logBuild("Failed to link Android because couldn't get config and arch from: " + configArch, true); + } + + // Copy other prebuilt libs. dest = path.join(cmd.dest, "cocos2d", "x", "lib", "Debug-Android"); - copyGlobbed(cmd.src, dest, "*.a", "android", 1); - + copyGlobbed(path.join(cmd.src, "external"), dest, "*.a", "android", 1); dest = path.join(cmd.dest, "cocos2d", "x", "lib", "Release-Android"); - copyGlobbed(cmd.src, dest, "*.a", "android", 1); + copyGlobbed(path.join(cmd.src, "external"), dest, "*.a", "android", 1); callback(); + +// build.sh used to combine all the .a files into one libcocos2dx-prebuilt.a like this: +/* +ar=$(ndk-which ar) +strip=$(ndk-which strip) +lib="libcocos2dx-prebuilt.a" +rm -f ${dest}/${lib} +for dir in audioengine_static cocos2dx_internal_static cocos_extension_static cocos_ui_static cocostudio_static spine_static \ + box2d_static cocos2dxandroid_static cocos_flatbuffers_static cocosbuilder_static bullet_static cocos3d_static \ + cocos_network_static cocosdenshion_static recast_static +do + ${ar} rs ${dest}/${lib} $(find ${src}/${dir} -name *.o) + if [ "$3" != "nostrip" ]; then + ${strip} -x ${dest}/${lib} + fi +done +*/ }; // @@ -1745,22 +1755,6 @@ var isWriteableDir = function(dir) { return false; }; -// -// a function to make paths cygwin-friendly -// -var cygwinDir = function(str) { - // cygwin needs c:\something => /cygdrive/c/something - if (process.platform === "win32" && ("TERM" in process.env)) { - str = str.replace(/\\/g, "/"); - str = str.replace(/c:/i, "/cygdrive/c"); - str = str.replace(/d:/i, "/cygdrive/d"); - str = str.replace(/e:/i, "/cygdrive/e"); - str = str.replace(/f:/i, "/cygdrive/f"); - str = str.replace(/g:/i, "/cygdrive/g"); - } - return str; -}; - // // reporting feature no longer used // diff --git a/src/proj.android/build.sh b/src/proj.android/build.sh deleted file mode 100755 index 8bedfd6..0000000 --- a/src/proj.android/build.sh +++ /dev/null @@ -1,155 +0,0 @@ -#!/bin/bash - -# Directory of script -CWD=$(dirname "$0") -#echo "CWD=${CWD}" -cd $CWD - -# Build settings -APP_PLATFORM="android-18" -if [ "$1" == "armeabi" ] || [ "$1" == "armeabi-v7a" ] || [ "$1" == "x86" ]; then - arch="$1" -else - arch="armeabi" -fi -if [ "$2" == "release" ] || [ "$2" == "Release" ]; then - config="Release" -else - config="Debug" -fi -if [ "$2" == "nojs" ] || [ "$3" == "nojs" ]; then - do_js="0" -else - do_js="1" -fi -echo "PLATFORM=${APP_PLATFORM}" -echo "ARCH=${arch}" -echo "CONFIG=${config}" -echo "DO_JS=${do_js}" - -# Get number of CPU cores -CORES=${NUMBER_OF_PROCESSORS} -if [ -z "$CORES" ]; then - CORES=$(grep -c ^processor /proc/cpuinfo 2>/dev/null || sysctl -n hw.ncpu) -fi -if [ -z "$CORES" ]; then - CORES=1 -fi -echo "CORES=$CORES" - -# Check for NDK_ROOT -if [ ! -d "${NDK_ROOT}" ]; then - echo "Please set the NDK_ROOT environment variable." - exit 1 -fi - -# Check for ANDROID_SDK_ROOT -#if [ ! -d "${ANDROID_SDK_ROOT}" ]; then -# echo "Please set the ANDROID_SDK_ROOT environment variable." -# exit 1 -#fi - -# Set module path -CC_ROOT=$(cd ../.. && pwd) -#SRC_ROOT=$(cd . && pwd) -SRC_ROOT=${CWD} -UNAME=$(uname -s) -#NDK_MODULE_PATH="${CC_ROOT}:${CC_ROOT}/external:${SRC_ROOT}" -NDK_MODULE_PATH="${CC_ROOT}" -echo "CC_ROOT=${CC_ROOT}" -echo "NDK_MODULE_PATH=${NDK_MODULE_PATH}" - -# Set NDK_TOOLCHAIN_VERSION -# Sam: NDK Toolchain Version 4.9 is now out (NDK r10e) -if [ -d "${NDK_ROOT}/toolchains/arm-linux-androideabi-4.9" ]; then - export NDK_TOOLCHAIN_VERSION="4.9" -elif [ -d "${NDK_ROOT}/toolchains/arm-linux-androideabi-4.8" ]; then - export NDK_TOOLCHAIN_VERSION="4.8" -elif [ -d "${NDK_ROOT}/toolchains/arm-linux-androideabi-4.7" ]; then - export NDK_TOOLCHAIN_VERSION="4.7" -else - echo "NDK toolchain version 4.9, 4.8 or 4.7 is required." - exit 1 -fi -echo "NDK_TOOLCHAIN_VERSION=${NDK_TOOLCHAIN_VERSION}" - -# Get which ar -# Sam: Tested on Mac as well and it works fine, appending NDK_ROOT to the beginning caused the problem on cygwin -ar=$(ndk-which ar) - -if [ ! -f "$ar" ]; then - echo "Missing the 'ar' NDK build tool. Please install the Android NDK and toolchains." - exit 1 -fi -echo "AR=${ar}" - -# Get which strip -strip=$(ndk-which strip) - -if [ ! -f "$strip" ]; then - echo "Missing the 'strip' NDK build tool. Please install the Android NDK and toolchains." - exit 1 -fi -echo "STRIP=${strip}" - -# Create build command -export CONFIG="${config}" -export DO_JS="${do_js}" -CMD="${NDK_ROOT}/ndk-build --jobs=${CORES} -C ${CWD} NDK_MODULE_PATH=${NDK_MODULE_PATH} APP_PLATFORM=${APP_PLATFORM} APP_ABI=${arch}" -echo "CMD=${CMD}" -echo - -# NDK build -echo "Building ${APP_PLATFORM} ${arch} ${config}..." -$CMD -res="$?" -if [ "$res" != "0" ]; then - echo 'ndk-build failed.' - exit 1 -fi - -# Link libraries -if [ "${config}" == "Debug" ]; then - src="obj/local/${arch}/objs-debug" -else - src="obj/local/${arch}/objs" -fi -src=$(cd ${src}; pwd) -if [ "${UNAME:0:6}" == "CYGWIN" ]; then - # Sam: Modify the path so that it replaces /cygdrive/c (11 characters) with C: on Windows - # Sam: cygwin must be installed in the root directory (recommended option in cygwin's setup) - temp=$src - src="C:" - src=$src${temp:11:4200} -fi -echo "SRC=${src}" - -# Sam: When rapidgame creates its directories, latest is created as a folder itself and not a symlink on Windows -# Sam: This must be updated for every version of rapidgame to continue to work, unless you get latest to be a symlink like on Mac -# To Sam: symlinks are possible on Windows and it should be that way (rapidgame init . is working for example...) -# To Nat: Yes, and I encountered the same problem when not running in root. I checked the symlink code in rapidgame.js and -# it seems you catch the permissions error exception without doing anything. It is okay to just have this line by itself -# now, but the first time someone creates a cocos2dx project, they MUST run with admin privileges, so that latest is created as a symlink. -dest=../../../../latest/cocos2d/x/lib/${config}-Android/${arch} - -mkdir -p ${dest} -dest=$(cd ${dest}; pwd) -if [ "${UNAME:0:6}" == "CYGWIN" ]; then - temp=$dest - dest="C:" - dest=$dest${temp:11:4200} -fi -echo "DEST=${dest}" - -lib="libcocos2dx-prebuilt.a" -rm -f ${dest}/${lib} -for dir in audioengine_static cocos2dx_internal_static cocos_extension_static cocos_ui_static cocostudio_static spine_static \ - box2d_static cocos2dxandroid_static cocos_flatbuffers_static cocosbuilder_static bullet_static cocos3d_static \ - cocos_network_static cocosdenshion_static recast_static -do - ${ar} rs ${dest}/${lib} $(find ${src}/${dir} -name *.o) - if [ "$3" != "nostrip" ]; then - ${strip} -x ${dest}/${lib} - fi -done - diff --git a/src/proj.android/makefile b/src/proj.android/makefile deleted file mode 100644 index f28709d..0000000 --- a/src/proj.android/makefile +++ /dev/null @@ -1,26 +0,0 @@ -SHELL=/bin/bash - -all: - ./build.sh armeabi Debug - ./build.sh armeabi-v7a Debug - #./build.sh x86 Debug - ./build.sh armeabi Release - ./build.sh armeabi-v7a Release - #./build.sh x86 Release -nostrip: - ./build.sh armeabi Debug nostrip - ./build.sh armeabi-v7a Debug nostrip - #./build.sh x86 Debug nostrip - ./build.sh armeabi Release nostrip - ./build.sh armeabi-v7a Release nostrip - #./build.sh x86 Release nostrip -minimal: - ./build.sh -minimal-nostrip: - ./build.sh armeabi Debug nostrip -clean: - rm -rf libs - rm -rf obj - rm -rf bin - rm -rf gen - rm -rf assets diff --git a/templates/cocos2dx/TwoScene/Projects/android/README.html b/templates/cocos2dx/TwoScene/Projects/android/README.html deleted file mode 100644 index eda1eaa..0000000 --- a/templates/cocos2dx/TwoScene/Projects/android/README.html +++ /dev/null @@ -1,1138 +0,0 @@ - - - - - - - Android README - - - - - - -

Building Android README

- -

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

- - - - -

Don't Forget! (Windows only)

- -

Run rapidgame prebuild android in a Cygwin shell to make sure the Android libraries are prebuilt.

- - - - -

Index

- -
    -
  1. TL;DR
    2. -
  2. Prefer a video instead?
    3. -
  3. Prerequisite Downloads
    4. -
  4. Setup Environment Variables
    5. -
  5. Building Your Project
    6. -
  6. Modifying for Your Needs
    7. -
  7. Building for Different Architectures
    8. -
  8. Useful Resources and Tools
    9. -
  9. Environment Variables Intro
    10. -
  10. Help!
    11. -
- - - - -

TL;DR

- - - -

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

- - - - -

Prefer a video instead?

- - - - - - -

Prerequisite Downloads

- - - -

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!

- - - - -

Setup Environment Variables

- -

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:

- - - - - -

Building Your Project

- - 
MyGame = example root project directory
- - -

Commands

- -
    -
  1. - 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
-
    -
    2. - -
  2. make release: Builds the release version of your game but creates the .apk file using the debug key (produces APPNAME-debug.apk).
    3. - -
  3. 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.
    4. - -
  4. 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.
    5. - -
  5. 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.
    6. - -
  6. 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.
    7. - -
  7. 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.
    8. - -
  8. 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.
    9. - -
  9. make run-emulator: Installs APPNAME-debug.apk on your chosen AVD. The selected AVD must already be running (make start-emulator).
    10. -
- - - - -

Modifying for Your Needs

- -

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.

- - - - - - -

Building for Different Architectures

- -

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.

- - - - -

Useful Resources and Tools

- - - - - - -

Environment Variables Intro

- -

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.

- -

Mac

-

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.

- -

Windows

-

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.

- - - - -

Help!

- 
MyGame = example root project directory
- -

Where do I save my code/assets?

-

You 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].

- -

I'm having trouble with the NDK!

-

Move the NDK folder to a path without any spaces.

- -

How do I install Cygwin?

-
    -
  1. Launch setup program
    2. -
  2. (Welcome page) > Next
    3. -
  3. Install from Internet > Next
    4. -
  4. Install for `All Users` > Next
    5. -
  5. Choose a safe directory > Next
    6. -
  6. Direct connection > Next
    7. -
  7. Choose a mirror (anyone but the first) > Next
    8. -
  8. Click the icon to the right of `Devel` to change it from `Default` to `Install` > Next
    9. -
  9. `Select required packages` should be checked > Next
    10. -
  10. Wait... > Finish
    11. -
- -

I ran 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.

- -

Where do I ask a question/submit an issue?

-

Here. You need a GitHub account first.

- - - -