I’m (re)learning Cocoa at the moment. I’m working my way through the wonderful Cocoa Programming for Mac OS X. But for my first solo project, I found myself needing to XML-RPC. I took one look at Web Services Core Programming Guide and barfed. After a quick hunt, I found Eric Czarny’s lovely XMLRPC project for cocoa. This looked exactly like what I needed.
I had one small problem though — it’s a framework. I’ve not used one before. How do I actually get this code included in my project?
After looking at the Framework Programming Guide, there are a few options for embedding the framework into my project (embedding is the only sensible choice — I don’t want the user to have to install this on their system).
- Build and install the framework locally, then just drag it into my project.
- Build the framework, and check the results into my source control system.
- Embed the framework into my own project, so it gets built on its own each time.
The first option means that the build is no dependent on my workstation. The second option works, but I dislike binaries in version control (and how non-reproduceable these can be). The third option is ideal as it means the build is self contained. However, it’s also the most non-obvious to implement.
After quite a few misdirected searches, I eventually found Jonathan “wolf” Rentzsch’s marvellous tutorial Embedded Cocoa Frameworks. Unfortunately, it’s gone 404. Archive.org has a copy, including the 8 minute screencast.
In case it goes away again, here’s what I did to integrate the XMLRPC framework. I’ll start with a brand-new Cocoa project, MyApp.
Next you need to git clone git://github.com/eczarny/xmlrpc.git in a nearby place (a sibling directory is ideal, though you could set up inside MyApp using git submodules).
Before we can get started, we need to open up the XMLRPC project and make a couple of changes. First, we need to ensure that the Configurations match the ones in my project. Otherwise, Xcode will use the default configuration, which may produce unexpected results. I did this by duplicating Development into Debug.
Now, build the XMLRPC project (⌘-B). You should end up with …/xmlrpc/build/Debug/XMLRPC.framework. Right-click on MyApp → Frameworks → Linked Frameworks and choose Add… → Existing Frameworks….
Navigate to the previously built framework and select it. In the sheet that pops up, ensure that you choose “Reference Type: Relative to Project,” as well as ensuring that MyApp is selected in “Add To Targets.”
If you’ve been fastidiously keeping an eye on things in git (as I like to do), you can see the changes in your xcode project file. As well as introducing a reference to the framework directory, you will also see that the FRAMEWORK_SEARCH_PATHS build setting has been set up for you:
FRAMEWORK_SEARCH_PATHS = ( "$(inherited)", ""$(SRCROOT)/../xmlrpc/build/Debug"", );
Unfortunately, this the point at which I realised that what I was doing wouldn’t work. We’re linking against the Debug configuration of the framework. I need to embed a reference in my project that’s independent of which configuration the XMLRPC project was built with. In order to do that, we have to modify the XMLRPC project a bit more.
Go back to the XMLRPC project and right click on the XMLRPC target. Choose Add… → New Build Phase… → New Run Script Build Phase. Type in the code:
set -x
rm -rf "${BUILD_DIR}/${FULL_PRODUCT_NAME}"
cp -r "${BUILT_PRODUCTS_DIR}/${FULL_PRODUCT_NAME}" "${BUILD_DIR}/${FULL_PRODUCT_NAME}"
The net effect is to copy the framework from …/xmlrpc/build/Debug to …/xmlrpc/build. This means that there’s a single location to pull in. You may wish to rename the Run Script phase to something like “Run Script: Copy to well-known location.”
In case you’re wondering, I figured out which environment variables to use by looking at the build output, as it has another Run Script phase which shows you what they all are.
Now, go back into MyApp, remove the reference to XMLRPC.framwork. Add back the version in the new location, which should be directly under build. You also need to clean up the FRAMEWORK_SEARCH_PATHS setting on the MyApp target for both Release and Debug configurations. Ooops. I wish I’d spotted my mistake earlier!
So now we’ve linked against the framework, and set up the header search path. To check the latter, add a new Objective-C class and add in:
#import <XMLRPC/XMLRPC.h>
A build of MyApp should succeed without error.
But there’s one more trick. We want to build the XMLRPC project as part of our own build. In order to do this, you need to drag XMLRPC.xcodeproj into MyApp.
This should pop up the same sheet where you need to choose “Reference Type: Relative to Project.”
With that done, right-click on the MyApp target and choose Get Info. On the general tab, add XMLRPC as a direct dependency.
Now, when you build MyApp, you should see the XMLRPC project being built too. Even better, if you switch configurations, you should see the framework being built in the same configuration.
In summary, the steps were:
- Modify the framework to support the same configurations as your project.
- Modify the framework to put the built artifact in a consistent location.
- Add the framework to your project (making sure to select “relative to project” and “add to target”).
- Add a reference to the framework’s project to your project.
- Add the target for the framework as a direct dependency of your target that needs it.
It may seem like a lot of effort, but it really only takes a few seconds. And now you’ve got the ability to pull in hundreds of wonderful open-source projects to make your app better!
Jabbering Giraffe 