How to change the Xcode version for compiling Unreal Engine 4

From time to time we like to share things we learn when developing our games. In this technical blog post, we'll cover how to change what version of Xcode is used by Unreal Engine to compile C++ projects for iOS.

We recently had to change what version of Xcode we were using to compile a project for iOS, due to a crash when trying to compile with Xcode 8.3 (which at the time of writing had just been released by Apple). You can find the AnswerHub question about the issue here: https://answers.unrealengine.com/questions/583010/error-in-unrealmathneonh-when-packaging-for-ios.html)

Update! The underlying bug that caused the issue with compiling using Xcode 8.3 has been fixed as of the Unreal Engine 4.15.2 hotfix! See the end of this tutorial for information on resetting back to the default Xcode installation.

After some time diagnosing the issue, we decided to try compiling our game in a previous version of Xcode. While this is doable, it's not that straight forward of a process, so we decided to write up a tutorial about it.

Here's a tutorial on how to change what version of Xcode you're using to compile your Unreal Engine projects, and how to then recompile a project targeting iOS, after changing Xcode versions:

Download the version of Xcode you need from Apple's Developer Portal by going to https://developer.apple.com/download/more/ and searching for Xcode (Note: you have to be a registered Apple Developer to get older versions of Xcode then what's publicly available on the Mac App Store)

Unzip the downloaded Xcode into to its own folder in Applications (a folder called Xcode_8_2_1, where 8_2_1 is a stand-in for the version number 8.2.1, is a good naming convention).

Before opening the downloaded version of Xcode, we recommend verifying the app signing identity of the downloaded new (old) Xcode using the spctl Terminal command (you can never be too safe).

To verify the identity of your copy of Xcode run the following command in Terminal on a system with Gatekeeper enabled:

spctl --assess --verbose /path/to/Xcode.app

For a version downloaded from the Apple Developer web site, the result should read either

/path/to/Xcode.app: accepted source=Apple

~ or ~

/path/to/Xcode.app: accepted source=Apple System

If the output doesn't match either of these *DON'T OPEN* the copy of Xcode, instead delete the copy of Xcode immediately, and re-download Xcode form Apple's Developer Portal.

Now that that's done, we need to set this new (old) Xcode as the default Xcode on your Mac using the xcode-selectcommand in the Terminal. This has to be done because the Unreal Build Tool uses whatever Xcode is set as the default when compiling code, generating project files, etc.

Here's the command (Note that it requires the use of sudo, so you will need to have Administrator privileges on your Mac before proceeding.)

sudo xcode-select -switch Xcode.app

Now we need to regenerate Xcode project files by right-clicking on your project's .uproject file, then under Services select "Generate Xcode Project" (you should see a message in Terminal about "Compiling with non-standard Xcode (xcode-select): ", which is what you want)

Open your new (old) version of Xcode.

- Note: you may get pop-ups about Xcode wanting to access your Keychain, this is fine, it's just wanting to gather developer certificates and profiles on your system)

Now run Product --> Clean to get rid of Precompiled Headers from other versions of Xcode.

Due to a bug with the Clean command in the Unreal Build Tool, after running Clean you have to Verify your Engine install. Go to the Epic Games Launcher. In Library, click the arrow next to Launch on your Engine version, and click Verify. This will take a few minutes.

After verifying your Engine install, go back into the new (old) Xcode and run Product --> Build --> For Profiling to build your project to run in the Editor. Depending on project size and complexity, this could take a few minutes.

Next, open your project's .uproject file.

You may get a pop-up about needing to rebuild modules. Go ahead and rebuild them now.

- Note: you may see a message about compiling with a non-standard Xcode. As long as the file path is pointing to the new (old) Xcode you downloaded, you're good to go.

Once your project's completed recompiling modules and has opened, now it's time to make a build for iOS. First, check that your Mobile Provisions are all set (in Project Settings --> iOS --> Mobile Provision).

If everything looks in order, you can now package for iOS:

- The Output Log should mention about "Compiling with non-standard Xcode (xcode-select) " So long as the file path points to the Xcode you downloaded, then you're good to go.

When the Editor is done packaging, you'll have a fresh iOS build of your game!

One more thing: if (when) you need to change back to the "default" version of Xcode on your Mac, then you can enter this command into the Terminal:

sudo xcode-select --reset

This will reset the command line tools back to the default Xcode installation. (Note the use of "sudo", which requires you to enter your administrator password).