Debugging iOS Projects With Xcode

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.

1. Open your application's Xcode project. In Xcode, from the main menu, select Product > Scheme > Edit Scheme.

2. Click the Run category, then change your Build Configuration to DebugGame.

1. Change the target device from My Mac to the iPhone you have connected.

2. 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.