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 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. 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:

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.

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 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 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!




8 thoughts on “Cocoapods: Creating and Sharing Your First Objective-C Open Source Project

  1. Pingback: CDSParticleFilter CocoaPod is now available ¶ Code, Politics, & Beer

  2. Viet Hung

    Thank you very much! I’m looking for how CocoapodsSpecs know my podspec file. Your post is very useful. Thanks again!

    Reply
  3. Nathan Rowe

    Great tutorial. I needed the steps starting from the fork CocoaPods section. This has taken me way too long to figure out and I wish I found this tutorial when I first started. Many thanks!

    Reply
  4. Pingback: CocoaPods: How To | AyeOhYes!

  5. Parth Patel

    hi, I done all steps you mention in this tutorials but i stuck when i reach your step “Fork Cocoapods/Specs”. When i go to this link “http://github.com/CocoaPods/Specs” and select fork it show me warning and that is “Failed to load latest commit information.” so what can i do for that?? And i am also totally stuck in your step “Add your podspec to the Specs repo” to the last step so can you understand me what i do for that. I upload my demo project to github but i am not able to create my own pod so help me.

    Reply
  6. Abhishek Thapliyal

    Hi , i’m unable to push my lproj folders and storyboard. i’m creating cocoapod of a framework and need to push all the things in pods. How it will be possible?

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *