Three20 to Xcode

Three20 is a modular open source Objective-C library used by numerous applications in the App Store, including well-known brands such as Facebook, Meetup.com, Pulse, etc. It provides developers with powerful view controllers built on top of the existing iOS framework.

A comprehensive set of  instructions on how to add Three20 to your project both manually and automatically for Xcode 3 can be found on their website. Along with that there is also a nice little transition guide for Xcode 4 users on the automatic method of adding Three20 to your project. As a developer that has just recently transitioned from Xcode 3 to Xcode 4, manually adding Three20 and figuring out where exactly you can add dependency targets and link libraries was a bit of a hunting game. So here is a little visual guide based on the original instructions provided by Three20:

1) Get the code

Clone the three20 git repository: git clone git://github.com/facebook/three20.git

2) Locate the “Three20.xcodeproj” file under “three20/src/Three20/”. Drag Three20.xcodeproj and drop it onto the root of your Xcode project’s “Groups and Files” sidebar. If a dialog appears — make sure “Copy items” is unchecked and “Reference Type” is “Relative to Project” before clicking “Add”. Open the Three20 Xcode Project that you just added to your app and expand the “Dependencies” group. Select all of the projects listed there and drag them to your app as well. You should now have the following list of Three20 projects added to your app:

  • Three20Core
  • Three20Network
  • Three20Style
  • Three20UICommon
  • Three20UINavigator
  • Three20UI
  • Three20

three20 to Xcode screen

4) Link the Three20 static libraries to your project. To do this, select your project on the sidebar and then select your target on the detail view that shows up in the editor pane. Select the “Build Phase” tab and you will see an option for “Link Binary With Libraries”. Click on “+” and you will see a number of items, such as libThree20.a and libThree20Core.a under the Workspace folder. Select each of the lib files (not the UnitTests) and add. This will link each part of the Three20 framework to your app.

three20 xcode

5) Add Three20 as a dependency of your project, so Xcode compiles it whenever you compile your project. This can be accomplished at the “Build Phase” tab as well. There will be a similar option to add Target Dependencies. As we did before, just click on “+”, select “Three20” and each of the other libs and add it to the project. You do need to add the UnitTests target for each lib.

three20 xcode screen 2

6) While we are at the “Build Phase” tab, Add the Core Animation framework to your project. This can be found under “Link Binary With Libraries”. Locate QuartzCore.framework and add it to the project.

7) Add the bundle of images and strings to your app. Locate “Three20.bundle” under “three20/src” and drag and drop it into your project. A dialog will appear — make sure “Create Folder References” is selected, “Copy items” is unchecked, and “Reference Type” is “Relative to Project” before clicking “Add”.

8 ) Finally, tell your project where to find the Three20 headers. Open the “Build Settings” tab that is located next to the “Build Phase” tab and look for “Header Search Paths” and double-click it. Add the relative path from your project’s directory to the “three20/Build/Products/three20” directory.

xcode screenshot

9) While you are in Build Settings, go to “Other Linker Flags” under the “Linker” section, and add “-ObjC” to the list of flags. WARNING: Make sure that you do this for all configuration settings, not just the active one.

10) You’re ready to go. Just #import “Three20/Three20.h” anywhere you want to use Three20 classes in your project. It’s recommended that you do so in a precompiled header for faster build times.

** Additional Tips/Steps by Ron Cirka **

Make sure to add both “-ObjC” AND “-all_load” to the linker flags.

The configuration name should be one word, eg. “adhoc” NOT “ad hoc”. You can try adding quotes in the path if you want to use a multiple word configuration name, but that may not always work. Otherwise you’ll get the dreaded – import “Three20/Three20.h” no such file or directory – when trying to archive.