CMake Quick Start Guide         A guide to get you building OGRE from source with the default settings in the shortest possible time
IMPORTANT: These instructions are meant to be used with old releases of Ogre. For Ogre 1.10+, rather use BuildingOgre.md.
Image

For the impatient: Learn how to build Ogre with CMake in two minutes. If you encounter any problems or need some more advanced procedures, do read the rest of the sections below!

Introduction

This guide is designed to get you building OGRE from source with the default settings in the shortest possible time, showing you the barest minimum of CMake to do that, and minus any real discussion. Remember that there is a lot more to the hows and whys of this process, so it's a good idea to go back to the Getting Started With CMake page and read the whole thing when you have time.

We assume here that you've already downloaded / extracted the OGRE source code into a folder on your local machine. From here, go to the section for your platform.


Here we target the lowest possible Android API, which is API 10 Android 2.3.3. This build process has been tested using OGRE v1.9 and v1.10 using both Linux and Windows hosts and up to Android 4.4 Kitkat (API 19).

General Android Build Instructions:

  1. Download and install the Android SDK:
    https://developer.android.com/sdk/
  2. Follow the instructions on the SDK site to use the tools included in the SDK to download and install your target Android API version.
  3. Download and install the Android NDK. Android NDK revision 8b is not supported due a bug in the toolchain.
    https://developer.android.com/tools/sdk/ndk/
  4. Initialize your Android SDK and NDK environment variables:
    1. Create environment variables ANDROID_SDK and ANDROID_NDK and set them to the full install path of the Android SDK and NDK respectively.
    2. Prepend %ANDROID_SDK%\tools, %ANDROID_SDK%\platform-tools, and %ANDROID_NDK% to the beginning of your PATH variable.
  5. Download and build the OGRE dependencies. This will require configuring `ogredeps` to target an Android build while running CMake.
    1. Download ogredeps.
      https://bitbucket.org/cabalistic/ogredeps
    2. Navigate your command prompt to the root of the ogredeps build directory.
    3. Run CMake to create your build files. ANDROID_ABI is usually armeabi-v7a, ANDROID_NATIVE_API_LEVEL should match whatever API level you downloaded via the SDK utilities, ANDROID_TOOLCHAIN_NAME should match the toolchain (i.e., build system) you wish to use from %ANDROID_NDK%\toolchains, and replace "Unix Makefiles" with whatever build system you wish to use. Assuming you are building from ogredeps/build:
      cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE="../cmake/android.toolchain.cmake" -DANDROID_ABI=armeabi-v7a -DANDROID_NATIVE_API_LEVEL=10 -DANDROID_TOOLCHAIN_NAME=arm-linux-androideabi-4.8 ..
    4. Build as usual using your target build system.
  6. Build OGRE for Android.
    1. Download the OGRE source code (either via the Mercurial repo or the compressed source archive).
    2. Run CMake from the OGRE build directory. Again, change parameters like you did while building ogredeps to suit your Android target. Assuming you want to build OGRE in the folder ogre/build, run CMake like so:
      cmake -DCMAKE_TOOLCHAIN_FILE="../CMake/toolchain/android.toolchain.cmake" -DOGRE_DEPENDENCIES_DIR="/path/to/ogredeps/build" -DANDROID_ABI=armeabi-v7a  -DANDROID_NATIVE_API_LEVEL=10 -DANDROID_TOOLCHAIN_NAME=arm-linux-androideabi-4.8 ..
    3. Build as usual using your target build system. Replace "darwin-x86" with the folder corresponding to your host build system. If using the Make build system, you may want to use the version of make included with the NDK.
      android-ndk/prebuilt/darwin-x86/bin/make)
  7. (Optional) Build and install the OGRE SampleBrowser onto your Android device.
    1. Download and install ant (http://ant.apache.org/bindownload.cgi) which will be used to build Android projects from the command line and install them on your device. On most OS, this could be done either manually or using a package manager (including Chocolatey on Windows, MacPorts or Homebrew on Mac OS X, or whatever package manager comes with your Linux distro).
    2. Navigate your command prompt to the SampleBrowserNDK subfolder in your OGRE build folder.
    3. Build the SampleBrowser as a native activity using ndk-build. Optionally use the "-j <# threads>" option — without the quotes of course — for a parallel build.
      ndk-build all
    4. Attach your Android device to your PC so that a call to 'adb devices' lists the device.
    5. Build a debug APK of the SampleBrowser and install on Android device:
      ant debug install
  8. (Optional) Build and install the OGRE JNI example application, which demonstrates how to interface a C++ OGRE application with a Java Android bridge.
    1. TODO: Fill me in.


Notes on building for Android on Linux host:

Notes on building for Android on Mac OS X host:

Notes on building for Android on Windows host:
Standard NMake can only build one file at a time. For functionality similar to "make -j" (parallel builds), use JOM in place of the "nmake" command above. JOM can be found here: http://qt-project.org/wiki/jom

Here is a sample CMake configuration command for building OGRE for Android on Windows using NMake as the build system and armeabi as the Android ABI (assuming you are building from ogre/build):

cmake -G"NMake Makefiles" -DCMAKE_TOOLCHAIN_FILE=..\CMake\toolchain\android.toolchain.cmake -DOGRE_DEPENDENCIES_DIR="/path/to/ogredeps/build" -DANDROID_ABI=armeabi -DANDROID_NATIVE_API_LEVEL=9 -DANDROID_TOOLCHAIN_NAME=arm-linux-androideabi-4.8 ..