Updated MacOS instructions for UE 5.4.

david-lively · david-lively · commit 9e67e04d0b83 · 2025-07-02T11:28:00.000-05:00
diff --git a/Documentation/developer-setup-osx.md b/Documentation/developer-setup-osx.md
@@ -6,10 +6,12 @@ Detailed instructions for setting up a Cesium for Unreal development environment
 # Prerequisities
 
 - Install CMake (version 3.15 or newer) from https://cmake.org/install/
-- Install Xcode 14.2+ from https://developer.apple.com/xcode/resources/
+- Install Xcode 14.1+ from https://developer.apple.com/xcode/resources/
 - For best JPEG-decoding performance, you must have [nasm](https://www.nasm.us/) installed so that CMake can find it. Everything will work fine without it, just slower.
 - Install the minimum supported version of Unreal Engine (version 5.4 as of this writing) from https://www.unrealengine.com/en-US/download
 
+These instructions are intended for Unreal Engine 5.4. The process is similar for newer versions of Unreal Engine. Supported Xcode versions are specified in `/Users/Shared/Epic Games/UE_5.4/Engine/Config/Apple/Apple_SDK.json`.
+
 # Cloning the git repos
 
 The following illustrates the recommended directory layout for developers:
@@ -35,88 +37,14 @@ git clone --recursive https://github.com/CesiumGS/cesium-unreal.git
 git submodule update --init --recursive
 ```
 
-# Setting up Xcode
-
-Unreal Engine 5.3 requires a version of Xcode _no later_ than Xcode 15.x. This means that Xcode 16, which is the earliest version supported on macOS 15.3 Sequoia, cannot be used to build a UE 5.3 project without some tricks. You will see an error like this when you attempt to generate project files:
-
-> Exception while generating include data for UnrealEditor: Platform Mac is not a valid platform to build. Check that the SDK is installed properly.
-
-We have a few options:
-
-1. Use an earlier version of macOS
-2. Use a later version of Unreal Engine
-3. [Hack UnrealBuildTool to allow us to build for UE 5.3 using Xcode 16](#modify-unrealbuildtool-for-xcode-16)
-4. [Hack Xcode 15.4 to run on macOS 15.2 Sequoia](#modify-xcode-for-sequoia)
-
-## Modify UnrealBuildTool for Xcode 16
-
-The source code for the UnrealBuildTool is installed with Unreal Engine, which makes it easy to modify it for our purposes. The file to edit in Unreal Engine 5.3 is here (or equivalent on your system):
-
-```
-/Users/Shared/Epic Games/UE_5.3/Engine/Source/Programs/UnrealBuildTool/Platform/Mac/ApplePlatformSDK.Versions.cs
-```
-
-Find a line in that file that looks like this:
-
-```
-MaxVersion = "15.9.9";
-```
-
-If you have Xcode 16, change it to:
-
-```
-MaxVersion = "16.9.9";
-```
-
-Now we need to build our modifications into a new binary, which we can do by running:
-
-```
-cd "/Users/Shared/Epic Games/UE_5.3/Engine/Source/Programs/UnrealBuildTool"
-"/Users/Shared/Epic Games/UE_5.3/Engine/Binaries/ThirdParty/DotNet/6.0.302/mac-x64/dotnet" build UnrealBuildTool.csproj
-```
-
-> [!note]
-> The path to the `dotnet` executable may be different in different Unreal Engine versions. You can also install a system `dotnet` if desired with `brew install dotnet`.
-
-This will build UnrealBuildTool to the place all of Unreal's build scripts expect to find it. You should now be able to [generate project files](#building-cesium-for-unreal) successfully.
-
-However, because this version of Unreal Engine has not been tested on this Xcode version, you may run into compiler errors, and these may be easy or difficult to fix. With Unreal Engine 5.3 and Xcode 16.2, you'll likely see errors like this:
-
-> /Users/Shared/Epic Games/UE_5.3/Engine/Source/Runtime/RenderCore/Public/ShaderParameterStructDeclaration.h:22:3: encoding prefix 'u' on an unevaluated string literal has no effect and is incompatible with c++2c [-Werror,-Winvalid-unevaluated-string]
-
-We can "fix" this by suppressing this warning. Open `/Users/Shared/Epic Games/UE_5.3/Engine/Source/Runtime/Core/Public/Apple/ApplePlatformCompilerPreSetup.h` and add a line to disable this warning:
-
-```
-#pragma clang diagnostic ignored "-Winvalid-unevaluated-string"
-```
-
-## Modify Xcode for Sequoia
-
-It's possible to run Xcode 15.4 on macOS 15.3 Sequoia, and probably later versions:
-
-* Download Xcode 15.4 from https://developer.apple.com/download/all/.
-* Extract the download to your home directory:
-
-```
-cd
-xip -x ./Downloads/Xcode_15.4.xip
-mv Xcode.app Xcode_15.4.app
-```
-
-* Launch this version of Xcode:
-
-```
-./Xcode_15.4.app/Contents/MacOS/Xcode
-```
-
-* Xcode should launch and ask you to select or create a project. Choose `Xcode` on the menu at the top and then `Settings`. Click the `Locations` tab.
-* Under `Command Line Tools` choose `Xcode_15 15.4`.
-
 # Building cesium-native
 
 The cesium-native libraries and their dependencies use CMake and must be built separately from Cesium for Unreal. Cesium for Unreal supports both Intel and Apple Silicon processors. In development, we usually just want to build for the host's architecture, which is done as follows:
 
+(It may be helpful to place these commands in a shell script for future use.)
+
 ```
+export UNREAL_ENGINE_ROOT='/Users/Shared/Epic Games/UE_5.4'
 cd ~/dev/cesium-unreal-samples/Plugins/cesium-unreal/extern
 cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
 cmake --build build --target install --parallel 14
@@ -125,11 +53,13 @@ cmake --build build --target install --parallel 14
 Or to build a Release version:
 
 ```
+export UNREAL_ENGINE_ROOT='/Users/Shared/Epic Games/UE_5.4'
 cd ~/dev/cesium-unreal-samples/Plugins/cesium-unreal/extern
 cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo
 cmake --build build --target install --parallel 14
 ```
 
+
 This will install the built libraries to one of these subdirectories of `~/dev/cesium-unreal-samples/Plugins/cesium-unreal/Source/ThirdParty/lib/`, depending on your configuration and processor architecture:
 
 * `Darwin-arm64-Debug` - Debug configuration for Apple Silicon.
@@ -190,6 +120,7 @@ Configure the CMake project in the `~/dev/cesium-unreal-samples/Plugins/cesium-u
 Execute the following commands to build and install a Release version of cesium-native:
 
 ```
+export UNREAL_ENGINE_ROOT='/Users/Shared/Epic Games/UE_5.4'
 cd ~/dev/cesium-unreal-samples/Plugins/cesium-unreal/extern
 cmake -B build-ios -S . -GXcode -DCMAKE_TOOLCHAIN_FILE="unreal-ios-toolchain.cmake" -DCMAKE_BUILD_TYPE=Release
 cmake --build build-ios --target install --config Release --parallel 14
@@ -210,23 +141,23 @@ Now we can generate Xcode project files for the Samples project and the plugin:
 
 ```
 cd ~/dev/cesium-unreal-samples
-"/Users/Shared/Epic Games/UE_5.3/Engine/Build/BatchFiles/Mac/GenerateProjectFiles.sh" -game -project="$PWD/CesiumForUnrealSamples.uproject"
+"/Users/Shared/Epic Games/UE_5.4/Engine/Build/BatchFiles/Mac/GenerateProjectFiles.sh" -game -project="$PWD/CesiumForUnrealSamples.uproject"
 ```
 
 You may see an error message like this:
 
 > Your Mac is set to use CommandLineTools for its build tools (/Library/Developer/CommandLineTools). Unreal expects Xcode as the build tools. Please install Xcode if it's not already, then do one of the following:
 >   - Run Xcode, go to Settings, and in the Locations tab, choose your Xcode in Command Line Tools dropdown.
 >   - In Terminal, run 'sudo xcode-select -s /Applications/Xcode.app' (or an alternate location if you installed Xcode to a non-standard location)
-> Either way, you will need to enter your Mac password.
+      > Either way, you will need to enter your Mac password.
 
 In which case, do what it says.
 
 If you see a message like this:
 
 > Exception while generating include data for UnrealEditor: Platform Mac is not a valid platform to build. Check that the SDK is installed properly.
 
-It probably means Unreal doesn't like your Xcode version. Be sure that Xcode is installed and that you have followed the [Xcode setup instructions](#setting-up-xcode).
+It probably means Unreal doesn't like your Xcode version. Be sure that a supported version of Xcode is installed.
 
 If the project file generation succeeds, you should see a file named `CesiumForUnrealSamples (Mac).xcworkspace` in the same directory as your uproject. Double-click it to open Xcode.
 
@@ -247,7 +178,7 @@ To get a call stack from a crash on an iOS device...
 - Copy this file to a separate directory.
 - Convert it to a .crash file using https://github.com/tomieq/AppleCrashScripts and convertFromJSON.swift. The input path must be a relative path, not an absolute one. So run it in the directory where you copied the ips file above.
   - `swift ~/github/AppleCrashScripts/convertFromJSON.swift -i dev-IOS-DebugGame-2025-02-06-204209.ips -o dev-IOS-DebugGame-2025-02-06-204209.crash`
-- Run symbolicatecrash, which comes with Xcode but is buried here /Applications/Xcode.app/Contents/SharedFrameworks/DVTFoundation.framework/Versions/A/Resources/
+- Run `symbolicatecrash`, which comes with Xcode but is buried here /Applications/Xcode.app/Contents/SharedFrameworks/DVTFoundation.framework/Versions/A/Resources/
   - `export PATH=$PATH:/Applications/Xcode.app/Contents/SharedFrameworks/DVTFoundation.framework/Versions/A/Resources/`
   - `export DEVELOPER_DIR=$(xcode-select --print-path)`
   - `symbolicatecrash ./dev-IOS-DebugGame-2025-02-06-204209.crash`
