Cinder

Creating a new Cinder project on Mac OS X

For Mac users, our GUI tool TinderBox is the easiest way to create new Cinder projects, and in general we recommend you use that. However it can be instructive and occasionally even necessary to know how to create a Cinder project from scratch. It's not too hard, really. Xcode offers tremendous flexibility in how users can structure their projects. This guide will show you how to setup a project similarly to the samples, but Cinder is designed to be flexible too, and you should feel free to adapt things to your preferences.


Let's start in the Finder. We'll create a folder for our project, and inside that a folder for source code called src.

Now open up Xcode, and from the File menu select New Project. In the dialog box, select Cocoa Application from the Application category.

New Project in XCode

Tell XCode where to save the project via the Save dialog that follows, and put it in the project folder we created earlier.

Save new project

At this point we would recommend closing your project in Xcode, and then locating your project in the Finder. Rename the folder named after your project (and housing your .xcodeproj) to xcode. This is certainly optional, but can simplify the eventual possibility of your project accommodating other compilers or operating systems.

New Project in Finder

Now open your project back up in Xcode. It has automatically created some files we don't need, so let's go ahead and delete those. Select main.m, InfoPlist.strings, and MainMenu.xib and use the context menu to delete them. When prompted, go ahead and click Also Move to Trash.

Delete from XCode

Now we'll create our first source file. Context-click (right-click) the Classes folder and select Add | New File... and choose C++ File from the C and C++ category.

New CPP File

Assign the new file a name, and save it to the src folder we created earlier. In general you will want to uncheck the Also create "<name>.h" option.

New CPP file name

For the purposes of this guide, we'll just copy and paste the code from cinder/samples/QuickTime/src/quickTimeSample.cpp as a starting point for this project.


At this point if you were to try to build your project, you'll get a number of compile errors due to Xcode not being able to find Cinder, so let's point Xcode at the right places for finding its headers. Under the Project menu, select Edit Project Settings. Go to the Build tab and in the Configuration popup in the window's upper left corner, select All Configurations.


Now we are going to add a user-defined build setting, which will make our lives easier shortly. We will be creating a build setting which defines where Cinder's directory is relative to our project. Click the popup-menu in the window's lower-left corner and choose the Add User-Defined Setting.

user Defined

Name your new setting CINDER_PATH and set the value to be the location of Cinder. Depending on personal preference, you should set its value to be either the absolute path where Cinder lives on your disk (for example, "/Users/mary/Code/cinder") or the path relative to your Xcode project. In general we recommend the latter, since it makes it possible for other users to build your project more easily. In this example the path is "../../../../cinder" but yours will depend on where you're creating your project.

CINDER_PATH

Now we'll make use of this new variable. Scroll up to the settings section entitled Search Paths, and modify the User Header Search Paths setting to be the value "$(CINDER_PATH)/include". Next, modify the Header Search Paths setting to be "$(CINDER_PATH)/boost".

header search paths

And finally, we'll need to tell Xcode where to find the Cinder libraries for linking. In general we use the project settings for defining header search paths, and the target settings for linker settings. So close the Project Settings window and under the Project menu select Edit Active Target <your project name>.


We only need to modify one setting here, which is to set the string which tells the linker to add libcinder and libcurl. Go to the Build tab and under the Configuration popup select Debug. Now find the Other Linker Flags setting under the Linking settings and set it to "$(CINDER_PATH)/lib/libcinder_d.a -lcurl". Now do the same for the Release configuration but set it to "$(CINDER_PATH)/lib/libcinder.a -lcurl".

Linker settings

Now the final step, which is to point Xcode at the Mac OS X frameworks Cinder applications need. Right-click the Frameworks folder in the project window and select Add | Existing Frameworks...

Add Existing Frameworks

In the Open dialog that follows, navigate to /System/Library/Frameworks and select the following frameworks (you can cmd-click to select several at once). Accelerate.framework, AudioToolbox.framework, AudioUnit.framework, CoreAudio.framework, CoreVideo.framework, OpenGL.framework, QTKit.framework, and QuickTime.framework.

Added Frameworks

That should be all there is to it. A summary of the relevant settings follows.

Category Setting Value
Project: All Configurations CINDER_PATH custom definition project-relative path to Cinder (or absolute path to cinder)
Project: All Configurations Header Search Paths
$(CINDER_PATH)/boost
Project: All Configurations User Header Search Paths $(CINDER_PATH)/include
Target: Debug Other Linker Flags $(CINDER_PATH)/lib/libcinder_d.a -lcurl
Target: Release Other Linker Flags $(CINDER_PATH)/lib/libcinder.a -lcurl

Frameworks Accelerate.framework, AudioToolbox.framework, AudioUnit.framework, CoreAudio.framework, CoreVideo.framework, OpenGL.framework, QTKit.framework, and QuickTime.framework