Cocoapods Handbook
In your life of a developer, you certainly have already dealt(or at least tried to deal) with the so famous Cocoapods. Cocoapods are the most used dependencies manager, which you can use to import a lot of third party features from other developers or even companies. For who just use that for enjoying other people's work, it is just a piece of cake, since you just need to edit a Podfile and know which frameworks and versions you shall get. After that, you tap pod install in your terminal and ta dá! Everything you need is up to use.
Unfortunately, creating a Cocoapod and sharing your own work is not trivial as importing from other sources. For most of my time as a developer, I relied on third-party frameworks and had never tried to develop one by myself, but when i started working on a large bank, whose apps work around several features, each one contained in a pod, it showed me I should go deeper in this topic.
This article was written based in all my experience developing banking pods, covering since the Cocoapod project creation until uploading it to cocoapods.org. I hope you enjoy!
Where do I start?
This is the first question you must be asking yourself right now. Well, the first thing you need to know, although this is obvious, is that you are not creating an iOS app, but a Cocoapod, or better saying, a framework that apps will consume as a dependency. So, we are trying a different template from the usual. There are two major ways to start your new pod: by terminal or through an Xcode preset template. I prefer the first one, but it is important to show the entire world to you.
I)Xcode
So, this is the easiest way to just create a cocoapod template project and a lot similar to creating a single view application. Open your Xcode, and tap on "Create new Xcode project". You can see multiple templates, but we are interested in a particular one: Cocoatouch Framework
II) By terminal
You may also create your own cocoapod by typing some lines of code in your Mac OS terminal, just type the following line bellow in your terminal and see the magic happening:
pod lib create MyOwnCocoapod
Now, your terminal will ask you some brief questions about how do you want to code your pod:
1)Language: Swift /Objc?
I expect you are learning with Swift, so, in this case, you must answer with ”swift”
2) PlatformOS/ MacOs?
Since we are developing a cocoapod for iOS projects, just type "ios”
3)Would you like to include a demo application? [Yes/ no]
You need an application to test your library working as a client since it doesn’t work by itself. You can always create a separated iOS project for that, but for simplicity, we are going to create a demo application. So, type ”yes".
4) Which testing framework would you like to use? [Quick / none]
That is totally up to you, if want to use Quick as a testing framework in your pod, just type the first option, but as long as i will not cover unit tests in this tutorial, i will choose ”none”.
5) Would you like to do view based testing? [Yes/ no]
If you want to view test, type ”yes”.
Now, if you followed all the steps correctly, your pod library was successfully created.
You may see your Xcode project like this:
As you can see above, the project is already almost completely setup to you. There are two main components in your project: your cocoapod, which is inside the Pods folder, which was already "pod installed" after its creation. If you go under Development Pods folder, you can see all the files and folders which are important for your library. You can see a Pods subfolder that holds a LICENSE, a READ.ME and a podspec file, which we will cover soon. The template also created a default swift file on MyOwnCocoapod file, which works as a simple default file to represent where all the classes must be placed.
Your Xcode project also counts with a sample project that works as a client to your pod. This is made for avoiding creating a new app to install your pod and doing all the setup. To test your pod while coding, just deal with the project inside Example for MyOwnCocoapod as a real app and use your library there. If you run your project, it will run the example project.
Now that we have explained about the files structure, it's time to tell about a new file that you may no be familiarized with.
Podspec
The podspec file can be found either inside your Pod files or in the Podspec Metadata folder in the root. If you take a look on it, you will see that it has the same syntax of the Podfile. They are both written in Ruby. The Podspec keeps all the important metadata about your project, which Cocoapods.org will use as a reference when publishing, and your client project will need. It saves information like the Swift version, the iOS system, remote repository, and more. Now let's take a brief introduction and check what does each field mean.
Podspec defines an instance s, which has a lot of fields saving the metadata about your pod. We will cover the meaning of the most important ones:
s.name = "MyOwnCocoapod"
The name of your pod that will be added to Cocoapods.org and installed in your client
s.version = "0.1.0"
It is very important for your client to know which version of your cocoapod it's going to install. By default, it installs the most recent version of it
s.summary = "Just a simple cocoapod"
A really brief description of your pod that will be placed in its head
s.description = "…."
This is where everything you want to tell about how your pod works and what it's supposed to do must be placed. Here is where the user will check about what exactly is your cocoapod. For example:
It is important to tell you that the description must be bigger than the summary, even when it is very simple. If it isn't, you will get a warning.
s.homepage = { :git => "https://github.com/user/MyNewCocoapod.git", : tag => s.version.to_s
The url to your repository git. It is essential that you push your cocoapod on a remote repository, since Cocoapods.org needs a reference to your code.
s.source_files = "MyOwnCocoapod/Classes/**/*"
This is the most important atribute in our list, t he path where all of our pod swift files will be fo und in Finder. You may have already noticed that a file's path is different considering Xcode and Finder. You find ReplaceMe.swift in Development Pods/MyOwnCocoapod path in Xcode, but in Finder it is found inside a Classes folder. You must place the relative path in Finder.
Pod Lint
If you want to publish your library in Cocoapods.org, you must verify your project data is ready to be read and interpreted. Run pod lib lint to check your podspec's integrity:
As you can see, we got three warnings, one of them complaining about our summary, and the other one saying that we didn't provide a remote repository to our pod. It is very important to run this command before publishing our pod. Just remembering, create a remote repository in github and make it public, in order to be found by cocoapods.org.
Pod install
You may have noticed that our Xcode project has a Podfile and you are figuring that it will take all the dependencies for our pod. I must tell that you are completely wrong. That Podfile is referring our sample project and all the pods it will install:
Don't you think it weird for a pod to install itself? Well, don't worry, it is installing your pod with the path relative to the sample project. It is important to mention that all the installed pods are being referred by our sample project. Our pod doesn't install anything. But pay attention, there may be libraries that our pod will use, but for that, it's mandatory for our client project to have them installed. In this case, those pods are not mentioned in the sample's podfile, but in the cocoapod's podspec:
When you "pod install" your client project, it will check the podspec and see all the libraries that pod relies, and then, install them together.
Common Error: Files vanishing!
A very head-sicking error I got when I built my first pods was that when I did "pod install" my sample project, most of of my files and folders inside my pod just disappeared. I got very angry with that because I didn't understand why it was happening since I placed them right inside the correct target and everything. The answer for that was: I wasn't placing them in the correct path since I was creating them in Xcode. Well, I strongly recommend keeping the root of your pod just with folders and place the files into them.
Let's create a new folder called "Common" directly in Finder:
Now, just drag the folder to Xcode right above MyOwnCocoapod:
Now that Common is in the correct path, you can run pod install that it will stay in Xcode.
Calling our pod
Now that we created a new file in our cocoapod, let's create a client application in another path. Create a new iOS project in Xcode and call it MyOwnClient. Run pod init, and them open its xcworkspace.
There are two ways to reference our pod in without having it published in cocoapods.org: By local path or through an Xcode repository.
If you desire to reference it locally in your machine, place the path as an atribute right after the pod:
If you have a repository on github, you just need to reference its URL and the branch you want to install:
Now, you can pod install your library and with an "import" statement everything that is declared public in your pod is accessible. It is important to remember that just classes declared as public are accessible in your client.
Publishing in cocoapods.org
If you desire to push your new pod to cocoapods.org, there are a few steps to be followed before:
- Run pod lib lint to check if all the metadata is ok
- Create a new version of your pod by running:
git add -A && git commit -m "release"
git tag '0.0.1'
git push — tags
3. Run:
pod trunk push MyOwnCocoapod.podspec
Later, your pod may be found in Cocoapods.org.
Conclusion
We have covered a brief tutorial about how a cocoapod is created, the most common issues we face and how can we publish that in cocoapods.org. If you create a very useful feature that may work with other developers, why not sharing to the world? It is very important for mobile developers to keep helping each other with their own code solutions.
I hope you enjoyed, and I see you in the next article ;)
