How to create, develop, and distribute iOS Static Frameworks quickly and efficiently

Building a static iOS framework is a pain in the ass. There are a variety of existing solutionsalready and each one has its own disadvantages. Presented here is a solution that meets all of thefollowing constraints while having no deal-breaking disadvantages.

• Fast iterative compilation times (up to 3x faster than some solutions!).
• Easy distribution and packaging.
• No modifications to Xcode.
• No trickery with fake bundle targets and the likes.
• Simple set-up for third-parties.
• Support for building the framework as a dependent target (i.e. modifying source in the frameworkand building an app will automatically rebuild the framework and relink as expected).
• Works with the latest version of Xcode

Shameless plug: if you appreciate high-speed iOS development, check outNimbus, the iOS framework whose growth is bounded by itsdocumentation.

This work is licensed under a Creative Commons Attribution 3.0 Unported License.

Table of Contents

• Existing Solutions
• How to Create a Static Framework for iOS
  • Overview
  • Create the Static Library Target
  • Create the Framework Distribution Target
• Resources and Bundles
• Adding the Framework to a Third-Party Application
• Developing the Framework as a Dependent Project
• License

Existing Solutions

Presented below are a few of the most popular solutions for building static iOS frameworks and thereasons why they should be avoided.

Note: Though the tone below is largely critical, credit is owed to those who pioneered thesesolutions. Much of the proposed solution is based off the work that these amazingly generouspeople have donated to the ether. Thanks!

iOS-Universal-Framework

Source: https://github.com/kstenerud/iOS-Universal-Framework

Major problems

• Slow iterative build times
• Has to modify Xcode for "Real" frameworks
• Can't properly add framework as a dependent target for "Fake" frameworks
• No adequate solution for resource loading

Overview

This project provides two solutions: "fake" frameworks and "real" frameworks.

A fake framework is a bundle target with a .framework extension and some post-build scripts togenerate the fat library for the .framework.

A real framework modifies the Xcode installation and generates a true .framework target. Realframeworks also use post-build scripts to generate the fat library.

Problems with Fake Frameworks

The problem with a fake framework is that you can't link to the framework as a dependent target. Youcan "trick" Xcode into linking to the framework by using the -framework flag in your LD_FLAGS,but changes to the framework will not be reflected in iterative builds. This requires that you cleanbuild every time you modify the framework, or make a trivial modification to the application itselfin order for it to forcefully relink to the new .framework. This bug is discussedhere.

Example warning when you attempt to link to the .framework target:

warning: skipping file
'/Users/featherless/Library/Developer/Xcode/DerivedData/SimpleApp-cshmhxdgzacibsgaiiryutjzobcb/Build/Products/Debug-iphonesimulator/fakeframework.framework'
(unexpected file type 'wrapper.cfbundle' in Frameworks & Libraries build phase)

Problems with Real Frameworks

To use real frameworks you need to modify your Xcode installation. This is simply not scalable whenyou want to work with a team of people. If you use a build farm this problem becomes even worsebecause it may not be possible to modify the Xcode installations on the build servers.

Problems with Both Fake and Real Frameworks

In both frameworks there is a post-build step that builds the "inverse" platform. For example, ifyou're building the framework for i386, the post-build step will build the framework for armv6/armv7/armv7sand then smush the libraries together into one fat binary within the framework. The problem withthis is that it triples the build time of the framework. Make one change to a .m file andsuddenly you're rebuilding it for three platforms. Change a PCH and your project will effectivelyperform three clean builds. This is simply not ok from a productivity standpoint.

There is also the problem of distributing resources with the .framework. Both the fake and realframeworks include an "embeddedframework" which is meant to be copied into the application. Thisresults in the .framework binary being distributed with the application! Alternatively we could askdevelopers to only copy what's in the resources folder to their app, but this is complicated andrequires we namespace our resource file names to avoid naming conflicts.

db-in's solution ("Fake" frameworks)

Source: http://db-in.com/blog/2011/07/universal-framework-iphone-ios-2-0/

Major problems

• Slow iterative build times
• Can't properly add framework as a dependent target
• No adequate solution for resource loading (recommends a remarkably bad solution)

Overview

db-in's solution is roughly identical to kstenerud's solution of using a bundle target to generate afake framework. This has the same disadvantages as outlined above so I won't repeat myself.

There is, however, a specific deal-breaker with the recommendations in this blog post: resources.Db-in recommends copying the .framework into your application as a resource bundle; this is NOTOK. This will end up copying not just the resources from your framework, but also the fat binaryof the framework! Doing this will inflate the size of your application by several megabytes morethan it should be because you're shipping off a fat binary with your application.

And so without further ado...

How to Create a Static Framework for iOS

There are a few constraints that we want to satisfy when building a .framework:

• Fast iterative builds when developing the framework. We may have a simple application that has the.framework as a dependency and we want to quickly iterate on development of the .framework.
• Infrequent distribution builds of the .framework.
• Resource distribution should be intuitive and not bloat the application.
• Setup for third-party developers using the .framework should be easy.

I believe that the solution I will outline below satisfies each of these constraints. I will outlinehow to build a .framework project from scratch so that you can apply these steps to an existingproject if you so desire. I will also include project templates for easily creating a.framework.

Overview

View a sample project that shows the result of following these steps in the sample/Serenitydirectory.

Within the project we are going to have three targets: a static library, a bundle, and an aggregate.

The static library target will build the source into a static library (.a) and specify which headerswill be "public", meaning they will be accessible from the .framework when we distribute it.

The bundle target will contain all of our resources and will be loadable from the framework.

The aggregate target will build the static library for i386/armv6/armv7/armv7s, generate the fat frameworkbinary, and also build the bundle. You will run this target when you plan to distribute the.framework.

When you are working on the framework you will likely have an internal application that links to theframework. This application will link to the static library target as you normally would and copythe .bundle in the copy resources phase. This has the benefit of only building the framework codefor the platform you're actively working on, significantly improving your build times. We'll do alittle bit of work in the framework project to ensure that you can use your framework in your appthe same way a third party developer would (i.e. importing should workas expected). Jump to the dependent project walkthrough.

Create the Static Library Target

Step 1: Create a New "Cocoa Touch Static Library" Project

The product name will be the name of your framework. For example, Serenity will generateSerenity.framework once we've set up the project.

Step 2: Create the Primary Framework Header

Developers expect to be able to import your framework by importing the header. Ensure that your project has such a header (if you created a new static library then thereshould already be a Serenity.h and Serenity.m file; you can delete the .m).

Within this header you are going to import all of the public headers for your framework. Forexample, let's assume that we have some Widget with a .h and .m. Our Serenity.h file would looklike this:

#import 

#import 

Once you've created your framework header file, you need to make it a "public" header. Publicheaders are headers that will be copied to the .framework and can be imported by those using yourframework. This differs from "project" headers which will not be distributed with the framework.This distinction is what allows you to have a concept of public and private APIs.

To change a file's target membership visibility in XCode 4.4+,you'll need to select the Static Library target you created (Serenity), open the Build Phases tab:

Xcode 4.X:Click on Add Build Phase > Add Copy Headers.

Xcode 5:Add Build Phases from the menu. Click on Editor > Add Build Setting -> Add Copy Headers. Note: If the menu options are grayed out, you'll need to click on the whitespace below the Build Phases to regain focus and retry.

You'll see 3 sections for Public, Private, and Project headers. To modify the scope of any header, drag and drop the header files between the sections. Alternatively you can open the Project Navigator and select the header. Next expand the Utilities pane for the File Inspector.(Cmd+Option+0).

Look at the "Target Membership" group and ensure that the checkbox next to the .h file is checked.Change the scope of the header from "Project" to "Public". You might have to uncheck and check the box to get the dropdown list. This will ensure that the header getscopied to the correct location in the copy headers phase.

Step 3: Update the Public Headers Location

By default the static library project will copy private and public headers to the same folder:/usr/local/include. To avoid mistakenly copying private headers to our framework we want to ensurethat our public headers are copied to a separate directory, e.g. $(PROJECT_NAME)Headers. To change this setting,select the project in the Project Navigator and then click the "Build Settings" tab. Search for "publicheaders" and then set the "Public Headers Folder Path" to "$(PROJECT_NAME)Headers" for all configurations.If you are working with multiple Frameworks make sure that this folder is unique.

Ongoing Step: Adding New Sources to the Framework

Whenever you add new source to the framework you must decide whether to expose the .h publicly ornot. To modify a header's scope you will follow the same process as Step 2. By default a header'sscope will be "Project", meaning it will not be copied to the framework's public headers.

Step 4: Disable Code Stripping

We do not want to strip any code from the library; we leave this up to the application that islinking to the framework. To disable code stripping we must modify the following configurationsettings:

"Dead Code Stripping" => No (for all settings)
"Strip Debug Symbols During Copy" => No (for all settings)
"Strip Style" => Non-Global Symbols (for all settings)

Step 5: Prepare the Framework for use as a Dependent Target

In order to use the static library as though it were a framework we're going to generate the basicskeleton of the framework in the static library target. To do this we'll include a simple post-buildscript. Add a post-build script by selecting your project in the Project Navigator, selecting the target, and then the"Build Phases" tab.

Xcode 4.X: Click Add Build Phase > Add Run Script

Xcode 5: Select Editor menu > Add Build Phase > Add Run Script Build Phase

Paste the following script in the source portion of the run script build phase. You can rename the phase by clickingthe title of the phase (I've named it "Prepare Framework", for example).

prepare_framework.sh

set -e

mkdir -p "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.framework/Versions/A/Headers"

# Link the "Current" version to "A"
/bin/ln -sfh A "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.framework/Versions/Current"
/bin/ln -sfh Versions/Current/Headers "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.framework/Headers"
/bin/ln -sfh "Versions/Current/${PRODUCT_NAME}" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.framework/${PRODUCT_NAME}"

# The -a ensures that the headers maintain the source modification date so that we don't constantly
# cause propagating rebuilds of files that import these headers.
/bin/cp -a "${TARGET_BUILD_DIR}/${PUBLIC_HEADERS_FOLDER_PATH}/" "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.framework/Versions/A/Headers"

This will generate the following folder structure:

-- Note: "->" denotes a symbolic link --

Serenity.framework/
  Headers/ -> Versions/Current/Headers
  Serenity -> Versions/Current/Serenity
  Versions/
    A/
      Headers/
        Serenity.h
        Widget.h
    Current -> A

Try building your project now and look at the build products directory (usually~/Library/Developer/Xcode/DerivedData/-/Build/Products/...). You shouldsee a libSerenity.a static library, a Headers folder, and a Serenity.framework folder thatcontains the basic skeleton of your framework.

Create the Framework Distribution Target

When actively developing the framework we only care to build the platform that we're testing on. Forexample, if we're testing on the iPhone simulator then we only need to build the i386 platform.

This changes when we want to distribute the framework to third party developers. The third-partydevelopers don't have the option of rebuilding the framework for each platform, so we must providewhat is called a "fat binary" version of the static library that is comprised of the possibleplatforms. These platforms include: i386, armv6, armv7, and armv7s.

To generate this fat binary we're going to build the static library target for each platform.

Step 1: Create an Aggregate Target

Click File > New Target > iOS > Other and create a new Aggregate target. Title it something like "Framework".

Step 2: Add the Static Library as a Dependent Target

Add the static library target to the "Target Dependencies".

Step 3: Build the Other Platform

To build the other platform we're going to use a "Run Script" phase to execute some basic commands.Add a new "Run Script" build phase to your aggregate target and paste the following code into it.

build_framework.sh

set -e
set +u
# Avoid recursively calling this script.
if [[ $SF_MASTER_SCRIPT_RUNNING ]]
then
    exit 0
fi
set -u
export SF_MASTER_SCRIPT_RUNNING=1

SF_TARGET_NAME=${PROJECT_NAME}
SF_EXECUTABLE_PATH="lib${SF_TARGET_NAME}.a"
SF_WRAPPER_NAME="${SF_TARGET_NAME}.framework"

# The following conditionals come from
# https://github.com/kstenerud/iOS-Universal-Framework

if [[ "$SDK_NAME" =~ ([A-Za-z]+) ]]
then
    SF_SDK_PLATFORM=${BASH_REMATCH[1]}
else
    echo "Could not find platform name from SDK_NAME: $SDK_NAME"
    exit 1
fi

if [[ "$SDK_NAME" =~ ([0-9]+.*$) ]]
then
    SF_SDK_VERSION=${BASH_REMATCH[1]}
else
    echo "Could not find sdk version from SDK_NAME: $SDK_NAME"
    exit 1
fi

if [[ "$SF_SDK_PLATFORM" = "iphoneos" ]]
then
    SF_OTHER_PLATFORM=iphonesimulator
else
    SF_OTHER_PLATFORM=iphoneos
fi

if [[ "$BUILT_PRODUCTS_DIR" =~ (.*)$SF_SDK_PLATFORM$ ]]
then
    SF_OTHER_BUILT_PRODUCTS_DIR="${BASH_REMATCH[1]}${SF_OTHER_PLATFORM}"
else
    echo "Could not find platform name from build products directory: $BUILT_PRODUCTS_DIR"
    exit 1
fi

# Build the other platform.
xcodebuild -project "${PROJECT_FILE_PATH}" -target "${TARGET_NAME}" -configuration "${CONFIGURATION}" -sdk ${SF_OTHER_PLATFORM}${SF_SDK_VERSION} BUILD_DIR="${BUILD_DIR}" OBJROOT="${OBJROOT}" BUILD_ROOT="${BUILD_ROOT}" SYMROOT="${SYMROOT}" $ACTION

# Smash the two static libraries into one fat binary and store it in the .framework
lipo -create "${BUILT_PRODUCTS_DIR}/${SF_EXECUTABLE_PATH}" "${SF_OTHER_BUILT_PRODUCTS_DIR}/${SF_EXECUTABLE_PATH}" -output "${BUILT_PRODUCTS_DIR}/${SF_WRAPPER_NAME}/Versions/A/${SF_TARGET_NAME}"

# Copy the binary to the other architecture folder to have a complete framework in both.
cp -a "${BUILT_PRODUCTS_DIR}/${SF_WRAPPER_NAME}/Versions/A/${SF_TARGET_NAME}" "${SF_OTHER_BUILT_PRODUCTS_DIR}/${SF_WRAPPER_NAME}/Versions/A/${SF_TARGET_NAME}"

Important Note

The above script assumes that your library name matches your project name in the following line:

SF_TARGET_NAME=${PROJECT_NAME}

If this is not the case (e.g. your xcode project is named SerenityFramework and the target name isSerenity) then you need to explicitly set the target name on that line. For example:

SF_TARGET_NAME=Serenity

Step 4: Build and Verify

You now have everything set up to build a distributable .framework to third-party developers. Trybuilding the aggregate target. Once it's done, expand the Products folder in Xcode, right click thestatic library and click "Show in Finder". If this doesn't open Finder to where the static libraryexists then try opening~/Library/Developer/Xcode/DerivedData//Build/Products/Debug-iphonesimulator/.

Within this folder you will see your .framework folder.

You can now drag the .framework elsewhere, zip it up, upload it, and distribute it to yourthird-party developers.

Resources and Bundles

To distribute resources with a framework, we are going to provide the developer with a separate.bundle that contains all of the strings and resources. This distribution method provides a numberof advantages over including the resources in the .framework itself.

• Encapsulation of resources. We can scope resource loading to our framework's bundle.
• Easy to add bundles to projects.
• The developer doesn't have to copy the entire .framework into their application.

The hard part about bundles is creating the target. Xcode's bundle target doesn't actually create aloadable bundle object, so we have to do some post-build massaging of the bundle. It's importantthat we create a bundle target because we need to create the bundle using the Copy Bundle Resourcesphase that will correctly compile .xib files (a Copy Files phase does not accomplish this!).

Step 1: Create the Bundle Target

In the framework project, create a new bundle target. Click on File > New > Target > OS X > Bundle. You will need to name the bundle somethingdifferent from your framework name or Xcode will not let you create the target. I've named the target SerenityResources. We will rename the output of the target to Serenity.bundle in a followingstep.

Ensure that the Framework setting is set to "Core Foundation".

Step 2: Clean up the Bundle Target Settings

By default the bundle will only show build settings for Mac OS X. It doesn't really matter what itbuilds for because the bundle isn't actually going to have any code in it, but I prefer to havethings nice and consistent. Open the bundle target settings and delete the settings forArchitectures, Base SDK, and Build Active Architecture Only.

Xcode 5: Deleting a build setting will reset it to the Project's build setting. It should switch from OS X to iOS.

This is also when you should change your bundle target's product name to the name of your frameworkrather than the target name. Click on your project in the Project Navigator and then selectthe bundle target. Click Build Settings, search for "Product Name", and then replacethe value of Product Name with the name of your framework (e.g. $(TARGET_NAME) replaced by Serenity)

Step 3: Remove HIDPI Mac OS X Build Setting

We created a OS X Bundle and it includes and option to merge HIDPI (retina and non-retina) art assets into a .tiff file. You don't want this behavior and need to disable it, or you will be unable to load your image assets from the bundle.

In the Bundle target go to Build Settings and search for COMBINE_HIDPI_IMAGES and delete the user defined setting. When you build, verify that your @2x.png and .png images are all in the bundle.

Ongoing Step: Add Resources to the Bundle Target Copy Files Phase

Whenever you add new resources that you want to include with your framework you need to add it tothe bundle target that you created.

Step 4: Add the Bundle Target to your Aggregate Target

Whenever we build the framework for distribution we likely also want to build the bundle. Add thebundle target to your aggregate target's dependencies.

Step 5: Loading Bundle Resources

In order to load bundle resources, we must first ask the third-party developer to add the .bundle totheir application. To do so they will simply drag the .bundle that you distributed with the.framework to their project and ensure that it is copied in the copy files phase of their apptarget.

To load resources from the bundle we will use the following code:

// Load the framework bundle.
+ (NSBundle *)frameworkBundle {
  static NSBundle* frameworkBundle = nil;
  static dispatch_once_t predicate;
  dispatch_once(&predicate, ^{
    NSString* mainBundlePath = [[NSBundle mainBundle] resourcePath];
    NSString* frameworkBundlePath = [mainBundlePath stringByAppendingPathComponent:@"Serenity.bundle"];
    frameworkBundle = [[NSBundle bundleWithPath:frameworkBundlePath] retain];
  });
  return frameworkBundle;
}

[UIImage imageWithContentsOfFile:[[[self class] frameworkBundle] pathForResource:@"image" ofType:@"png"]];

You can see an example of loading a resource from within the framework in the Widget object in theincluded Serenity framework.

Xcode 5: Do not use the Asset Catalog for any resources within a bundle. On an iOS 7.0 only project, a bug causes the pathForResource method to return nil.

Adding the Framework to a Third-Party Application

View a sample project that shows the result of following these steps in the sample/ThirdPartydirectory.

This is the easy part (and what your third-party developers will have to do). Simply drag the.framework to your application's project, ensuring that it's being added to the necessary targets.

Import your framework header and you're kickin' ass.

#import 

Resources

If you're distributing resources with your framework then you will also send the .bundle file to thedevelopers. The developer will then drag the .bundle file into their application and ensure thatit's added to the application target.

Developing the Framework as a Dependent Project

View a sample project that shows the result of following these steps in the sample/DependentAppdirectory.

When developing the framework you want to minimize build times while ensuring that your experienceroughly matches that of your third-party developers. We achieve this balance by only building thestatic library but treating the static library as though it were a framework.

Step 1: Add the Framework Project to your Application Project

To add the framework as a dependent target in your application, from Finder drag the framework's .xcodeproj toXcode and drop it in your application's frameworks folder. This will add a reference to theframework's xcodeproj folder.

Step 2: Make the Framework Static Library Target a Dependency

Once you've added the framework project to your app you can add the static library product as adependency. Select your project in the Project Navigator and open the "Build Phases" tab. Expandthe "Target Dependencies" group and click the + button. Select the static library target and click"Add".

Note: Close your Static Library Project or the dependencies will not appear in the list. You can only have one instance of an Xcode project open.

Step 3: Link your Application with the Framework Static Library

In order to use the framework's static library we must link it into the application. Expand the"Link Binary With Libraries" phase and click the + button. Select the .a file that's exposed byyour framework's project and then click add.

Step 4: Import the Framework Header

You now simply need to import the framework header somewhere in your project. I generally preferthe pch so that I don't have to clutter up my application's source with framework headers, but youcan obviously choose whatever practice suits your needs.

#import 

Step 4-b: Adding Resources

If you are developing resources for your framework you can also add the bundle target as adependency.

You must then add the bundle to the Copy Bundle Resources phase of your application by expandingthe products folder of your framework product and dragging the .bundle into that section.

Step 5: Check Dependent Target Build Settings

Set the setting Skip Install to Yes for any static library or bundle target that you create. Check all the targets that are dependencies of your application project. If the option is No then you will be unable to build an archive of the project containing the target dependencies. Xcode will create a Generic Xcode Archive, which cannot be shared adhoc, validated, or submitted.

Step 6: Build and Test

Build your application and verify a couple things:

• Your framework should be built before your application.
• Your framework should be linked into the application.
• You shouldn't get any compiler or linker errors.

License

Except as otherwise noted, the content of this page is licensed under the Creative CommonsAttribution 3.0 Unported License, and code samples are licensed under the Apache 2.0 License.

To view a copy of this license, visit http://creativecommons.org/licenses/by/3.0/ or send a letterto Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.

转自：https://github.com/jverkoey/iOS-Framework