Introduction

CocoaPods is a great tool to help with dependency management when building iOS or OS X applications. Having been around and well supported for years, CocoaPods' maturity is evident. While it's very common to use CocoaPods in your iOS or OS X software projects, it's less common to actually create a pod others to use. This tutorial will walk you through creating your first pod and it will give you some tips on what characterizes a great pod.

1. Install CocoaPods

Obviously, to create a pod, you need to install CocoaPods. It’s available as a Ruby gem fromRubyGems. To install CocoaPods, execute the following commands from the command line:

1

geminstallcocoapods

This tutorial was written against CocoaPods 0.37.2.

2. Step by Step Overview

From a high level, there are five steps involved to create your first pod:

1. Determine the idea for your first pod.
2. Use the pod lib command to create the skeleton directory structure and associated files for your pod.
3. Update the metadata of your pod, such as its license and version information.
4. Add the code for your pod. This includes both the code for the pod itself as well as any code that would be needed for an example project.
5. Make the pod publicly available.

3. Podstorming

Podstorming isn’t actually a word, but it’s time to brainstorm the functionality for your first pod. There are over 10,000 publicly available pods indexed in the official Specs repository. People have found all sorts of things to make available as a pod. Here are some suggestions to help you start podstorming, err, I mean brainstorming:

• Utility Code: Do you have a unique take on how to perform certain string manipulations? Do you have a favorite subclass that you wrote for performing a slick animation on aUIView? Specific utility code like this is a great example of what can be turned into a pod. It’s often already well-factored and decoupled from other existing code bases.
• Third Party Packages: Have you created a wrapper around another third party API? Do you have an app for which you’d like to provide hooks for other apps to integrate with, such as for authentication? Does your company provide a web API for web based resources that would be useful for other iOS apps to easily integrate with? If so, then a pod makes sense since it’s an easy way for other iOS applications to easily integrate with these packages.
• UI Components: Did you create a buttery-smooth UI widget that you’d like other applications to be able to use? These are my favorite pods. It’s great to be able to add a complicated and delightful UI component to an application by simply including a pod dependency.
• Anything that you’d like others to be able to use. Did you create something that you think others would find useful? If so, turn it into a pod so others can easily use it.

This tutorial will walk you through creating a pod that allows you to create aUILabel that blinks. We'll call it BlinkingLabel.

4. Create the Project

Time to dig in. Now that you know the functionality that your pod is going to provide, it’s time to create it. The pod lib command is an important tool that we'll use for two purposes during the creation process.

1. pod lib lint will validate that everything is okay with your pod and that it’s ready to use by CocoaPods.
2. pod lib create will actually help give you a jump start by providing a standard directory structure with a bunch of boilerplate files necessary for a high quality pod. pod lib create isn't the only way to create your pod, but it is the easiest.

Open a Terminal window, navigate to a working directory, and execute the following command:

1

pod lib create BlinkingLabel

• When you're asked what language you want to use, answerSwift.
• When asked if you’d like to include a demo application, answerYes.
• When determining whether to create a sample project or not, theCocoaPods team suggests asking yourself "Should this Pod include a screenshot?" If so, then it’s a good idea to include a sample project.
• When asked which testing framework to use, answerNone.
• AnswerNo to the prompt regarding view based testing.

Testing is outside the scope of this tutorial, but don’t let it stop you from investigating this further after this tutorial. The ratio of tests to lines of code is a factor that is considered by the CocoaPods Quality Index.

When the scaffolding for your pod is set up, Xcode will open your brand new project ready for you to work on your pod.

5. Updating Your Pod's Metadata

There are three main pieces of metadata that need to be included with your pod:

• .podspec: This file describes information about this specific version of your pod. Your pod's, version number, homepage, and author names are some examples of what’s included. Check theofficial reference page for more information.
• README: If you’ve used GitHub before, you know how important a README is. A project’s README, written inMarkdown, is displayed on the homepage of a project on GitHub. A proper README can be the difference between someone using your project or not. Additionally, it’s a factor contributing to a highCocoaPods Quality Index as well.
  
• LICENSE: To have your pod accepted in the Spec repository, your pod needs to include a license. The pod lib create command automatically populates the LICENSE file with theMIT License and that's what we're going to use for this tutorial.
  

To get the.podspec in shape, open it in Xcode. You’ll find it underBlinkingLabel/Podspec Metadata/BlinkingLabel.podspec. Luckily, CocoaPods has created a well populated template for us when we executed the pod lib create command. You’re about to love that tool even more. The pod lib lint command will automatically validate the.podspec file to ensure it complies with best practices. Or, if you’re lazy, you can also use it figure out the bare minimum you need to do to create a proper.podspecfile.

From the command line, in the root of the BlinkingLabel project, execute the following command:

1

pod lib lint BlinkingLabel.podspec

This should output the following:

1

> pod lib lint BlinkingLabel.podspec

2

3

 -> BlinkingLabel(0.1.0)

4

    - WARN  | The summary is not meaningful.

5

    - WARN  | The description is not meaningful.

6

    - WARN  | There was a problem validating the URL https://github.com/<GITHUB_USERNAME>/BlinkingLabel.

7

8

[!] BlinkingLabel did not pass validation.

9

You can use the`--no-clean` option to inspect any issue.

The tool tells you that there are three things that need to be fixed in the.podspec file:

• add more information to the summary
• add a proper description
• specify a URL for the pod's homepage

Here are some suggested values for these fields:

• s.summary: A subclass on UILabel that provides a blink.
• s.description: This CocoaPod provides the ability to use a UILabel that may be started and stopped blinking.
• s.homepage: https://github.com/obuseme/BlinkingLabel (replaceobuseme with your GitHub username)

But wait, if you’ve been following the instructions step by step, technically there isn’t a project at that URL yet. It’s time to push your project to a public repository onGitHub. While there are other options for hosting your pods, GitHub is by far the most common.

To push your project to GitHub, browse to GitHub, login or create an account, and create aNew Repository calledBlinkingLabel. Then, from the command line, execute the following commands:

1

git add.

2

git commit-m “Initial Commit"

3

git remote add origin https://github.com/<GITHUB_USERNAME>/BlinkingLabel.git // replace <GITHUB_USERNAME> with your github.com username

4

git push -u origin master

At this point, if you’ve done everything correctly and lint the.podspec file again, it should pass validation.

1

> pod lib lint BlinkingLabel.podspec

2

3

 -> BlinkingLabel(0.1.0)

4

5

BlinkingLabel passed validation.

6. Adding Code

You now have the basic shell of a pod, but it doesn’t do anything. It’s time to add some functionality. The nifty thing about the sample project that CocoaPods created for you is that you can simultaneously write code for both the pod and the example project.

First, find the fileReplaceMe.swift underPods/Development Pods/BlinkingLabel/Pod/Classes/ and delete it.

Next, create a new Swift file in the same directory and name it BlinkingLabel.swift. Replace the contents of the new file with the following:

1

publicclassBlinkingLabel:UILabel{

2

publicfuncstartBlinking(){

3

letoptions:UIViewAnimationOptions=.Repeat|.Autoreverse

4

UIView.animateWithDuration(0.25,delay:0.0,options:options,animations:{

5

self.alpha=0

6

},completion:nil)

7

}

8

9

publicfuncstopBlinking(){

10

alpha=1

11

layer.removeAllAnimations()

12

}

13

}

You just added functionality to your first pod, a subclass onUILabel. The subclass provides a method to make the label blink and another method to stop it from blinking.

To ensure it’s easy for other developers to understand how to useBlinkingLabel, add some sample code to the example project. OpenBlinkingLabel/Example for BlinkingLabel/ViewController.swift and make it look like this:

1

importUIKit

2

importBlinkingLabel

3

4

classViewController:UIViewController{

5

6

varisBlinking=false

7

letblinkingLabel=BlinkingLabel(frame:CGRectMake(10,20,200,30))

8

9

overridefuncviewDidLoad(){

10

super.viewDidLoad()

11

12

// Setup the BlinkingLabel

13

blinkingLabel.text="I blink!"

14

blinkingLabel.font=UIFont.systemFontOfSize(20)

15

view.addSubview(blinkingLabel)

16

blinkingLabel.startBlinking()

17

isBlinking=true

18

19

// Create a UIButton to toggle the blinking

20

lettoggleButton=UIButton(frame:CGRectMake(10,60,125,30))

21

toggleButton.setTitle("Toggle Blinking",forState:.Normal)

22

toggleButton.setTitleColor(UIColor.redColor(),forState:.Normal)

23

toggleButton.addTarget(self,action:"toggleBlinking",forControlEvents:.TouchUpInside)

24

view.addSubview(toggleButton)

25

}

26

27

functoggleBlinking(){

28

if(isBlinking){

29

blinkingLabel.stopBlinking()

30

}else{

31

blinkingLabel.startBlinking()

32

}

33

isBlinking=!isBlinking

34

}

35

36

}

At this point, you'll see Xcode complaining with a lot of errors in ViewController.swift. This is because the pod forBlinkingLabel isn't installed on the example project yet. To do that, switch to the command line and from the root of theBlinkingLabel directory execute the following command:

1

>cdExample

2

> podinstall

3

Analyzing dependencies

4

Fetching podspecfor`BlinkingLabel` from`../`

5

Downloading dependencies

6

Installing BlinkingLabel 0.1.0(was 0.1.0)

7

Generating Pods project

8

Integrating client project

Next, switch back to Xcode and select theBlinkingLabel-Example target and click the Run button.

You should see something like this:

Tap Toggle Blinking to try out your new pod. The final step in creating your pod is to update the README.md. In Xcode, openREADME.md under BlinkingLabel/Podspec Metadata/README.md. You’ll see that CocoaPods added some default documentation for you. Don’t stop there, you can make it better. Add some documentation about the pod and include a screenshot. Remember that a README is often the first thing that someone will see when looking at your pod. It’s important that it is of high quality. Take a look atmine for some inspiration.

7. Making Your Pod Available

Now that you have a fully functional pod running on your local machine, it’s time to makeBlinkingLabel available to others for inclusion in their projects. At a high level, this is accomplished by getting your new pod into the publicSpecs repository.

TheSpecs repository is the public place on GitHub where all public pods are indexed. You actually aren’t forced to use GitHub to host your pod's source code. You can also use BitBucket for example. Your pod's spec will be stored in the Specs repository on GitHub though.

It’s very simple to have your pod added to the Specs repository. There are three steps involved for submitting your pod. Don’t try these steps as I’ve already made BlinkingLabel public. They are only here to serve as a reference.

As a prerequisite, make sure your local changes to theBlinkingLabel project directory are added to git and pushed to the remote.

Step 1: Tagging

Tag your most recent commit and push it to the remote.

1

> git tag 0.1.0

2

> git push origin 0.1.0

3

Total 0(delta 0), reused 0(delta 0)

4

To https://github.com/obuseme/BlinkingLabel.git

5

*[new tag]         0.1.0 -> 0.1.0

This step indicates that you are marking this commit as a specific release of your pod. The name of the tag should matchs.version in your.podspec file. The next step will validate this.

Step 2: Validation

Next, run the following command from the command line to verify that everything is configured correctly between where your source code is stored and your.podspec file:

1

 pod spec lint BlinkingLabel.podspec

This should output the following:

1

> pod spec lint BlinkingLabel.podspec

2

 -> BlinkingLabel(0.1.0)

3

Analyzed 1 podspec.

4

BlinkingLabel.podspec passed validation.

Step 3: Pushing to Specs Repository

Finally, push the spec to theSpecs repository by executing the following command:

1

pod trunk push BlinkingLabel.podspec

This should output the following:

1

> pod trunk push BlinkingLabel.podspec

2

Updating spec repo`master`

3

4

Validating podspec

5

 -> BlinkingLabel(0.1.0)

6

7

Updating spec repo`master`

8

9

  - Data URL: https://raw.githubusercontent.com/CocoaPods/Specs/f7fb546c4b0f80cab93513fc228b274be6459ad2/Specs/BlinkingLabel/0.1.0/BlinkingLabel.podspec.json

10

  - Log messages:

11

    - June 29th, 20:40: Pushfor`BlinkingLabel 0.1.0' initiated.

12

    - June 29th, 20:40: Push for `BlinkingLabel 0.1.0' has been pushed(1.701885099 s).

8. What Makes a Great Pod?

There are literally thousands of pods available in theSpecs repository. When browsing for a pod, it’s not easy to determine a pod's quality. When bringing in third party code into your project, you want to have a high level of confidence in the code that you will be shipping to customers. Historically, a developer had to make their own interpretation of the quality of a random pod that they found.

As of June 2015, CocoaPods has provided a tool called the Quality Index that provides a summarized judgement on the quality of a given pod based on certain metrics. The comprehensive and most up to date metrics can be found onGitHub.

In summary, here are things that can help improve theQuality Index of your pod:

• project popularity as measured by stars, forks, subscribers, and contributors
• code documentation
• high quality README
• written in Swift
• use of the GPL license
• not many open issues
• code quality ensured through automated tests
• lean install size by minimizing included assets
• smaller, well composed, classes

TheQuality Index of a pod may either go up or down based on how well a given project conforms to these metrics.

Conclusion

Creating pods for others to use is fun and a good way to contribute back to the community. This tutorial has shown you what pieces of code make for good pods, how to create your first pod, how to make it publicly available, and what techniques can make for a great pod.

You now have the knowledge to create your first pod. I’d love to hear what pods you have in mind to build. Please come back and drop a link to your pod once it’s created.