How to create a custom cocoa framework

I was recently trying to rip out some code from the Thoughtback app into it’s own framework so that I could eventually open source when we decide to make our API public. I’ve used frameworks plenty of times, but I’ve never actually made my own.

I started off by just using the default Cocoa Framework project that XCode makes for you. It all seemed to work just fine, but when I tried actually using the framework in a different project, it wouldn’t load. I kept getting this error

Library not loaded: path/to/framework
 Referenced from: path/to/app/
 Reason: image not found

After lots of looking around I finally figured out the problem. Frameworks can be referenced at the System level (requires admin rights to install), the User level (could be useful to share a framework between apps), and at the application level. Bundling your framework inside the application is the most common way to do that. The “image not found” error has to do with some pathing in the framework. To fix it, you’ll need to change the “Installation Directory” in the build settings of your framework. Right click on your framework’s target to bring up the info panel. Search for “Installation Directory” and set it to be @executable_path/../Frameworks.

Now the framework should load just fine in any project you want to use it in. I still had a problem though. If you’re familiar with cocoa frameworks, you’ll know its just a bundle with a library and some header files in a certain directory structure. I looked at my framework and couldn’t find the “Headers” folder with my header files so I couldn’t use anything that was in my framework. I googled around for a little while and found nothing. Thats when I noticed the “Role” column when I clicked on my framework target. That let me set the header files to public, private, or project, depending on how I wanted them to show up in my framework.

So now that I have the library path right and the header files right, there is just one thing I needed to do to get it working in my test app. You’ll need to add another build step to your application target that copies the framework to your application bundle.

1. Right click on your application target.
2. Click “New Build Phase”
3. Click “New Copy Files Build Phase”
4. Change the destination to “Frameworks”
5. Close the window.
6. Drag and drop your framework into the build phase.

Hopefully you found this useful. I couldn’t find all of the resources I needed in one place and what I did find wasn’t detailed enough to solve my problem immediately. This post from Cocoa Is My Girlfriend got me most of the way there and has some more good information on the subject.