Create and Distribute Private Libraries with Cocoapods

Hey Guys,

In this post I’m going to show you how to develop and distribute in-house private code libraries using Cocoapods. Cocoapods by the way is an excellent tool for managing third party dependencies in a project. It not only provides a way for easily integrating those dependencies but also allows you create your own dependencies and manage them as well. And best of all, you can it to simplify code sharing inside your organization. This is known as a private pod and is described in great detail on the cocoapods site.

In this blog I’m going to show you a simpler way to create a private pod, which will be easier to understand for beginners as well.

The most important thing you should keep in mind while creating a private pod is that it requires the creation of two repositories. One repository is for the code or classes you want to share (which we call the ‘Pod’) and the other is the ‘Podspec’ repository which includes all the information about that Pod. The Podspec repository needs to be created once for all the pods you create, but the pod repository is a separate repository for each branch of code you want to reuse and share with your team.

Having said that, the first step we need to perform is to create these repositories. Let’s jump right to it.

Step 1: Create your Podspec Repository on Github

First of all, you need to create the private ‘Podspec’ repository. For this you need to create a repository in Github first. To do so:

• Go to Github
• Create new repo
• Select the private option and name your spec repository. In this case we have created a repository named folio3-specs in Github.)
• Now run the following commands

echo “# folio3-specs” >> README.md
git init
git add README.md
git commit -m “first commit”
git remote add origin https://github.com/shahabejaz/folio3-specs.git
git push -u origin master

The above created repository does not hold anything yet other than a Readme.md file. We will address this later when we create our first pod.

Step 2: Add your Private Repository to your CocoaPods Installation

Once you’re done with creating a spec repository in Github, you only need to run the following command in the terminal to add your private repository to the cocoapods installation.

pod repo add [REPO_NAME] [SOURCE_URL]

In the above code snippet REPO_NAME is the name you will use to reference the ‘PodSpec’ repo and SOURCE_URL is the Github url of the repository you just have created. In this case our repository name is folio3-specs and the source URL is the Github URL of that repository.

If everything worked correctly then you should be able to link your spec repository by running the following commands.

cd ~/.cocoapods/repos/REPO_NAME
pod repo lint .

Now that our podspec repository is ready, we can move forward and create our second private repository which is our Pod repo. This repository will hold the code you want to share within the organization.

Step 3: Create your Pod Repository on Github

First we’ll need to create an empty Github repository as specified in Step 1 above, only now, we’ll give it the name of the pod we want to share. So we’ll name the repository FLCommonLibrary. This is basically a repository that holds a bunch of utilities and categories that are used in different projects across the organization.

Step 4: Generate the Pod Project

CocoaPods provides a nice utility to help you setup your Pod project along with a test app and testing framework. So to generate your Pod project, just run the following command while standing at your empty github repo directory.

pod lib create [POD_NAME]

where [POD_NAME] is the name of the pod you’re creating and want to share with fellow developers in your organization.

After running the above specified command you will be prompted by an interactive script to select various options for your new Pod project. After selecting those options (as shown below) cocoapod will run ‘pod install’ on the sample project we’ve just created.

The end result will be an XCode workspace that is setup for you to commence Pod development. If you already have some source files to add to the project, you can copy them into the Pod/Classes folder that has been created for you. You’ll also find that a default test app has been created for you where you can write unit tests and view tests for your Pod.

After the completion of this command the .workspace project will open up automatically. If it does not, open the .workspace file in the sample project. You will see a ReplaceMe.m file in the pod target as shown below.

This is the location where you will put the files [.h,.m] that you want to share with your pod. You will also see the Podspec Metadata folder as well. Next, we need to edit the podspec file.

Step 5: Edit the Podspec File

Open the newly generated podspec file. Thankfully Cocoapod has generated a well completed pod spec template for us.

A Podspec file, or Spec, describes a version of a Pod library. It includes details about where the source files are located, which files to use, the build settings to apply, dependencies, frameworks used and other general metadata such as the name, version and description for the Pod.

Below is an example of a Podspec generated by cocoapod for our private pod:

Now, open up the terminal again and go to the folder where the .podspec file is located and run the following command without changing anything in the .podspec file.

pod lib lint FLCommonLibrary.podspec

When you do that, you might see the following output.

If you do, it means that something’s wrong with our podspec file. So we’ll need to resolve those issues. To do so, we need to do the following.

• Specify the proper summary of our pod
• Add some description
• Replace the <GITHUB_USERNAME> with our Github’s username

After making these changes, run the pod lib lint FLCommonLibrary.podspec again.

Tip: You should also specify the Github username for the s.source field otherwise it will generate errors later on when you push this podspec to your spec repo.

This time you’ll see that the command is successful, as you can see in the screenshot below.

Now, we’re good to go with the podspec file and our pod is ready to have some shareable files added to it. So we’ll do exactly that.

Step 6: Add Code in your Pod

Since we have created some reusable utility classes and extensions which we want to share with our team, we will drag and drop these files in the folder (as depicted below).

Now we want to test these files in the sample project we created. For this we will run the pod install command on our sample project. This will install these files in the sample project’s Pod file. You can include these files in the sample project by using the following command.

<FLCommonLibrary/[FILE_NAME_HERE.h]>.

After testing in the sample project, you are ready to push the pod project and share it with fellow developers in your organization.

Note: Remove the ReplaceMe.m file, it’s of no use any more.

Step 7: Push your Pod in the Specs Repo

Now that you’ve built and tested your Pod, it’s time to deploy it to your private Podspec repository. The first thing you need to do, in order to do this, is tag your Pod’s Git repo.

Step 7a: Tagging

First we will update the pod version in the .podspec file to 1.0.1 and will commit the changes on Github. You can change it to any version that is suitable to you but make sure that it is the same version as your Git tag version.

Now we will tag the code on Github by running following command on our repo from the terminal.

git tag ‘1.0.1’
git push --tags

Step 7b: Push to Spec Repo

After pushing the tag to the pod repo, you need to push this pod to your private spec repo which you created in the first step. To do that, run the following command to send the library your private Podspec repo.

pod repo push [REPO_NAME] [POD_NAME].podspec

In this case, folio3-specs is the repo_name and FLCommonLibrary is the pod_name of our pod. So you should specify (substitute) these names in above code snippet.

Tip: Before running this command you should run the pod spec lint FLCommonLibrary.podspec to validate that your spec is correct.

Now you can see that this pod repo is referenced in your spec repo (as shown below).

Step 8: Share It with Your Team

If you want other members of your development team to be able to use this pod then they should have access to the spec repo, and they must add the private repo to their local Cocoapods installation with the command:

pod repo add [REPO_NAME] [SOURCE_URL]

They also need to specify the source URL of the spec repo at the top of the pod file, so that cocoapods knows where to find the installation of your pod (as shown below).

Congratulations! You have just published your first private Pod with your team. You can now leverage the benefits of reusable code in your internal iOS projects using the power of cocoapods.

Tip: You can get the latest updates in cocoapods by following them on twitter:https://twitter.com/cocoapods

Happy coding and keep sharing :)