Add a Framework to an iOS App

How to add a framework, using a Git submodule, to your Xcode project.

Photo by Dakota Roos on Unsplash


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:

  1. Add a some kind of synchronised link to the external repository and download it.
  2. Add the .xcodeproj (Xcode project) file from the external repo as a sub-project to your own project, in Xcode’s File Navigator.
  3. 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:

  1. Git’s submodule
  2. CocoaPods
  3. Carthage

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.

BFWControls Framework

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

👉 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

👉 Hit Return.

👁 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 BFWControls.xcodeproj file.

👉 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 theGeneral tab. Scroll down to the Embedded Binaries section and click on the + button.

👉 Xcode shows a list of frameworks. Select the first BFWControls.framework (Note, not the BFWControls

👉 Click the Add button.

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