This document describes how to integrate CleanroomASL into your application.
Integration is the act of embedding the CleanroomASL.framework binary into your project, thereby exposing the API it provides to your code.
CleanroomASL is built as a Swift framework, and as such, it has the following base platform requirements:
| Platform | Minimum version |
|---|---|
| iOS | iOS 8.0 |
| Mac | OS X 10.10 |
CleanroomASL is Swift 2.0-compliant and requires Xcode 7 beta 2 or higher to be built.
- Options for integration
- Instructions for manual integration
- Instructions for integration using Carthage
Some familiarity with the Terminal application, the bash command line, and the git command is assumed.
The steps below have been tested with git 2.3.7 (Apple Git-57), although they should be compatible with a wide range of git versions.
Official support for third-party iOS frameworks was introduced with Xcode 6 and iOS 8. Prior to that, developers had been using frameworks in an unsupported fashion by placing shared libraries and resources inside a filesystem structure that mimicked that of the frameworks published by Apple.
Given that real third-party iOS framework support is still in its infancy, it should be no surprise that there are still kinks in the development process when using them:
-
The iOS Simulator uses a different processor architecture than real devices. As a result, frameworks compiled for device won’t work in the simulator, and vice-versa. Sure, you could use
lipoto stitch together a universal binary and use that instead, but... -
Apple will not accept App Store binaries containing iOS Simulator code. That means if you go the universal binary route, now you need a custom build step to make the universal binary, and you need another step to un-make the universal binary when you’re building for submission. Okay, well, why not just build two frameworks: one for the iOS Simulator and one for devices?
-
Xcode won’t be happy if you import two separate frameworks with the same symbols. Xcode won’t notice that there really is no conflict because the frameworks are compiled for different processor architectures. All Xcode will care about is that you’re importing two separate frameworks that both claim to have the same module name.
For these reasons, we do not release Cleanroom projects as framework binaries. Instead, we provide the source, the Xcode project file, and options for integrating so that you can use it from within your code and submit an app that Apple will accept. (Or, at the very least, if Apple doesn’t accept your app, we don’t want it to be the fault of this project!)
There are two supported options for integration:
-
Manual integration — The
CleanroomASL.xcodeprojXcode project file is embedded directly within your project. You then addCleanroomASL.frameworkto the Embedded Binaries and Linked Frameworks and Libraries sections under the General tab for your application target. -
Carthage integration — Carthage is a dependency package manager designed to build frameworks. Once Carthage is installed, to add CleanroomASL to your project using Carthage, you would put the line
github "emaloney/CleanroomASL"in yourCartfileand then issue the commandcarthage update.
Whether you choose one over the other largely depends on your preferences and—in the case of Carthage—whether you’re already using that solution for other dependencies.
Manual integration involves embedding CleanroomASL.xcodeproj directly in your Xcode project.
This will ensure that CleanroomASL is built with the exact same settings you’re using for your app. You won’t have to fiddle with different settings for different architectures — when you’re running in the simulator, it will work; when you then switch to building for device, it’ll work, too.
You’ll also be able to step into CleanroomASL code directly in the debugger without worrying about .dSYM resolution, which is very helpful.
Manual integration is a bit involved; there are five high-level tasks that you’ll need to perform:
- Download the CleanroomASL source into your project structure
- Embed
CleanroomASL.xcodeprojin your Xcode project - Build
CleanroomASL.framework - Add
CleanroomASL.frameworkto your application target - Fix the way Xcode references the framework you added in Step 4
Launch Terminal on your Mac, and cd to the directory that contains your application.
For our integration examples, we’re going to be showing the top-level CleanroomASL directory inside a Libraries directory at the root level of of your application’s source.
You do not need to use this structure, although we’d recommend it, if only to make the following examples work for you without translation.
If you do not already have a Libraries directory, create one:
mkdir LibrariesNext, cd into Libraries and follow the instructions below.
If you’re already using git for version control, we recommend adding CleanroomASL to your project as a submodule. This will allow you to “lock” your codebase to specific versions of CleanroomASL, making it easier to incorporate new versions on whatever schedule works best for you.
If you’re using some other form of version control of if you’re not using version control at all—shame on you!—then you’ll want to clone the CleanroomASL repository. We suggest putting the CleanroomASL clone somewhere within your application’s directory structure, so that it is included in whatever version control regimen you’re using.
Important: Skip this section if you plan to download CleanroomASL using
git clone.
From within the Libraries directory, issue the following commands to download CleanroomASL:
git submodule add https://github.com/emaloney/CleanroomASL.git
git submodule update --init --recursiveNext, you’re ready to embed the CleanroomASL.xcodeproj project file in your Xcode project.
Important: Skip this section if you already performed the tasks outlined in “Downloading CleanroomASL as a submodule” above.
From within the Libraries directory, issue the following command to clone the CleanroomASL repository:
git clone https://github.com/emaloney/CleanroomASL.gitIn the Terminal, the command open CleanroomASL to open the folder containing the CleanroomASL source in the Finder. This will reveal the CleanroomASL.xcodeproj Xcode project and all files needed to build CleanroomASL.framework.
Then, open your application in Xcode, and drag CleanroomASL.xcodeproj into the Xcode project browser. This will embed CleanroomASL in your project and allow you to add the targets built by CleanroomASL to your project.
Before we can add CleanroomASL.framework to your app, we have to build it, so Xcode has more information about the framework.
Important: The next step will only work when the framework is built for a device-based run destination. That means that you must either select the “My Mac” or “iOS Device” run destination before building, or you must select an actual external device (an option that’s only available when such a device is connected to your development machine).
Once a device-based run destination has been selected, select the appropriate build scheme for the target platform: “CleanroomASL iOS” or “CleanroomASL OSX”.
Then, select Build (⌘B) from the Product menu.
Once the build is complete, open CleanroomASL.xcodeproj in the project navigator and find the “Products” group. Open that, and right-click on CleanroomASL.framework. Select Show in Finder. This will open the folder containing the framework binary you just built.
You may see several files in this folder; the one we’re concerned with is:
CleanroomASL.framework
If that file isn’t present, something went wrong with the build.
In Xcode, select the General tab in the build settings for your application target. Scroll to the bottom of the screen to reveal the section entitled Embedded Binaries (the second-to-last section).
Go back to Finder, select the file CleanroomASL.framework, and then drag it into the list area directly below Embedded Binaries.
If successful, you should see CleanroomASL.framework listed under both the Embedded Binaries and Linked Frameworks and Libraries sections.
Unfortunately, Xcode will reference the framework you just added in a way that will eventually cause you pain, particularly if multiple developers are sharing the same project file (in which case the pain will be felt almost immediately).
So, to make things sane again, you’ll need to make sure Xcode references CleanroomASL.framework using a “Relative to Build Products” location.
To do this:
- Locate
CleanroomASL.frameworkin the Xcode project browser - Select the framework
- Ensure the Xcode project window’s Utilities pane is open
- Show the File Inspector in the Utilities pane
- Under the Identity and Type section, find the dropdown for the Location setting
- If the Location dropdown does not show “Relative to Build Products” as the setting, select “Relative to Build Products”
Once you’ve done this for each framework, you’re all done integrating CleanroomASL!
Skip to the Adding the Swift import section to see how you can import CleanroomASL for use in your Swift code.
Carthage is a third-party package dependency manager for iOS and Mac OS X. Carthage works by building frameworks for each of a project’s dependencies.
Before attempting any of the steps below, you should verify that Carthage is available on your system. To do that, open Terminal and execute the command:
carthage versionIf Carthage is available, the version you have installed will be shown.
As of this writing, the current version of Carthage is 0.7.5.
If Carthage is not present, you will see an error that looks like:
-bash: carthage: command not found
Installing Carthage is beyond the scope of this document. If you do not have Carthage installed but would like to use it, you can find installation instructions on the project page.
When building iOS frameworks, Carthage creates universal binaries, meaning that they will work in the iOS Simulator as well as on actual devices. However, because Apple will not accept App Store submissions containing universal binary code, Carthage requires the addition of a build step that strips all unused architectures out of the universal binaries. That way, when building for the simulator, device code is removed; conversely, when creating a device build, simulator code is removed. This keeps Apple happy, while also making it easy to switch back and forth between running on the device and in the simulator.
Carthage integration is a little simpler than manual integration:
- Update the
Cartfilewith an entry for CleanroomASL - Download and build CleanroomASL
- Add
CleanroomASL.frameworkto your application target - Create a build phase to strip the extra processor architectures from the Carthage framework (not necessary for Mac OS X builds)
We’ll start in the Terminal, by cding into to your project’s root directory. The commands you’ll need to issue below can all be done from this location.
In your project’s root directory, edit the file named Cartfile—creating it if necessary—to add the following line:
github "emaloney/CleanroomASL"
In Terminal, issue the command:
carthage updateThis will cause Carthage to download and build CleanroomASL.
Carthage puts its files within a top-level directory called Carthage at the root of your project’s directory structure (i.e., the Carthage directory is a sibling of the Cartfile). Within this directory are two more directories: Build, which contains any frameworks built by Carthage; and Checkouts, which contains fully populated directory structures for each repository specified in the Cartfile.
Note: By default, Carthage builds a framework for each platform supported by the project. You can limit the build to a specific platform by specifying a value for the
--platformargument when invoking thecarthagecommand.
Once Carthage is done building CleanroomASL, you can use the open command to locate the framework binaries in Finder:
open Carthage/Build/iOSThe command above opens the directory containing the iOS framework binary; to locate the Mac OS X binary, execute:
open Carthage/Build/MacIf all went well, the Carthage build directories should contain the file CleanroomASL.framework. If that file isn’t present, something went wrong with the build.
In Xcode, select the General tab in the build settings for your application target. Scroll to the bottom of the screen to reveal the section entitled Embedded Binaries (the second-to-last section).
Go back to Finder, select the file CleanroomASL.framework, and then drag it into the list area directly below Embedded Binaries.
If successful, you should see CleanroomASL.framework listed under both the Embedded Binaries and Linked Frameworks and Libraries sections.
Note: You do not need to perform this step when building for Mac OS X. This step is only necessary when building for targets that can be run in a simulator.
In Xcode, select the Build Phases tab in the build settings for your application target.
At the top-left corner of the list of build phases, you will see a “+” icon. Click that icon and add a “New Run Script Phase”.
Then, in the script editor area just below the Shell line, add the following text:
$PROJECT_DIR/Carthage/Checkouts/CleanroomASL/BuildControl/bin/stripCarthageFrameworks.sh
This script will ensure that any frameworks built by Carthage are stripped of unnecessary processor architectures. Without this step, Apple would reject your app submission because the framework would be included as universal binaries, which isn’t allowed in App Store submissions.
Once you’ve done this, try building your application. If you don’t see any errors, you’re all done integrating CleanroomASL!
Once CleanroomASL has been successfully integrated, all you will need to do is add the following import statement to any Swift source file where you want to use CleanroomASL:
import CleanroomASLWant to learn more about CleanroomASL? Check out the README.
Happy coding!