CocoaPods and RHMAP: a Love Story.

2016 will see CocoaPods make the big step of going version 1.0 (Yay!) and RHMAP embracing CocoaPods (Yay! Yay!).

In RHMAP v3.8.0 all your Studio iOS templates are based on CocoaPods. Broadly adopted by iOS developers, chances are that you might have already encountered a CocoaPods project (if not, no worries, this post will guide you through).

What is CocoaPods for?

Before delving in its usage, let’s ask this simple question: What is CocoaPods?

From CocoaPods site: CocoaPods manages library dependencies for your Xcode projects. Ultimately the goal is to improve discoverability of, and engagement in, third party open-source libraries by creating a more centralised ecosystem.

Simply put: CocoaPods provides a centralised git repository where:

  • libraries developers published their artefacts (using a PodSpec) in the form of source file.
  • app developers can consume them, easily managing versions (using a Podfile).

RHMAP and CocoaPods: as it all started

As FeedHenry iOS SDK contributors, we’ve been using CocoaPods for building FeedHenry iOS SDK since 2.25. You might have noticed that iOS SDK has been released to central repo. We liked CocoaPods so much that we starting making our templates used it in cocoapods git branches.

Since 3.7.0, Build Farm has been updated to fully support CocoaPods. The iOS blank template has been made available in CocoaPods in RHMAP 3.7.0. Going further for 3.8.0, all iOS templates present in studio will be based on CocoaPods.

Let’s see how CocoaPods makes your RHMAP project management easier.

How to use CocoaPods in RHMAP

When working in Studio, you don’t need to do anything to build your CocoaPods project, all is taking care of by the Build Farm and the template available in studio. If you create a new Native iOS Blank Project project, you see FH.framework directory is missing. You now fetch the dependencies through Podfile:


When you cloned you iOS project locally, you will need some additional steps to be able to use your CocoaPods project. All those steps are described in the README of all the templates but let’s go through then in the next section.

Using CocoaPods locally

Pre-requisites: Have CocoaPods gem installed

CocoaPods is built with Ruby and it will be installable with the default Ruby available on OS X. To install it, simply type in a shell: 

$ sudo gem install cocoapods

If you already have CocoaPods installed and want to update to the latest release version simply install the gem again.

If you want to lock the version you want to install, do as below:

$ sudo gem install cocoapods -v 0.39.0

Note: at the time of writing CocoaPods 1.0 is not yet released, RHMAP v3.8.0 templates are based in CocoaPods 0.39.0.

Clone the template repo

If you want to work locally simply clone the repo. In this example, you’re going to work with helloworld-ios:

$ git clone
$ git checkout cocoapods

You need to change to cocoapods branch as at the moment master is still holding the FeedHenry framework embedded version of the template. You next step is to check the content of Podfile file.

Create Podfile

When using a Studio template for your iOS project, a Podfile is available for you which looks like:

source ''
xcodeproj 'helloworld-ios-app.xcodeproj'
platform :ios, '7.0'
pod 'FH', '>= 3.1.1' 

Here you Podfile is pretty simple it used a default target and define only one pod: the FeedHenry SDK.

Note that you can also cocoapodify your own project afterwards. All you need to do is:

  • add a new Podfile file
  • remove embedded frameworks

You can see as an example this commit where I moved the iOS HelloWorld project into a CocoaPods based project.

Generate Workspace and Pods

With your Podfile, you now need to fetch the dependencies and generate a workspace. Open a terminal at your project root and run the command:

$ pod install

Install command is fetching for you the dependencies, available in the Pods folder of your project.

The command has also generated for you a workspace project. For now on, you should always use the .xcworkspace instead of the .xcodeproj because this workspace contains your code source and the Pods folder with all the dependencies as source code. Opening the .xcodeproj will end up with compilation errors as the dependencies are not embedded in the project anymore. As you work with CocoaPods, you will enjoy the fact that the dependencies are expressed in source code, making it easier to debug and set breakpoints.

Another file that is generated is Podfile.lock,  this file is generated after the first run of pod install, and tracks the version of each Pod that was installed. For example, you can take a look inside Podfile.lock:

 - AeroGear-Push (1.2.0)
 - FH (3.1.1):
 - AeroGear-Push (= 1.2.0)
 - Reachability (= 3.2)
 - Reachability (3.2)
 - FH (>= 3.1.1)
 AeroGear-Push: 02104f3ec9fc42dd328497ecfbcc8bb6ade0700f
 FH: 33353448996384a4c05626b8a42ac7ebee75bdc5
 Reachability: 33e18b67625424e47b6cde6d202dce689ad7af96

In the Podfile only the direct FH dependency is expressed, whereas in Podfile.lock, all dependencies are visible even the transitives ones: Reachability and AeroGear-Push. Moreover, Podfile.lock actually locks the dependencies version at the time the initial pod install was launched.

In our example, HelloWorld app fetches the latest FH at least equal or greater than 3.1.1 version. FH SDK 3.1.1 locks the version of the transitive dependencies in its PodSpec. But some Pod might be more permissive in expressing their dependencies, having a Podfile.lock checked in you git repo ensures that you fixed the version of your dependencies for all users. If you want to read more on Podfile.lock and best practices, check CocoaPods blog.

Another usual command you want to get use to is: pod update. You use it when you want to update the dependencies to fetch a newest version of FH SDK, let’s say 3.2.0. To read more about the differences between install and update, delve into this guide.

Open workspace

Last, to start working simply open the workspace:

$ open blank-ios-app.xcworkspace

And run the project on your preferred simulator or device.

Well done, you’ve got your project running on CocoaPods!

The end

This is the end of this blog post: I’m convinced you will love CocoaPods. It’s easy to setup and doesn’t intrude in your work. It’s pretty simple to modify, as well, if you need to add or remove libraries later. Once you start using CocoaPods, you wouldn’t want to go back to managing library dependencies yourself. The same applies to RHMAP and since then, they lived happily ever after.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s