CocoaPods - nhan/ios_guides GitHub Wiki
- Overview
- Installing Cocoapods
- Basic use
- Where to search for CocoaPods
- Bridging from Objective-C
- Carthage: an alternative option for Swift projects
- Example: using CocoaPods to integrate a progress HUD library
Overview
CocoaPods is a dependency management system for iOS (and other Cocoa-based) projects. It is very similar in function and usage to npm for JavaScript and Bundler for Ruby. CocoaPods can
- download specific versions of libraries automatically
- automatically resolve transitive dependencies
- automatically integrate any libraries into the Xcode build settings for your project
- help you package your library or component for redistribution
Installing Cocoapods
CocoaPods is packaged as a Ruby gem. Since Ruby comes with new OS X installations, you can install CocoaPods simply by running the following commands in a terminal.
gem update --system # Updates RubyGems to latest version
sudo gem install cocoapods # install CocoaPods gem
pod setup # clones the CocoaPods specs repo to ~/.cocoapods
If you for some reason need to perform a sudo-less install or need to install a beta version of CocoaPods, a guide on how to do that can be found here.
Basic use
CocoaPods uses a plain text file named Podfile
to define your
project's dependencies and build targets. If you're familiar
JavaScript or ruby, the format is similar to npm's package.json
or
Bundler's Gemfile
.
If you have already created a project and want to add dependencies using
CocoaPods, you should create a file named Podfile
in the root
directory of your project. This is the the parent directory of your
YourProject.xcodeproj
directory.
The Podfile
format has many commands but the two most important are pod
which
specifies a dependency, and platform
which defines the target
platform. Here is a simple Podfile
platform :ios, '7.0'
pod 'AFNetworking', "~> 2.0"
This tells CocoaPods that we want to target iOS versions 7.0 and above. It also says our project is dependent on the AFNetworking library and can use any version of AFNetworking between 2.0 up to but not including 3.0.
Once you have created your Podfile
and defined the dependencies you
want to be pulled-in, you can have CocoaPods download and integrate them
for you by executing
pod install
in a terminal in the directory containing your Podfile
. CocoaPods
will download your dependencies and generate a .xcworkspace
for your
project. From now on you should only open YourProject.xcworkspace
and
not YourProject.xcodeproj
. The former will have all the
dependencies already integrated.
If you later need to change or update your Podfile
to reflect new
dependencies, simply run pod install
again and reopen
YourProject.xcworkspace
to load the new dependencies.
Where to search for CocoaPods
The master CocoaPods Specs repository is the default repository where CocoaPod will look for your dependencies. Most publically available pods will be published here. The following sites can be used to help locate the right library for your needs:
Bridging from Objective-C
The current version of CocoaPods (0.35 as of this writing) does not have first class support for Swift. What this means in practice—if you only wish to consume libraries in your Swift project—is that you'll have to add an Objective-C bridging header for any CocoaPod library you want to use in a Swift project.
This can be done by File -> New -> File ... -> iOS -> Source -> Header File
. You'll want to name this file something like
YourProject-Bridging-Header.h
, but the name doesn't actually affect
the build process. You'll need to specify this file as a bridging
header in your project's Build Settings
.
You will then #import
every Objective-C header you want to expose to
Swift in this file.
NB: The beta version of CocoaPods 0.36 does support Swift projects and is required in order to use CocoaPods for certain Swift libraries like AlamoFire
Carthage: an alternative option for Swift projects
An alternative depdency management system for Cocoa applications that has gained some traction recently is Carthage. Carthage officially supports Swift and Frameworks. However it does not automatically integrate dependencies into your workspace and only supports iOS 8 and above. Many Swift only libraries provide a Carthage package.
Example: using CocoaPods to integrate a progress HUD library
We'll extend our NY Times Viewer example from the table view guide to show a loading HUD when fetching the latest stories. We can use CocoaPods to install a library that provides us with a covenient way to show a loading indicator while our network request is pending and dismiss the indicator once we are fully loaded.
Since this project previously did not use CocoaPods, we created the
following Podfile
in the root directory of the project
pod 'MBProgressHUD'
This tells CocoaPods that we want to download and integrate the latest version of MBProgressHUD into our project. Notice that since we did not specify a target platform, CocoaPods will infer this from what was already defined in our project.
After executing pod install
we open up NYTimesViewer.xcworkspace
and
add a bridging header BridgingHeader.h
and configure it in our
project's build settings (see above for
how to do this). The bridging header allows us to import the
MBProgressHUD.h
header.
#ifndef NYTimesViewer_BridgingHeader_h
#define NYTimesViewer_BridgingHeader_h
#import <MBProgressHUD.h>
#endif
Finally we update our view controller's logic to display the progress HUD while our network request is pending and dismiss the HUD once we receive a response.
import UIKit
class ViewController: UIViewController, UITableViewDataSource {
@IBOutlet weak var tableView: UITableView!
var stories: [Story] = []
override func viewDidLoad() {
super.viewDidLoad()
tableView.dataSource = self
fetchStories()
}
func fetchStories() {
MBProgressHUD.showHUDAddedTo(self.view, animated: true)
Story.fetchStories({ (stories: [Story]) -> Void in
dispatch_async(dispatch_get_main_queue(), {
self.stories = stories
self.tableView.reloadData()
MBProgressHUD.hideHUDForView(self.view, animated: true)
})
}, error: nil)
}
...
}