# Building with Xcode

Homebrew is fine and good, but for macOS, building with Xcode is preferred. It is also the only way to build universal binaries at the moment. The only prerequisites here are downloading the [current](https://apps.apple.com/us/app/xcode/id497799835?mt=12) or [older](https://developer.apple.com/download/more/?=xcode) version of Xcode, and [installing Homebrew](https://brew.sh/).

## Setting Up Command Line Tools

After Xcode has been installed, open the settings through either the menu bar or the **⌘+,** keyboard shortcut.

![](https://4194526085-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Ly3C4Vp3GTOeBYj2WYY%2F-MPOpQ1lAmoc_rnLTCec%2F-MPOrhVEySNog2aO_3I0%2Fimage.png?alt=media\&token=68e95cc6-6eb7-4d52-9bd0-65177c8b41e4)

Move to the **Locations** tab, set **Derived Data** to "Relative" (this isn't necessary, but it makes the build result easier to find), and set **Command Line Tools** to your current version of Xcode.

![](https://4194526085-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Ly3C4Vp3GTOeBYj2WYY%2F-MPOpQ1lAmoc_rnLTCec%2F-MPOsWiQnnufZGYpKVpe%2Fimage.png?alt=media\&token=86d1d821-a652-4cef-bbf4-4f3c69e0645d)

## Setting Up the Repository

Now, to clone the repository, open up your terminal and run:

```
cd $HOME/Documents
git clone https://gitlab.com/mkxp-z/mkxp-z --recursive $HOME/Documents/mkxp-z
cd $HOME/Documents/mkxp-z/macos/Dependencies

brew bundle
```

{% hint style="warning" %}
If you intend to integrate your game with Steam, you will first need to:

1. [Download Steamworks](https://partner.steamgames.com/downloads/steamworks_sdk.zip).
2. Move the `sdk` folder contained inside to `macos/Dependencies/Frameworks/steam` within the repository's folder.
3. That's it. Make sure it's done *before* you run `setup.command` in a minute. If you already have, you can just run it again.
   {% endhint %}

## Building mkxp-z

{% hint style="info" %}
When debugging through Xcode (or when mkxp-z is launched with the `MKXPZ_SELECT_PATH` environment variable is set to `1`), you will be asked to select a path pointing to the location of the game you want to launch.

Normally, however, relevant game files must be placed within `Contents/Game` within mkxp-z's application bundle, unless it has been set otherwise within the json configuration.
{% endhint %}

### Debugging

Cool, now you've got all that done, the rest is pretty simple. The repository has been downloaded to your Documents folder, so you can either go there yourself, or type this last thing into the terminal: `open ~/Documents/mkxp-z`.

Navigate to `macos`  and open `setup.command` by double clicking it. It will build all the dependencies that mkxp-z needs to run, and might take a while.

Once it's done, open the Xcode project, and open the **Schemes** menu in the title bar.

![Select the scheme that is most relevant to you.](https://4194526085-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Ly3C4Vp3GTOeBYj2WYY%2Fuploads%2FvjjOpLKcgqf4bHjp87th%2Fimage.png?alt=media\&token=39786029-5453-4068-b0ca-c9aba31c265a)

Select the scheme that is most relevant to you. This is probably either the **Universal**  or **Universal (Steam)** scheme. If the version of Xcode you are using is older than 12, you must use either the **Intel** or **Intel (Steam)** scheme. *(Building the Universal Steam scheme requires a version of Steamworks >= 1.52).* You should also make sure that **My Mac** is selected as the build target; debugging might not work otherwise.

Now, you can build the app by clicking the debug icon on either Xcode's sidebar, or your Touch Bar (if you have one).

If you set your DerivedData location to relative, you can find the build results in the same folder as the Xcode project.

#### Setting Your Steam App ID

If you are building with Steamworks integration, mkxp-z will look for `steam_appid.txt` within the `Contents/Resources` subfolder of the bundle. If you would like to have the app use `SteamAPI_RestartAppIfNecessary` rather than the default behavior, set `STEAM_APP_ID` in `macos/config/steam/steamshim.xcconfig`.

### Distribution

mkxp-z must be built in Debug mode, otherwise ANGLE will break and no display will be shown in the game's window. Therefore, all you need to do is change your build target from **My Mac** to **Any Mac**, then build the application with **Command+B**. The result can found in `DerivedData` within the repository's `macos` subdirectory if you set the build directory to relative. If not, you can choose **Product > Show Build Folder in Finder** from the menu bar.