Building PSUnreal on macOS

Reference docs

• Downloading Unreal Engine source code: https://docs.unrealengine.com/en-US/GettingStarted/DownloadingUnrealEngine/index.html
• Compiling Unreal Engine source code: https://github.com/EpicGames/UnrealEngine/blob/release/README.md

Compiling Unreal Engine

Note: As of 2024, you need ~XXXGB of disk space for a compiled version of the Unreal Engine 5.

• Step 1: Install the latest version of Xcode.
  • Install the latest version of Xcode from the App Store.
  • Install the Command Line Tools by running xcode-select --install from a Terminal.

• Step 2: Get access to the Unreal Engine source code.
  • You must be an Unreal Engine subscriber (if not, open an account there: https://www.unrealengine.com)
  • You must have a GitHub account (if not, open an account there: https://github.com)
  • Have associated your GitHub account with your Unreal Engine account as described on the UE4 on GitHub page.
  • At this point you should be able to access the Unreal Engine repository on GitHub.

• Step 3: Get the Unreal Engine source code.
  • Get the source code with: git clone https://github.com/EpicGames/UnrealEngine.git --depth=1 --single-branch 5.4.3-release
  • This will create an 5.4.3-release sub-directory where you run the commands of the next step.

• Step 4: Prepare the Xcode workspace.
  • In the UnrealEngine directory, run the script Setup.command. It downloads 19.4GB of dependencies and may take a while.
  • At the same location, run the script GenerateProjectFiles.command. It generates the UE5 (Mac).xcworkspace Xcode workspace.

• Step 5: Compile Unreal Engine with Xcode.
  • Load the UE5 (Mac).xcworkspace into Xcode.
  • Select the "Project Navigator" icon (looks like a folder icon) on the left, then click on "Unreal Editor (Mac)" , the right panel will populate.
  • Click on "Signing and Capabilities" and leave "Team" empty, "Sign to run locally"
  • Click on "Build Settings", search "Signing Identity", remove everything there by clicking on "Others" and clearing the field. Or use Sign Run Locally. This way we disable the signing completely.
  • Select the ShaderCompileWorker > My Mac target in the title bar, then build with Product > Build menu item.
  • Click on the last icon "Report Navigator" , looks like a document, you can see here the log of the build. Wait for the build to complete.
  • Select the UnrealEditor > My Mac target, and build again.
  • Compiling may take a long time, depending on your system specs.
  • After the compilation finishes, select the 'Product > Run' menu item to load the editor.

• Step 6: set xcode tools
  • Open Xcode and go to Preferences>Locations and set the Command Line Tools or Unreal will give this error: "Xcode is not installed on this Mac ... Falling back to runtime text shaders, which are slower. "

• Launch the Editor to test if it works
  • You can launch the editor with \UnrealEngine\Engine\Binaries\Mac\UE4Editor.app

If you get this error:

 xcode command codesign failed with exit code 1 

Check the error log detail, I had some old files in /Users/luke/UnrealEngine/Engine/Binaries/Mac/UE4Editor.app/Contents/MacOS/ which I had to delete, and then it worked.

Obtaining PSUnreal

• Create PSUnreal dir

 > cd \
 > mkdir PSUnreal

• Install macports and svn command line
  • Install macports: Download https://distfiles.macports.org/MacPorts/MacPorts-2.6.2-10.15-Catalina.pkg

 > sudo port install subversion

Get the sources from the Planeshift repository.

• Open a Terminal and go to you home directory with

 > cd ~. We will build from there; adapt if needed.

• Checkout the sources from the PS Unreal repository with:

 > svn co svn://xxx.xxx.xxx/psunreal/PSUnreal PSUnreal

Building dependencies

MariaDB connector

• Build the MariaDB Connector from source.
  • Install prerequisites: sudo port install cmake jemalloc judy openssl boost gnutls
  • Download the MariaDB Connector for C (source code version) from https://downloads.mariadb.com/Connectors/c/connector-c-3.3.10/mariadb-connector-c-3.3.10-src.tar.gz
  • In your home directory: tar -xvf mariadb-connector-c-3.3.10-src.tar.gz.
  • From your terminal, cd ~/mariadb-connector-c-3.3.10-src, to go to the directory that contain the MariaDB Connector sources.
  • move the sources in PSUnreal: mv * /Users/luke/PSUnreal511/ThirdParty/MariaDB
  • cd /Users/luke/PSUnreal511/ThirdParty/MariaDB
  • Generate the makefiles with cmake . .
  • Build and install the connector in your PSUnreal source tree with make all install.
  • file /Users/luke/PSUnreal511/ThirdParty/MariaDB/libmariadb/libmariadb.dylib (check if it's arm64 or x86_64)

Wordnet

• Build Wordnet

 > cd /Users/luke/PSUnreal511/ThirdParty/Wordnet

Compiles the library for arm64 architecture:

 > gcc -shared -o Wordnet.dylib -fPIC *.c

Compiles the library for x86_64 architecture:

 > gcc -shared -arch x86_64 -o Wordnet.dylib -fPIC *.c

Compiles for arm64

> gcc -shared -arch arm64 -o Wordnet.dylib -fPIC *.c

libzip

• Obtain https://libzip.org with:

 > git clone git@github.com:nih-at/libzip.git

• In the newly created libzip directory, create a build sub-directory.

 > cd libzip
 > mkdir build

• In libzip/build run cmake as follows (this turns off all the options we do not need):

 > cd build
 > cmake -DENABLE_COMMONCRYPTO=OFF -DENABLE_GNUTLS=OFF -DENABLE_MBEDTLS=OFF -DENABLE_OPENSSL=OFF -DENABLE_WINDOWS_CRYPTO=OFF -DENABLE_BZIP2=OFF -DENABLE_LZMA=OFF ..

• Then build with:

 > make --build .

• Copy the libzip library and headers to the third party subfolder of PSUnreal.

 > cp lib/libzip.5.3.dylib PSUnreal/ThirdParty/Libzip/Libraries/Mac/libzip.5.dylib
 > cp ../lib/zip.h PSUnreal/ThirdParty/Libzip/Includes/.
 > cp zipconf.h PSUnreal/ThirdParty/Libzip/Includes/Mac/.

• Finalize the library.

 > cd PSUnreal/ThirdParty/Libzip/Libraries/Mac
 > install_name_tool

Create a signing certificate

(OPTIONAL) If you need to create a signing certificate, you can do it by opening XCode, click on the top menu "XCode" then "Preferences", then Accounts, and Manage Certificates.

Build PS Unreal.

• Generate project files (NO QUOTATION MARKS on -project option):

 > /Volumes/DATA-2TB/5.4.3-release/GenerateProjectFiles.command -project=/Users/luke/PSUnreal511/PSUnreal.uproject -game

• The resulting files should be directories, not files, like:

drwxr-xr-x@  5 luke  staff    160 Aug 24 18:10 PSUnreal (Mac).xcworkspace

• Launch XCode and open PSUnreal.xcworkspace
• Select the UE4 blue icon for the project on the left, and click on "Project Navigator" icon (looks like a folder icon)
• Click on "Signing and Capabilities" and leave "Team" empty, "Sign to run locally"
• Click on "Build Settings", search "Signing Identity", remove everything there by clicking on "Others" and clearing the field. Or use Sign Run Locally. This way we disable the signing completely.
• Build with Product > Build menu item.

Finalize PS Unreal

Note: The following should be added to the build process. To be done by hand for now.

• Copy Wordnet.dylib, libmariadb.3.dylib, libmariadb.dylib to inside folder ./PSUnreal.app/Content/MacOS.
• Modify the library paths in the main PSUnreal executable as follows:
  • install_name_tool -change /Users/luke/PSUnreal/ThirdParty/MariaDB/libmariadb/libmariadb.3.dylib @loader_path/libmariadb.3.dylib ./PSUnreal.app/Contents/MacOS/PSUnreal
  • install_name_tool -change Wordnet.dylib @loader_path/Wordnet.dylib ./PSUnreal.app/Contents/MacOS/PSUnreal
• Add file serverlist.xml to inside folder ./PSUnreal.app/Contents/UE4/PSUnreal/Config. (Config directory needs to be created)
• Finally, you can sign the app bundle with the following codesign -s <email> PSUnreal.app, where <email> is the E-mail for your Apple Development ID (check it in your Keychain Access app > My Certificates).

Troubleshooting

PSLauncher codesign error

I got this error while trying to build PSLauncher:

/usr/bin/codesign --force --sign - --entitlements /Users/luke/PSLauncher511/Binaries/PSLauncher\ \(Mac\).build/Mac/PSLauncher.build/PSLauncher-Mac-Shipping.app.xcent --timestamp\=none --generate-entitlement-der /Users/luke/PSLauncher511/Binaries/Mac/PSLauncher-Mac-Shipping.app
 /Users/luke/PSLauncher511/Binaries/Mac/PSLauncher-Mac-Shipping.app: code object is not signed at all
In subcomponent: /Users/luke/PSLauncher511/Binaries/Mac/PSLauncher-Mac-Shipping.app/Contents/MacOS/libzip.5.dylib
Command CodeSign failed with a nonzero exit code
** BUILD FAILED **
The following build commands failed:
        CodeSign /Users/luke/PSLauncher511/Binaries/Mac/PSLauncher-Mac-Shipping.app (in target 'PSLauncher' from project 'PSLauncher (Mac)')
(1 failure)
ERROR: Failed to finalize the .app with Xcode. Check the log for more information

I had to recompile the libzip located in ThirdParty and codesign it, otherwise when it's copied over the PSLauncher install during the build it fails on codesign.

XCode 16.0

After an update to Xcode 16.0 , I got this error while building UE 5.4.3 from Xcode

Platform Mac is not a valid platform to build.

I downgraded my XCode to 15.4 by downloading it from this page:

https://developer.apple.com/download/all/?q=xcode

Undecorated configuration

When building with PSUnreal.Target.cs modified with :

UndecoratedConfiguration = UnrealTargetConfiguration.Shipping;

I get this error

fatal error: cannot open file '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/__functional/operations.h': No such file or directory

The only way in 5.4.3 is to comment out the UndecoratedConfiguration line.

Could not create socket

https://forums.unrealengine.com/t/ue-5-4-3-macosx-shipping-build-could-not-create-socket-for-bind-address-and-error-initializing-network-layer/1990023

For some reason the "PSUnrealClient (Mac)" project in XCode, under "Signing & Capabilities" -> "App Sandbox" had "Incoming/Outgoing Connections" disabled. Must be enabled.

arm64 vs x86_64

When you are compiling you will see a tag on each line saying if you are compiling for arm64 [Apple] or for x86_64 [Intel], example:

[1681/3233] Compile [Apple] Module.LandscapeEditor.4.cpp
vs
[1681/3233] Compile [Intel] Module.LandscapeEditor.4.cpp

you can change the way the solution is compiled by using the -specifiedarchitecture and -architecture flags on RunUAT. For some reason after 5.4 upgrade the -architecture was not enough anymore, and I had to add also -specifiedarchitecture

Example:

-specifiedarchitecture=x86_64 -platform=Mac -architecture=x86_64

Unable to load module

If there is a problem like:

 Unable to load module '/Users/luke/PSUnreal/Binaries/Mac/UE4Editor-PSUnreal.dylib' because the file couldn't be loaded by the OS.
 OR
 The game module 'PSUnreal' could not be loaded. There may be an operating system error, the module may not be properly set up....

You can use otool to see the dependencies

 otool -L /Users/luke/PSUnreal/Binaries/Mac/UE4Editor-PSUnreal.dylib

If the problem is Wordnet then use this command:

 install_name_tool -change Wordnet.dylib @loader_path/Wordnet.dylib /Users/luke/PSUnreal/Binaries/Mac/UE4Editor-PSUnreal.dylib
 AND/OR
 install_name_tool -change /Users/luke/PSUnreal/ThirdParty/MariaDB/libmariadb/libmariadb.3.dylib /Users/luke/PSUnreal511/ThirdParty/MariaDB/libmariadb/libmariadb.3.dylib /Users/luke/PSUnreal511/Binaries/Mac/UnrealEditor-PSUnreal.dylib

After this command you should relaunch RunUAT, but without -build or it will recreate the same problem.

Your session has expired

While building , RunUAT is trying to read this URL: https://developerservices2.apple.com/services/QH65B2/viewDeveloper.action , but this URL gets a "Your session has expired. Please log in." message. This is the error in the log

DVTPortal: Error: Error Domain=DVTPortalServiceErrorDomain Code=1100 "Your session has expired. Please log in."

The problem seems to happen only if you run the build command from ssh, running it directly on the Mac works well.

Info.plist During compilation from XCode you may get this error:

Cannot code sign because the target does not have an Info.plist file and one is not being generated automatically. Apply an Info.plist file to the target using the INFOPLIST_FILE build setting or generate one automatically by setting the GENERATE_INFOPLIST_FILE build setting to YES (recommended).

Click on the left on the Folder icon, then PSUnreal, then on the right select "Build Settings", search for "Generate Info.plist File" and set it to YES.

During compilation from XCode you may get this error:

/Users/luke/UnrealEngine/Engine/Source/Runtime/Core/Public/Math/BigInt.h:964:9: variable 'Result' set but not used [-Werror,-Wunused-but-set-variable]

In this case open

Engine/Source/Programs/UnrealBuildTool/Platform/Mac/MacToolChain.cs

and change line 218 to this:

Result += " -Wall -Werror -Wno-error=unused-but-set-variable";

I got this error after XCode was updated to 13.0 , previous was 12.3.

/Users/luke/UnrealEngine/clang:1:1: no such sysroot directory: '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX12.3.sdk' [-Werror,-Wmissing-sysroot]

a clean build of everything, including Unreal Engine fixed this error.

AutomationTool exiting with ExitCode=25 (Error_UnknownCookFailure)

This error was not saying anything in the log file, so I had to

tail -f /Volumes/DATA-2TB/5.1.1-release/Engine/Programs/AutomationTool/Saved/Cook-2023.02.19-23.53.38.txt

and in that file the real error showed: "The game module 'PSUnreal' could not be loaded. " which is the otool thing.

Compilation on M1 hardware

  ld: warning: ignoring file /Users/luke/UnrealEngine/Engine/Source/ThirdParty/rd_route/lib/Mac/librd_route.a, building for macOS-arm64 but attempting to link with file built for macOS-x86_64
  ld: warning: ignoring file /Users/luke/UnrealEngine/Engine/Binaries/Mac/UnrealHeaderTool-BuildSettings.dylib, building for macOS-arm64 but attempting to link with file built for macOS-x86_64
  Undefined symbols for architecture arm64:
    "BuildSettings::GetBuildDate()", referenced from:
        FApp::GetBuildDate() in Module.Core.9_of_15.cpp.o
    "BuildSettings::GetBranchName()", referenced from:
        FApp::GetBranchName() in Module.Core.9_of_15.cpp.o
        FGlobalEngineVersions::FGlobalEngineVersions() in Module.Core.10_of_15.cpp.o
    "BuildSettings::GetBuildVersion()", referenced from:
        FApp::GetBuildVersion() in Module.Core.9_of_15.cpp.o
        FApp::PrintStartupLogMessages() in Module.Core.9_of_15.cpp.o
    "BuildSettings::IsPromotedBuild()", referenced from:
        FApp::GetEngineIsPromotedBuild() in Module.Core.9_of_15.cpp.o
    "BuildSettings::IsLicenseeVersion()", referenced from:
        FMacCrashContext::GenerateCrashInfoAndLaunchReporter() const in Module.Core.7_of_15.cpp.o
        FMacCrashContext::GenerateEnsureInfoAndLaunchReporter() const in Module.Core.7_of_15.cpp.o
        FGlobalEngineVersions::FGlobalEngineVersions() in Module.Core.10_of_15.cpp.o
    "BuildSettings::GetCurrentChangelist()", referenced from:
        FGlobalEngineVersions::FGlobalEngineVersions() in Module.Core.10_of_15.cpp.o
    "BuildSettings::GetCompatibleChangelist()", referenced from:
        FNetworkVersion::GetNetworkCompatibleChangelist() in Module.Core.10_of_15.cpp.o
        FGlobalEngineVersions::FGlobalEngineVersions() in Module.Core.10_of_15.cpp.o
  ld: symbol(s) not found for architecture arm64

https://forums.unrealengine.com/t/building-shipping-package-on-mac-m1-for-intel-architecture/685206

Was giving me again the problem, what I did was to go on the macmini, and recompile UnrealHeaderTool forcing x86_64 architecture, then the compilation worked

Exceeded max memory on all configured triggers

Change BaseEditor.ini

    MemoryMinFreePhysical=1024

    MemoryMinFreeVirtual=1024

Detected max mem exceeded - forcing shader compilation flush

    MemoryMinFreePhysical=256

Running a local server

Prepare the server database

• Connect to your database as root, create the planeshift database and user.

 > mysql -u root -p

 mysql> CREATE DATABASE planeshift;
 mysql> CREATE USER 'planeshift'@'localhost' IDENTIFIED WITH mysql_native_password BY 'planeshift';
 mysql> GRANT ALL PRIVILEGES ON planeshift.* TO 'planeshift'@'localhost';
 mysql> quit

• Connect to the database as planeshift, populate the database (adapt psunreal_mysql_XXXXXXXX.sql to the currently available file).

 > cd PSUnreal\Scripts
 > mysql -u planeshift -pplaneshift

 mysql> USE planeshift;
 mysql> SOURCE psunreal_mysql_XXXXXXXX.sql;
 mysql> quit

• If you need to upgrade your database, perform the following as root, and re-populate the database as done above.

 > mysql -u root -p

 mysql> DROP DATABASE planeshift;
 mysql> CREATE DATABASE planeshift;
 mysql> GRANT ALL PRIVILEGES ON planeshift.* TO 'planeshift'@'localhost';
 mysql> quit