Modernized Xcode Workflow

Unreal Engine (UE) from 5.3 onward updates the Xcode project workflow for Unreal Engine to be more consistent with standard Xcode app projects. The new project setup improves organization and quality of life for Xcode developers and provides access to several tools within Xcode to streamline codesigning and provisioning, including:

• Automatic Code-Signing

• Managing entitlements

• Editing .plist files

• Standard Xcode framework handling

This page overviews the changes for users transitioning to UE 5.3 and newer (5.3+) from earlier versions.

Prerequisites

The updated Xcode workflow is available for UE 5.3 and newer, and is enabled by default for new projects. If you need to enable it manually, however, follow these steps:

1. Open your engine's install directory, open Engine/Config/BaseEngine.ini, and make sure that you set the following config variable:

   Engine/Config/BaseEngine.ini

   C++

   [/Script/MacTargetPlatform.XcodeProjectSettings]
        bUseModernXcode=true

   Copy full snippet(2 lines long)

2. Regenerate your Xcode project files for both the engine and your project. If you are using a source build of UE, run the GenerateProjectFiles.command script in your engine install directory to regenerate the project files for UE's source code. You should see three Xcode workspace files in your project's directory:

   • UE5 (Mac).xcworkspace

   • UE5 (TVOS).xcworkspace

   • UE5 (IOS).xcworkspace

The new Xcode setup is now ready to use. The following sections explain what's new compared to the old project setup.

Projects, Schemes, and Build Configurations

Previously, UE Xcode projects combined targets and build configurations under Schemes. For example, under a single project (MyProject), users had a "Development Editor" scheme that built a Development build of an Editor target.

UE 5.3+ provides a separate Xcode project (within the same Xcode workspace) for each target type. For example, an Xcode workspace for a project titled "MyProject" would have a separate project for MyProjectEditor, MyProjectGame, MyProjectClient, and MyProjectServer.

Each target has only the build configurations it supports. For example, most editors do not support Test or Shipping configuration, so they are unavailable under Editor projects.

Updated workspaces have a large number of schemes. When looking through them, use the Filter and the Recent section to narrow your list as needed.

Per-Platform Workspaces

Previously, when UE generated project files, it created one monolithic workspace that included targets for each of Apple's platforms.

In UE 5.3+, when UE generates project files, it creates a separate workspace for each Apple platform.

This simplifies workspaces and projects, and since Xcode can open multiple workspaces, you can toggle between platforms by pressing Command + ` (backtick).

Each workspace only contains the targets that support that platform, so iOS and tvOS have fewer schemes available. They do have an UnrealEditor target, but it can't successfully build. Instead, these targets are present to make the source code available for searching.

Self-Contained Apps

Previously, UE bundled all the data needed to run iOS, iPadOS, and tvOS apps into their respective .app files, making them self-contained. However, macOS projects split the data between the .app, the Saved/Cooked/Mac directory, and other locations in the Engine and Project directories.

In UE 5.3+, all Mac platforms use the same workflow, which gathers the needed data into one location and bundles it into a .app that you can run manually or with Xcode. To do this, you need to use the Stage step in the cooking process.

Package and Distribute

The packaging processes for macOS and iOS/tvOS/iPadOS are now fully consistent with one another.

Distribution

Distribution mode no longer codesigns using a Distribution certificate. Instead, it creates a standard Xcode archive (.xcarchive), which you can use to distribute the .app to various destinations, such as the App Store or your team. When making distribution builds, Xcode also generates a .dSYM file to put into the Xcode archive, which is useful for debugging crashes and can be sent to Apple for debugging live crashes. You submit your .dysm alongside your app when uploading your app to Apple for submission.

To package normally, click Platforms > Package Project in Unreal Editor, or add -package -clientconfig=Shipping to your BuildCookRun command line.

To package for distribution, check the Distribution check box in your Project Settings, or add -package -clientconfig=Shipping -distribution to your BuildCookRun command line.

Alternatively, you can click Product > Archive in Xcode.

Xcode uses the standard flow to generate a .xcarchive, including bringing in the Staged directory and codesign frameworks. This uses the Shipping configuration, even if you set the scheme to Development.

If you use Archive in Xcode, it automatically opens the Archives window and selects the new archive. If you use other UE methods to create it, you have to manually open the window by clicking Window > Organizer, then select your project and Archives in the upper left.

Use the buttons on the right of the Archives window to Validate or Distribute your app. You can use this to create an iOS .ipa file for internal usage by following the prompts for each option. For App Store validation/distribution, you must make an App entry at appstoreconnect.apple.com.

The prompts for distributing or validating your app may require you to choose a Distribution certificate or follow other provisioning steps. Refer to Apple's documentation for more information.

Archiving in Xcode uses Shipping because it is the default configuration for the Archive action in the scheme UE generates. Additionally, -package -distribution will use the archive Xcode action in the background instead of the build action.

You can change this in the Scheme if needed for testing, but we recommend only distributing Shipping builds.

Configure Your App's Display Name on MacOS

Your app's display name is the name of the Mac .app when making an archived build. When you package for distribution (or using Archive menu in Xcode), the display name is the name of the .app that users see when using Finder. If this is not set, the .app will have the same name as the .uproject file. To change your display name in UE 5.3.2 and newer, open your MacEngine.ini file and set the ApplicationDisplayName config variable:

MacEngine.ini

[Xcode]
	ApplicationDisplayName="Friendly Application Name"

Content/Blueprint-Only Projects

Because content-only (or Blueprint-only) projects do not have an Xcode project or build target source files, they re-use the generic UnrealGame targets from the engine combined with their project-specific data to create a build.

Standard Xcode Practices

The updated Xcode workflow uses Xcode to handle as many components according to the standard Xcode workflow as possible, including:

• Codesigning.

• .plist files.

• Entitlements files.

• Frameworks.

Codesigning

Previously, only iOS/iPadOS/tvOS required codesigning. As of 2023, Apple also requires codesigning for macOS. The updated workflow uses Xcode's Automatic Codesigning for all platforms by default.

To use Automatic Codesigning, follow these steps:

1. Log into your Apple Developer Account in Xcode.

2. Open your Project Settings, then locate Platforms > Xcode Projects and set the following properties:

   

Find Your Team ID

To find your Team ID for the Modern Signing Team setting, open the Apple Developer Page, log into your account, and click Membership Details. Your Team ID is displayed.

.plist Files

Every app needs to include an embedded .plist file. The final .plist file is usually made from a partial (template) that Xcode will modify based on Xcode project settings. Due to UE generating Xcode projects, this can be a complicated process.

The updated Xcode workflow provides high-level control over .plist file handling. Additionally, editing of the .plist settings in Xcode is now supported

Template vs Premade

It is preferred for Xcode to finalize the .plist in the app using settings from the UE-generated Xcode project. However, UE also supports premade .plist files that Xcode will not modify. Because this is an advanced feature, it is not exposed in the Xcode Project Settings and requires editing a config file. Refer to Use a Premade .plist below for instructions.

The .plist settings in your Project Settings (the Mac Target Info.plist and IOS Target Info.plist items) provide a way to specify either the default Template .plist, or your own custom Template .plist.

The default locations for the Template.plist files are in your project's Build/IOS directory. When UE generates Xcode project files for your project, it will look to see if you have a Template .plist file in your project, and if it is not present, it will copy a .plist from the engine into your project folder.

The UnrealEditor target has a unique .plist, as the .app is shared across all projects. This is something most users will not have to deal with.

Use a Premade .plist

If you want to use a premade .plist, modify your DefaultEngine.ini file, and set one or both of the following settings with paths to the files you want to use:

DefaultEngine.ini

[/Script/MacTargetPlatform.XcodeProjectSettings]
	PremadeMacPlist=(FilePath="/Game/Build/Mac/Resources/MyGameMac.plist")
	PremadeIOSPlist=(FilePath="/Game/Build/IOS/Resources/MyGameIOS.plist")

Restore a .plist to Default

You can also use the Restore Info.plist to default button to re-copy the Engine directory's Mac default Template .plist file to your project, and set the values appropriately. This can be useful if you want to use updated default .plist files in future UE versions.

You can take a .plist file out of a generated app and use that as the source for a premade .plist.

Privacy Manifests

Xcode uses Privacy Manifests to summarize what kind of data your app collects about its users and why it collects that data. This includes data collected by your own code as well as third-party SDKs you are using. When you distribute your app, Xcode combines the privacy manifests for your SDKs and your app into a single privacy report, making it easy to provide users with transparent information about your app's privacy practices.

UE provides default privacy manifests in the following locations:

• MacOS: Engine/Build/Mac/Resources/UEMetadata/PrivacyInfo.xcprivacy

• iOS, tvOS, and iPadOS: Engine/Build/iOS/Resources/UEMetadata/PrivacyInfo.xcprivacy

Projects using additional privacy functions need to provide an additional PrivacyInfo.xcprivacy file in the location specified by their UE project settings. By default, these are:

• MacOS: /Game/Build/Mac/Resources/PrivacyInfo.xcprivacy

• iOS, tvOS, and iPadOS: /Game/Build/IOS/Resources/PrivacyInfo.xcprivacy

For more information, refer to Apple's documentation on Privacy Manifests.

MacOS vs. iOS

Working with .plist files differs between macOS and iOS in the new Xcode workflow because UBT has deeply-embedded logic for generating iOS .plist files. Bringing that logic over to the project generator/Xcode was not feasible.

If you look at the default settings for UBT, you can see that it points to /Game/Build/IOS/UBTGenerated/Info.Template.plst**,** which indicates that every time UBT runs, it can potentially change the contents for iOS .plists.

However, you can change the project setting to use your template (or premade) .plist file, which will ignore what UBT generates. If you do that, you can use Xcode to edit the .plist file.

The following is an overview of the differences between Mac and iOS .plist files:

Entitlements

Every app designates Entitlements as part of codesigning. Entitlements control some Apple-made features or restrictions, such as GameCenter support or running in the Mac security Sandbox.

UE's Xcode project generation treats entitlements similarly to the (Mac) .plist files above. UE generates an Xcode project, and if there is no Entitlements file in the default location in the project, the default is copied from the Engine directory. You can then use Xcode (or a text editor) to modify the entitlements, which are are located under Build/Mac/Entitlements or Build/IOS/Entitlements in your project.

If you have different Sandbox restrictions or other differences in what you ship to end users, you can set separate entitlements for Shipping and Development. You should point them at the same file if you don't need separate features.

The following are the default entitlement settings for macOS and iOS:

Frameworks

Frameworks are an Xcode system for collecting headers, libraries, and content. The new Xcode workflow now handles Frameworks using standard Xcode methods instead of manually copying and codesigning as with the previous workflow. When UE generates an Xcode project, it uses the build system to find the referenced Frameworks set in various build source files. It then sets up the Xcode project to copy dynamic libraries and content into the app bundle, and codesign as needed.

Access Logs

Log files can appear in different locations depending on your sandbox settings and how you are running your application:

• If Sandbox is enabled:

  • Running through xcode: ~/Library/Logs/[project name]

  • Running by double-clicking or by using terminal: ~/Library/Containers/[your app's bundle ID]/Data/Library/Logs

• With Sandbox disabled:

  • ~/Library/Logs/[project name]