It used to be quite hard to add third-party libraries to Mac or iOS projects. You would have to deal with all sorts of dependencies, configuring special behavior, and spend days on integrating big libraries to your project.
This was not an issue for some other platforms. C# with Visual Studio has had the NuGet package manager for quite a while. And Ruby has its RubyGems with Bundler. Recently, the situation has changed for iOS and Mac app developers. Highly inspired by Ruby's Bundler, a new package manager for us arrived—CocoaPods. It is the best way to manage library discrepancies in Objective-C projects.
Now in comparison to RubyGems' Gemfile
, CocoaPods uses a so-called Podfile
, where a developer lists the names of a library he is willing to use and his version. By the way, it uses
Podspec
files to describe how a particular library should be integrated with your project. Actually, CocoaPods is using an Xcode Workspace for the integration between your project and a Pods
project, which includes all third-party libraries.
If you have never installed a CocoaPods package manager before, let's do so! You start by executing the following commands:
$ [sudo] gem install cocoapods $ pod setup
The pod
is an executable package, which is installed with CocoaPods.
Next, we want to search the Spec
repository using the following command to get, which version of RestKit is available as of today:
$ pod search RestKit
The result might look like this:
bash-3.2$ pod search RestKit -> RestKit (0.20.3) RestKit is a framework for consuming and modeling RESTful web resources on iOS and OS X. pod 'RestKit', '~> 0.20.3' - Homepage: http://www.restkit.org - Source: https://github.com/RestKit/RestKit.git - Versions: 0.20.3, 0.20.2, 0.20.1, 0.20.0, 0.20.0-rc1, 0.20.0-pre6, 0.20.0pre5, 0.20.0-pre4, 0.20.0-pre3, 0.20.0-pre2, 0.20.0-pre1, 0.10.3, 0.10.2, 0.10.1, 0.10.0 [master repo] - Sub specs: - RestKit/Core (0.20.3) - RestKit/ObjectMapping (0.20.3) - RestKit/Network (0.20.3) - RestKit/CoreData (0.20.3) - RestKit/Testing (0.20.3) - RestKit/Search (0.20.3) - RestKit/Support (0.20.3)
In addition, you can also hit your browser to view the official website of CocoaPods (http://CocoaPods.org), where you will be able to use the web-based search and get more info on the available packages and CocoaPods news.
Now change to the directory of your Xcode project, and create (or edit) your Podfile
with your favorite text editor and add RestKit (or create it using Xcode if you like):
$ cd /path/to/MyProject $ nano Podfile # Platform - ios, mac platform :ios, '5.1' # List of libraries to install pod 'RestKit', '~> 0.20.3' # Testing and Search are optional components pod 'RestKit/Testing' pod 'RestKit/Search'
By specifying the platform and its version we want to be sure that all libraries and dependencies we are using will smoothly run on the target.
Now with RestKit, ~> 0.20.3
in the previous command-line snippet, means we want to use at least Version 0.20.3 or advanced in the range of 0.20.X. If you skip specifying the version, CocoaPods will install the latest.
Tip
If you enter pod
'RestKit', :head
, CocoaPods will install the library from the latest sources. Or you can provide your source path (if you forked it, for example) by entering the following line of code:
pod
'RestKit',
:git
=>
'https://github.com/RestKit/RestKit.git'
Now it's time to install it in your project. Just run the following command:
$ pod install
And you will probably see the following output:
bash-3.2$ pod install Analyzing dependencies Downloading dependencies Installing AFNetworking (1.3.2) Installing RestKit (0.20.3) Installing SOCKit (1.1) Installing TransitionKit (1.1.1) Generating Pods project Integrating client project
CocoaPods downloads the third-party code and creates a new workspace—a file named YourProject.xcworkspace
. From now on, you will use the .xcworkspace
file to open your project in Xcode.
As you can also see, CocoaPods will install some libraries (such as SOCKit) that we did not ask for. They are dependencies of a RestKit library, and are specified in a RestKit's Podspec
file.
Tip
Run pod update
to fetch and install the latest versions of packages. In addition, running [sudo] gem update cocoapods
will update the CocoaPods manager to the latest version.
Once again, do not forget that you need to use workspace from now on. So to open your project in Xcode, one can shoot the following command in the terminal:
$ open MyProject.xcworkspace
The following screenshot shows the sample project tree in the workspace after installing RestKit and few other libraries.
Add the following line to your .pch
file (it is a precompiled header file, which is automatically included in all source files of your project) to be able to use all RestKit components through your code:
#import <RestKit/RestKit.h>
Tip
If you've worked previously with RestKit 0.10, you should know that with the release of Version 0.20, it had major API changes, which are backwards incompatible. Consider checking RestKit's Wiki article Upgrading from v0.10.x to v0.20.0 in the following link:
https://github.com/RestKit/RestKit/wiki/Upgrading-from-v0.10.x-to-v0.20.0
Please note that if your installation fails, it may be because you are installing with a version of Git lower than what CocoaPods is expecting. Please ensure that you are running Git 1.8.0 or higher by executing git --version
. You can get a full picture of the installation details by executing pod install --verbose
.
If you want to install RestKit as a Git submodule or from a release package, the best way is to follow the instructions on RestKit's Wiki article Installing RestKit v0.20.x as a Git Submodule in the following link:
https://github.com/RestKit/RestKit/wiki/Installing-RestKit-v0.20.x-as-a-Git-Submodule