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 Studio 2 project. This means that you no longer have to supply the frameworks and SDKs directly within your GameMaker Studio 2 projects, as these will be "pulled in" by the Cocoa Pods system when the app is built in XCode.
NOTE: If you have downloaded an extension that uses CocoaPods from the Marketplace, then you only need to follow the section "Installing CocoaPods", below, to be able to use it.
To be able to use the features that CocoaPods offers, you will first need to install it on your Mac. This is covered by the official CocoaPods setup guide, available from the link below. However, please note that for GameMaker Studio 2 to work correctly and interface with CocoaPods, you must use the Sudo-less Installation.
NOTE: If you don't have a .bash_profile, you can create one by doing the following:
- Start up Terminal
- Type "cd ~/" to go to your home folder
- Type "touch .bash_profile" to create your new file.
When you've followed the guide linked above, you will have created a .bash_profile file and now 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:
You only need the first part of the path listed, which you can now add into your .profile file with the following format:
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:
and you should get back one of the following:
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:
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 Studio 2 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 Studio 2 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 Studio 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 Studio 2 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:
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 to an extension in your project. You can get CocoaPods by searching the following page for those that you require:
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 Cocoa Pod to add to GameMaker in an extension. In the case of the example image above for Google Analytics, the instillation 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 Studio 2 for your extension. To add this to an extension you would first create the extension, then select the "iOS" or "tvOS" option in the Extra Platforms, and in the CocoaPods section, add the pod name:
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 (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:
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 paste it into CocaoPods Dependencies section of your extension, as shown below:
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 cocoa pods on their Mac, otherwise the the project will not build and run correctly (if at all).