How to Make Your Own iOS CocoaPods Framework?

Hello guys!

So you wanted to create your framework (no matter, one little custom view or the entire system to rule all your projects) and ran into the issue: you don’t know what to do. That’s OK.

Many topics about that are outdated and official CocoaPods documentation is skinny. I’m sure, this little guide will be outdated in the close future. But while it’s not, I’m here to help you with this easy deal.

Let’s go, make something!

Preparation

What do you need to create your own framework?

1. Latest Xcode.
   For me, it’s the 12.0 version. You can always find the latest version here.
2. Latest CocoaPods.
   For me, it’s the 1.9.3 version. You can always install the latest version via a command in Terminal:
   sudo gem install cocoapods
3. Github account.

Project creating

So you have all that you need, go next. Create your Xcode project.
It’s not necessary, but I advise you to choose the “Framework” type for your project.

Important! Choose the unique name for your framework. Check here for existed CocoaPods framework names.
Try to not forget this, because you will receive related errors really late.

Important! Choose a license, because it’s a requirement for the CocoaPods framework. (MIT is the default choice)

Description, .gitignore, and README are optional, but the last one is important to describe your framework on cocoapods.org.

Then, clone your repository on your device with command in Terminal and create your project:

1. Reach your project directory.
   For me it’s Documents/Projects/Medium: cd ~/Documents/Projects/Medium
2. And then just clone your repository:
   git clone https://github.com/<your_github_username>/<repo_name>.git
   (e.g., git clone https://github.com/krotoff/KrotoffMediumProject.git)
3. Create an Xcode project.
   Open your Xcode app, choose File -> New -> Project, select type “Framework” and select the directory you created with git clone.

Great! You created your project. Now you can fill it with your extensions/classes/protocols and etc.

Important! Don’t forget to clarify all entities as public or open to make them available to use with import.

Also, don’t forget a simple rule: lower supported iOS version you choose earlier your framework will be unsupported (e.g. with Xcode 12 release we lost iOS 8 support in newer projects). So if you choose minimal available iOS version to support, be ready to update your framework with the new Xcode release.

Done with it? Nice. Go next.

Creating a .podspec file

The most terrible part of our journey. A specification has a huge set of hidden issues. So we’ll try to avoid them all.

Let’s create this monster with a few steps:

1. Create a .podspec file.
   Be sure, that you are in your project directory. If not, reach it with the cd command (e.g. cd ~/Documents/Projects/Medium/KrotoffMediumProject)
   Create a file with touch command: touch KrotoffMediumProject.podspec
2. Fill it.
   Open your .podspec file with a text editor.
   Here is the minimal required set of filled fields:

The last 3 fields are not required, but still important. source_files helps you to clarify paths to required files, swift_versions and ios.deployment_target help you to avoid warnings (or even errors) with linting your framework.

But let’s figure out all these unfamiliar lines:

1. name — it’s quite obvious, right? Unique name of your framework.
2. version — version of your framework. Must be the same with version of your project.
3. authors — list of project authors. Could be listed with commas.
4. license — license type and file. Quite obvious as well. Just must be the same with your license.
5. homepage — web page of your project. Mostly, it’s a github page, but if you have a landing page or something like this, you can write a link on it.
6. source — source for your repository. Clarify link, branch, and tag. In my case, I used a version from specification, transformed to string. If you do it another way, just clarify it in quotes as any other fields.
7. summary — short summary of your framework. Will be used on cocoapods.org.
8. source_files — list of files you need to use from your framework. By default, all root directory files are source files. But you can clarify paths with your needs. **— mask to use any recursive directories. *— mask to use any file. *.swift— mask to use any .swift file.
9. swift_versions — list of swift versions that used in your framework. Could be a few separated with commas.
10. ios.deployment_target — minimal iOS version for your framework.

You can read more about a specification here. In each section, authors described related fields.

Troubles. Most popular of them:

• If you don’t clarify any of required fields — an error.
• If you don’t clarify source_files, but you have some required files not in root directory — you just can’t use these files with an import.
• If you don’t clarify swift_versions, be ready to get an error about unknown types/methods and etc.
• The name must be unique and the same with your project name. If not — an error.
• The version must be the same with you project version. If not — an error.
• The source must be valid. Check it several times. Really, it’s very often point to make a mistake.
• The summary must be shorter than the description. If not — an error.
• Check here source_files syntax. There is a bunch of hints.

So, you are ready to publish? Great! Go next.

Work with Git

The next steps are quite simple, but it has some moments, so we will discuss it.

1. Commit and push your code.
   Add all project files to stage: git add .
   Commit them with your message: git commit -m "your message"
   Push your changes: git push -u origin master
2. Make a tag. It’s a good practice to make a tag the same with your framework version.
   Make a tag: git tag 0.1.0
   And push it: git push --tags
3. You can create a release with your tag, but it is not required. It would be just useful to observe your releases in perspective.

Pod publishing

Okay, we went through the common actions of iOS developers. So now the special final.

First, you need to check your pod with
pod lib lint
If you did everything correctly, you’ll see cherished text: passed validation.

If not, try to fix issues. If it’s not clear, try to add the flag --verbose to the previous command. It will give you detailed info about linting.

Passed? Great! Next step — register yourself in CocoaPods via command
pod trunk register your_email
You will receive an email with a confirmation link. Just click on it and see the CocoaPods confirmation page.

Got it? Go next, push your spec via command
pod trunk push FrameworkName.podspec
(e.g. pod trunk push KrotoffMediumProject.podspec)
If everything is OK, you will get something like that in your console:

Important! Sometimes CocoaPods frameworks have a glitch with their local repo. If you want to use your framework on the same device, where the pod was created, you need to clear the trunk repo via command:
pod repo remove trunk
And, as an option, you will need to update thelocal repo with installation:
pod install --repo-update

That’s all!

Quite simple, isn’t it? But without concrete information, it could take a lot of time. So I just hoped to save your time. Here is the example project:

krotoff/KrotoffMediumProject

Easy coding and fewer bugs to you, see ya!