Tutorial

The Complete Guide to Creating Your Own CocoaPods in Swift


CocoaPods is a dependency manager for Xcode projects. It is an extremely useful service to add libraries and frameworks to your project.

Sometimes one makes a library so game-changing and revolutionary that it is impossible not to let the world have it. Long story short, you need to know how to publish your own CocoaPod!

Prerequisites

In this tutorial, I will be using Xcode 8 along with Swift 3. To learn more about the changes to Swift 3, read this helpful tutorial.

Currently, CocoaPods has a pre-release intended for Swift 3 and Xcode 8. To compile a Swift 3 project, you need to use this version. To install it, run the following command in your Terminal:

You must also have some experience using CocoaPods. Check out this truly amazing tutorial by Gregg Mojica to learn more about it.

On to the tutorial!

Making Something Pod-Worthy

Let’s make something groundbreaking that’s worthy of a pod. I think I want a UIView that slowly changes its color. I believe this might be useful for backgrounds.

Okay, let’s begin with the basic stuff. First, create a new Xcode project and select to use the single view template. Name the project FantasticView. Once the project is created, add a new Swift file named FantasticView.swift.

fantasticview-project

Now that you have added FantasticView.swift, define a class called FantasticView and inherit UIView:

Defining the initializers

Next, add two initializers for the class:

The first initializer is the init(frame: CGRect) method. This method will be called when a frame is passed to the constructor of FantasticView. We will call our color changing function here.

The Majestic Colors

Next, define an array called colors where we contain UIColors. In our main code, we will “loop” through this array and changed the background color of the UIView.

You should also add a counter object that will count each time the color has changed:

But why do I need a counter? Aren’t we looping through the colors?

Notice how I said “loop” 🙂

The Magic Sauce

Now I’m going to tell you how I dealt the problem of looping through the colors.

You might think one way could be to set a bunch of colors in a UIView animation block. However, this won’t work because the final color will always be the one that takes effect.

One way would be to create a for-loop and run an animation block in it. This will also encounter the former problem. To fix this, you could use GCD to wait for the animation block to finish running.

But I believe there is a simpler way. You could use an NSTimer!

In your init(frame: CGRect) method, add the following code:

Let’s go through the above code line by line:

  1. Create a Timer object, formerly NSTimer. Schedule a timer with an interval and tell it to repeat the actions. After the set time interval, our Timer will run a code block.

  2. Call the good old animate(withDuration) function.

  3. Set the UIView.layer.backgroundColor. Note that I didn’t animate the UIView.backgroundColor because the layer property is animatable, not the UIView property.

  4. Add 1 to our counter.

  5. Fire up the timer.

Let’s see what I did in #3. By subscripting colors you will get a UIColor. The colorCounter should only be a number between 0 and 5 because that is the range of our colors array. I used the % or the mod operator to get the remainder of our colorCounter when divided by 6. So if our colorCounter is 10, the output will be 4, therefore selecting the 4th option on our colors array.

Using the Fantastic View

Now it’s time to use our Fantastic View in our main View Controller. I want the background of my View Controller to be Fantastic, so insert the following code in the viewDidLoad method of ViewController.swift:

Here we define a FantasticView and let the frame be the ViewController‘s view bounds. Then add the fantasticView as a subview to the main view.

It’s time to run the app in the simulator. You’ll see the background color changes over time.

fantasticview-demo

Pushing to GitHub

I’m sure you are asking: “Why isn’t this fantastic view out in the public? People should know about this!”

Yes, that’s right. Let’s create the Pod so people could use it! But before that, we need to push this to GitHub.

CocoaPods needs a source for the Pod. In most cases, developers use GitHub for this. I will quickly go through the necessary steps to push your project to GitHub. To learn more about the basics of Git, check out this great tutorial.

In brief, here is what you need to do:

  1. Create a repository on Github. Call it FantasticView.
  2. Copy the URL to your repo.

  3. In Terminal, navigate to your project.

  4. Initialize Git: git init

  5. Add the changes: git add .

  6. Commit the changes: git commit -m "init"

  7. Add a remote origin: git remote add origin <paste your URL here>

  8. Push your commit: git push -u origin master

Now you must create a release for your repository. A release is a new version of your product. You can create one in your GitHub dashboard. Navigate to your repository on GitHub.

  1. Click the releases button.
  2. github-cocoapods-1
  3. Click Create a new release.
  4. github-cocoapods-2
  5. Set the version number to 0.1.0, then set a title and description for the release.
  6. github-cocoapods-3
  7. Click Publish release and you should get something like this:
  8. github-cocoapods-4

That’s it with GitHub, let’s create the Pod itself!

Creating the Pod

First, we need to make sure that you have CocoaPods installed and ready to use in your Terminal. Open your Terminal and run the following command:

Now that CocoaPods is installed, you should be set to create your own Pod.

Creating a Podspec

All Pods have a podspec file. A podspec, as its name suggests, defines the specifications of the Pod! Now let’s make one:

  1. To create a Podspec, navigate to your project file in the Terminal.
  2. Run the following command to create the file: touch FantasticView.podspec.

  3. Now open the file using an editor.

  4. Paste the following code inside the Podspec:

These variables that come after the s are all required by CocoaPods and supply the necessary information such as the name, version, summary, description, source, source files, etc.

Some important variables that require attention:

  1. s.name – This one is obvious. It is the name that others can use to add the Pod to their project.
  2. s.version – This is the version of your Pod. Notice that this is equal to the version number of our GitHub release. If this version number doesn’t match the GitHub release, you will encounter an error.

  3. s.summary and s.description – These two will be displayed on the CocoaPods website. Make sure that the description is longer than the summary otherwise you will encounter a warning.

  4. s.homepage – it is the source URL for the Pod. Make sure to replace YOUR GITHUB USERNAME with your username.

  5. s.author – this is where the developer’s info goes. Replace the corresponding placeholders.

  6. s.source_files – This is the most important parameter. It tells CocoaPods which files you need to clone. I want my FantasticView.swift file to be cloned, and the directory for that file is FantasticView/FantasticView.swift. There are ways to add more than one file as a source. Let’s look at an example:

In this example, I want to include all the .swift files. To do this I will assign the following to the source_files variable:

The asterisk * indicates that any file should be used. When the asterisk is placed before a file type, it will include all the files with that file type.

Say you want all the files in /FantasticView to be included when the Pod is installed. To accomplish that, just put an asterisk instead of the file name and type:

This will include everything, even other directories. To limit the file types, you can also use the following syntax:

In this instance, all the swift and plist files will be included.

Linting The Project

CocoaPods needs to verify that nothing is wrong with a project. This spans from limitations and requirements to errors and even suspicious code. CocoaPods requires you to lint your project.

Linting a project is extremely easy, but could be incredibly annoying! To lint your project run the following in your project directory:

You may get the following warnings:

Warnings are pretty straight forward. In this example, you should increase your description length and submit a valid URL for your source. CocoaPods will fail the lint if it encounters an error or even a warning.

Now let’s look at an error that you might encounter:

When you get an error, try to read it completely and analyse what may have gone wrong. In this example, you will see the following message:

But why can’t it realize that UIColor does, in fact, have a member called red?

A smart guess would be that UIColor.redColor() has been changed to UIColor.red in Swift 3.0. One could speculate that CocoaPods, or specifically, xcodebuild is compiling the project using Swift 2.2 or 2.3. The second error also confirms our speculation since NSTimer has converted to Timer.

So how can you fix this problem? CocoaPods released a fix for this. You must specify the Swift version when linting. To do this, you must create a new file called .swift-version and add the compiler version. Simply print the following command:

Now run pod lib lint and you should get a validation message:

Woohoo! You have passed the most challenging part of this process.

Note: If you get a vague error or warning message, try typing this command instead of the regular Pod lint: pod lib lint –verbose. This will give you a more detailed message.

Publishing Your Pod

It’s time to publish your Fantastic View to CocoaPods. Every developer should have a CocoaPods account to be able to publish to CocoaPods.

Now you might think the name of your CocoaPods account should just be called a CocoaPods account, but no, it’s a Trunk account. Now I’m not judging CocoaPods, but this is a very weird decision and left me confused for a while. You might want to read their blog post on why they made Trunk.

Making a Trunk Account

Now Trunk isn’t exactly an account; it’s a session. So basically there is no need for a password, just an email.

The process is incredibly simple:

You should quickly get an email from CocoaPods to verify your ‘session’. Verify your account by clicking the link provided in the email. CocoaPods will greet you with friendly message: ACE, YOU ARE SET UP!

Pushing Your Pod

All that is left is to push your podspec using Trunk to CocoaPods:

Since I’ve already taken credit of this truly amazing and Fantastic View, the name is not available. You should change the s.name in your podspec and also your podspec file name.

After doing the changes, lint your podspec as shown in the previous section and push your trunk again. You should get the following message after successfully pushing your Pod:

Congrats! It wasn’t that hard after all. Now you can add the Pod ‘FantasticView’ to your podfile.

Conclusion

There are a couple of different ways to push your Pod. You can create Pod projects using the CocoaPods template and house an example project, readme, license, etc. However, I found that to be slightly complicated, since it contains unnecessary steps, overhead, and confusion.

In this tutorial, I created a project, added a podspec, explained the different options of the podspec file, created a trunk account and pushed the Pod. If you ever encounter a problem, you could submit an issue on the CocoaPods GitHub repo. The community is friendly, awesome, and they will always respond quickly.

Hopefully, you enjoyed reading this tutorial! You can download the full project for your reference over here.

macOS
Beyond the Sandbox: Signing and distributing macOS apps outside of the Mac App Store
Tutorial
Mastering Swift: Enumerations, Closures, Generics, Protocols and High Order Functions
Tutorial
How to Add Apple Pencil Support to your iPad Apps
  • Sergey Gamayunov

    Great article, took it to bookmarks! Thanks, Sahand!


  • Christopher Kong

    I ran into trouble of getting it to pass validation:

    [!] FantasticView did not pass validation, due to 1 error.
    You can use the --no-clean option to inspect any issue.

    [!] Unable to read the license file…

    Not sure how to fix this. I followed the steps with the exception of adding a ‘MIT’ license when I created the repo. Is that the reason behind the error?


    • Sahand Edrisian

      The licence file is not the problem here. Try running with –verbose and see what explanations it has. Please keep me updated!


  • Adil Muhammad

    What’s the best way to include file such as images and sound in your pod and also using them within your pod files?


  • Adil Muhammad

    And how we can add objective-c files in our swift Pod


  • momoko

    momokomomoko

    Author Reply

    Thanks for the great tutorial, for registering with Trunk, I had to add my project name to `pod trunk register ” as shown on cocoa pods docs,
    https://guides.cocoapods.org/making/getting-setup-with-trunk.html


  • Michael Peterson

    ^ Registering with trunk has changed. A name is now required.

    Example:
    pod trunk register [email protected] ‘Michael Peterson’ –description=’Work Laptop’


  • Vinay Chopra

    Thanks mate, its very easy to understand article…

    Though i was stuck at one place: pod trunk register

    Adding more details worked for me:

    pod trunk register , ‘Your Name’ –description=’macbook pro’

    Ref:
    https://stackoverflow.com/questions/23900688/cocoapods-trunk-cannot-push-update-you-need-to-register-a-session-first


  • shivaram

    shivaramshivaram

    Author Reply

    unable to instantitate my pod class file after importing, although the build is successful


  • sush

    sushsush

    Author Reply

    Can we use branch name instead of tag in podspec file (s.version). I want to avoid using tags.


Leave a Reply to Adil Muhammad
Cancel Reply

Shares