I introduced Playground Driven Development on the last project I worked on. It sped up my development and forced me to write view controllers in a decoupled way. But before I was able to reap the benefits of PDD I hit a roadblock: Xcode Playgrounds kept throwing a Couldn't look up symbols error, because it couldn’t see Carthage-built dependencies. Here’s how to fix this issue.

Identifying the problem

Initially I wasn’t sure what the source of my Playgrounds problem was, so I made a sample PDD project without Carthage. Next I installed Carthage and added a single dependency1. This reproduced the problem:

Screenshot of Xcode Playgrounds with the couldn't lookup symbols error

Fixing the couldn’t look up symbols issue

I knew Playgrounds were missing some symbols, and I knew this was Carthage related. It became clear that Carthage supplied dependencies weren’t being seen by Playgrounds. What wasn’t so obvious to me is how to fix this issue in a way that wouldn’t require any kind of Xcode project restructuring.

I reached out to the iOS community with the sample project that reproduced the problem, and it turned out that Logan Moseley was having the same problem. Within a day Logan figured out the simple fix I was searching for. Thank you Logan! Here are the steps:

  1. Select Xcode → Project Settings → Targets → your main AppFramework target
  2. Click on the Build Phases tab
  3. Add a Copy Files phase
  4. Select Products Directory as the Destination
  5. Drag all Carthage-supplied frameworks in from the project navigator’s frameworks group
  6. Clean and re-build the project, open the project playground and start playing

Here’s how the new Copy Files phase should look:

Screenshot of Xcode project target settings that fix the Carthage Playground Driven Development issue

We’re done. Playground Driven Development with Xcode and Carthage should now work. 💫

Screenshot of Xcode Playgrounds working with Carthage after applying the fix

  1. The master branch has a self-contained Xcode project with working PDD. The carthage branch installs Carthage and shows the problem (you still have to run carthage bootstrap). The fix is on carthage-fix