MAR 15, 2013

Switching from Git Submodules to CocoaPods

I've been using CocoaPods for the last month and so far it's really been a love/hate relationship (more on that later). Because it's still a young project, I wasn't able to find a good tutorial on how to make the switch, so hopefully this will be of help to some of you.

Break free from submodules

From your project's root:

  1. Delete .gitmodules.
  2. Delete the .git/modules directory.
  3. Remove references you have to your submodule files in Xcode or in the file system.

Install CocoaPods

$ gem install cocoapods
$ pod setup

This pulls the CocoaPods/Specs repo into ~/.cocoapods.

The Podfile

In your project root, create a file named Podfile with the pods that you would like to use. Here's mine for Shows:

platform :ios, '6.0'
pod 'OBSlider'
pod 'SVGeocoder', :head
pod 'SVHTTPRequest', :head
pod 'SVProgressHUD', '0.9'
pod 'SVSegmentedControl', :head
pod 'SVWebViewController', :head

Head over to the official CocoaPods Wiki for more advanced options. If you'd like to use a library that is not listed on CocoaPods/Specs, I suggest you either keep that component as a Git submodule or add the files manually to your project. Properly adding someone else's project to the CocoaPods/Spec repository is still extremely cumbersome (in my experience anyway) and deserves a blog post of its own.

Once your Podfile is all setup, open Terminal and run pod install. In case you're unfamiliar with Bundler, Podfile.lock will be created automatically. That file contains the pod commit SHAs that just got installed so that you can easily restore that exact environment later on other machines.

Towards the end of pod install, CocoaPods might throw a few warnings about your project settings. Make sure you fix those.

Adapting to CocoaPods

Switching to Xcode workspaces

What CocoaPods does is build a libPods.a static library for your Xcode project to use. For that to work, it uses an Xcode workspace to incorporate both projects. If you weren't already using Xcode workspaces, MyApp.xcworkspace is your new friend.

Broken code autocompletion

Depending on how you used to add 3rd party libraries before, CocoaPods might break code completion for your newly added Pods. To fix that, in my case I had to replace

#import "SVHTTPRequest.h"


#import <SVHTTPRequest/SVHTTPRequest.h>

(thanks @SteveStreza)

Version control

Podfile and Podfile.lock should both be added to version control. Also add Pods/ if you want to be able to checkout the repository and build it without having to run pod install.

Updating Pods
$ pod install

will install the pod versions specified in Podfile.lock. If none is specified in there, it will install from Podfile.

$ pod update

makes CocoaPods ignore your Podfile.lock and installs from Podfile directly.