Building a universal framework for iOS

Document directory

• What is a 'framework' and why are they useful?
• What is a 'global' framework?
• Building a 'global' framework

Apple has invested quite a bit of time into making it easy to compile for a number of different ubuntures in xcode. For instance, compiling a library into itsarmv6,
Armv7, and
I386 variants is just a matter of specifying the supported architecture types. However, there isn't a built-in mechanic to take the binaries built for the varous ubuntures and merge them into a universal IOS

Framework.

Before we go through the steps of building a universal IOS framework we shoshould first reviewWhatA framework is and
WhyThey are useful.

What is a 'framework' and why are they useful?

Apple defines a framework:

... 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
Framework 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 should des all of the necessary Header
Files to reference as well.

What is a 'global' framework?

A universal framework can be defined as a framework that contains a binary which has been built for a number of ubuntures (armv6, armv7, i386) and can beStatically^{1
Linked against. This is particle ly useful in iOS development because an application can be built for the simulator (i386) and the device (armv6, armv7 ).}

1 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 'global' framework

Firstly, there is a project called
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 understandHowA universal framework is built using xcode.

Lets get started:

Create a new project

1. File-> New Project (command-shift-N)
2. Select frameworks & Libraries under IOS
3. Select "cocoa touch static library" and click "Next"
4. Provide a name for the library

Configure ubuntures

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.

1. File-> New Target
2. Select "other" under IOS
3. Select "aggregate"
4. 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 andarm. in the next step we'll all merge the binaries into a fat binary.

1. Select mylibrary-Ios target
2. Select "build phases"
3. Click "add build phase"
4. Select "add run script"
5. Name it "build static libs"

12 3

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

View rawgistfile1.sh
This gist brought to you bygithub.

Build universal binary

We are going to add another "run script" phase that builds the framework itself. The script is going:

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" &&

Merge the static libraries built for the varous ubuntures into a fat binary using a tool calledlipo:

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

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 here.

Copy header files into place

1. Select "add build phase"
2. Click "add copy files"
3. Set "destination" to "absolute path"
4. Set subpath${BUILD_DIR}/${CONFIGURATION}-iphoneuniversal/${PRODUCT_NAME}.framework/Versions/A/Headers/
5. Add header files that shoshould be public to the list

Configure aggregate target build against the 'release' Configuration

1. Product-> edit Scheme
2. Choose aggregate target (mylibrary-Ios)
3. Select "run"
4. Choose "release" under build configuration

Build and verify framework

1. Select aggregate target
2. Build it (command-B)

Verify that the binary was built for the correct ubuntures 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