Using CocoaPods With Xcode Playground

By Aasif Khan | December 28, 2021 4:35 pm | 4-min read

Creating a playground in Xcode is a great way to practice Swift coding, try out a new Swift feature, or work out an algorithm. And CocoaPods can integrate 3rd-party libraries and frameworks in your code with zero fuss!

Problems arise however, when you want to use CocoaPods and a playground together. We’re going to solve that today, in this tutorial. I’ll show you how you can use your favourite libraries with CocoaPods, and try them out in a playground.

But… why would you want to do that? Using CocoaPods with a playground has a few advantages:

You can try out a new library or framework without setting up a complete new Xcode project
You can isolate a particular feature of a library or framework and experiment with it in a playground
You can keep a library of playgrounds and code snippets of your favourite frameworks and libraries

Installing CocoaPods
Using CocoaPods With A Playground
Quick Tips & Common Errors
Further Reading

Installing CocoaPods

CocoaPods is a so-called dependency manager. You use it to add dependencies, such as 3rd-party libraries and frameworks, to your app. CocoaPods can download popular Swift libraries, such as Alamofire, and install its code in your app’s codebase.

Once you’ve added a library (called a “pod”) to your app, you can use CocoaPods’ command-line tools to keep the library up-to-date with new versions. And CocoaPods has convenient configuration options, for instance to keep your code up-to-date with specific library versions.

You tell CocoaPods which libraries and frameworks you want to use with a simple file, called a Podfile. CocoaPods reads this file, downloads the 3rd-party libraries, and adds them to a Pods Xcode project. That project, and your app’s Xcode project, are then added to a workspace. This effectively adds the library’s code to your own project.

CocoaPods was the first major dependency manager for iOS apps. You can also use Carthage or Swift Package Manager. The directions found in this tutorial will work with Carthage and Swift Package Manager, too.

First, let’s make sure you’ve installed CocoaPods on your Mac. Open Terminal and type the following command:

$ pod –version

You don’t have to type the $-sign (dollar sign) on the command-line. In the code above it simply indicates that the text should be typed on the command-line, such as in Terminal. And always check what you’re typing! Don’t just input anything you read on the internet.

When the above command fails and outputs something like “Command not found”, then install CocoaPods with the following command:

$ sudo gem install cocoapods

This will install the Ruby “gem” for CocoaPods. CocoaPods is developed with the Ruby programming language, which is installed by default on macOS.

It’s recommended to keep CocoaPods up-to-date with the latest version. To update CocoaPods, simply repeat the same command:

$ sudo gem install cocoapods

Now that you’ve installed CocoaPods, let’s continue!

Using CocoaPods With A Playground

There’s no straightforward way to add a pod to a playground, but what we’re going to do today comes pretty close.

Here’s the gist of it:

Create an Xcode project
Create the Podfile
Install pods with CocoaPods

Add a playground to the workspace

Import a pod’s module directly in the playground

If you’re already familiar with CocoaPods, Xcode and using playgrounds – go for it. Happy coding! If not, let’s move on with the first step.

1. Create An Xcode Project

First, we’re going to create a simple project in Xcode. Here’s how:

Open up Xcode on your Mac

Choose File -> New -> Project…

Choose the Single View Application template and click Next

Input CocoaPodsExample as the Project Name and click Next

Finally, choose a convenient location to save this project and click Create

2. Create The Podfile

Next, we’re going to create the Podfile. This file will contain all information about the libraries we want to add to our project.

Here’s how:

Right-click on the CocoaPodsExample project in the Project Navigator, on the right of Xcode, and choose New File…

Choose the Empty template from the Other category (scroll down) and click Next

Name the file Podfile and make sure to save it in the same directory as the CocoaPodsExample.xcodeproj file

Finally, click Create

Note: Make sure to name the file Podfile and nothing else. So no extension, just Podfile.

Then, add the following text to the Podfile:

platform :ios, ‘11.0’
use_frameworks!

target ‘CocoaPodsExample’ do
pod ‘SwiftyJSON’, ‘~> 4.0’
end

What’s that code mean?

The first line with platform tells CocoaPods the iOS version we want to support is iOS 11.0. This is typically indentical to the deployment version of your Xcode project.
The use_frameworks! indicates that we want to create Cocoa Touch Frameworks instead of static libraries. In short, this is a necessary setting to work with libraries written in Swift.
The target block wraps pods we want to add to a specific build target. In our case, that’s CocoaPodsExample. This is the name of our app project.
The pod ‘SwiftyJSON’, ‘~> 4.0’ code is the most important! It tells CocoaPods that we want to use the SwiftyJSON library in our project.

You can use logic expressions like >= to indicate which pod versions you accept in your project. When you omit the ‘~> 4.0’ part, CocoaPods just uses the latest version of this pod. This is often recommended at the start of a project.

The ~> is called an optimistic operator, and it will accept versions “up to” a certain version. For example, ~> 4.0 means we’ll accept any version from 4.0 to 4.9 (inclusive), but not 5.0. It’s ideal for situations where you want updates for a library, unless they’re major updates that can break your code.

Learning how CocoaPods works is good practice, because it touches on a lot of practical software development topics.

3. Install Pods With CocoaPods

Now that CocoaPods knows which libraries we want, let’s install them.

First, close your project in Xcode, and then close Xcode itself.

Then, open Terminal and use cd to navigate to your project directory. If you don’t know how to do that, it’s easiest to simply type cd in Terminal, then drag-and-drop your project’s directory from Finder to Terminal and finally press the Enter key.

Then, type this on the command-line:

$ pod install

This will install the pods from your Podfile, by creating that Pods project and adding that to a new workspace.

CocoaPods needs to download a large file, called a podspec, if this is the first time you’re using CocoaPods, or if you haven’t used CocoaPods for a while. Depending on your internet speed and the size of the podspec, this can take a few minutes.

When the pod has successfully installed, you see something like this:

Analyzing dependencies
Downloading dependencies
Installing SwiftyJSON (4.1.0)
Generating Pods project
Integrating client project
[!] Please close any current Xcode sessions and use `CocoaPodsExample.xcworkspace` for this project from now on.
Pod installation complete! There is 1 dependency from the Podfile and 1 total pod installed.

See that notice? You’ll have to use CocoaPodsExample.xcworkspace from now on. So, locate that file in Finder and open it in Xcode.

Does your project appear “closed” when opening the workspace? Make sure you’ve closed the Xcode project first, then close the workspace, then open it again.
Using CocoaPods With Xcode Playground

4. Add A Playground To The Workspace

The key part of using CocoaPods with a playground is adding the playground to the workspace, instead of just creating a standalone playground. So, that’s what we’ll do next.

With the workspace opened in Xcode, do this:

First, choose File -> New -> Playground…
Then, choose the Blank template
Then, name the file CocoaPodsExample and save the playground file in the same directory as your Xcode workspace
Finally, close the playground editor that has appeared

Next, find the CocoaPodsExample.playground file in Finder and drag it from Finder into the Xcode workspace.

Xcode will probably add the playground within the CocoaPodsExample project. Make sure to drag it outside the project, directly into the workspace!

In the Project Navigator you can drag-and-drop the file to the top-most level. When Xcode creates a copy of the playground, simply delete the previous reference to the playground.

This step is a bit quirky, but you know you’ve done it right when your workspace’s projects are organized like this:

5. Import Pod’s Module In The Playground

The last step is to use the modules that CocoaPods generates directly in the playground. This is similar to how you would use a pod in an Xcode project, when you code an import at the top of a file.

First, compile the workspace by pressing Command-B. This will compile the projects in the workspace and make the pod’s modules available in the playground.

Then, open the playground in Xcode by clicking on it in the Project Navigator. Type this at the top of the file:

import SwiftyJSON

As you’re typing “Swifty”, the available modules should already pop up in the auto-complete box. Like this:

A few common errors may occur as you’re compiling the workspace, and running the playground. Please check the next section for solutions for these errors.

Finally, let’s put SwiftyJSON to work! Add the following code to the playground:

let json = JSON(parseJSON: “{\”hello\”: \”Playground!\”}”)
print(json[“hello”])
And when you run the playground, this should appear in the Console:

Playground!
Awesome! It works 🙂

Quick Tips & Common Errors

A few common errors may occur as you’re using CocoaPods with playgrounds. You can find the solutions for these errors below. And also check out some quick tips to get the most out of CocoaPods and playgrounds!

No such module

When you see an error like “No such module SwiftyJSON”, you’ve missed a step somewhere. Go back to the previous section and make sure you’ve added the pods correctly, and compiled the workspace successfully with Command-B.

Couldn’t lookup symbols

This error pops up when you use CocoaPods version 1.5 with Xcode 9. You can solve it by adding the following code to the end of your Podfile:

post_install do |installer|
installer.pods_project.build_configurations.each do |config|
config.build_settings.delete(‘CODE_SIGNING_ALLOWED’)
config.build_settings.delete(‘CODE_SIGNING_REQUIRED’)
end

installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings[‘CONFIGURATION_BUILD_DIR’] = ‘$PODS_CONFIGURATION_BUILD_DIR’
end
end
end

Make sure to run pod install again to regenerate the Pods project. Then clean the build with Command-Shift-K, rebuild it with Command-B, and run your playground. The error should disappear.

JSON is null

In the example code of SwiftyJSON we used earlier, the json constant may be empty when the JSON cannot be parsed. So, if you’ve changed the JSON, make sure it doesn’t contain any mistakes. You can read more about how to use SwiftyJSON here: https://github.com/SwiftyJSON/SwiftyJSON.

Manually Run Playground

Do you find it annoying that your playground runs as you’re coding? Set it to manual! Hold-click on the Play button in the bottom-left corner of your playground, and then select Manually Run.

Run Playground Indefinitely

If you’re working with asynchronous or long-running code, you may want your playground to run indefinitely. Otherwise, the playground may quit before your async code returns. Here’s how you do that:

Add import PlaygroundSupport to the top of your playground file.
Add PlaygroundPage.current.needsIndefiniteExecution = true in your Swift code

Playground now runs indefinitely, and will stop execution at a certain timeout (typically, 30 seconds). You can also stop execution of the playground manually, with this code:

PlaygroundPage.current.finishExecution()

When your asynchronous code returns, for instance after downloading a resource, you can call the above line to stop execution of the playground.

Using CocoaPods With Xcode Playground

Table of Contents