How do I configure my project for Cocoa Pods correctly?

The best way to use Cocoa Pods is to follow the official example's lead.

This consists of several steps.

Setting up Cocoa Pods for the first time

1. Install Cocoa Pods on your computer

Begin with the Getting Started Guide to install Cocoa Pods on your computer.

2. Create a Podfile

Do not create the Podfile in Xcode, since it should not be part of your project!

Create the file in your favorite text editor, and save it at the same level as your .xcodeproj file.

An example of a Podfile's contents are:

pod 'CupertinoYankee', '~> 1.0'

3. Run pod install

Navigate to your Podfile's directory in terminal and run pod install.

4. Open the generated workspace

Once you run pod install, you will see a message such as:

[!] From now on use MyProject.xcworkspace.

Close the Xcode project, and open up the generated .xcworkspace file.

Understanding the Changes

It is always useful to know what changes were made to your project in case things go wrong.

1. Directory structure

You should have started with a structure such as:

... then manually added a Podfile:

After running pod install, your directory structure now looks like this:

Notice how the only new objects are:

• MyProject.xcworkspace
• Podfile.lock
• Pods

2. Project Navigator

In Xcode, you started with this:

... and ended with this in the new workspace:

For reference, here is an expanded look at the new directory structure:

Obviously, the Pods project was added to the Project Navigator, but there are a few other key things to notice:

Notice how Podfile is located at the root of the MyProject folder in Finder, but is inside of the Pods project in Xcode's project navigator.

Likewise, notice how Pods.xcconfig is located inside the Pods folder in Finder, but is inside of the MyProject in Xcode's project navigator.

3. Configurations

These are the same screenshots as before:

In Xcode, you started with this:

... and ended with this in the new workspace:

Notice how under Configurations, the "MyProject" target now has Pods specified.

This is important because otherwise PODS_ROOT will not be set up properly (among other things), and when you build, you will get errors.

4. PODS_ROOT added

Your target's Build Settings went from this: (Note: this is scrolled all the way down)

... to this:

Notice how PODS_ROOT was added as a User-Defined setting.

Note: this part of the configuration sometimes gets bugged out when reinstalling Pods, so you may need to close and open the Xcode project to fix it.

5. Other changes

You can see a complete list of the changes here.

---