Today I set up openFrameworks (OF) on my new Mac, and added my first addon. I chose to add an addon which allows OF to talk to SuperCollider (SC), so that I can experiment with some of the synesthesic effects that I have described previously.

In this post I'll describe the OF setup experience with XCode 4, and instructions for adding, compiling and running a real-world addon (ofxSuperCollider by Daniel Jones).

XCode and openFrameworks
To give you some sense of how much easier it is to set up OF on a Mac than on a PC, assuming you have little-to-no previous experience OF / C++ like me, take a look at these screengrabs of the OF setup guides:

At first, those thumbnails on the left look bigger. And then you realise that the one on the right is just really, really long. It's not necessarily a problem with the platform, I don't know which platform is really 'better'. It's about the community support - the community mostly use XCode, and most of the online help is in the context of XCode.

It's the same sort of deal with SC. Therefore I'm glad I switched to Mac.

Anyway, you can go to the nice, long setup page here and easily follow the instructions. At the time of this writing the setup page was slightly out of date with respect to both XCode and OF, but there's nothing about it which is drastically different.

By the time you are finished with that you should be able to launch OF projects in XCode, and compile and run them as-is.

Adding addons
There is a really nice video by Theo Watson which guides you through adding addons, and makes everything look really easy. But before you watch it, it's worth having a quick refresher on how openFrameworks is structured:

The addons are usually just wrappers around some external library (or libraries). This is the whole point of OF: to package up disparate, useful libraries into an easily accessible format that is standard across everybodys machines.

Here's the video:

Makes it look easy, right? All you have to do is drag the addon folder into XCode, and choose the 'relative path' option. And with OpenCV, you just have to add an extra search path because of how the internal library is relatively addressed.

Well from my experience today, it's almost that easy. But not quite.

Adding the ofxSuperCollider addon
So as described in the video the first thing I did was copy the emptyExample project to a new directory, and rename the new directory to 'superColliderExample'.

As Elliot Woods helpfully notes in the comments below the vimeo, when it comes to renaming the actual project file in XCode 4, don't rename it in the Finder - XCode will get confused. Simply launch emptyExample.xcodeproj as-is, and rename it from within XCode. To do this, click on the emptyExample project in the XCode left nav, and then edit the Project Name field in the property sheet on the right. When you hit return, XCode will offer to rename your targets and compiled application names, this is a good idea.

The ofxSuperCollider addon page helpfully tells us that it uses the OF-bundled ofxOsc addon, which makes perfect sense. So I checked out ofxSuperCollider via SVN straight into the OF addons directory. I then selected both ofxOsc and ofxSuperCollider, and dragged them into the addons directory in the left-nav of the XCode project. In XCode 4 it doesn't bother you with questions about relative or absolute paths, so I can only hope it's defaulting to relative.

So then I compile, but there are errors:

What's happening here is that the ofxOsc openFrameworks addon is trying to include a header file from the oscpack base library (refer back to the OF structure image). The oscpack library doesn't happen to appear in the image, but you can see that it's the base library that ofxOsc uses by drilling down into the contents of the ofxOsc addon.

So it appears to be a Search Path issue - the compiler doesn't know where to find the specified files. This is actually a very similar issue to that described by Theo when talking about ofxOpenCv in the Vimeo. And it's fixed the same way... sort of.

Things have changed with OF search paths
In the latest release, if you follow Theo's steps and go to the .xcconfig file in the opencvExample, you'll notice the additional paths highlighted in the Vimeo aren't there:

Instead, they are in the project Build Settings: click on the project root node in the left nav, select PROJECT (not TARGETS) in the pane next to the nav, and click the Build Settings tab. Here, if you scroll down (or use the search/filter bar), you'll see Header Search Paths.

As you can see, it looks like a recursive listing of every directory path that exists within the folder 'libs', inside the ofxOpenCv addon folder. In fact, it's a series of strings, which together happen to make up a recursive directory listing. But you can double-click them and edit them individually (although that's not a great idea right now!)

If you then go and take a look at the oscSenderExample project, which demonstrates ofxOsc in use, you'll notice that the oscpack directory structure is similarly mirrored in Build Settings:

So ofcourse, I copied the strings one-by-one into superColliderExample's Build Settings, and recompiled.

Another compiler error
This time there is only one error, and the paths seem to have been found. At first the error seems cryptic, as it only specifies intermediary compile-time files, and doesn't point to a line of human-written code:

But the clue is in the error type: 'duplicate symbol'. Somewhere the compiler is trying to compile something it has already encountered before.

Looking into the ofxSuperCollider addon, the author has included some example code:

This example code is probably conflicting with the existing sample code in the root src folder above, because if you remove the examples folder, the project compiles OK.

Still an empty window
At this stage, if you launch the program, you still only get an empty window. Despite the additional libraries, the emptyExample 'src' folder and it's default empty contents are still running the show.

So from wihin XCode, you can delete the default emptyExample contents of the src folder, moving the three files to the trash.

You can then go out to the Finder to find the ofxSuperCollider addon. Locate it's internal example project (yes, the same project we just de-referenced from XCode a minute ago). Copy the three files from the src folder, and still in the Finder, paste them where the emptyExample src files used to be. Highlight the three newly-copied files, and drag them into the matching folder in XCode.

XCode's foibles
Deleting things and dragging them in again might seem a bit weird - it is. But it seems XCode is funny about letting you move files around inside a project. Sometimes you have to do it the long way round.

Whatever you do, don't drag the contents from the ofxSuperCollider addons example folder back in directly - we want to be able to edit these files so it's no good if the references point back to another location on the filesystem.

A quick aside
The convention in OF seems to be that your root-level src files should match the underlying filesystem and be editable. However, addons should simply reference relatively the contents of the addons folder.

I'm not sure how convinced I am by this - you will end up with lots of projects pointing to the same underlying addons. Your personal software releases will be tied to the addons bundled with specific OF releases. As we have seen in this post, things change from release to release, so if you don't specify which OF release your software is designed for, it may not work when you share it with others.

I think there may be something to be said for copying the addons you want to use with each project, and having XCode always match the filesystem. I don't have enough experience with OF / XCode yet though, so we'll see how I feel about it later.

Addon running successfully!
On the plus side though, the superColliderExample project I made at the beginning now compiles and runs OK!

Hearing it in SuperCollider
In order to hear the sound from the example project in SC and manipulate it from the OF window, you have to do a few more things (in order):

1. Launch SC (quit and start again if it's already running)
2. Boot the SC localhost server
3. Copy the three SynthDefs from the top of the testApp.h file in XCode
4. Paste them into SC, highlight them all and execute them to load the synths on the localhost server
5. Copy the data directory containing the bell.aif file from the example project (inside ofxSuperCollider) to the bin folder of the new XCode project
6. Finally, run the application from the new XCode project (if it's already running, stop it and start it again)

Drawing on the canvass will now cause the synths to play in SC. So the project not only compiles and runs, but we can also see it doing it's job.