CocoaPods is an easy-to-use dependency management tool for iOS and OS X development. Even though CocoaPods is fairly clear and simple to use, I feel that many cocoa developers are reluctant to give it a try. In this tutorial, I will show you how to get started with CocoaPods in less than five minutes.

What Is CocoaPods?

CocoaPods is a dependency management tool for iOS and OS X development. It makes managing third party libraries in an Xcode project easy and straightforward. CocoaPods has gained considerable traction in the cocoa community, and as a result, hundreds of open source libraries now provide support for CocoaPods. To get an idea of which libraries are available through CocoaPods, visit the CocoaPods website and search for some of your favorite third party libraries. Companies like TestFlight, Mixpanel, and Google make their libraries available through CocoaPods.

Why Should I Use CocoaPods?

Working with third party libraries in an Xcode project isn't always easy and it can often be a pain, especially when integrating non-ARC libraries in an ARC-enabled project. Eloy Durán started the CocoaPods project to ease this pain. Before switching to CocoaPods, I did what most developers do; they manually copy the source files of third party libraries into an Xcode project and compile those files with the rest of the project. Even though this method worked fine, updating a project's dependencies was a cumbersome and error-prone process.

CocoaPods makes managing a project's dependencies much easier and intuitive. You only need to specify which dependencies, or pods, you want to include in your project and CocoaPods takes care of the rest. Updating a pod to a new version is as simple as executing a single command on the command line. If you have avoided the command line in the past, now might be a good time to become familiar with it.

1. Installing CocoaPods

Another great feature of CocoaPods is that it is distributed as a Ruby gem. This makes installing CocoaPods virtually painless. To install the CocoaPods gem, your system needs to have Ruby and RubyGems installed. Fear not because both Ruby and RubyGems are probably already installed on your computer.

Open a new Terminal window and type gem -v to determine if RubyGems is installed on your system. If you need help installing Ruby or RubyGems, Andrew Burgess wrote a great tutorial about RubyGems on Nettuts+. In case you run into problems installing CocoaPods, chances are that Andrew's article has the solution to your problem.

Before installing CocoaPods, make sure to update RubyGems by running the following command on the command line:

gem update --system

Depending on your system configuration, it may be necessary to prefix this command with sudo.

Installing CocoaPods is easy once Ruby and RubyGems are installed. Just run the following:

gem install cocoapods

Once installed, setup CocoaPods by running the pod setup command. During the setup process, the CocoaPods environment is formed and a .cocoapods directory is created in your home folder. This hidden folder contains all the available pod specifications or pod specs.

2. Starting With CocoaPods

Step 1

Instead of explaining how CocoaPods works, it is far easier to show you by creating a simple Xcode project using CocoaPods. Open Xcode and create a new project based on the Empty Application template. Name the project CocoaPods and make sure to enable ARC (Automatic Reference Counting) for the project (figure 1).

Step 2

Now that we created the project, we need to add a Podfile. A Podfile is similar to a Gemfile. It is a text file that contains information about the project and it also includes the project's dependencies, that is, the libraries that are managed by CocoaPods. Close the Xcode project and open a new Terminal window. Browse to the root of your Xcode project and create a new Podfile by running touch Podfile in the Terminal. The touch command updates the modified date of a file, but it creates the file for you if it doesn't exist, which is exactly what we want. Make sure to create the Podfile in the root of your Xcode project.

touch Podfile

Step 3

Open the Podfile in your favorite text editor. At the time of writing this tutorial, the current version of CocoaPods is 0.16. In this version, it is required to specify the platform, iOS or OS X. This will no longer be necessary in the next version of CocoaPods (0.17). In this example, we tell CocoaPods that we target the iOS platform as shown below. It is possible to specify the project's deployment target, but this is optional. The default deployment target is 4.3 for iOS and 10.6 for OS X.

platform :ios, '6.0'

Step 4

With the platform specified, it is time to create the list of dependencies for the project. A dependency consists of the keyword pod followed by the name of the dependency or pod. A pod is just like a gem, a dependency or library that you wish to include in a project or application. You can optionally specify the version of the dependency as shown below.

pod 'SVProgressHUD', '0.9'

By omitting a pod's version number, CocoaPods will use the latest version available (that is what you want most of the time). You can also prefix the version number with a specifier to give CocoaPods more control over which version to use. The specifiers are mostly self explanatory (>, >=, <, <=), but one specifier, ~>, might seem odd if you are not familiar with RubyGems. I'll explain what ~> means in the example shown below. The pod specification shown below indicates that the version of the AFNetworking library should be between 1.0.1 and 1.1 but excluding the latter. This is very useful if you want to give CocoaPods the ability to update a project's dependencies when minor releases (bug fixes) are available, but exclude major releases that can include API changes that might break something in your project.

pod 'AFNetworking', '~> 1.0.1'

A dependency declaration has a lot more configuration options, which can be set in the Podfile. If you want to work with the bleeding edge version of a library, for example, you can replace a pod's version number with :head as shown below. You can even tell CocoaPods what source to use by specifying the git repository or referring CocoaPods to a local copy of the library. These are more advanced features of CocoaPods.

pod 'AFNetworking', :head
pod 'SVProgressHUD', :git => 'https://github.com/samvermette/SVProgressHUD'
pod 'ViewDeck', :local => '~/Development/Library/ViewDeck'

Step 5

With our list of dependencies specified, it is time to continue the setup process. Update the Podfile as shown below and run pod install in the Terminal. Make sure to run this command in the root of your Xcode project where you also created the project's Podfile.

platform :ios, '6.0'

pod 'ViewDeck', '~> 2.2.2'
pod 'AFNetworking', '~> 1.1.0'
pod 'SVProgressHUD', '~> 0.9.0'
pod 'HockeySDK', '~> 3.0.0'

pod install

CocoaPods inspects the list of dependencies and installs each dependency as specified in the project's Podfile. The output on the command line shows you what CocoaPods is doing under the hood. The last two lines are especially interesting to us; CocoaPods creates an Xcode workspace and adds our project to that workspace. It also creates a new project named Pods, adds the listed dependencies to that project, and statically links that with a library. The newly created Pods project is also added to that same workspace (figure 2).

Resolving dependencies of<code>./Podfile'
Updating spec repositories

Cocoapods 0.17.0.rc7 is available.

Resolving dependencies for target<code>default' (iOS 6.0)
Downloading dependencies
Installing AFNetworking (1.1.0)
Installing HockeySDK (3.0.0)
Installing SVProgressHUD (0.9)
Installing ViewDeck (2.2.5)
Generating support files
2013-03-28 11:13:54.663 xcodebuild[1352:1207] XcodeColors: load (v10.1)
2013-03-28 11:13:54.665 xcodebuild[1352:1207] XcodeColors: pluginDidLoad:

[!] From now on use<code>CocoaPods.xcworkspace'.
Integrating<code>libPods.a' into target<code>CocoaPods' of Xcode project<code>./CocoaPods.xcodeproj'.

When running the pod install command, CocoaPods tells us that we should use the CocoaPods.xcworkspace from now on. Xcode workspaces are a key component of how CocoaPods works. An Xcode workspace is a container that groups one or more Xcode projects, which makes it easier to work with multiple projects. As we saw earlier, CocoaPods creates a new project for you, named Pods, and it automatically adds this project to a new Xcode workspace. The project that we started with is also added to this workspace. The key advantage is that your code and the project's dependencies are strictly separated. The dependencies in the Pods project are statically linked with a library that you can see in the Build Phases tab of our project (figure 3). It is important thing to remember to use the workspace created by CocoaPods instead of the project we started with. Our project is now ready for us and we can start using the libraries specified in the project's Podfile.

3. Updating Dependencies

It is obvious that CocoaPods makes it easier to quickly set up a project with several dependencies. However, updating dependencies becomes easier as well. If one of your project's dependencies received a major update and you want to use this update in your project, then all you need to do is update your project's Podfile and run pod update on the command line. CocoaPods will update your project's dependencies for you.

4. Command Line

The CocoaPods gem has many more tricks up its sleeve. Even though you can use the CocoaPods website to browse the list of available pods, the CocoaPods gem also lets you list (list) and search (search) the available pod specs. Open a new Terminal window and enter the command pod search progress to search for libraries that include the word progress. The advantage of searching for pods using the command line is that you only see the information that matters to you, such as the pod's source and the available versions.

Run the pod command (without any options) to see a complete list of available options. The CocoaPods manual is excellent, so make sure to read it if you run into problems or have any questions.

Conclusion

You should now have a basic understanding of CocoaPods so that you can use CocoaPods in your development. Once you start using CocoaPods, chances are that you won't be able to live without it. Even though I had heard of CocoaPods many times, it took me some time to make the transition. However once I started using CocoaPods, I haven't created a single project without it. I am sure you'll love it once you've given it a try. Not only will it save you time, it will also make your life as a developer a bit easier.