Why You Should Consider Using CocoaPods

CocoaPods is a dependency manager for Swift and Objective-C projects. A’pod’ is a package or framework of pre-built functionality you can download and include in your applications to avoid building it yourself.

An example might be that you need to do some network communication and need JSON encoding along with chainable requests/responses. Well, Just like there is an ‘app for X,’ there is a Pod for that!

It has over eighteen thousand libraries and can help you scale your projects elegantly.

You can also create your own Pods. This is great for sharing versioned frameworks or encapsulated functionality within teams.

If you prefer to try Carthage, I have a post for that.

Install CocoaPods on your Mac.

To install CocoaPods, you need Ruby. Well, you are in luck because a Mac already has it. Still, I’d recommend checking and updating your Ruby install since the version that ships on a Mac is invariably old (on the terminal, you can type ruby -v to get the installed version number).

At a terminal type (you may have to give the administrator password)

sudo gem install cocoapods

That’s the install taken care of … what you expected some complicated crazy terminal voodoo, sorry they made it real simple to work with 🙂

Create a Swift Application in Xcode

For this example I am using Xcode 7.3.1 and the Terminal (I use the amazing iTerm2).

Create a Single View Application and ensure you are using Swift. We are not going to be doing anything outside of the ViewController.swift file so go ahead and open that in the Xcode editor now.

Now open a terminal and go to the location of your Xcode project.

Creating the Podfile, … the What Now?

OK fair enough, I did spring that one on you a little bit, so let me explain the basics of setting up to use a pod in your application before we go any further.

Much like build tools (npm, gulp, yeoman, whatever), you create a simple file that can be read by CocoaPods and perform the tasks you tell it to. In our case we are going to tell it to download a particular pod file. This not only keeps it easy to manage dependencies but also share the project with other people and ensure they have the build script (instructions) to get everything they need to make it build. There is a good explanation of what a Podfile is in the documentation and the syntax reference can be found here.

I will not go in to great depth here on the actual contents of the Podfile since we only need to use the basics in this tutorial. Suffice to say there is a simple command we can use on the terminal to make the magic happen for us for now.

We can create a basic version of a Podfile by typing pod init at the terminal so go ahead and do that now.

If you now open the file it created called ’Podfile’ in a text editor of your choice (I do recommend doing this on the terminal since we are going to be there for the next few steps anyway, so I’m using Vim). You will see something like

# Uncomment this line to define a global platform for your project # platform :ios, '9.0'   `target 'CocoaPodsExample' do # Comment this line if you're not using Swift and don't want to use dynamic frameworks use_frameworks!   # Pods for CocoaPodsExample  end

Let’s go through this quickly.

# platform :ios '9.0'

If this line was uncommented (you comment a line by putting # at the beginning) we would be targeting a specific platform number, 9.0 for example in this case. We do not really need to mess with this for our tutorial so leave it alone. It is worth noting that when you find pods to download they may have specific platform versions in the requirements.

The target to end lines are what we are interested in. Since we are using Swift, the comment regarding use_frameworks! can be left alone since we will be using a framework. Notice the target has our application name, in this example it is ‘CocoaPodsExample’, this tells CocoaPods all it needs to know as to which project we will be using this with.

Inside the target and before end is where we list any pods we want to use, so let’s go find one!

Find and Download the CocoaPod You Want to Use

Open up a web browser and go to https://cocoapods.org or just click on the link here.

This is the main web site, we can search for pods. For this tutorial I have chosen a nice little date utility that extends NSDate. Search for ‘Timepiece’.

This cool pod adds some great functionality to NSDate like easily adding time to a current date without having to work out the math. On the page you will find details on usage, installation, platform support and much more. The one thing you need to find is how to tell our Podfile what it needs to know to perform the install. The observant may of noticed by now that Ruby is the language of choice in the Podfile.

I followed the link to the GitHub repository where it tells me what I need to know. I need to add pod “Timepiece” to my file. Always pay attention since the instructions for installing can be very different depending on the pod.

So I’ll do just that and save the file.

Now the file is ready to run the magic for us, so go ahead and run on the terminal by typing pod install. This will run the script and actually download the pod file to your project location, it will also create an Xcode workspace adding our project and the newly downloaded pod.

If everything went well you will see that it installed Timepiece and integrated it in to our project.

This part is VERY important.

I cannot stress how important this part is, from here on out you will not be opening your Xcode project file. You will be opening a workspace that was created when the script was run. The reason for this is CocoaPods adds some extra information for us that needs to be known about when we open our project. If you look at the file listing in the terminal or a Finder window you will see a file called YourProjectName.xcworkspace. The xcworkspace file is what you need to open in Xcode.

At this point, you need to close the project in Xcode. I want to give you a tip here you may not know so close Xcode as well.

You can either open Xcode as normal and go File > Open and open the xcworkspace file we discussed above.

OR if you still have the terminal open you can simply type open yourprojectname.xcworkspace and it will open Xcode and the workspace directly.

Notice you now have a listing for the project and something called Pods. I have opened the file tree a little to show the Timepiece.framework under Pods/Products/Timepiece.framework that we will be using.

Use the Pod in Your Application

Go ahead and expand the application project, in this example it is called CocoaPodsExample, find the ViewController.swift and open it up in the Xcode editor.

I am going to take you through a little exercise first so I can demonstrate that the pod is included and working in the application. Ironically I’ll do this by showing it it is not included and working right now 🙂

The pod I downloaded extends NSDate(), so let’s start by creating an NSDate object and try using some of the functionality mentioned on the Timepiece CocoaPods page.

It says we can add a duration of one week to an NSDate object, let’s try it and yes it will fail since it is not part of the standard NSDate object in Swift. Go ahead and after the super.viewDidLoad() in viewDidLoad() of our ViewController add the following

let now = NSDate() let nextWeek = now + 1.week

Uh oh, we get the Red nasty error because there is no such thing as 1.week

Remove the let nextWeek = now + 1.week line. Before we go any further we need to do a build to compile the pod framework file. So go ahead and run the build by using the shortcut CMD + b.

Now we need to import the Timepiece.framework that the pod provided us, so under import UIKit in the viewController add the following

import Timepiece

You will most likely notice that it will now offer to auto-complete the name which is fine. Go ahead and add back the line

let nextWeek = now + 1.week

You will now see that once you type 1. it will give you the auto-complete options since the project knows all about what the Timepiece framework can offer us to use.

That is the downloaded and installed pod in action.

Wrap Up

OK I know this was a very long way of showing you something short but I wanted to make sure you knew exactly what was going on all the way. Trust me, do this once or twice and you will be using pods without even thinking about the extra steps needed.

Pods can save you a ton of time by providing functionality you need but either do not have time or the knowledge to build. If you come up with something that you think is cool, why not look into creating a pod and sharing with the rest of us.