If you are using Unity to build your iOS projects and use SDK’s like Firebase, Facebook etc. which require CocoaPods, then these steps enlisted below should help you run a smooth and successful build.

Even if you are not using Unity and just using Xcode project, these steps should ensure that the pods get installed in your project successfully.

Once everything is setup, the builds usually almost always run successfully and rarely give problems. It is mostly during the first build or sometimes after an OS update or after a hard disk change or moving to a new machine, that problems creep up and the Unity build fails with the message – “iOS framework addition failed due to a Cocoapods installation failure. This will will likely result in an non–functional Xcode project.“. It is a long error message in the Console which would probably state how even the “pod repo update” was attempted and it failed as well.

For the people who aren’t aware how Pods work and not familiar with the Xcode CocoaPods workflow, this error is very hard to decipher and fix.

If you have encountered this error, follow the steps below to fix it and setup CocoaPods correctly.

The setup used for the purpose of this writeup:

MacOS Catalina (10.15.6)

Unity 2018.4.22f1

Xcode 11.4.1

CocoaPods 1.9.1 

 

1) Install Xcode. 

Pretty self explanatory and in all probability you should have done this step already. Xcode can be installed from the Mac AppStore or by downloading a xip file from the apple developer site.

 

2) Sudo xcode-select

Now we have to ensure that our system knows where our Xcode is and specifically where the developer tools which come bundled with it are installed.

Open Terminal on your Mac and run the following command.

sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer

Please note that the path to Xcode on your machine may vary. The path listed above is the default location of Xcode. You may have installed or moved Xcode to a new location. In that case, please run the command with the appropriate path.

Sometimes, just this magic command can make your build run fine. If it doesn’t, follow the next steps to install and correctly setup CocoaPods on your system.

 

3) CocoaPods installation and setup.

If your build is failing, the most likely cause is that CocoaPods is not installed and setup properly. So follow the steps below and by the end of it, CocoaPods would be installed successfully on your system.

First lets remove any previous installations so that we can make a fresh start. Open a Terminal and run the command below. If there was a previous installation (or more than one installations) this will remove them. Type “y” and press “Enter/Return” on any prompts that this command makes.

sudo gem uninstall cocoapods

Once you have uninstalled the previous version (or if no previous version exists) proceed to install cocoapods. Run the following command on the Terminal.

sudo gem install cocoapods

Let the process complete successfully. This should install the latest version of CocoaPods on your system.

But the installation process isn’t complete. CocoaPods is basically a repository of frameworks and their dependencies. You just have to specify which “pods” you want in your project in a podfile and it installs them. But in order for it to work, the entire repository needs to be on your system in a specific folder. There are several ways to do that. The first time you run a pod install, it will download the repository before proceeding. In older versions of CocoaPods, you can run pod setup and it should do the job (since version 1.8.0, pod setup does nothing!). Or in some cases pod repo update might work. 

But I am going to list the method that I use which works for me every time.

First we need to create a folder. Go to your user folder using Finder Explorer. Look for a folder name .cocoapods. (It is a hidden folder since the name starts with a dot). If you can’t see the folder, press Command+Shift+. to reveal the hidden folders. If the folder doesn’t exist, then create one with the name. Open the folder and look for a folder named repos. If the folder doesn’t exist, create one by that name. Open the repos folder. If there is a master folder inside it, then delete it. We are going to recreate it. Your folder structure should look like this :

Once you have got this open the terminal and run the below commands one by one.

cd ~/.cocoapods/repos

git clone --depth 1 https://github.com/CocoaPods/Specs.git master

pod repo update

The git command should take a few minutes to complete as it downloads the repository to your system. Ensure all the commands listed above are completed successfully. Your folder structure should look like this.

Voila! Now you have completed the installation correctly. Go back to Unity and build for iOS again. And this time the build should succeed without any errors!

 

 

4) Use .xcworkspace file instead of .xcodeproj

If you are new to using Pods, then you probably won’t even be aware of this. If you are experienced, there is still a chance that you might forget this.

Always, use the .xcworkspace file to open your project in Xcode and not the .xcodeproj which you are probably used to.

Once the unity build process completes and the pods are installed successfully, notice that the generated Xcode project now has a .xcworkspace file alongside the usual .xcodeproj file. Use the .xcworkspace file to open you project in Xcode. Using the .xcodeproj file to open the project will lead to errors when building the Xcode project.

 

 

4a) There is no .xcworkspace file in my Xcode project!

Relax. This may not be a problem. Unity also has the ability to load pods from .xcodeproj file as well. The External Dependency Manager used by Unity to manage pods has the option to add pods to either to the workspace or the project file as shown in the image below. Check which setting you are using by going to the following location in Unity.

Assets -> External Dependency Manager -> iOS Resolver -> Settings 

If there is no workspace file in your project, try building the project using the .xcodeproj file. If it doesn’t work, try changing the iOS Resolver Setting and generate a .xcworkspace file.

 

5) Keep CocoaPods updated.

Everything might work correctly for some time and then suddenly you might face the pod installation error again. This might be because the repo could not be updated due to some error. Try running the ‘pod repo update’ command manually again and see if it helps.

Also it might be possible that your CocoaPods version is outdated and one or more of your pods require a higher version of CocoaPods. In that case, just run the below command (same command which was used for installing) and it will update you CocoaPods to the latest version. 

sudo gem install cocoapods

 

There is a strange bug currently if you are using Unity + Firebase where the Xcode build will fail with error –

Unable to read Google Service plist at path….

This error is surprisingly being caused because of spaces in build folder name! To fix this error, just rename your build folder without any spaces and then run the build again. It should run successfully now.

Refer to below links:

https://github.com/firebase/quickstart-unity/issues/557
https://github.com/firebase/quickstart-unity/issues/714

Some parting info on CocoaPods

There’s a lot of information on CocoaPods out on the internet, some old some new. A lot of questions being answered on StackOverflow. If you have been going through all the material, it can cause quite a lot of confusion. Especially with the new versions of CocoaPods not requiring the master repository on your system. Let me help you out with that.

As of CocoaPods version 1.8.0, there is no mandatory requirement for the master repository on your system. However, this also requires a change in the projects podfile to change the source of download. When testing with Unity 2018.4.22f1, I found the podfile still tries to download from the master repository and hence the master repo is required on the system. If the repo is not present, the Unity build process will try to download and install the repo which may fail due to network issues or some other error and will cause the build to fail. So it is better to have the master repository for now. In the future, when the new methodology is stable and becomes the norm, we probably won’t need the master repository.

When running into issues, a lot of old answers on internet can point you to “pod setup”  to solve the problem. Let me reiterate that as of version 1.8.0, this command does nothing and just prints a completed message. Hence don’t rely on it.

“pod repo update” command can be run to keep the master repo updated but it requires the master repository correctly configured to work. It especially requires the .git folder inside the master folder to be configured correctly. This command can be run on Terminal from any folder.

“pod install” command is used to install the pods in your project. It will also download and install the master repository if it is not present. This command can only be run from a folder which has a valid podfile.

Hopefully you won’t run into any issues if you follow the above mentioned steps correctly and won’t need any additional help.

I am no expert on CocoaPods. But I have had to fiddle around to get my project to build with Google Firebase SDK and Facebook SDK. Hopefully this writeup will help any one else coming across the same problems.