Short Note: Embedding a private framework within your OS X app bundle

Sometimes solutions are so simple and yet it is so hard to find the right information that points towards them. So in the „Short Note“ posts I will share information about different topics that will hopefully make your search less time consuming.

Today: How to embed a private framework into your OS X App bundle, so that you can distribute your App as one single package.

[spoiler title=“Background“]Often you want to build an application around already developed functionalities, like for example in my case a serial data communication system. The way to include these functionalities are frameworks aka. dynamic libraries. OS X stores and shares system wide available frameworks inside the /Library/Framework folder. All libraries available there can be used by any application relying on them. In my article about how to implement a 3Dconnexion 3D mouse into your project using Swift I used the 3dconnexion framework. If you don’t have it installed before launching my app, you’ll get a warning that tells you to install the proper driver that provides the framework installation as well. But this kind of framework linkage requires to have always at least to files to handle if you want to share an application: the application itself and the framework(s). This problem gets frustrating at the latest when you want to start applications outside of Xcode. Whenever you run your application from within the IDE it will work, but after exporting the app it crashes – or displays a helpful hint link mine. 😀

So if your application relies on a framework but you want to keep distribution as simple as possible and don’t want to clutter any OS X system with tons of frameworks that are not used by several applications, simply include them into your app bundle. Back in the day it was cumbersome to perform the setup in Xcode for this. So a lot of information on the internet refer to the involved procedure. Even Apple’s documentation is no exception (Installing Your Framework). But fortunately at least with Xcode 7 (I am currently using 7.3 Beta 2) it is much easier.[/spoiler]

All you have to do is to head over to your project settings‘ General tab and find the Embedded Binaries section. It should be right above the Linked Frameworks and Libraries section where you usually make frameworks available for your project. Click the plus sign and add the framework to the list. You“ll notice that the framework also appeared inside the Linked Frameworks and Libraries section. So if you have the framework listed twice there, simple remove the upper of the two entries. Now you are good to go.

XCode will automatically set the installation path of the framework to @executable_path/../Frameworks This tells the app where to look for the framework at runtime. You can check this at the Build Settings tab at the Linking section.

Now you can archive and export your app and it should run without any problems outside of Xcode.