Guide to Installing Ogre3D on Mac OS X (Xcode + Ogre SDK 1.7.3)

This guide serves as an introduction to getting started with Ogre3D on Mac OS X, namely setting up the development environment and building a basic application. It’ll serve as the first in several series of blog posts I intend to write on the subject. Let me say this first. I am not an expert on Ogre, 3D graphics development or theory, or Macs. I may get the jargon wrong and my instructions may not work for very system, so contacting me for help may not the best thing to do, however I’ll do what I can to assist if you do.

There is a lot of information on Ogre in general on the Internet, but not too much on configuring it on Mac or Linux. I will write a document for installing Ogre on Linux at a later date, but for now it’s OSX time. Also, you should definitely visit the Ogre Wiki after reading this tutorial for even more information.

Step 1 – Download & Install Apple Xcode IDE

To get started, you should first get the Xcode IDE if you don’t already have it. Apple makes it available as a free download after you create an account on their website (the 3.x version is free at the time of this writing). Visit the Apple Developer Website to download a copy of the Xcode 3 IDE. After you download Xcode, then install it. I’m not going into detail for this step as it’s very straightforward to install the Xcode IDE.

Step 2 – Download & Install NVIDIA Cg Toolkit

The NVIDIA CG Toolkit isn’t required but is needed for the Ogre Cg Program Manager. To install the toolkit, you’ll need to go to the NVIDIA developer website, create a login if you don’t already have one, then download the Mac OS X DMG image. To do this, visit the NVIDIA Developer Cg Toolkit Page and scroll to the bottom of the page. Click on the download link. On the Access Denied page, click on the Login link. Proceed to create an account by clicking on the Create new account tab. Go back to the download page and fetch the Mac OS X file image. Install the NVIDIA Cg Toolkit it like you would any other Mac setup package.

Step 3 – Download & Install Ogre SDK 1.7.3 & OSX Dependencies

At the time of this article the current version of Ogre3D is 1.7.3. To keep things simple we’ll be installing the prebuilt release of Ogre SDK for OS X instead of compiling from source. To get started, we have to visit the Ogre3D website and download the Ogre 1.7.3 SDK for Mac OS X. On that page there is a link to the latest Mac OS X Ogre3D release. Download the Ogre SDK to your computer (it’ll be a .DMG Apple Disk Image File). Double-click the Ogre SDK DMG to mount the disk image.

You’ll be greeted with an Ogre SDK window (as shown on the left). There is a blue folder called OgreSDK in that window, ctrl-click (aka right-click) on that folder and select the Copy “OgreSDK” menu option. Paste the folder to your hard drive (I recommend the root, that being /OgreSDK). Open a Finder window, select your hard drive under Devices, ctrl-click and Paste the OgreSDK folder.

As you can see from the image to the right, the OgreSDK folder is quite large so the copy process may take a moment. When it’s done we move on to the next step, that being installing the Ogre dependency files. There is a zip file containing dependencies we’ll need to be able to build our own Ogre Mac OSX applications, and these dependencies are boost, FreeImage, freetype, OIS, and zzip.

The Ogre Mac OSX dependencies zip file is located on SourceForge. When you get there, follow the ogre-dependencies-mac -> 1.7 folder path. Download the file OgreDependencies_OSX_20110208.zip and extract its contents. You’ll get a folder called Dependencies. Move that folder into the /OgreSDK folder (or wherever you put yours).

Step 4 – Download & Install Ogre Xcode Templates

Xcode templates are available for creating minimal Ogre3D Mac Projects. The Mac OS X Universal Precompiled Dependencies for OSX and iOS can be found of the SourceForge website. There are two installer versions available: the one that has Ogre templates for Xcode 3 and the other for Xcode 4. My directions are made for Xcode 3 so that is the Ogre template installer I’ll be using. I can’t tell you if my directions will work for Xcode 4 since I don’t have it to test against.

Okay, so first thing is to download the Ogre Xcode template installer package. Visit the Ogre SourceForge Files website. Download the Ogre_Xcode_Templates_20101211.pkg.zip file to your Desktop or some other location on your Mac, extract the Ogre Xcode Templates Package from the zip file, and launch the installer by double-clicking on the package.

On Step 5 of the installer you’ll be asked for the paths to the OSX and iOS Ogre SDK locations. I haven’t discussed the iOS iPhone SDK release of Ogre and we’ve only installed the OSX version, so for now choose the Find Ogre button for the OSX option. Point to the /OgreSDK path (or to the location where you decided to install the Ogre SDK). Wrap up the rest of the installation by clicking Continue and finally Close.

Step 5 – Create a Mac OSX Ogre Project From The Xcode Template

Fire up Xcode and create a new Ogre3D project. You’ll notice on the left side there is now an Ogre section under User Templates. Click on Ogre and there are two template to choose from: iPhone OS and Mac OS X. I’m going to save the iPhone stuff for my next Ogre tutorial, so for now pick Mac OS X and click the Choose button. When the Xcode popup dialog appears point it to the location where you’d like to save your Ogre project and give it a name (e.g. OgreDemo).

You should now be looking at your Ogre Xcode Project. You may notice that there is some text in red (it indicates a problem). Basically, these files are broken, the paths don’t resolve. This is caused by a bug in the Ogre Xcode Templates. Step 6 below will resolve this issue. If you attempt to build the project, you’ll receive over 200 errors.

I recommend you familiarize with Xcode if you’ve never used it before. You can find documentation on the Apple Developer Website.  Follow this link for the User Guide – Xcode 4 User Guide: About Xcode 4.

Step 6 – Resolving the Ogre Xcode Template Bugs

This next phase deals with fixing some bugs that exist within the Ogre Xcode Templates. What we need to do is correct some Framework and .dylib paths, change the Mac Base SDK, Xcode project format, GCC compiler version, alter the header and library search paths, and make these changes permanent for future projects. Let’s get started.

1) Correct the Framework and .dylib paths – We’ll start with Cg.framework. Ctrl-click it and select Get Info. When the info box displays you’ll see the path is red. There is a Choose button to the far right of the window, click that and navigate to this file system path /Library/Frameworks and select Cg.framework then click the Choose button. On the info screen the path is now black. Hit the close button in the upper left of the window.

Follow this same procedure for the following files:

• Ogre.framework – /OgreSDK/lib/release/Ogre.framework
• libOIS.a –  /OgreSDK/lib/release/libOIS.a
• Plugin_CgProgramManager.dylib – /OgreSDK/lib/Plugin_CgProgramManager.dylib
• Plugin_OctreeSceneManager.dylib – /OgreSDK/lib/Plugin_OctreeSceneManager.dylib
• RenderSystem_GL.dylib – /OgreSDK/lib/RenderSystem_GL.dylib

2) Change the Mac Base SDK, Xcode project format, and GCC compiler version – Go to the Project menu and select Edit Project Settings option. On the info screen’s General tab, change the Xcode Project Format to Xcode 3.1-compatible and Base SDK for All Configurations to Mac OS X 10.6. Click on the Build tab, All Configurations, scroll down to the Compiler Version section, and for C/C++ Compiler Version change the value to System default (GCC 4.2). Close the info window.

3) Alter the Header and Library Search Paths – Go back to the Project menu and select the Edit Active Target “Project Name” option (Project Name will be what you chose to name your project when you created it). Click on the Build tab, All Configurations, and scroll down to the Search Paths section. There are three lines we’re interested in: Framework Search Paths, Header Search Paths, and Library Search Paths. You’ll see that the paths prefix with _OGRESDK_ROOT_. This was supposed to be replaced with the Ogre SDK install location (aka /OgreSDK) you selected during the Xcode Template installation. To correct this we’ll edit each entry and replace _OGRESDK_ROOT_ with /OgreSDK. Close the window when you’re done.

Amendment – July 4, 2011

Change the boost headers directory from boost_1_42 to boost_1_46_1 in the header Search Paths. Thanks to Guido for pointing this out.

That’s it for the changes. Build your project (Build menu -> Build and Run option). You shouldn’t receive any build errors (if you did, check all the setting changes from above and make sure you didn’t miss something). When the demo launches there will be a settings window, accept the defaults and click the OK button. Tada! It’s an Ogre!

Press the Escape key to exit the Ogre3D program. There is still one last thing to do.

4) Make the Changes Permanent for Future Projects – The changes we’ve made are for this project only, so how do we apply them to any future projects created from the Ogre Xcode template? Luckily the solution is rather simple. Our modified project contains a settings file called project.pbxproj that holds the paths of all the frameworks, headers, libraries, and etc we applied as well as more information that isn’t relevant to our topic. All we have to do is copy the project.pbxproj file and overwrite the version that came with the Ogre Xcode Templates.

Open your Ogre project folder. Inside there is an item called PROJECT.xcodeproj (where PROJECT is the name of the project you created). Ctrl-click the xcodeproj and select Show Package Contents. Next copy the project.pbxproj file (ctrl-click, copy) and open a new Finder window. Navigate to the Ogre Xcode Templates file system path shown below.

/Library/Application Support/Developer/Shared/Xcode/Project Templates/Ogre/Mac OS X

Here you’ll find the project template files that Xcode uses to create your Ogre3D projects. Move into the xcodeproj folder (ctrl-click, Show Package Contents) and paste the project.pbxproj you copied earlier. Replace the existing version. Technically we are done but we should change the file’s permissions to match.

Open a Terminal window (Applications -> Utilities -> Terminal). Navigate to the same Ogre Xcode Templates path from above. Change ownership of the project.pbxproj using the chown command. The full list of commands are show in the image.

computer:~ tony$ cd /Library/Application\ Support/Developer/Shared/Xcode/Project\ Templates/Ogre/Mac\ OS\ X/
computer:~ tony$ cd ___PROJECTNAME___.xcodeproj/
computer:~ tony$ sudo chown root:admin project.pbxproj

Amendment – July 4, 2011

In my haste of making this tutorial I didn’t completely test every aspect. The stricken out text above was for copying the OgreDemo project’s project.pbxproj settings file on top of the Ogre Xcode Project template’s version. The problem is that some settings then become hard-coded to use a file name of OgreDemo and the project won’t build unless it has the same exact name. Obviously that won’t work. You could rename but that defeats the purpose of a template. So we’ll be making modifications to the Ogre Xcode project template project.pbxproj directly this time around. We’re also going to bypass the copy, paste, ownership stuff, and use nano for editing to make the changes. Open a Terminal and issue the commands below.

computer:~ tony$ cd /Library/Application\ Support/Developer/Shared/Xcode/Project\ Templates/Ogre/Mac\ OS\ X/
computer:~ tony$ cd ___PROJECTNAME___.xcodeproj/
computer:~ tony$ sudo nano project.pbxproj

Make the following changes to the Ogre Xcode Template project.pbxproj settings file. I’ve included the line numbers for your information. To see what line number you’re on in nano, press ctrl-c. [ Control-C ]

Replace libois.a with libOIS.a
[ Lines 16, 73, 98, 126 ]

Replace boost_1_42 with boost_1_46_1
[ Lines 311, 342 ]

Replace the path to Cg.framework _OGRESDK_ROOT_/Dependencies with /Library/Frameworks
[ Line 71 ]

Replace all _OGRESDK_ROOT_ with your Ogre SDK path /OgreSDK
[ Lines 72-73, 76-78, 299-300, 309-312, 318-320, 333-334, 340-343, 349-351 ]

Fix the Build Configurations (Debug & Release)
Change ARCHS = “$(ONLY_ACTIVE_ARCH_PRE_XCODE_3_1)”; to ARCHS = “$(ARCHS_STANDARD_32_BIT)”;
Change GCC_VERSION = 4.0; to GCC_VERSION = “”;
Change ONLY_ACTIVE_ARCH_PRE_XCODE_3_1 = “$(NATIVE_ARCH)”; to ONLY_ACTIVE_ARCH = YES;
Change SDKROOT = /Developer/SDKs/MacOSX10.4u.sdk; to SDKROOT = /Developer/SDKs/MacOSX10.6.sdk;
[ Lines 360, 363, 366, 368 ] and [ Lines 375, 377, 380, 382 ]

Once you’ve made all the changes to the Ogre Xcode Template project.pbxproj, save the file by pressing ctrl-o. [ Control-O ] and ctrl-x [ Control-X ] to exit nano. Now any project created from the Ogre Xcode Templates will compile and from any name you save your project as.

That concludes this tutorial on installing the Ogre SDK 1.7.3 on a Mac OS X system. Any future Xcode projects you create using the Ogre Xcode Template won’t need changes to compile out the door. Stay tuned for more Ogre3D Mac articles from me.