Frameworks in Xcode 6


EDITED TO ADD 2014-11-10: The edit below was written while I was setting up Squarespace 6 and published to the Squarespace 5 version. I noticed that over the weekend so I went back and copied the change here.

EDITED TO ADD 2014-10-17: I found a pair of interrelated gotchas about frameworks on iOS. so there's some new information below. I did not originally have step 10 about copying the framework into the app bundle. That worked OK on the simulator but I got a dynamic link error on hardware without step 10. I also didn't have step 11 which addresses if your app target is pure Objective-C but your framework contains a Swift file. My first version of HJSKit.framework was all Objective-C code from Combat Imp but I added a Swift file while working on the new project and it broke the framework version of Combat Imp until I set the proper build flag.

Combat Imp is in the store and I have a new version winding through App Review, so I've started looking at a new project. I immediately wanted some of my custom code from what I call HJSKit and I decided it was time to convert from just using source files in multiple projects to having a shiny new framework. However that's more complicated than it ought to be. Frameworks are new to iOS 8 but there have been some weird ways to hack them for years, so it's difficult to search the web for imformation about the modern ways. There was a WWDC talk about frameworks this year but what they showed was creating a framework inside a single project for multiple targets to use. The Apple development documents are more for OS X and say things like "You don't want to make an umbrella framework" which is wrong: see the Swift/Obj-C interaction document which specifically tells you to use an umbrella framework. I wanted to have a completely separate project, complete with version control, and then I could add that framework to multiple projects. Oh and the new project is in Swift so I wanted Swift/Obj-C interoperability.

Here's what I found. It's actually pretty straightforward but right at then end Xcode threw me a curveball. I also had some trouble figuring out how I wanted to set up git around all of this but that's probably another post (I'm currently using git submodules, but I'm not a git expert. Let me know if you want to know what I did in Git. It took a few tries to get it all right.) This post is focused on Xcode. (All of this is correct for Xcode 6.0.1.) TL;DR: Xcode behaves badly if you try to add a project to a workspace while the project is open in another window. See my OpenRadar for more details.

The steps to a fancy framework!

  1. Pull all the code you want in your framework into a folder. I'd already done this: ~/code/HJSKit already existed.
  2. Create a new project, pick IOS->Cocoa Touch Framework.
  3. Add the files you want to the project. So far this is all completely normal.
  4. Here's where thing get interesting. The header files are actually listed as part of the target. In your Project Navigator select a header file and open the File Inspector. You should see it listed as a member of the framework but there's a new drop-down to the right that can change between "Project", "Public", and "Private". If you want the contents of the header exposed to app clients you have to change the header to "Public". For example, in HJSKit I have both HJSDebugCenter.h and HJSDebugMailComposeDelegate.h. While the apps need to see HJSDebugCenter the MailComposeDelegate is an implementation detail I'd like to hide inside the framework. So I set HJSDebugCenter.h to "Public" and left the other headers at "Project" level.
  5. You also have a new framework "umbrella" header that Xcode created. For me it's simply HJSKit.h. It has a comment that reads "In this header, you should import all of the public headers of your framework using statements like #import <HSJKit/PublicHeader.h>" This didn't work for me because that's not where I wanted the headers. I just went with vanilla #import "HJSDebugCenter.h" and it worked fine.
  6. Build this, make sure it all works.
  7. SUPER IMPORTANT: Now close the framework project window. If you don't do this Xcode will do something visually weird in the next step and you'll think you broke something.
  8. Open the project/workspace for the app client. Drag the framework's xcodeproj bundle into the Project Navigator. Make sure it drops as a top-level line, not indented under anything. (NOTE: this is where it gets weird for git. For git reasons I ended up with a copy of the HJSKit folder in each place. That's fine, just make sure you're referencing the HJSKit you really wanted.)
  9. Select the app target, go to Build Phases, and in the "Link Binary With Libraries" section click the + button. In addition to the usual iOS8.0 frameworks you'll now see a "Workspace" folder with your framework listed. Click it and you're good to go!
  10. NEW 2014-10-17: While you're in Build Phases add a Copy Files phase. Set the Destination to Frameworks, then click the + button. Select the framework from the Products folder of your framework project. See Using an Embedded Framework to Share Code for more on this step. We're not really sharing code in the sense of that article but we still need to do this step and I don't see it documented anywhere else. (The WWDC talk about Modern Frameworks doesn't show it either.) I didn't have this in the first version of this checklist and things ran on the simulator but not on hardware.
  11. NEW 2014-10-17: If your framework contains Swift code but your application does not there is a build Setting you need to configure on the app target. Under Build Options look for "Embedded Content Contains Swift Code" and set it to "Yes". This makes Xcode copy the Swift runtime into your app. Note you have to do this even if you don't call the Swift parts of your framework. The simple presence of a Swift file requires this or you'll get an error immediately in dyld_fatal_error saying that libswitCore.dylib can't be loaded. My framework didn't have Swift code originally so I didn't have this step in the first version of the checklist. If your app target itself contains Swift code then you don't need to set this Yes, as the runtime is already present.
  12. Now you can just put #import "HJSKit/HJSKit.h" in any source file and anything imported in the umbrella folder is available.
  13. You can repeat steps 8-10 for other projects, and each will get a copy. I currently have two workspaces for two different apps and each has a HJSKit framework included.

If you've read about how to hack this up in the past you'll notice what I didn't do: I didn't run lipo at any time, I didn't make an aggregate target, I didn't have to go fussing about and figure out where the Build folder is for the framework. Each app is building its own copy of the framework but that's the behavior I wanted. I have code completion from the framework in each app and the other git magic means I can push changes from one app to the other if I so desire, but I also have a version history where I can see that App A and App B are using different revisions of the framework.

Step 7 was the bugaboo for me. If you have the framework project open then the project file just sort of drops into the workspace without targets listed and isn't available when you go to "Link Binary With Libraries" in Step 9. If you close all the open windows and reopen the workspace it will work fine but I don't know why you'd know that without a lot of experimentation. After you have these all set up any other sequence I've tried to open both the workspace and the project simultaneously generates an error somewhere. But there's this one way that silently just does something broken. And it's the one that I was naturally trying yesterday because I kept thinking I had made the framework wrong, so I had the framework project open so I could tinker with it. It's basically a Heisenbug at that point.