Cocoapods: Creating and Sharing Your First Objective-C Open Source Project

This took me way too long to figure out, so I thought that I would write up some instructions, should I need to do this all again!

There are plenty of tutorials related to adding [Cocoapods](http://cocoapods.org) to your Xcode project, but there is scant documentation on how to share a library of your own. You’ll need to create a podspec, but you’ll also need a repository to take it.

This tutorial works from a blank project – you may already have a project setup for your library development, but you should be able to figure out the specifics needed.

### Create a Github Repository

The first thing you need is to create a repository (‘repo’) on [Github](http://github.com). Sign up there if you need to, then choose the ‘Create a Repo’ option. You’ll be prompted for

* The repo name (required)
* A short description (optional)
* Checkbox for inclusion of README.md (do this if one doesn’t already exist in your local folder)
* Dropdown to choose `.gitignore` default for your project (select Objective-C if you don’t already have one if your local folder)
* Dropdown to choose a licence type (I chose the MIT licence)

Create the repo.

### Establish the local repository

If you already have an existing project you are working from for the shared library, then chances are you already have a local repo established, but if not:

* Switch to your project folder
* `git init`

### Connect your local repo to the remote

Now you need to connect your local repo to the remote repo on Github:

* `git remote add origin https://github.com/YOURNAME/YOURPROJECT.git`

Use your Github user name and the the name of the repo that you specified earlier in the previous command.

### Pull the Remote to Sync Repos

* `git pull origin master`

You will now have pulled down the `LICENCE`, `README.md` and `.gitignore` files from the remote repository.

### Create a Podspec

The heart of sharing a library via Cocoapods is to create a Podspec. Create a new file in the root project folder named `YOURPROJECT.podspec`, load it into an editor and start with the following template:

#!ruby
Pod::Spec.new do |s|

s.name = ‘YOURPROJECT’
s.version = ‘0.0.1’
s.summary = ‘Description of your project’
s.homepage = ‘https://github.com/YOURNAME/YOURPROJECT’
s.license = {
:type => ‘MIT’,
:file => ‘LICENSE’
}
s.author = {
‘YOURNAME’ => ‘YOUREMAILADDRESS’
}
s.source = {
:git => ‘https://github.com/YOURNAME/YOURPROJECT.git’,
:tag => s.version.to_s
}
s.source_files = ‘YOURPROJECT/*.{m,h}’, ‘AnotherFolder/*.{m,h}’
s.requires_arc = true

end

* `s.name` establishes the name of your project as it will appear in the Cocoapods list of projects, so should match the Github repo name.
* `s.version` is a string that defines the current version
* `s.summary` is a description, again for the Cocoapods list
* `s.homepage` is the URL of the projects homepage, and can be the Github repo main page if you don’t have a specific website elsewhere
* `s.license` establishes the licence type and should match what you specified when creating the Github repo.
* `s.author` is an array of author names and contain email addresses
* `s.source` is the Github repo address (note the `.git` ending) and the repo tag that is used to locate the version number.
* `s.source_files` establishes which files in your project should be included in the Cocoapod. Its worth ensuring that your Xcode project is setup so that all source files are under a common sub folder, but new Xcode projects do this for you (`YourProject` and `YourProjectTests` by default). You will probably only need one value, not the multiples shown above (for illustration).
* `s.requires_arc` tells Cocoapods whether your source needs Automatic Reference Counting.

There are plenty of other [options available in the Cocoapods documentation](http://docs.cocoapods.org/specification.html).

### Syntax Check your Podspec

You need to ensure that your podspec is valid, so at the command line:

* `pod spec lint .`

You’ll receive warnings or errors to resolve if any are encountered. Note that you cannot publish Cocoapods whilst there are warnings or errors, so get this right now.

### Create a Podfile

If your library depends on other Cocoapods, you’ve probably already got a `Podfile` in your project folder. Dependancies for the actual library code will need to be moved to the `dependency` directive in the `podspec`. You can then remove them from your existing `Podfile` and instead use the `podspec` directive in the `Podfile` to indicate that the project should use the dependancies outlined in the `podspec`.

I use [Kiwi unit testing](http://github.com/allending/kiwi) in my project, so my Podfile needs to establish what I’m working from.

platform :ios, ‘5.0’

podspec

target :YOURPROJECTTests, :exclusive => true do

pod ‘Kiwi’

end

The above `Podfile` establishes that the target is iOS 5.0 or later (required by Kiwi), and to use any dependencies defined in the `podspec` located in the same folder. It then establishes that the Kiwi pod should be used only on the Unit Testing Target.

* Setup the Pods with `pod install` (or `pod update` if you’d previous done an install)

### Push the Changes Back to the Remote

Once you are happy that the podspec is correct and the project is building again, you can commit and push your changes back to the Github remote repo.

* `git add .` will add any new files to the local repo (your `.gitignore` might need revisions to exclude things you don’t need)
* `git commit` will commit your changes to the current branch (vi will open to allow you to add a commit message)
* `git push origin master` will merge your changes with the remote repo

### Code!

You can now work on your library until you are ready to release it to the world.

### Tag and Release

Cocoapods relies on tags in order to locate appropriate versions of your library. When your have your code in a state for release:

* Commit the final code changes.
* Edit your `podspec` to increment the `s.version` directive to the new release version number.
* Commit the pod spec revision
* Tag the release – `git tag 1.0.0`
* Push the changes to the remote – `git push origin master`

### Fork Cocoapods/Specs

In order to publish your Cocoapods project, you need to add your `podspec` to the [Cocoapods/Specs](http://github.com/cocoapods/specs) repository. In order to do this, you need to create your own working copy of the repo (a fork), make the amendments that follow, and then issue a Pull Request so that the maintainers can pull in your changes.

On Github:

* Go to `http://github.com/CocoaPods/Specs` and then choose ‘Fork’ – this will create your own fork of the repo (at github.com/YOURNAME/Specs)

On your computer:

* Create a local clone of your Specs fork (outside of your library project folder – I created a `Cocoapods` folder in my normal dev folder, then switched into this folder before cloning)
* `git clone https://github.com/YOURNAME/Specs.git` will create a local copy of your fork.

### Add your `podspec` to the Specs repo

The Specs repo is organised in a hierarchy along the lines of `YOURPROJECT/VERSION/YOURPROJECT.podspec`, so

* Create a new top level folder named after your project.
* A subfolder named after the current version number.
* Copy your `YOURPROJECT.podspec` file from your working folder to this version numbered directory.

Make sure that you have staged the new files and committed them:

* `git add .`
* `git commit`

Then push the changes back to your Github fork:

* `git push origin master` (from the Cocoapods/Specs folder, not your project)

### Create a Pull Request

Now you need to let the Cocoapods maintainers know that you have some changes for them, so on Github, you need to issue a Pull Request.

* Go to your Specs repo on Github
* Click on ‘Pull Request’
* Github will show a page outlining the changes
* Click on the ‘Create a pull request for this comparison’ link and in the box provided, add a subject and message to let them know what you’ve changed.

### Bask in Glory

That’s about it, now you can bask in the glory (or the flames) that result from other people incorporating your work into theirs!