The TinderBox tool which comes with Cinder is the easiest way to create new projects, and in general we recommend you use that. However it can be instructive to know how to create a Cinder project from scratch, which is discussed in the section below.
TinderBox is our GUI tool for creating Cinder projects quickly and easily. It can generate Xcode as well as Visual C++ 2008 and 2010 projects. It is located at cinder/tools/TinderBox in our packaged releases. The first time you launch it, TinderBox will ask you to point it at the location of Cinder on your hard drive.
Navigate to the top level Cinder directory and hit Open. If you ever need to change this later, you can do so from the preferences menu.
Whenever you launch TinderBox, it will start by asking you where you would like to save your new project, and what you would like to call it.
There are a number of settings in TinderBox, but the defaults will suffice for most users. Simply hit the Create button, and you'll have a complete Cinder project ready for you to start coding in.
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.
Tell XCode where to save the project via the Save dialog that follows, and put it in the project folder we created earlier.
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.
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.
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.
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.
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.
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.
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".
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. 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". Now do the same for the Release configuration but set it to "$(CINDER_PATH)/lib/libcinder.a".
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...
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.
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 |
Target: Release | Other Linker Flags | $(CINDER_PATH)/lib/libcinder.a |
Frameworks | Accelerate.framework, AudioToolbox.framework, AudioUnit.framework, CoreAudio.framework, CoreVideo.framework, OpenGL.framework, QTKit.framework, and QuickTime.framework |
---|