Saturday, July 27, 2013

Building mobile game engine with Android NDK: 1 - installing the tools and running samples

all parts
1 - installing the tools and running samples
2 - calling C++ library from Java
3 - abstracting types and logging
4 - timing service

 This post is first in series of articles on creating your own simple game engine. The engine will be written in C++ (mostly) and will use OpenGL ES 2.0 for rendering the graphics. It will start with building the engine for Android NDK and in later parts we will go multiplatform.

 In first part we will install the tools and test it with one of the examples delivered within NDK package.


 As written above we will start with Android NDK. You should have installed:
  • Android SDK
  • Android NDK
  • Eclipse (with CDT plugin)
 I had Android SDK installed previously and used it with older version of Eclipse (Juno). I will describe here how to set it manually with latest Eclipse release (Kepler). Installing ADT bundle can probably save some work as it contains Android SDK + Eclipse. So, if you do not have Android SDK installed from past skip to place where NDK installation is described.

 To install eclipse download the latest (Kepler) .zip package from Eclipse site. The installation package you are interested in is "Eclipse IDE for Java Developers". I have 64 bit Windows 7 so I grabbed 64 bit version. Unzip it into directory of your choice. Now, you have pure eclipse. You still can not develop for Android under it. You have to install ADT plugin. In menu, go to "Help->Install New Software..":
 Press "Add..." button and put "" into second edit field:

 Install all items that are offered then.

 Now you need to install CDT plugin that will allow you to develop C++ code under Eclipse. repeat the procedure above but this time enter these values:
 Again, install all that is offered.

 Plugins are installed so let's do some settings.Now we need to install Android NDK. Get it here. The installation is again simple unzipping into directory of your choice.

 Get back to Eclipse and go to "Window->Preferences":
 And set path to you NDK installation directory:

 If you do not have any virtual Android Virtual Device (emulator) created, create one. You can find step by step how to here.

 In your Windows environment variables check that you have ANDROID_SDK and ANDROID_NDK variables set and correctly pointing into your installation directories. If you do some changes here do not forget to restart Eclipse.

Running example

 Now let's test the tools with some example. We will chose San Angles demo that is one of the samples in "android-ndk-r9\samples\" directory. Go to "File->New->Other...":

  Select "Android Project from Existing Code":

  Navigate with "Browse..." button to directory:

Go again to "File->New->Other..." and convert the project to C/C++ project:
 Then select "Makefile project" and "-- Other Toolchain --":

 The Eclipse will offer you to open C/C++ perspective.
 Right click the project name and open "Properties" (in very bottom). Uncheck "Use default build command" and replace "Build command" with "ndk-build.cmd"
 (update 1: Andrew K in comments bellow pointed that it was necessary for him to put "${ANDROID_NDK}ndk-build.cmd" here)
 (update 2: the reason for above is that ANDROID_NDK variable must be part of your environment PATH variable. Put it there like this: %ANDROID_NDK%.  It will take content of ANDROID_NDK variable so you do not have to rewrite it every time you upgrade to higher NDK version. Adjusting ANDROID_NDK variable will be enough):

  You should be now able to build the demo with hammer icon or with "Build Project" command when right-clicking on the project name. The build output is located in "Console" tab in the bottom.
 Unfortunately you are not finished yet. On the left side you have directory structure of the demo. Go to "jni" directory and open "app-android.c" file. If it is the same for you as I got it, you will have lot of errors in the file:

 Right click the project again to get into Properties and in "Builders" change the order so CDT builder is behind Java Builder:

 Then go to "C/C++ General -> Paths ans Symbols". Click tab Includes and add these two lines into all Configurations and Languages:
  • "${env_var:ANDROID_NDK}/toolchains/arm-linux-androideabi-4.8/prebuilt/windows-x86_64/lib/gcc/arm-linux-androideabi/4.8/include"
  • "${env_var:ANDROID_NDK}/platforms/android-18/arch-arm/usr/include"

 Also define these symbols - "__ANDROID__" and "__GNUC__" (there are two underscores):
 After rebuilding the index, the errors should disappear.


 Now you can start the emulator and run the demo in it:

 The steps in "Preparation" part need to be done only once while the steps described in "Running example" need to be done every time you start new project (or try to run any of the samples).
 In next part we will start some coding.