Android NDK Setup

This page explains how to compile gameplay for Android devices on Windows 7.

Install Tools

Install the Android SDK

1. Download and install the Android SDK.
2. Make sure <android-sdk-path>/tools and <android-sdk-path>/platform-tools are added to PATH.

Install the Android NDK

1. Download and install the Android NDK.
2. Follow these instructions.
3. Make sure <android-ndk-path> is added to PATH.

Install Apache Ant

1. Download and install Apache Ant.
2. Make sure <ant-path>/bin is added the PATH.

Install Cygwin

1. Download and install Cygwin
2. Select and add the package make: The GNU version of the 'make' utility during installation.
3. Rename awk.exe to something else (awk_.exe for example) in <android-ndk-path>/prebuilt/windows/bin. This is to prevent the Android build system from being confused by the cygwin's awk.

Choose your Android target

android.bat list targets

This will print the available Android targets. Remember the id of the target you wish to target (such as Android 2.3.3). You will need the id in the next part. Gameplay requires at least version 2.3.3.

Available Android targets:
----------
id: 1 or "android-10"
     Name: Android 2.3.3
     API level: 10
     Revision: 2
----------
id: 3 or "android-13"
     Name: Android 3.2
     API level: 13
     Revision: 1
...

Building the gameplay library

1. Open the Cygwin terminal.

2. Change directory to <gameplay-root>/gameplay/android

3. Run the following command to generate the needed files to build the project:

   android.bat update project -t 1 -p . -s

   Where -t 1 is the id of the target you picked in the previous step. You can also use -t "android-10".

4. Build the gameplay library: ndk-build

Building a sample game

1. Open the Cygwin terminal.

2. Change directory to <gameplay-root/gameplay-samples/sampleXX-XXXXX>/android

3. Run this command to generate the needed files to build the project:

   android.bat update project -t 1 -p . -s

   Where -t 1 is the id of the target you picked in the previous step. You can also use -t "android-10".

4. Build the gameplay sample: ndk-build

Loading a sample game

Make sure developer mode is enabled and USB debugging is turned on.

1. Change directory to <gameplay-root/gameplay-samples/sampleXX-XXXXX>/android
2. Install the app: ant debug install

Troubleshooting

Device not detected

If ant debug install does not work, ensure your device is being detected properly by running adb devices. If no devices are reported, try downloading the correct USB drivers from you phone manufacturer's website. (OEM Drivers)

Android NDK permissions errors

If you see an error like ./obj/local/armeabi/libpng.a: No such file: Permission denied, make sure that the *.a files have read permission by running: chmod +r obj/local/armeabi/*.a

Debugging

Use logcat to capture the log file from the device.

adb logcat -d > logcat.txt

If your program crashed then the log file will contain the stack trace without symbols. Use ndk-stack to make the stack trace readable.

-sym points to the directory that contains the symbols while -dump points to the log file.

ndk-stack -sym C:\Git\gaming\GamePlay\gameplay-samples\sample00-mesh\android\obj\local\armeabi -dump d:\logcat.txt

How to build in ARM mode (instead of thumb mode)

• Open Android.mk in gameplay/android/jni/Android.mk

• Open Android.mk in each of the games you want to compile in ARM mode.

  (Example: gameplay-samples/sample00-mesh/android/jni/Android.mk)

• Below LOCAL_STATIC_LIBRARIES, add the following line:

  LOCAL_ARM_MODE := arm
  

Note: You will have to re-run android.bat update (....) to update the build settings.