Unreal Engine 4.26 Documentation

Unreal Engine 4.27 Documentation

Unreal Engine 5.0 Documentation

Unreal Engine 5.1 Documentation

Unreal Engine 5.2 Documentation

> Sharing and Releasing Projects > Mobile Game Development > iOS Game Development > Debugging iOS and tvOS Projects > Debugging iOS Projects With Xcode

Light Theme

Dark Theme

Debugging iOS Projects With Xcode

Use Xcode to launch your project on device and debug with break points and LLDB commands.

Choose your operating system:

Windows

macOS

Linux

On this page

1. Required Setup
2. Cooking Content for iPhone
3. Compiling and Launching Your Project in Xcode
4. Additional Information

To debug Unreal Engine games on iOS, you will need to cook and package your project, then use Xcode to rebuild your code with debugging support. This page will walk you through the steps you should follow any time you need to debug a new build.

1. Required Setup

To create a build for iOS or tvOS devices, you must set up your code signing certificate and provisioning profile for your application, otherwise it will fail to build and deploy to your iOS device in later steps. Refer to iOS Provisioning for more information on this process.

If you are building a C++ project, you must also have an XCode project for your application. Locate your project's .uproject file, control-click it, then click Generate Xcode Project to create one if you have not already.

2. Cooking Content for iPhone

Before you can debug on iPhone, you need to use the Unreal Editor** to cook and package your game's content. The reason you need to do this is because XCode can compile your game's source code, but it cannot cook content. Therefore, any time there are significant changes to your game's content, you should remember to re-package everything before you move to XCode for debugging.

You can package your game by clicking File > Package Project > iOS in the Unreal Editor. For more information about the prerequisites needed to package iOS projects, refer to Packaging iOS Projects.

3. Compiling and Launching Your Project in Xcode

Once you have packaged your game, you need to rebuild it in Xcode with debugging support enabled. This will replace the binaries and executable generated by Unreal Engine's packaging process.

Open your application's Xcode project. In Xcode, from the main menu, select Product > Scheme > Edit Scheme.
Click the Run category, then change your Build Configuration to DebugGame.

If you are using a source code build of Unreal Engine, you can use the Debug configuration to debug the engine code.

Change the target device from My Mac to the iPhone you have connected.
Click the Build and Run button to start building the project from Xcode and launch it on the device.

Once you have completed these steps, the project will build and launch on your device. From here, you can use breakpoints, logs, and LLDB commands to debug your project and examine information at runtime.

4. Additional Information

For more information about how to use Xcode's debugging features, refer to Apple's developer documentation on Debugging With Xcode.

For more information about LLDB, refer to the Getting Started with LLDB page in Apple's documentation archive.