Debugging iOS Projects With Xcode

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

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.

    The Edit Scheme button is located under Product/Scheme

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

    Set the Build Configuration to DebugGame in the Product/Scheme/Edit Scheme menu

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

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

    Use the button in the upper-right corner of the Xcode window to change your target device to the iPhone

  2. Click the Build and Run button to start building the project from Xcode and launch it on the device.

    Click the Play button in the upper-left to build and run your project.

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.

This page was written for a previous version of Unreal Engine and has not been updated for the current Unreal Engine 5.0 release.
Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey