The open-source community for iOS is amazing. There are so many high-quality, incredibly useful open-source projects out there now that it would be crazy to work on an iOS project without bringing in at least a few open-source projects. However, manually managing each of the libraries that you bring in can be tedious at best. Most of them are hosted on GitHub, which has improved a lot in the last few years to streamline the process. With GitHub for Mac, it’s easy to quickly clone a project straight from your browser, but you still have to move the appropriate files into your Xcode project. And then you have to do it all again when the project is updated and you want to take advantage of the latest release.
It doesn’t have to be this way.
CocoaPods is the best way to manage library dependencies with Xcode. It’s still in the alpha phase, but it’s continually being improved. With CocoaPods, you can easily manage your project dependencies, even specifying the specific version number for each. This is all tracked in a plaintext file, so you can keep this in your source repository and your whole team will automatically be in sync. As an added bonus, you won’t have to keep the projects in your source repository, so you can keep your repository’s footprint small.
CocoaPods is distributed as a Ruby gem. If you’re new to Ruby, you should consider using an environment manager like rbenv to keep track of your Ruby environments. It’s not just for Rails—more and more command line tools are being written in Ruby, and they often have specific Ruby version requirements. I wrote a simple guide to getting started with rbenv that will have you up and running in no time.
If you don’t have it already, install Ruby 2.0.0-p247. CocoaPods will work in older versions, but I wouldn’t go older than 1.9.3. It’s distributed as a gem, so installing is simple.
This will download and install CocoaPods and its dependencies. (Don’t forget to rehash if you’re using rbenv.)
Now, perform the initial setup, which will create ~/.cocoapods, setup the initial podspec repos, and more.
Installation is that simple. You’re ready to get started.
Dependencies are tracked in a special plaintext file named Podfile. You should create this file in the same directory as your Xcode project. The first line of this file tells CocoaPods what platform your project is targeting (iOS or OS X), and the subsequent lines list the dependencies for your project.
E.g., a very simple iOS Podfile specifying the latest LastFm and TestFlightSDK frameworks:
1 2 3
Note that the platform is case sensitive. If you want to specify the version for a pod, simply append the version number like so:
1 2 3
You can also prefix the version number with a version constraint to indicate a range of versions.
1 2 3
Finding the pods you need for your project is simple thanks to the search function on the CocoaPods site.
Once your Podfile has been defined, the next step is to install the pods and generate the Xcode workspace. This, too, is quite simple. In the same directory as your Podfile, run the following command.
This will download the pods and build a Xcode workspace that includes a Pods target in addition to your Xcode project. Note that you need to use the .xcworkspace file generated by CocoaPods from now on when working with your project.
Whenever you add a new pod to your Podfile, just run
pod install again to regenerate the workspace.
I like to keep the pods out of my source code repositories. You can update the ignore file for your source control repository to exclude the Pods/ directory created by CocoaPods.
I like to keep the
Podfile.lock files in source control so that it’s easy to recreate the workspace using
pod install after cloning the repository.
This is just the beginning of what CocoaPods can do. Explore more of the advanced features—such as specifying pods for certain targets—in the CocoaPods documentation.