Building a Universal Framework for iOS

Apple has invested quite a bit of time into making it easy to compile for a number of different architectures in XCode. For instance, compiling a library into its “armv6”:http://en.wikipedia.org/wiki/ARM_architecture, “armv7”:http://en.wikipedia.org/wiki/ARM_architecture, and “i386”:http://en.wikipedia.org/wiki/Intel_80386 variants is just a matter of specifying the supported architecture types. However, there isn’t a built-in mechanism to take the binaries built for the various architectures and merge them into a universal iOS “framework”:http://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html#//apple_ref/doc/uid/20002303-BBCEIJFI.

Before we go through the steps of building a universal iOS framework we should first review _what_ a framework is and _why_ they are useful.

What is a “framework,” and why are they useful?

Apple defines a framework as:

… a hierarchical directory that encapsulates shared resources, such as a dynamic shared library, nib files, image files, localized strings, header files, and reference documentation in a single package.

So instead of having header files and binaries in disperate locations a “framework”:http://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html#//apple_ref/doc/uid/20002303-BBCEIJFI brings everything together into one package (a directory with a known structure). Packaging a library as a framework simplifies things for developers because it not only provides a binary to link against but it includes all of the necessary header files to reference as well.

What is a “universal” framework?

A universal framework can be defined as a framework that contains a binary which has been built for a number of architectures (armv6, armv7, i386) and can be _statically_[1] linked against. This is particularly useful in iOS development because an application can be built for the simulator (i386) and the device (armv6, armv7).

fn1. Statically linking a library resolves symbols at compile time and embeds the library into the application. It is not possible, currently, to create a dynamic framework for iOS.

Building a “universal” framework

Firstly, there is a project called “iOS Universal Framework”:https://github.com/kstenerud/iOS-Universal-Framework that simplifies the process of building a universal framework by providing an XCode template. However, I think it is still a meaningful exercise to understand _how_ a universal framework is built using XCode.

Lets get started:

Create a New Project

# File -> New -> New Project (Command-Shift-N)
# Select Frameworks & Libraries under iOS
# Select “Cocoa Touch Static Library” and click “Next”
# Provide a name for the library

Configure Architectures

By default the static library is configured to only build for armv7 so we need to add armv6 and i386 to ensure that the static library is built for older devices (iPhone 3G/Original, early generation iPod Touch) and the simulator.

Create Aggregate Target

An aggregate target aggregates other targets together. In effect, it wraps a number of script executables and copy file tasks in a specified order.

# File -> New Target
# Select “Other” under iOS
# Select “Aggregate”
# Give it a name (MyLibrary-iOS for example)

Build Static Libraries

Under the “Build Phases” section of the aggregate target we are going to add a build phase that compiles a static library for i386 and ARM. In the next step we’ll merge the binaries into a fat binary.

# Select MyLibrary-iOS target
# Select “Build Phases”
# Click “Add Build Phase”
# Select “Add Run Script”
# Name it “Build Static Libs”

xcodebuild -project ${PROJECT_NAME}.xcodeproj -sdk iphonesimulator -target ${PROJECT_NAME} -configuration ${CONFIGURATION} clean build CONFIGURATION_BUILD_DIR=${BUILD_DIR}/${CONFIGURATION}-iphonesimulator
 
xcodebuild -project ${PROJECT_NAME}.xcodeproj -sdk iphoneos -target ${PROJECT_NAME} -configuration ${CONFIGURATION} clean build CONFIGURATION_BUILD_DIR=${BUILD_DIR}/${CONFIGURATION}-iphoneos

Build Universal Binary

We are going to add another “Run Script” phase that builds the framework itself. The script is going to:

1. Create a directory structure that mimics the same directory structure seen in Apple’s dynamic frameworks.

SIMULATOR_LIBRARY_PATH="${BUILD_DIR}/${CONFIGURATION}-iphonesimulator/lib${PROJECT_NAME}.a" &&
DEVICE_LIBRARY_PATH="${BUILD_DIR}/${CONFIGURATION}-iphoneos/lib${PROJECT_NAME}.a" &&
UNIVERSAL_LIBRARY_DIR="${BUILD_DIR}/${CONFIGURATION}-iphoneuniversal" &&
UNIVERSAL_LIBRARY_PATH="${UNIVERSAL_LIBRARY_DIR}/${PRODUCT_NAME}" &&
FRAMEWORK="${UNIVERSAL_LIBRARY_DIR}/${PRODUCT_NAME}.framework" &&
 
# Create framework directory structure.
rm -rf "${FRAMEWORK}" &&
mkdir -p "${UNIVERSAL_LIBRARY_DIR}" &&
mkdir -p "${FRAMEWORK}/Versions/A/Headers" &&
mkdir -p "${FRAMEWORK}/Versions/A/Resources" &&

2. Merge the static libraries built for the various architectures into a fat binary using a tool called lipo.

 # Generate universal binary for the device and simulator.
lipo "${SIMULATOR_LIBRARY_PATH}" "${DEVICE_LIBRARY_PATH}" -create -output "${UNIVERSAL_LIBRARY_PATH}" &&

3. Move the appropriate files into place.

# Move files to appropriate locations in framework paths.
cp "${UNIVERSAL_LIBRARY_PATH}" "${FRAMEWORK}/Versions/A" &&
ln -s "A" "${FRAMEWORK}/Versions/Current" &&
ln -s "Versions/Current/Headers" "${FRAMEWORK}/Headers" &&
ln -s "Versions/Current/Resources" "${FRAMEWORK}/Resources" &&
ln -s "Versions/Current/${PRODUCT_NAME}" "${FRAMEWORK}/${PRODUCT_NAME}"

The full script can be found “at github”:https://gist.github.com/1472295.

Copy Header Files into Place

# Select “Add Build Phase”
# Click “Add Copy Files”
# Set “Destination” to “Absolute Path”
# Set subpath to ${BUILD_DIR}/${CONFIGURATION}-iphoneuniversal/${PRODUCT_NAME}.framework/Versions/A/Headers/
# Add header files that should be public to the list

Configure aggregate target build against the ‘Release’ configuration

# Product -> Edit Scheme
# Choose aggregate target (MyLibrary-iOS)
# Select “Run”
# Choose “Release” under Build Configuration

Build and Verify Framework

# Select aggregate target
# Build it (Command-B)

Verify that the binary was built for the correct architectures using lipo:

lipo -info build/Release-iphoneuniversal/MyLibrary-iOS.framework/MyLibrary-iOS 
 
Architectures in the fat file: build/Release-iphoneuniversal/MyLibrary-iOS.framework/MyLibrary-iOS are: i386 armv6 armv7

Ensure that the header files are copied into place (XCode is known to mess this up on occasion):

tree build/Release-iphoneuniversal/MyLibrary-iOS.framework/
build/Release-iphoneuniversal/MyLibrary-iOS.framework/
├── Headers -> Versions/Current/Headers
├── MyLibrary-iOS -> Versions/Current/MyLibrary-iOS
├── Resources -> Versions/Current/Resources
└── Versions
    ├── A
    │   ├── Headers
    │   │   └── MyLibrary.h
    │   ├── MyLibrary-iOS
    │   └── Resources
    └── Current -> A
 
7 directories, 3 files

h2. Conclusion

Creating a universal framework certainly requires a fair amount of upfront work. However, it is a great mechanism to distribute your library to the masses without making _them_ work to use it. There is not any configuration (header paths) or tweaking (warnings, ARC vs non-ARC files) required on the part of the user. Which means less work for _you_ having to respond to issues and complaints.

Update 02/07/2012: I’ve updated the scripts to ensure that they work when XCode is configured to choose the build directory (derived). The “Build static libs” script is the one that must be updated.