A guide to Cocoapods, Dependency Management for Xcode
Whether you’re developing an iOS or Mac application, if you’re not using Cocoapods then you’re simply doing it wrong! Ok, maybe not wrong, but you’re definitely not developing as fast or effectively as possible.
Cocoapods manages third-party library dependencies for Xcode projects. It allows stand alone projects to easily access hundreds of open-source libraries, while also giving development teams the ability to automatically and safely work together.
- Easy – Simply add a single file to the xCode project’s root folder and you’re ready to go.
- Automatic – Run a single command and your project will be setup with the same libraries used by the rest of your team.
- Safe – Cocoapods’s use of semantic versioning ensures that you’ll only get the library updates you want and trust. Future updates are propagated across the team ensuring that everyone is working on exactly the same code base.
Head over to Cocoapods’s getting started guide for instructions on downloading and installing the
pod command line tool.
Inside your Xcode project’s root folder run the following commands.
touch Podfileto create an empty pod file
pod installto add Cocoapods to your project
open YourProject.xcworkspaceto your new Xcode project’s workspace.
Notice the new pods project that has been added to your Xcode project’s workspace. It is empty for now.
Finding and installing a pod
Now that we have a Cocoapods-enabled Xcode project, we can add third-party libraries to it. For this demo, let’s add the Facebook’s iOS SDK in order to implement a Facebook login feature.
To find the Facebook library, we use the Cocoapods web search bar. Simply type
site link to see who owns this pod.
Copy the pod spec text to your clipboard, and paste it into your
…and open your Xcode project’s workspace.
Notice that the pods project now contains a few new targets. These will be the targets to compile and build the Facebook SDK and any libraries it depends on.
Notice too that we have not performed any configuration within our Xcode project. All necessary core frameworks have been added, additional pod dependencies resolved and our main project is now aware of the new Facebook pod.
Using a pod
Remember that each pod could require configuration before use. For more information on each pod and how it’s used, consult that pod’s website via Cocoapods.
Following the Facebook Login documentation, we’re required to add a Facebook app id our project’s
And now the fun part of implementing a simple Facebook login. Add a
UIView component to our storyboard’s first view controller and change that component’s class from
FBLoginView using the Identity Inspector (
⌥⌘3 keyboard shortcut)
Enhance our login view controller (optional).
Run the application.
If you’ve correctly added the Facebook app id to your project, when a user hits the ‘Log in with Facebook’ button, they’ll be presented with the most appropriate Facebook login view.
You may log in to Facebook, and because we’re using Facebook’s native view, our users can log out, too.
While this is a very simple application, it should not take away from what’s been achieved here. With almost no effort, we’ve added the entire Facebook SDK to our project. This involved, among other things:
- Downloading Facebook SDK code and any other libraries dependent on it.
- Adding all necessary core frameworks to the project.
- Compiling all source code to work within your project’s target platform and architecture.
- Making all public headers and compiled source available to your project’s targets.
We have used Cocoapods to decrease the amount of time configuring, and increase the amount of time coding.
Updating a pod
In this tutorial we installed the Facebook SDK by adding the following to the
pod 'Facebook-iOS-SDK', '~> 3.16'
This tells the pod command tool to install the latest version of the
Facebook-iOS-SDK pod version 3.16.x and up to but not including 3.17. Below is a complete list of pod versioning operators 
> 0.1Any version higher than 0.1.
>= 0.1Version 0.1 and any higher version.
< 0.1Any version lower than 0.1.
<= 0.1Version 0.1 and any lower version.
~> 0.1.2Version 0.1.2 and the versions up to 0.2, not including 0.2. This operator works based on the last component that you specify in your version requirement. The example is equal to >= 0.1.2 combined with < 0.2.0 and will always match the latest known version matching your requirements.
When it comes time to upgrade to a newer version of any pod, simply run the command
It will alert you to any new version of your installed pods. You can then run
pod update to update all pods or
pod update <pod_name> to update individual pods.
You may notice that if you change a pod’s version within your
Podfile and run
pod installagain, you’ll always get the same version that you installed the first time.
This is because on first install, a special
Podfile.lock file is created. This file “locks” the versions of all pods at the first time of installation.
Podfile.lock should ideally not be edited. Use
pod update to update your pods. More on this in the next section.
Working in a team
If you’re working in a team, you’ll want to push your changes to your fellow developers. Any pod-enabled Xcode project should look something like this.
All that’s required to get your fellow developers using this new pod is to commit the following two files.
Podfilethe file that describes how pod was initially setup
Podfile.lockthe file that describes the current state of the pod project
When a team member pulls your new changes, they simply need to run
pod install. This will install all pods specified in
Podfile and install the versions of those pods specified in the
The combination of a
Podfile.lock ensure that every member of your team is working off exactly the same third-party code base as you are.
All mainstream and popular open-source libraries are available on Cocoapods.org as this is becoming the de facto mechanism to manage and install third-party libraries.
Below are some popular, almost essential pods to use
- AFNetworking: The only framework to use for your networking needs.
- OCMock: Your one-stop unit test mock framework.
- Facebook-iOS-SDK: Maintained by Facebook, so you know it’s legit.
- Google: All things Google.
- Custom ViewController
- API Integrations
- And loads more.
Thanks for reading!
Author: Alasdair McCall