CocoaPods manages library dependencies for your iOS and tvOS projects in Xcode.

The dependencies for your projects are specified in a single text file called a Podfile, and CocoaPods will resolve dependencies between libraries, fetch the resulting source code, then link it together in an Xcode workspace to build your GameMaker project.

This means that you no longer have to supply the frameworks and SDKs directly within your GameMaker projects, as these will be "pulled in" by the CocoaPods system when the app is built in XCode.

Support for building using CocoaPods in GameMaker depends on the version that you're using:

In GameMaker 2024.4 and after, CocoaPods is enabled by the extension that requires it using injection tags (see Code Injection on this page)
In GameMaker 2022.11 and after, the iOS Game Options and tvOS Game Options allow you to tick the CocoaPods checkbox under Build Settings.
Versions earlier than that and the LTS versions (v2022.0.0 and v2022.0.1) do not have this checkbox. In these versions, the iOS and tvOS Game Options show two buttons Podfile and Podfile.lock under Build Settings instead.

This article first covers the CocoaPods injection and checkbox methods. In case you're using a GameMaker version that doesn't have it, the remainder of this article applies.

Current Method

Using the YYIosCocoaPods and/or YYTvosCocoaPods injection tags in an extension will make GameMaker handle everything automatically. More specifically, GameMaker will do the following when building the game:

NOTE: In older versions that have the "CocoaPods" checkbox, GameMaker will do the same if it's enabled:

Check if CocoaPods is installed, if it is not, install it.
Check if the Podfile and Podfile.lock files exist. If not, create them and add the required macros.
Execute the "pod install" command.

Do not include the injection tags (or leave the checkbox unchecked in older versions) in case you want to manage your Xcode project dependencies manually.

For older versions of GameMaker that have the Podfile and Podfile.lock options, refer to the rest of this guide to manually install and set-up CocoaPods.

Legacy Method

Installing CocoaPods

To be able to use the features that CocoaPods offers, you will first need to install it on your Mac.

Installing using sudo

Run the following command in the Terminal:
```
sudo gem install cocoapods
```
Make sure you have a .bash_profile file in your User folder with the following line:
```
export LANG=en_US.UTF-8
```
1. This file should be called .profile on M1 Macs.
Scroll down to the "Generating the Podfile" section as your Cocoapods installation is now finished.

NOTE: If you don't have a .bash_profile (or .profile) file, you can create one by doing the following:

1. 1. Start up Terminal
  2. Type "cd ~/" to go to your home folder
  3. Type "touch .bash_profile" to create your new file.
    1. or, on M1 Macs, type "touch .profile"

Installing without sudo

Run the following command in the Terminal:

gem install cocoapods --user-install -v 1.10.2

Make sure you have a .bash_profile file in your User folder with the following lines:
```
export GEM_HOME=$HOME/.gem
export PATH=$GEM_HOME/bin:$PATH
export LANG=en_US.UTF-8
```

Follow the rest of the steps below for sudoless installation.

You now have a .bash_profile file and you need to either create or edit two other files on your Mac. The first file is the .profile file, which you should open for editing (or create if it doesn't exist, in the same place as the .bash_profile following the same steps as outlined above, and then open it for editing) and add in the path to where Ruby has installed the CocoaPods program itself. You can find this path by typing the following in Terminal:

gem which cocoapods

This will give you something like the following as a return:

/Users/<username>/.gem/ruby/2.6.0/gems/cocoapods-1.9.3/lib/cocoapods.rb

You only need the first part of the path listed, which you can now add into your .profile file with the following format:

export PATH=/Users/<username>/.gem/ruby/2.6.0/bin:$PATH

The final file you need to edit (or create) will depend on what shell you are using:

If you are on an older version of macOS - pre 10.15 Catalina - you will need to update your ".bashrc" file.
If you are on Catalina or above, you will need to update your ".zshrc" file.

You can check which shell your OS is using from terminal with the following command, as even though you may be on Catalina or above, you could still be using a bash shell:

echo $SHELL

and you should get back one of the following:

/bin/bash

/bin/zsh

Regardless of the shell, if the file doesn't exist then you will need to create it and then you will need to update it . For the bashrc file you would add:

source ~/.profile

And if its a zshrc file then you would add:

[[ -e ~/.profile ]] && emulate sh -c 'source ~/.profile'

The following image shows how the three files should look (they are for a bash shell, but zsh would be almost identical except the .zshrc file):

Once you have everything installed and the files correctly set up, you should restart your Mac before continuing.

Generating The Podfile

Once you have installed CocoaPods, you can now go back to GameMaker and open the project that you want to use them in. To be able to use any CocoaPod in the project, you will need two files to tell GameMaker what to use - the Podfile and the Podfile.lock. The Podfile is where you are able to define a list of "pods" for your project, and this will then be used by CocoaPods to fetch and install the various specified libraries and frameworks in XCode. The Podfile.lock is a file that is used to ensure that the dependencies of any given CocoaPod are also fetched at the required versions. Essentially, you can specify the version of the top level CocoaPod that you request, however it is up the developer of the CocoaPod to specify the versions of its dependencies.

You can generate the Podfile and Podfile.lock files from within GameMaker from the iOS or tvOS Game Options (see here for iOS or here for tvOS), by simply clicking the buttons at the bottom of the General options, as shown for iOS in the image below. To start with you only need to create the Podfile, as we'll be making the Podfile.lock file later:

These buttons will add the required files to your Game Options and open a browser window on them should you wish to edit them. These files, by default, hold a series of macros that GameMaker will use to communicate with Xcode and setup the required CocoaPods dependencies based on what you specify in the actual extension.

While we recommend you use these files, you can supply either of them yourself and save it in the iOS/tvOS "options" folder of the project, but note that since they won't contain the Macros that GameMaker needs to detect them in the IDE, the pods and dependencies they use won't be shown as part of the extension (functions in the extension should, however, still work fine communicating with them). How to manually create these files is outside the scope of this article, but it is fully documented on the CocoaPods web page:

Using CocoaPods

NOTE: Creating your own Podfile and Podfile.lock will mean that the project cannot be uploaded to the Marketplace as the extension system will not be able to pick up on the required pods and dependencies.

Adding CocoaPods To An Extension

Once you have everything set up and have created the Podfile (but not the Podfile.lock), you can then add the required CocoaPods (or simply "pods") to an extension in your project. You can get pods by searching the following page for those that you require:

CocoaPods

Once you have found the one you want, you need to click the button on the page labeled "Installation Guide":

Clicking this will open a window that has the install instructions you should be using with XCode to build the APP, however, from these instructions you can get the name of the CocoaPod to add to GameMaker in an extension. In the case of the example image above for Google Analytics, the installation guide looks like this:

The important part here - highlighted in the image above - is the "pod" name that is given as this is what you will be adding into GameMaker for your extension. To add this to an extension you would first create the extension, select the "iOS" or "tvOS" option under Extra Platforms, and inject it into the YYIosCocoaPods (or YYTvosCocoaPods, depending on the platform) tag under Code Injection:

If you're using an older version of GameMaker (<=2.3.3) which doesn't have the Code Injection field, you can add the pod directly into the field titled CocoaPods:

Generating The Podfile.lock

Once you have added the Podfile, you need to do a test build of the game, as we need to extract the dependencies from the Podfile.lock that XCode will generate to add them into the extension properties. Note that when you build and your game has a Podfile added to it, XCode will create a workspace for your game, which will consist of a CocoaPods project and the game project. However the process for running or creating an executable for the store is exactly the same.

Once you run a test build of the game, you need to go to the folder where XCode has saved the Podfile.lock. The easiest way to do this is to right click (or CMD + Left Click) on the "Podfile" in the Pods project in XCode and then select "Open In Finder". The Podfile.lock should be beside the Podfile in the temp directory. The path itself will be something like this:

/Users/<username>/GameMakerStudio2/GMS2IOS/<project_name>/<project_name>

If you open the Podfile.lock in a text editor, you will see a list of "PODS" that are in use. The image below shows our Google Analytics example Podfile.lock contents:

You need to copy the line that has been marked EXACTLY AS IT IS WRITTEN, and then inject it into the YYIosCocoaPodsDependencies (or YYTvosCocoaPodsDependencies) tag under Code Injection in your extension:

If you're using an older version of GameMaker (<=2.3.3) which doesn't have the Code Injection field, you can add the pod directly into the field titled CocoaPods Dependencies:

You now need to go to the iOS/tvOS preferences and generate the Podfile.Lock for your project clicking the appropriate button, just as you did for the Podfile earlier. The created file contains a macro that will automatically add all the listed dependencies for the extension when you build your game.

Note that when extracting the dependencies from the XCode generated Podfile.lock, you need to ensure that you copy everything that is listed, and use the exact same formatting. For example the Facebook SDK Podfile.lock has the following:

In this case, you would copy all the listed dependencies under "PODS", maintaining the indentations and formatting as shown.

Once that has been done, you should be able to compile and build your game as normal and XCode will correctly create the required workspace and projects.

CocoaPods And The Marketplace

Setting up a CocoaPods extension as shown above will ensure that the extension can be uploaded to the Marketplace and that users who download it will be assured that the correct pods and dependencies will be used. However, you should always direct users to this page, as anyone downloading the extension will need to have installed CocoaPods on their Mac, otherwise the the project will not build and run correctly (if at all).