Adopting Cocoapods in your iOS app
Today we will be adopting Cocoapods — a popular dependency manager for Objective-C and Swift into our own project.
Cocoapods is a tool to make your development faster by reducing the amount of time spent managing external code (third-party frameworks) in your own projects.
Cocoapods gets its name from the thousands of available “Pods” which link to popular third-party projects. In our tutorial, we will be integrating one called SwiftyJSON, which makes it quick and easy to parse JSON inside your Swift app.
How can we get SwiftyJSON from Github into our own project? We could simply add the source files for SwiftyJSON into the Xcode project, although we would then have to manually manage updates and integration each time. Not fun or a particularly good use of our time.
A better, more efficient way is to use Cocoapods to automatically add SwiftyJSON to the project with a single command. Cocoapods isn’t just great for adding third-party code, but also managing it. We can revert to an older version of a project if something isn’t working in the latest build or try a beta version if we’re feeling adventurous.
Let’s jump right in.
Cocoapods is built with Ruby, which luckily for us, has been included with Mac OS X for some time now. Installation is done via command line using the Terminal app.
To get started, open Terminal by navigating to the Applications folder in Finder or use the Spotlight tool to search for it.
Once open, you can issue a single command to start installation:
sudo gem install cocoapods
Note: You use the sudo command this one time to install the gem, but it isn’t needed afterwards.
Press enter and the Cocoapods gem will download and be installed on your machine.
Creating a Podfile
Now the Cocoapods gem is installed on our machine, we can add the Podfile — a text-based file which lists which third-party projects you wish to use inside your Xcode project. This file also holds the settings and preferences for these projects.
Let’s open Terminal again and use the cd command to navigate to your Xcode project directory.
The command above shows the specific project path to the Xcode project on my machine, be sure to change it to your own.
Once we are inside our project directory, we issue the following command to create our Podfile (you will only need to do this step once, per project).
If you take a look inside your project directory using the Finder app, you will notice that a new file called Podfile has appeared.
Modifying the Podfile
Go right click on the Podfile and open it with either Xcode or a programming-oriented text editor. Here are a few options if you can't decide the best text editor for you.
Tip: Don’t edit your Podfile with the TextEdit app, as the formatting will cause issues.
With our Podfile open, you can see that we have a target called "MyProject." The Pods that you wish to install inside your app will go in this area.
Tip: If you have multiple targets inside your app like a Watch app, tvOS app, etc, you can specify your different targets in the Podfile. This ensures that a framework you need for your iOS target doesn’t get added to your other targets unnecessarily.
Let’s add our first Pod, SwiftyJSON. If you navigate to the SwiftyJSON Github page, you can see that the Pod name is simply "SwiftyJSON." It’s important to always get the Pod name from the project’s Github or webpage, as the pod name doesn’t always match the project name.
Now our Podfile looks like this:
Your Podfile is now ready to go. We’ve included the library that we want inside the correct target and now we simply need to have Cocoapods download the required files and integrate them into our Xcode project.
Before we run the Cocoapods tool be sure to close all instances of Xcode.
With the Terminal app open and inside your project directory (where your Podfile resides), type the following command:
Note: This can take a bit of time depending on the size of the requested libraries.
Cocoapods will now check the repository and install the latest version of SwiftyJSON into your project.
Once that process is complete, open the Finder app and you will now see a new file with the extension of
.xcworkspace. This is the project file you will now need to use when opening your project. Don’t use the old
.xcodeproj file anymore (it doesn’t include your Cocoapods).
Opening the new project workspace
Double-click the new
.xcworkspace file to open your project. In the Project Navigator (left side of Xcode) you will notice that you have two separate projects. Your original project and one called “Pods."
Everything is now installed and ready to go. The Pods project is managed automatically by Cocoapods, you don’t need to modify anything inside it with the exception of your Podfile when changes are needed.
You will now be able to use the specified third-party library (in our case: SwiftyJSON) inside your project by simply using the import command at the top of your .swift file(s).
When you want to update your project’s dependencies, simply open Terminal, navigate to the Xcode project directory that contains your Podfile and issue the following command:
Cocoapods will check for updated versions of your Pods, install them and integrate them into your project automatically.
Customizing your Pods
In our previous example, we installed SwiftyJSON, which at the time of writing was in version 3.1.1. If we wanted to stay on this version until manually changed we could make the following change to our Podfile:
pod ‘SwiftyJSON’, ‘3.1.1’
Updating your Podfile at this point would only download the 3.1.1 version, even if a newer update was available.
If you wish to revert back to a previous version, you can simply specify the version you want and run the pod update command again.
I hope you’ve learned a bit about Cocoapods and how it can be a powerful tool in your developer toolkit. Spending the time to learn about Cocoapods will reward you with more time coding the things that you love and less time worrying about those mind-numbing tasks like managing framework dependencies.