Five Steps to Migrate an iOS Project From CocoaPods to Carthage
Five Steps to Migrate an iOS Project From CocoaPods to Carthage
There's more than one dependency management tool for iOS. If you've decided to switch to Carthage, follow these steps to migrate your projects.
Join the DZone community and get the full member experience.Join For Free
Apple may not like the fact that iOS developers are adding third-party dependencies to iOS projects. Apple's core technologies have provided enough frameworks and tools with healthy documentation that developers can use to build and distribute iOS apps. This might be the reason Apple didn't have any official package manager to manage dependencies for iOS apps yet. However, this is not the reality; iOS developers want to share and distribute code for reusability, avoid duplication, and save time.
CocoaPods has been serving as a dependency management solution for iOS apps for a long time. It's written in Ruby and iOS developers need to know Ruby in order to use it. As long as it works, everything is OK, but the pain starts if something breaks in CocoaPods or the magical settings that CocoaPods has done inside the Xcode project. Carthage is another dependency management solution which is written in Swift and maintained by GitHub engineers. In my last blog post, I explained the difference between CocoaPods and Carthage and how to choose the right framework. I would strongly recommend reading that post to understand the basic difference. In this post, we will assume that you have decided to go to Carthage and we will see how easy it is to migrate from CocoaPods to Carthage. It can be easily achieved by applying these five steps:
- Dependency Analysis
- Carthage Dry Run
- CocoaPods Decommissioning
- Cleaning Xcode Project
- Linking Frameworks to the targets
We will discuss each phase in detail. One thing to note here: we are only talking about the Swift frameworks and dynamic libraries, not about the old Objective-C or static frameworks.
1. Dependency Analysis
The first step to migrate the iOS project to Carthage is dependency analysis. If you are using CocoaPods, then there must be a list of dependencies hanging there inside the Podfile of the iOS project. In the analysis phase, you should do two major things.
Ditch Unwanted Dependencies
At this stage, try to get rid of the dependencies that you no longer using or can be replaced with another approach if possible. An example would be SwiftLint; think, why do we need to add SwiftLint as a dependency to an iOS app? It can be easily run on a GitHub pre-commit hook or from a command line script on the local machine or Continuous Integration server. Similarly, check how many other dependencies are being used and see if those can easily be replaced by native Apple technologies like Alamofire Or SwiftyJSON can be replaced by URLSession and Codable. Fewer dependencies, less hassle.
Check Carthage Support
Almost all the major third-party Swift frameworks support Carthage. The way to check that is to visit the GitHub repo page of the framework and look at the README file. There should be a badge stating the Carthage support as well the platform support, as shown below (not that big, though)
If you don't see the badge there and it's a Swift framework that can be built with
xcodebuild and have schemes supported by the iOS platform, then that should be OK as well. Once you confirm these both things, you can go ahead and run next step, which is the Carthage dry run.
2. Carthage Dry Run
At this stage, you have confirmed that dependencies that you need to migrate from CocoaPods to Carthage have been supported. It's time to prepare the Cartfile and add all the dependencies there with correct versions mentioned either in the Podfile or Podfile.lock. Once the Cartfile is prepared, try running the Carthage update on the current project:
$ carthage update --platform iOS
After this command, it might be time for a coffee break. When you return from your coffee break and everything has been successfully built, then you are good to go to the next step. However, if you are stuck with errors, it's a good time to fix those errors. The common errors are
- The Swift version might be different.
- The framework does not support the iOS platform or doesn't build with Carthage in mind.
- Or, any other error that has been specified by Carthage.
Once everything is successfully built, you should have a Carthage directory with
Build subdirectories with all the source code of the dependency frameworks and pre-built frameworks. At this stage, you are good to ditch CocoaPods from your iOS project.
3. CocoaPods Decommissioning
When you integrated CocoaPods into your iOS project, you might have observed that CocoaPods almost invaded your Xcode project. CocoaPods not only created Xcode Workspace, but also penetrated deep into the build settings and build phases. The process of removing all the mess from your iOS project sounds like yak shaving, but it's not. There is no need to manually delete the CocoaPods files, scripts, and frameworks. Big thanks to the CocoaPods-Deintegrate plugin that removes almost all marks that CocoaPods puts inside Xcode projects. We just need to download the plugin and run the
pod deintegrate script from the root of the iOS project or where your Xcode project or workspace is located.
$ [sudo] gem install cocoapods-deintegrate $ pod deintegrate
There is no need to reinvent the wheel as long this script works, but it's important to understand what this script is doing under the hood. In summary, this script does the following things:
- Deletes CocoaPods-specific scripts from the build phases of each target. The scripts are usually "Copy Pod Resources," "Check Pod Manifest.lock," and "Embed Pods Frameworks."
- Removes Pod Libraries from the build phases
- Deletes Pod file references from the project, including
.afiles as well as all the
.xcconfigfiles for all the targets.
Podgroups from the Xcode project.
If you know Ruby, then feel free to have a look at this deintegrator.rb file on GitHub, or you can write your own scripts in bash or Python to remove the above things. Again, we can do the above steps manually as well, but the automated way mentioned above will save your day for sure.
4. Clean XCode Project
As you have seen above, we have almost removed the references of CocoaPods in the previous step, but there are still some CocoPods marks in our Xcode project that we need to remove manually. The CocoPods-Deintegrate plugin doesn't remove the following things:
- Xcode Workspace
- Podfile and Podfile.lock files
- The values attached to build configurations, like
We have to delete those things manually or using scripts. There is another plugin, cocoapods-clean, to remove workspace and Podfile, but its very easy to delete it manually. You can also cross-verify the Xcode project to see if there are any custom settings left behind.
Once you are done with the above steps, you are completely CocoaPods-free. You have successfully removed the elephant from your iOS project. Yay!
5. Link Frameworks to Targets
This is the last step of the migration from CocoaPods to Carthage. At this point, you might have the
Carthage/Checkout directory with the source code of the dependencies and the
Carthage/Checkout directory with all the built
.framework bundles. Now we have to link all these frameworks to the respective targets, as mentioned in the Carthage documentation here. This is a bit of manual process, but we have to do it only once. However, this gives you full control of the dependencies and you know what you are doing instead of the magic happening under the hood.
Once you have linked all the frameworks to targets as per the old Podfile and added the Carthage
copy-frameworks scripts, all your projects and dependencies should works as they were working with CocoaPods. Once you confirm that everything is working as expected and nothing is broken as part of these steps, this is the time to celebrate your new tool written in Swift. No Ruby and no magic under the hood.
Things to Remember
Now that, we have seen the steps to migrate your iOS app to use Carthage. There are certain things to remember about Carthage:
- The idea of Carthage is based on frameworks. Carthage only supports dynamic Swift frameworks, not static libraries. In the future, you will only able to add dynamic Swift frameworks as dependencies. You can still add static dependency source code using the
--no-buildoption, but it's not the way you should use Carthage.
- Carthage is designed for Swift. If you are still dealing with some Objective-C, then fix that first before moving to Carthage.
- Migrating from CocoaPods to Carthage doesn't solve the problems within iOS apps. It just allows you to take control of your Xcode project and frees you from dealing with Ruby problems.
There are various benefits of using Carthage over CocoaPods. You can refer to the previous post on Carthage vs. CocoaPods for a detailed comparison.
Removing CocoaPods is not as big a task as you might think; using these simple five steps, we can get rid of CocoaPods from an iOS project completely and use a Swift-based dependency management solution for iOS apps. This could be the first step of removing Ruby from iOS apps. Carthage will give you less hassle and full control of your Xcode project. Have you recently migrated to Carthage from CocoaPods? What are your experiences?
Published at DZone with permission of Shashikant Jagtap , DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.