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 and Ray Wenderlich’s tutorial: CocoaPods Tutorial for Swift: Getting Started.
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:
sudo gem install cocoapods
Then, enter this command in the Mac OS terminal window:
pod setup --verbose
Since the entire pod spec library is downloaded during the step and stored in ~/.cocoapods folder, it will take some time to complete. The verbose option provides a visual progress of the installation.
A podfile is a project-specific text file that specifies the library dependencies for a specific Xcode software project and resides in the project folder. A typical Podfile specifies the device platform and a list of libraries with some versioning info. Note: Since it is a simple text file, TextEdit or MS Word should not be used. A real text editor (e.g., UltraEdit) should be used.
Open the default podfile that was created in the project folder and edit it, as needed: An example podfile with two dependencies is shown below:
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '10.0' target 'projectName' do use_frameworks! pod 'Alamofire', '~> 4.5' pod 'GRDB.swift' end
- The projectName should be replaced with the actual Xcode project name.
- The pods listed will likely need to be changed to match the desired pod for the Xcode project.
After the Podfile has been created, it needs to be installed from the Mac OS terminal command line within the 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‘.
PODS: - Alamofire (4.5.1) - GRDB.swift (2.3.1) DEPENDENCIES: - Alamofire (>= 4.5) - GRDB.swift SPEC CHECKSUMS: Alamofire: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx GRDB.swift: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx PODFILE CHECKSUM: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx COCOAPODS: 1.3.1
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:
pod setup --verbose
As before, the verbose option provides a visual progress of the installation.
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.