Xcode Static Library Subprojects and Submodules[1]

In which a method is presented for reliably building static libraries with subprojects in Xcode, and it is suggested that this method, combined with Git submodules or other similar mechanisms, provides the best way to share libraries, frameworks, or other code between projects.

I’m sure I don’t need to tell you that it’s a useful thing to be able to share code between projects. On the small end of the scale, you might have created some nice views, or text processing classes, and want to be able to include them in multiple apps. On the larger end, perhaps you produce games written with a shared framework, or you’re maintaining an open source library.

One way to do this is to copy files - or even just snippets of code - between your projects. At a very small scale this works, but as things get larger, inevitably, over time, it leads to a codebase that’s hard to maintain, and probably buggy, because it’s nigh on impossible to keep all the copypasta in sync.

It would be better to keep the shared source together in one place. Doing this, you ensure that bug fixes easily propagate to all the apps using the code, and you can keep tests etc. in a central location.

For iOS (and I would argue, Mac, although I’m focusing on iOS in this post) the ideal way to do this is to create an Xcode project that builds a static library, then include that as a subproject in your app projects. Using features like Git’s submodules, or Subversion’s externals, you can ensure that the files for the same subproject in every app that uses it are kept in sync, with one master copy of the subproject kept centrally. This also enables easier collaboration - whether it’s with colleagues in your company, or the app-developing-public at large via GitHub.

I use this method with libEucalyptus to allow it to be included in multiple apps, some of which I don’t control, but keep it in a central location, and it works well.

“Someone on StackOverflow told me this could never work work.
Or, wait…, maybe they said it always worked automatically?…”

There’s a lot of confusion - and misinformation - out there on the web about how to do this. Most people seem to think that creating a static library project in Xcode, and using this as a subproject in other projects, is fraught with peril - a path filled with custom project configurations, header path manipulation, and strange project-editor voodoo to get things to work. Xcode 4 actually provides fairly good support for doing this though. Set things up correctly once, and you’ll be good to go.

By the end of this blog post, you’ll know how to create an Xcode project that compiles a static library, exposing public headers to other projects in a way that makes them easy to #import, and how to use that project as a subproject in other projects.

You’ll also be able to include this project in superprojects as a submodule using Git, or, if you’re not a Git user, it’ll hopefully be fairly obvious how you could use your favourite version control system to accomplish something similar (for example, using SVN externals).

Create an Xcode project for the static library

Let’s get started making our static library. First, we’ll fire up Xcode and create a new project:

We’ll use the Cocoa Touch Static Library template:

Next, we get to choose a name for our library. Let’s go with the imaginative name of SampleSubproject:

After this, you’ll get a file dialog allowing you to choose where to put the project. I also let Xcode create a Git repository for me - there’s a checkbox in the dialog for that - we’ll use that later.

Hurray, a static library project!

Configure the static library target’s header location

Now, there’s basically only one thing to do to get this ready for other projects to use. By default, Xcode will place your public library headers in place where superprojects can include them like this: #import <HeaderFromTheSubproject.h>. This strikes me as a little messy. I like to change things so that I can include the headers like this: #import <SampleSubproject/HeaderFromTheSubproject.h> - just as you would when using a header from a framework (or, indeed, from many system-provided dynamic libraries). Xcode’s default configuration will also treat the library headers as ‘part of’ your finished product, and when you do an Archive build they’ll be included in the Archive. This is obviously wrong for an iOS app, and besides being messy will also cause your app to fail verification - not desirable.

To fix these problems, we’ll need to change one setting in the project editor. Select the project in the Navigator sidebar, then select theSampleSubproject library target, and make sure that All, not Basic, is selected at the top of the list of settings. Then, in the Packaging section, find the setting entitled Public Header Folders Path. Change it, in the target’s column, to read include/$(TARGET_NAME). This will make Xcode place the headers in a subfolder named after the target, and the lack of a ‘/’ at the start of the path means they’ll be placed next to the library, rather than in what Xcode sees as being a location on the target system, so they won’t be included in the products of Archive builds.

That’s it. Before we go on to setting up an app project to use this subproject though, let’s make the library do something so we can see it working later.

Write the static library code

First, let’s make a simple class to use - we’ll call it “SSHelloer”. It will, in fine sample code tradition, return strings with a “hello” message. I won’t walk you through adding a class to an Xcode project, since I’m sure you know how to do it already, but here’s the code:

#import <Foundation/Foundation.h>@interface SSHelloer : NSObject- (NSString *)hello;@end

#import <SSHelloer.h>@implementation SSHelloer- (NSString *)hello{
    return @"Hello from SSHelloer in SampleSubproject!";}@end

Create a global header for the static library

Next, it’s a bit odd, really, that the template sets us up a class called SampleSubproject. Usually we’d expect a statement like#import <SampleSubproject/SampleSubproject.h> to import all the headers from the SampleSubproject library, not a SampleSubproject class. Let’s rectify this. Delete the SampleSubproject.m file entirely, and change the interface in SampleSubproject.h file to just #import <SampleSubproject/SSHelloer.h>. It’s not very helpful in our simple single-class library, but in a big project with lots of headers you could list all the headers in a list here, and then clients could just #import <SampleSubproject/SampleSubproject.h> to get everything from the library.

Set the visibility for the library headers

The last thing to do is to set the visibility of the headers in the project. For each header, there are three options. Public means that clients of the library will be able to see the header. This is what we want for headers that we’re intending to be visible to the apps including our project as a subproject. Project means that only files in this project will be able to see the headers. It’s useful for classes that are intended to be available to the library you’re creating, but not exposed to clients of the library. Private is a little misleading. Intuitively, you might think its a synonym for Project, but it’s not. It’s intended for headers that are intended for some clients of the library, but are not public. It’s useful, for example, for Apple, which can have headers for private APIs that are available at build-time for ‘internal’ clients to use, but will not be shipped out to us in Mac OS X SDKs. It doesn’t really make any sense in our situation, so it’s best to just ignore that it’s there, and choose from Public or Package.

From that explanation, you can hopefully see that both our headers, SampleSubproject.h and SSHelloer.h need to be Public. You can set this in the “Target Membership” section of the right-hand “Utilities” panel:

Library subproject ready!

Lastly, just as a sanity check, build the library, and all should be well.

That’s it, our subproject is ready to go. At this point, I committed everything to Git, and pushed it to GitHub at http://github.com/th-in-gs/SampleSubproject. I’ll use the repo from GitHub later to clone it into the app that’s using it. If you want to do something similar, even if you’re using Git, it’s not necessary to use GitHub. You can use submodules from any Git host - or even the local filesystem. You could also use another version control system that supports submodules or externals, or even just filesystem symlinks if you like to live dangerously.