Updated: December 2020
CocoaPods is a software program that manages the dependencies (called pods) of over 30,000 third-party open-source libraries for use with Xcode software development projects. App developers use external libraries (e.g., open source software, reuse of software from another project) to add known and tested functionality to their software project. Using CocoaPods allows version management of the external libraries to be independent from the version management of the project files. Effective version management is one of the tenets of software development best practices. A significant amount of information on how CocoaPods works is found at CocoaPods.
CocoaPods software program uses Xcode’s command line tools which are not installed during a typical installation of Xcode. Prior to installing CocoaPods, the Xcode command line tools need to be installed using the following command in the Mac OS terminal window from the home folder:
Installation of CocoaPods
The CocoaPods software program is written using Ruby and can be installed (or updated) as a gem using the default Ruby software available on Mac OS using the following command in the Mac OS terminal window from the home folder:
Then, enter this command in the Mac OS terminal window:
Since the entire pod spec library is downloaded during the step and stored in ~/.cocoapods folder, it will take some time to complete. If during this step, the following error message is displayed,
then, the Xcode command line tools need to be installed as described above. This error message appears when the MacOS has been updated to a new release.
To update the CocoaPods software program to its latest released version, re-enter the previous two commands.
A podfile is a project-specific text file that specifies the library dependencies for a specific Xcode software project and resides in the Xcode project folder (i.e., same folder as the ‘*.xcodeproj‘ file. A typical Podfile specifies the device platform and a list of libraries with some versioning info. Note: Since it needs to be a text file, TextEdit or MS Word should not be used. A real text editor (e.g., Atom) should be used.
Either create a new podfile or open an existing podfile and edit it, as needed. Examples of podfiles are shown below for a single platform (i.e., ios, ‘14.3’) simple Xcode project with a single target ‘SeattleHobbies’ and for a multiple platform (i.e., ios, ‘14.3’ and osx, ‘10.15’) Xcode project with targets ‘SeattleHobbies’ and ‘SeattleHobbiesMac’:
The projectName (e.g., ‘SeattleHobbies’) should be replaced with the actual Xcode project name.
The pods listed need to be changed to match the pods needed for a specific Xcode project.
Use either (platform :ios, ‘14.3’) and (platform :osx, ‘10.15’) in the podfile to indicate whether an iOS app for iPhone/iPad or an app for the Mac is being developed with Xcode.
Name the podfile: Podfile and save it the Xcode project folder.
After the Podfile has been created, it needs to be installed from the Mac OS terminal command line from within the Xcode project folder (note: Xcode should not be open during this step).
This command will create a pods project within Xcode and a project workspace file (*.xcworkspace). From this point on, the project workspace (*.xcworkspace) must be opened to continue with project software development instead of the xcode project file (*.xcodeproj).
When the project workspace is opened in Xcode, a pod project with each library (e.g., Alamofile) listed in the Podfile is now included in the left project folder pane in addition to the original project.
To use a pod, import it into the project files. For example:
By adding the following to Build Settings -> User Header Search Paths, Xcode will support autocomplete when entering import statements:
Since pods are external software libraries that are managed and updated by their incredibly talented owners, updated pods need to be folded into an Xcode project for the app software to remain up to date with any changes in its pod dependencies.
There are a few steps to incorporate an updated pod into an Xcode project:
Is an update available for a pod?
Update the pod spec library.
Update the pod.
Rebuild app within the Xcode project.
Step 1: Is an update available for a pod?
First, the version of the pod that is currently used in the Xcode project is checked. Using a text editor, examine the contents of the text file, ‘Podfile.lock‘ (located in the Xcode project folder), to see the pod versions currently used.
An example ‘Podfile.lock‘ with two pods and their version dependencies is shown below. Note: The long sequence of ‘x’ characters in the example are just replacing the checksums that are part of the actual ‘Podfile.lock‘.
Next, the latest available version of the pod is checked. Access the website, cocoapods.org, and type in the name of the cocoapod in the search field. The search results will list the cocoapod and show its current version. Clicking on ‘ Expand‘ will reveal a lot of information about the pod and its entire version history.
If the latest available version is more recent than the version used in the Xcode project, updating the pod is warranted.
Step 2: Update the pod spec library
To update the pod spec libary, rerun the following command in the Mac OS terminal window:
As before, if the following error message is displayed during this step,
then, the Xcode command line tools need to be installed as described above. This error message appears when the MacOS has been updated to a new release (e.g., Mojave).
Step 3: Update the pod
To update the pod, run the following command in the Mac OS terminal from within the project folder (note: Xcode should not be open during this step).
This command will update the pods used in an Xcode project and the project workspace file (*.xcworkspace). As before, the project workspace (*.xcworkspace) must be opened to continue with project software development instead of the xcode project file (*.xcodeproj).
Step 4: Rebuild app within the Xcode project
At this point, launch Xcode and reopen the project. Press shift-cmd-k (menu -> Product -> Clean) to clean and click on the build-run button (cmd-B and cmd-R) to rebuild and run the app.
Removing a Pod
A pod can be removed by deleting the relevant line from the Podfile that resides in the project folder and effecting the change from the command line within the project folder (note: Xcode should not be open during this step):
The first five listed references are guides from CocoaPods. The final reference describes use of Git and CocoaPods.
Getting Started with CocoaPods
pod install vs. pod update
Git and Project Dependencies
CocoaPods Tutorial for Swift: Getting Started
The Xcode logo is a copyright and trademark of Apple.
The CocoaPods logo is a copyright and trademark of CocoaPods.