Getting started with CocoaPods
If you’ve ever worked on a large project that used several 3rd party libraries, you’ve probably run into what programmers lovingly refer to as “dependency hell” – the painstaking task of getting the right version of each 3rd party library installed and configured correctly, and then later keeping those libraries up to date.
CocoaPods is a dependency manager for open-source libraries used in Objective-C (i.e. OS X and iOS) projects. It is incredibly easy to use and wildly popular in the Objective-C open-source community.
If you’ve created an open-source component or library for Objective-C, or plan to create one, I highly recommend registering it with CocoaPods so others can easily find and incorporate your component into their projects.
I recently open-sourced a simple iOS component I’d written called NTMonthYearPicker that allows users to pick a month / year in your application (surprisingly, this functionality is not available in the core iOS API). It took me a little while to figure out how to register this component with CocoaPods, and I felt that most of the articles I found on the net were not quite at the “dummies level” that I prefer, so I decided to write a simpler guide of my own.
1. Install CocoaPods
CocoaPods is distributed as a ruby gem, so use the gem command to get it installed on your system.
|
1 2 |
sudo gem install cocoapods pod setup |
2. Create a pod spec file
Information about your component, or “pod”, is captured in a spec file. The CocoaPod framework uses this spec file to get the name of your component, the version, the target platform, where to download your component from, etc.
Copy and paste the following into a file named MyComponent.spec.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
Pod::Spec.new do |s| s.name = 'MyComponent' s.version = '1.0.0' s.summary = 'A component for displaying cat pictures in your app.' s.description = 'MyComponent is a component for displaying amazing cat pictures in your iOS application.' s.homepage = 'https://github.com/myusername/MyComponent' s.license = 'MIT' s.author = { 'President Camacho' => 'myusername@gmail.com' } s.platform = :iOS s.source = { :git => 'https://github.com/myusername/MyComponent.git', :tag => s.version.to_s } s.source_files = 'MyComponent/*.{h,m}' s.requires_arc = true end |
3. Adjust your spec file
Edit the spec file and update the relevant attributes – most are self-explanatory. Notes on a couple of them:
- version: for version numbers, it is recommended that you use semantic versioning, i.e. of the form x.y.z
- homepage: doesn’t of course have to be the GitHub page for your component. If you hosted it someplace else, link to that. If you have a blog post describing your component, link to your post.
- source: again, doesn’t have to be GitHub, but must be a Git, Mercurial or Subversion repository.
- source_files: ensure that all relevant source files from your component are captured here
You may wish to add more attributes to your spec file. The spec file format is documented here, but a better way to get documentation is to simply run the spec create command, which creates a template pod spec file with excellent documentation within the file itself:
|
1 |
pod spec create MyComponent |
4. Validate your spec file
Once you’re done adjusting the spec file, run the spec lint command to ensure that there aren’t any syntax errors, etc:
|
1 |
pod spec lint MyComponent.podspec |
5. Test your spec file
If your spec file passes the lint command, you’re good to go and can submit your spec file to the CocoaPods master list. I would however recommend that you create a simple test project and quickly test out your spec.
Create a test project in Xcode. Go to the project folder of the test project you just created, and in there create a file called Podfile with the following content, adjusting the path to point to your spec file:
|
1 2 |
platform :ios pod 'MyComponent', :podspec => '/path/to/MyComponent.podspec' |
Now run the following command to install your pod:
|
1 |
pod install |
As instructed by the command, close your project in Xcode and instead open the workspace (xcworkspace) file in the same project folder. Verify that the MyComponent source files have been imported correctly. Try using the component in your test project if you want to be doubly sure that everything works.
6. Register your pod
So you have your pod and the associated spec ready. Now you need to register your pod with the “master spec list” so other people can find and install it.
The master spec list is maintained on GitHub at CocoaPods/Specs. Since you likely do not have “push” (i.e. write) permissions to this repository, you need to create a fork (i.e. your own copy) of the repository, make your changes there, then create a pull (i.e. merge) request so someone who does have write permissions can “pull in” the changes you made back into the main repository.
To fork the main repository, visit the CocoaPods/Specs GitHub page and click on the “Fork” button. (Note that to do this, you need a GitHub account.) Once the fork is complete, run the following commands:
|
1 2 3 4 5 6 7 |
git clone https://github.com/myusername/Specs.git cd Specs mkdir -p MyComponent/1.0.0 cp /path/to/MyComponent.podspec MyComponent/1.0.0 git add MyComponent git commit -m "Added podspec for MyComponent 1.0.0" git push origin master |
Your spec has now been added to your forked copy of the repository. Initiate a pull request by visiting your forked repository’s GitHub page, clicking on Pull requests, then clicking on New pull request.
GitHub should show a diff highlighting the addition your new spec file. Click on Click to create a pull request for this comparison. Add a title (e.g. Added MyComponent 1.0.0) and if you wish, a brief description of your changes, then submit the request.
You now need to wait for a CocoaPods maintainer to merge in your changes. For my component, this was completed in just a couple of hours.
7. Check that your pod is available
Run the following commands to check that your component is available via CocoaPods:
|
1 2 |
pod repo update pod search MyComponent |
The output should show some information about your component.
8. All done!
Congrats, your first library is now available via CocoaPods!