Skip to content

Commit c8cdb11

Browse files
authored
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.
1 parent e42d386 commit c8cdb11

File tree

1 file changed

+28
-0
lines changed

1 file changed

+28
-0
lines changed

docs/profiling.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
- [Perf flame graph](#perf-flame-graph)
1111
- [GPU runtime](#gpu-runtime)
1212
- [Vendor tools](#vendor-tools)
13+
- [Xcode's Metal debugger](#xcodes-metal-debugger)
1314
- [Tracy RenderQueue](#tracy-renderqueue)
1415
- [Compile time](#compile-time)
1516

@@ -147,6 +148,33 @@ For profiling GPU work, you should use the tool corresponding to your GPU's vend
147148

148149
Note that while RenderDoc is a great debugging tool, it is _not_ a profiler, and should not be used for this purpose.
149150

151+
#### Xcode's Metal debugger
152+
153+
Follow the steps below to start GPU debugging on macOS. There is no need to create an Xcode project.
154+
155+
1. In the menu bar click on Debug > Debug Executable…
156+
157+
![Xcode's menu bar open to Debug > Debug Executable...](https://github.com/user-attachments/assets/efdc5037-0957-4227-b29d-9a789ba17a0a)
158+
159+
2. Select your executable from your project’s target folder.
160+
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.
161+
162+
![Xcode's Schema Editor opened to an environment variable configuration](https://github.com/user-attachments/assets/29cafb05-0c49-4777-8d41-8643812e8f6a)
163+
164+
4. Click the play button in the top left and this should start your bevy app.
165+
166+
![A cursor hovering over the play button in XCode](https://github.com/user-attachments/assets/859580e2-779b-4db8-8ea6-73cf4ef696c9)
167+
168+
5. Go back to Xcode and click on the Metal icon in the bottom drawer and then Capture in the following the popup menu.
169+
170+
![A cursor hovering over the Capture button in the Metal debugging popup menu](https://github.com/user-attachments/assets/c0ce1591-0a53-499b-bd1b-4d89538ea248)
171+
172+
6. Start debugging and profiling!
173+
174+
![Xcode open to the Performance tab in the Debug Navigator.](https://github.com/user-attachments/assets/52732391-9306-44a9-ae01-dcf4573f77ab)
175+
176+
These instructions were created for Xcode 16.4.
177+
150178
### Tracy RenderQueue
151179

152180
While it doesn't provide as much detail as vendor-specific tooling, Tracy can also be used to coarsely measure GPU performance.

0 commit comments

Comments
 (0)