Xcode and Libraries

Since the dawn of the human species around 200.000 B.C. (Before Computers), countless hours have been wasted by software developers trying to include a library in their project. In most cases, what's missing is definite clarity about the process. Even though you might find some hacky way of building your library from source and somehow getting it to work in your project after furiously interrogating Google, the results are often neither optimal, nor sustainable.

In this post I will describe the three simple and quick steps that will take you from wanting a library, to including and using it in your Xcode project on Mac OS X.

If you've stumbled upon this post in your hunt for quick solutions, do this to make everything work:

1. Download Brew. From a command line, do brew search <library>, if your library's available, do brew install <library>.

2. In Xcode, click on your project name next to the blue icon, at the very top of your files/directories, which will open your project's configuration settings. Go to the Search paths menu. For the Header Search Paths, insert /usr/local/include.

3.  At the top of this configuration settings page, you'll see three tabs: Build Settings, Build Phases and Build Rules. Click on Build Phases. Click on the Link Binary with Libraries menu. Click the little plus sign in the bottom left corner. Click on Add Other. Do ⌘ + Shift + G and type /usr/local/lib. Click on the .dylib you want to include and add it.

4. Profit

Now, if you want to know why you did these things and what you're actually doing, or need some pictures and explanations for these steps, read on. 

1. Getting the library

Most struggles people have with libraries stem from the initial process of getting the library you want onto your computer. What do I mean? Don't you just extrude the files from the glorious womb of the interwebs and plant them somewhere on my system? No, no you don't. What you need is a package-manager, namely Homebrew. If you've ever used Linux and installed applications on it, you most likely will have come across something like apt-get, so you should be familiar with what a package manager is. For everyone else, a package manager is a handy command-line utility that takes care of downloading and installing (in the right places) a certain library/application as well as all of its dependencies. I strongly recommend you download Homebrew.

Now, since package-managers are maintained by humans, who cannot know of every library in the world, some libraries might not be available via Brew. However, more often than not you will find what you're looking for and in any case, it should be your first resort.

Example

For the purpose of showing you how easy it is to use brew, I will download the Boost C++ library. Do the same things for your library, but change the name of course.

Open up a command line, go to your kitchen and make a sandwich. Ok maybe do the last part later on. From the command line, let's first see whether you have brew installed. To do that, simply type brew into your terminal. This should come up:

If bash couldn't find the brew command, you probably didn't install Homebrew correctly. To the Google! Installing Homebrew.

If the above command works, we can look to see whether Brew has the library we want, by issuing the brew search <library> command, so, in my case:

As you can see, brew found three libraries that include the name "boost". If brew also found your library, it is now time to install the library. Do brew install <library>, so for me:

If the above command worked, you should now be the proud owner of a library. Congratulations. What brew did for you, here, is install all the right files in all the right places, meaning the necessary header files went into /usr/local/include and the library against which you'll have to link your project later on went into /usr/local/lib. Also, if your library depended on any vital other libraries, brew took care of installing those for you too.

Help! It didn't work! What now?

If the installation of your library failed for some reason, consult Homebrew's built-in debug utility, the brew doctor. Brew's doctor examines your system for some basic errors and warns you about a bunch of things that could get in the way of installing a package. For example, this comes up when running brew doctor for me:

As you can see, brew is warning me about a few issues that could come up at one time or another. If the doctor doesn't help, consult your search engine of choice.

2. Including the Header files

Now that we have the library installed, we can move on to making the library work in our Xcode project. For example purposes, I have created an Xcode project called Potato. Your workspace will most likely look something like this:

At the top of your file/directory listing on the left of your screen, you can see the name of your project, in my case Potato, next to the blue icon with the 'A' on it. Click on it, this will open your project's configuration settings:

Now, find the Search Paths menu by either scrolling down or by typing in 'Search Paths' in the search bar you can see in the top right corner there.

The Search Paths menu should look like this:

What we're looking for here is the Header Search Paths tab, in the middle of the menu. Click on it and hit enter, which lets you type in a path. Enter the path /usr/local/include, the path where brew installed our header files. Now you have access to all the header files of the library. You can include them in your project now! However, there is a final step left:

3. Including the library

The last thing we have to do is include the library, which is stored in a .dynlib file in the /usr/local/lib directory. The dynlib, or dynamic library, is a collection of implementation files for our library. We need to link it to our project.

At the very top of this configuration page, you can see three tabs, Build Settings, Build Phases and Build Rules:

Click on the Build Phases tab, which will open a new configuration page. On it, you will see a menu Link binary with libraries. Click on it. In the bottom left corner, you can see a little plus sign, which you need to click again. This will open a new window:

Here you can find OS X's built-in frameworks. Should you need to include any of those libraries or frameworks, you can add them here. If you're looking for an external library, like I'm looking for boost, you need to click on the Add Other button. This will enable you to search for a framework or library anywhere you want to. Hit ⌘ + Shift + G and type /usr/local/lib into the little window that pops up. This will take you to the folder where Brew installed our dynlib file. Look for it and add it by clicking on it and pressing the Add button in the bottom right corner. 

That's it, build your project, you're set to go.

Cheers.