How to Ship a CocoaPod
18 February 2013

How to Ship a CocoaPod

After a long, frustrating day of failing to find a good iOS library for parsing Well-Known-Text (WKT), we gave up and decided to write something. If WKT strings are what you are getting, you can parse geometries from the coordinate data there to draw polygons on a MKMapView. In fact, WKT can define 18 different geometric objects, but we were only dealing with polygons and multi-polygons, and only exterior ones at that. MooreChris and I spiked on it late one day. Over the next two nights I put together a WKTParser class that takes a string of WKT, and spits out arrays of MKPolygons, making use a lot of Peter’s existing coordinate generating code.

It seemed obvious that we should share this, since we went through so much pain to find something and came up empty-handed. We love CocoaPods so it seemed like a great opportunity to contribute something.

I began looking at a few existing repos to get a feel for how to organize the code into a CocoaPod library. Judging by the variety of what I saw, the first lesson was, perhaps there’s no right way to do it. What matters is that your CocoaPods .podspec can find the core files and classes it needs to install. CocoaPods docs suggest creating publicly accessible directory named “Classes” for this, but it seemed that most libraries put their core files in a top- level folder having the same name as the repo. Although technically this collection of core files is all that is needed to install a CocoaPod, the core files most often exists inside of a larger repository. That repository usually includes a sample application that demonstrates the functionality of the library, or serves as a basis for running the library’s tests against.

WKTParser was no exception. Even though I was only shipping one class, WKTParser needed an AppDelegate to run my Kiwi specs against. I landed on this structure for the library.


I created an empty iOS application named WKTParserExample, in xCode. WKTParserExample is the also the group / directory where the AppDelegate would be generated and the sample project would be created. I Installed Kiwi, using CocoaPods. And I worked my specs into WKTParserTest/ and my core classes into WKTParser/. Getting the directory structure on the filesystem in line with the project references in xCode is still a bit confusing to me. I landed on a pattern of creating and organizing the files on the filesystem, and then dragging them into the xCode project navigator from Finder. After setting up and configuring my test target, specs were passing, I pushed it up to github, and I was ready to take the next step.

How do you make a public repo a CocoaPod? It’s pretty painless, you publish a .podspec file. It only needs to be publicly accessible, the top level of your library’s github repo is a fine place to put this. Consumers of your library can simply point to this public .podspec in their Podfile to install your code. If you’re generally unfamiliar with CocoaPods, see MooreChris’ earlier article, CocoaPods and You: A Primer for the Uninformed.

After installing CocoaPods on your machine, you can run pod spec create ProjectName to generate a ProjectName.podspec file. In the .podspec you set configurations that tell CocoaPods where to fetch the project, where the important source files are, what the license is, and dependencies that should be installed. The commented contents of the generated file will lead you through this. The only other trick is that you’ll need to version your repo with git tag and set that version number in the .podspec config as well. You’ll make a couple gaffs. Run pod spec lint ProjectName.podspec and correct any reported issues.

That’s it! Find a project you want to integrate your classes into, and put a line for your library in the Podfile, pointing to your publicly accessible .podspec.

pod 'WKTParser', :podspec => ""

Run pod install and watch CocoaPods install your library!

Enjoy, and in the meantime, submit your podspec to the canonical github repo. You’ll need to make sure it lints without issue. When it’s accepted, consumers of your CocoaPod will no longer need to specify the :podspec location, only the name.

Happy publishing!

Heads up! This article may make reference to the Gaslight team—that's still us! We go by Launch Scout now, this article was just written before we re-introduced ourselves. Find out more here.

Related Posts

Want to learn more about the work we do?

Explore our work

Ready to start your software journey with us?

Contact Us