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:
Building for running the sample projects.
Building for compatibility with Ogre's "iPhone OS" Xcode project template.
These two cases are detailed below.
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)