Add a Framework to an iOS App
How to add a framework, using a Git submodule, to your Xcode project.
When building an iOS app in Xcode, we often need to add code from another project. Projects that add functionality to other apps are usually designed to build a “framework” target. A framework gives your project the benefits of someone else’s hard work, so you don’t have to reinvent the same wheel.
We could just download a copy of the framework’s code files and add it to our own project. But then our copy would be immediately out of sync with the original repository. To continue to enjoy the benefits of someone else’s work, we’re better off adding the “sub-project” using a mechanism that keeps our copy in sync with the original.
Adding an External Respository, Sub-Project and a Framework
In general, to use an external framework in Xcode, you need to:
- Add a some kind of synchronised link to the external repository and download it.
- Add the
.xcodeproj(Xcode project) file from the external repo as a sub-project to your own project, in Xcode’s File Navigator.
- Add the framework to your project’s build phases.
It’s actually a lot simpler than it sounds. For instance, step 2 is a single drag and drop and step 3 involves clicking on two buttons.
In this tutorial, we will go through these steps in detail.
If at any point this becomes at all confusing for you, then I suggest going through the Build an App Like Lego tutorials, which assumes no previous knowledge of Xcode or coding, and builds an app step by step, including adding a framework (in Tutorial 8).
Choices for Managing External Repositories
There are several mechanisms available for syncing a sub project into your own project. They include:
- Git’s submodule
Using submodules is an intrinsic part of the Git version control system and has been around for a long time. As such, you don’t need to install anything else for it to work and it’s relatively easy to use. It’s integrated into the main Git flow so, for instance, when you commit your code, Git automatically knows to commit any changes in the submodule code. If you use a GUI for Git, such as SourceTree, it takes care of submodules for you.
The most cited limitation of submodules, that I’ve heard, is the difficulty in managing cross dependencies between submodules, where two submodules might need to each load a third submodule.
CocoaPods takes care of cross dependencies, and takes care of all three steps above. However, I think it takes more to set up, with no GUI tool, and it hinders my ability to contribute changes to the submodules.
In this tutorial, we will use a submodule.
In this tutorial, we’re going to add a framework called BFWControls to an Xcode project. These steps are the same for adding any framework. If you want to add a different framework, you can follow the steps here, but just replace the BFWControls references with your desired respository.
BFWControls includes raft of features that simplify making apps visually in Xcode’s Interface Builder.
Create Your Own Xcode Project
If you already have an Xcode project in which you want to add a framework, you’re all set to start this tutorial.
If you don’t have an Xcode project ready, just create a new one using any iOS template.
Or, hop over to the Embed a Xib in a Storyboard tutorial to create a basic app with a custom view, to test that the framework works, after you add it. In the rest of this tutorial, I’ll use snapshots from the
XibSample project. If you’re using a different Xcode project, then of course your screen will look slightly different.
Prepare a Submodules Folder
We could put the submodule code anywhere in our Xcode project, but let’s create a
Submodules folder to make it obviously separate.
👉 In Xcode, add a new group named
👉 Launch Terminal and
cd to the new
Submodules directory. You can do this by just dragging the
Submodules folder from Xcode straight into a Terminal window, and holding the
Command key while releasing the mouse button.
Add the Submodule
👉 Still in Terminal, type (or copy and paste):
git submodule add https://github.com/BareFeetWare/BFWControls.git
👁 In Terminal, Git will download the BFWControls “repo” (respository) and configure your main repo to use it as a submodule.
Add the Sub-Project
👉 In the Finder, inside the
Submodules folder, inside the newly added
BFWControls folder, locate the
👉 Drag the
BFWControls.xcodeproj file from the Finder into the
Submodules group folder in Xcode.
Add the Framework
👉 Click on the main
XibSample project file in Xcode. Select the app target and the
General tab. Scroll down to the
Embedded Binaries section and click on the
👉 Xcode shows a list of frameworks. Select the first
BFWControls.framework (Note, not the
👉 Click the
👉 Build the project.
That’s it. The framework is added to our project.
In this tutorial, we added a submodule to our Xcode project, with one a one line command in Terminal. We added a sub-project by dragging the BFWControls.xcodeproj file from the Finder into our Xcode project’s File Navigator. And finally, we added the framework as an embedded binary.
If you’re curious to see what the BFWControls framework can do, go through the Embed a Xib in a Storyboard tutorial for a quick introduction as to how the
NibView works. For a more detailed coverage of the features, step through the detailed Build an App Like Lego tutorial.