From c8cdb1197e36f52189538e1f5eaa71e0a8267de1 Mon Sep 17 00:00:00 2001 From: jf908 Date: Wed, 2 Jul 2025 15:55:25 +0100 Subject: [PATCH] Add instructions for GPU debugging in Xcode (#19915) # Objective - Using Xcode can be confusing to setup for rust projects. # Solution - Add instructions to docs/profiling.md for how to use start debugging a bevy project with Xcode's GPU debugging/profiling tools. --- docs/profiling.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/profiling.md b/docs/profiling.md index ef6a46a608..fe55b048af 100644 --- a/docs/profiling.md +++ b/docs/profiling.md @@ -10,6 +10,7 @@ - [Perf flame graph](#perf-flame-graph) - [GPU runtime](#gpu-runtime) - [Vendor tools](#vendor-tools) + - [Xcode's Metal debugger](#xcodes-metal-debugger) - [Tracy RenderQueue](#tracy-renderqueue) - [Compile time](#compile-time) @@ -147,6 +148,33 @@ For profiling GPU work, you should use the tool corresponding to your GPU's vend Note that while RenderDoc is a great debugging tool, it is _not_ a profiler, and should not be used for this purpose. +#### Xcode's Metal debugger + +Follow the steps below to start GPU debugging on macOS. There is no need to create an Xcode project. + +1. In the menu bar click on Debug > Debug Executable… + + ![Xcode's menu bar open to Debug > Debug Executable...](https://github.com/user-attachments/assets/efdc5037-0957-4227-b29d-9a789ba17a0a) + +2. Select your executable from your project’s target folder. +3. The Scheme Editor will open. If your assets are not located next to your executable, you can go to the Arguments tab and set `BEVY_ASSET_ROOT` to the absolute path for your project (the parent of your assets folder). The rest of the defaults should be fine. + + ![Xcode's Schema Editor opened to an environment variable configuration](https://github.com/user-attachments/assets/29cafb05-0c49-4777-8d41-8643812e8f6a) + +4. Click the play button in the top left and this should start your bevy app. + + ![A cursor hovering over the play button in XCode](https://github.com/user-attachments/assets/859580e2-779b-4db8-8ea6-73cf4ef696c9) + +5. Go back to Xcode and click on the Metal icon in the bottom drawer and then Capture in the following the popup menu. + + ![A cursor hovering over the Capture button in the Metal debugging popup menu](https://github.com/user-attachments/assets/c0ce1591-0a53-499b-bd1b-4d89538ea248) + +6. Start debugging and profiling! + +![Xcode open to the Performance tab in the Debug Navigator.](https://github.com/user-attachments/assets/52732391-9306-44a9-ae01-dcf4573f77ab) + +These instructions were created for Xcode 16.4. + ### Tracy RenderQueue While it doesn't provide as much detail as vendor-specific tooling, Tracy can also be used to coarsely measure GPU performance.