Building From Source - iPhone         Instructions for building iPhone using CMake

Before You Read This...


This article assumes that you have already downloaded and installed CMake, and obtained the Ogre source. For instructions on obtaining the Ogre source via Mercurial, see Building Ogre.

Xcode 4.3 changed the layout of developer tools on disk which can cause some serious problems for CMake. The issue has been fixed but is not yet publicly released. CMake 2.8.8 will include Xcode 4.3 support. At the time of writing, a release candidate is available that includes this support.

You will also need to install the Command Line Tools from within Xcode's Downloads Preferences and set the Xcode path from the command line like this.

Assuming that Xcode is installed in /Applications,

sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer

If you want to test your build on an iOS device (instead of just the simulator), you should also have obtained an App ID from the iOS Provisioning Portal on developer.apple.com.

Obtaining Dependencies


Head over to http://sourceforge.net/projects/ogre/files/ogre-dependencies-mac/ and download the latest iPhone dependencies package. Once it has finished downloading, double-click on the disc image to mount it. Copy the iPhoneDependencies folder to the root of the Ogre source tree. It should reside alongside folders such as OgreMain, Samples, Tests, PlugIns, etc.

For Ogre 1.8 forward, this directory should be named iOSDependencies.

Your Ogre directory should look similar to this:

CMake
Components
iOSDependencies
Docs
OgreMain
Other
PlugIns
RenderSystems
Samples
SDK
Tests
Tools

Building


Two common cases are:

  1. Building for running the sample projects.

  2. Building for compatibility with Ogre's "iPhone OS" Xcode project template.


These two cases are detailed below.

 Building with Xcode 4
If you are using Xcode 4, the ALL_BUILD target will not work. Use the SampleBrowser target instead.

 Libc++ is required for Ogre 1.9
Starting with Ogre 1.9 libc++ and C++11 are enabled by default. That means that in the Xcode build settings for your project you must choose C++11 for the C++ Language Dialect and libc++ as the C++ Standard Library.

For Running the Sample Projects


The best way to configure for iPhone is using Terminal. Using CMake-Gui doesn't quite configure correctly at the time of this writing.
First change to the directory of the Ogre sources. Now create a build directory and change to it:
mkdir build && cd build
You need to run cmake from the build directory and provide it with the location of the build directory. If you followed the above guideline, then you can simply type:
cmake -D OGRE_BUILD_PLATFORM_IPHONE=1 -G Xcode ..

For OGRE 1.8 and beyond, this has been changed because iOS is used on devices besides iPhones now. If you are using the 1.8 branch here is the command to use:
cmake -D OGRE_BUILD_PLATFORM_APPLE_IOS=1 -G Xcode ..

CMake will now parse the scripts in the Ogre source tree. Watch the output, especially if all necessary dependencies have been found. If not, you might need to install the missing ones or provide their locations manually.

A Xcode project has now been generated in the build directory, so to start the Ogre build, open OGRE.xcodeproj and build as usual.

To run samples on your device you will need to have a valid iPhone Developer certificate installed. For each sample, double click on target in the Groups & Files list. Ensure that a valid identity is selected in the Code Signing Identity drop menu.

Also, because we can't tell CMake what Xcode project format you want, you will have to change it yourself. Open the Project Menu, choose Edit Project Settings. Click on the General tab in the settings window. Change Project Format to Xcode 3.1-compatible. If you are using CMake 2.8 it is not necessary to change the Project Format.

And another thing. You will need to manually set the Bundle Identifier property of the Info.plist file to match the App ID of the chosen code signing identity. This can be done from the Target Properties panel. It must match the bundle identifier of a valid developer certificate if you are building for devices.

For Compatibility with the Template Project


If you want to use the Xcode template installer package after building the source, use the script below to create and modify your build directory so it matches the pre-built SDK.

NOTE: If you get "BUILD FAILED" error because of No architectures to compile for (ONLY_ACTIVE_ARCH=YES, active arch=x86_64, VALID_ARCHS=i386). then replace line xcodebuild -sdk iphonesimulator -configuration $CONFIG" with "xcodebuild -sdk iphonesimulator -configuration $CONFIG ARCHS="i386 x86_64" ONLY_ACTIVE_ARCH=NO

NOTE: Modify the constants at the start of the script depending on your own directory paths and configuration preferences. Also, when building Ogre 1.8 or later, replace OGRE_BUILD_PLATFORM_IPHONE with OGRE_BUILD_PLATFORM_APPLE_IOS

#! /bin/bash

#############
# CONSTANTS #
################################################################################

# Absolute path to the source code directory.
SRC=`pwd`/src

# Absolute path to the build directory.
BUILD=`pwd`/build/iOS

# The build configuration. Recommended values are:
#   Release        - optimized code that excludes debugging information.
#   RelWithDebInfo - optimized code that includes debugging information.
CONFIG=Release

################################################################################

# Clear the old build and recompile the new one.
rm -rf $BUILD
mkdir $BUILD
cd $BUILD
cmake -D OGRE_BUILD_PLATFORM_APPLE_IOS=1 -G Xcode $SRC
cd $BUILD
xcodebuild -sdk iphoneos -configuration $CONFIG
mkdir $BUILD/lib/Release-iphoneos
mv $BUILD/lib/Release/* $BUILD/lib/Release-iphoneos
xcodebuild -sdk iphonesimulator -configuration $CONFIG
mkdir $BUILD/lib/Release-iphonesimulator
mv $BUILD/lib/Release/* $BUILD/lib/Release-iphonesimulator
for FILE in `ls $BUILD/lib/Release-iphoneos`
do
  lipo $BUILD/lib/Release-iphoneos/$FILE \
    -arch i386 $BUILD/lib/Release-iphonesimulator/$FILE \
    -create -output $BUILD/lib/Release/$FILE
done
rm -rf $BUILD/lib/Release-iphoneos
rm -rf $BUILD/lib/Release-iphonesimulator

# Copy the dependencies.
cp -R $SRC/iOSDependencies $BUILD
ln -s $BUILD/iOSDependencies/include/OIS $BUILD/include/OIS
rm -rf $BUILD/iOSDependencies/lib/Debug

# Add necessary files to the lib directory.
mv $BUILD/pkgconfig $BUILD/lib

# Remove samples, which are not useful as libraries.
rm $BUILD/lib/Release/*Sample*

# Add necessary files to the include directory.
mkdir $BUILD/include/OGRE
mkdir $BUILD/include/OGRE/iOS
mkdir $BUILD/include/OGRE/Paging
mkdir $BUILD/include/OGRE/Plugins
mkdir $BUILD/include/OGRE/Plugins/BSPSceneManager
mkdir $BUILD/include/OGRE/Plugins/OctreeSceneManager
mkdir $BUILD/include/OGRE/Plugins/OctreeZone
mkdir $BUILD/include/OGRE/Plugins/ParticleFX
mkdir $BUILD/include/OGRE/Plugins/PCZSceneManager
mkdir $BUILD/include/OGRE/Property
mkdir $BUILD/include/OGRE/RenderSystems
mkdir $BUILD/include/OGRE/RenderSystems/GLES
mkdir $BUILD/include/OGRE/RenderSystems/GLES/EAGL
mkdir $BUILD/include/OGRE/RenderSystems/GLES2
mkdir $BUILD/include/OGRE/RenderSystems/GLES2/EAGL
mkdir $BUILD/include/OGRE/RTShaderSystem
mkdir $BUILD/include/OGRE/Terrain
mkdir $BUILD/include/OGRE/Threading
mv $BUILD/include/OgreBuildSettings.h $BUILD/include/OGRE
cp $SRC/OgreMain/include/*.h $BUILD/include/OGRE
cp $SRC/Samples/Common/include/* $BUILD/include/OGRE
cp $SRC/OgreMain/include/iOS/* $BUILD/include/OGRE/iOS
cp $SRC/Components/Paging/include/* $BUILD/include/OGRE/Paging
cp $SRC/Plugins/BSPSceneManager/include/* $BUILD/include/OGRE/Plugins/BSPSceneManager
cp $SRC/Plugins/OctreeSceneManager/include/* $BUILD/include/OGRE/Plugins/OctreeSceneManager
cp $SRC/Plugins/OctreeZone/include/* $BUILD/include/OGRE/Plugins/OctreeZone
cp $SRC/Plugins/ParticleFX/include/* $BUILD/include/OGRE/Plugins/ParticleFX
cp $SRC/Plugins/PCZSceneManager/include/* $BUILD/include/OGRE/Plugins/PCZSceneManager
cp $SRC/Components/Property/include/* $BUILD/include/OGRE/Property
cp $SRC/RenderSystems/GLES/include/*.h $BUILD/include/OGRE/RenderSystems/GLES
cp $SRC/RenderSystems/GLES/include/EAGL/* $BUILD/include/OGRE/RenderSystems/GLES/EAGL
cp $SRC/RenderSystems/GLES2/include/*.h $BUILD/include/OGRE/RenderSystems/GLES2
cp $SRC/RenderSystems/GLES2/include/EAGL/* $BUILD/include/OGRE/RenderSystems/GLES2/EAGL
cp $SRC/Components/RTShaderSystem/include/* $BUILD/include/OGRE/RTShaderSystem
cp $SRC/Components/Terrain/include/* $BUILD/include/OGRE/Terrain
cp $SRC/OgreMain/include/Threading/* $BUILD/include/OGRE/Threading

# Remove everything except headers and libraries.
for FILE in `ls $BUILD`
do
  if [ $FILE != "include" ] &&
     [ $FILE != "iOSDependencies" ] &&
     [ $FILE != "lib" ]
  then
    rm -rf $FILE
  fi
done


When the script starts running, pay attention to any initial warning messages about missing dependencies. You might need to install additional libraries on your system in order to make everything build properly (i.e. to avoid runtime failures later). Among other things, zziplib (ex. "libzzip" in MacPorts) seems to be necessary.

Once you have built your SDK, head over to http://sourceforge.net/projects/ogre/files/ogre-dependencies-mac/ and download the latest Xcode templates installer. Once it has finished downloading, extract and run the installer.

Create an Xcode project using the template. When prompted, enter the absolute path to your build directory (BUILD in the script above) as the Ogre iOS SDK Path. Build and run.


Alias: Building From Source (for iPhone)