How to link Custom Frameworks from your Xcode Projects

In order to use the functionality of Remoting SDK or Data Abstract (or any other framework, whether third party or created by yourself), you will need to link your application against the framework in question, and deploy the framework along with your application. There are two common ways to do this, either by referencing the pre-compiled framework directly or, if available, by referencing the project that represents the framework.

Linking Frameworks

Unless you are working on and making frequent changes to the frameworks themselves, the easiest way to link frameworks into your application is to just link against a recompiled version of them. For Remoting SDK and Data Abstract, the frameworks ships in pre-compiled form and ready to use, so unless you are applying custom changes to the code (which we recommend against), this is the best option for using RO and DA.

Adding Framework References

The first step for linking against a framework is to add a reference to the framework to your project. This can be done either my locating a framework folder (for example RemObjectsSDK.framework) in the Finder and dragging it into your project tree in Xcode, or by right-clicking the tree and choosing Add -> Existing Frameworks... In theory, the framework references can be placed anywhere in your project hierarchy, but most projects have a Frameworks folder that provides a good default location.

Linking Frameworks into your Targets

Once you have a reference to the framework(s) in your project, you can configure your targets to link to them. Usually, Xcode will perform this step automatically when you add references, but if you have multiple targets, or change framework references frequently, you will need or want to manually control this.

Linking a target to an already references framework is easy: simply drag the framework from your project hierarchy to the Link Binary with Libraries build phase for the target in question:

Once these two steps are set up, you can start to code against your framework, for example by including header files provided by the frameworks, using

#import <FrameworkName/HeaderFileName.h>

Most frameworks, including Remoting SDK and Data Abstract, provide a compiled header file, named after the framework, that pulls in all the individual headers. So all you need to gain access to the entirety of the framework is to import, say, <RemObjectsSDK/RemObjectsSDK.h>. Since third party framework headers seldomly change during your normal develop/build/text routine, it is a good idea to add this #import to the Pre-Compiled Header (.pch) file of your project, rather than to individual source modules. This way, framework headers will not need to be reparsed for each and every build, drastically increasing your build turnaround time.

We're almost done but there's one last step:

Deploying Linked Frameworks

When you link your project against a framework, your application binary will contain calls to classes and functions provided by the framework, but it will not automatically include a copy of the framework. As a result, when you run your application, it would fail because it cannot locate a copy of the framework(s) it needs to function.

For your application to run properly and independently, you will need to set your project up to deploy the framework you are using as part of the application bundle that is being generated when you build.

Luckily, setting a framework up for deployment inside the .app bundle is easy.

The first step is to right-click your target, and add a new Copy Files build specifically for frameworks.

Once the build phase has been added, right-click it and choose Get Info (or press Cmd-I) and set the Destination to Frameworks. This will tell Xcode to copy any files added to this build phase to the /Contents/Frameworks folder of the .app bundle, where frameworks will be expected to reside*.

As the final step option-drag the frameworks form the Link Binary with Libraries build phase down to your new Copy Files phase (holding the option key will make sure the info is copied to the new location; accidentally dragging without the option key you move the framework, essentially removing it from the Link Binary with Libraries phase – and we do not want that.

And that is it - your application is good to go.

Linking Projects

Sometimes you are in a situation where a framework you are using is changing frequently. Maybe you are debugging (or even writing) the framework as part of the application project you are compiling, so you want to be able to seamlessly switch between making changes to framework and application, and have both automatically rebuilt when you run your app.

This can be achieved by referencing the project for your framework, rather than the pre-compiled binary version, in your application project, as the following steps outline.

Adding Project References

Just like direct framework references, references to secondary projects can be added to your Xcode project either by dragging the .xcodeproj file into your project tree or by right-clicking your project and choosing Add -> Existing Files... and browsing for your project (make sure that when the conformation dialog for adding the project pops up, the Copy items into destination option is unchecked. After all, you want to reference the framework project from its existing location).

As you see, rather than having the yellow tool-chest framework icon, the referenced projects are using the regular blue Xcode icon, with the actual framework they represent being shown nested underneath. (If a referenced project has not been built yet, the framework will show it as missing, using red text, until you build.)

Configuring Dependencies

There's two more things that need to be set up, before our two (or more) projects work together perfectly. The first is to set up project dependencies, to let Xcode know that our main project depends on the referenced projects, and that those should be rebuilt if they changed. To do this, right-click your application's target and choose Get Info (or press Cmd-I)

On the general tab, click the + button for the top list and select the framework or frameworks that your project depends on. Click Add target to complete the action.

Finally, you will need to configure the build folders for all projects (your application and all framework projects you want to work with) to match. It's unclear whether this is by design or an Xcode bug, but unfortunately project dependencies will only work consistently if all projects are set to build into the same base folder (opposed to their unique /build/Debug sub-folders).

So as a final task, right-click the root project node (the one showing the name of your project, Bugs in the above screenshot) and choose Get Info (or, once again, press Cmd-I). In the resulting info pane, change the Place Build Products In option from the default to Custom Location and type in or select a folder of choice where you want all your products to build to:

As you can see, the location for intermediate files will adjust automatically, there is no need to manually fix that as well.

Linking and Deploying

With the above steps completed, you can now set up your target to link and deploy the frameworks, just as you have seen in the first part of this article. Once that is done, you are all set to develop and debug your main project and the framework(s) it depends on, together.