forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add instructions for GPU debugging in Xcode (#19915)

Browse Source 
# 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.
This commit is contained in:
jf908 2025-07-02 15:55:25 +01:00 committed by GitHub
parent e42d386625
commit c8cdb1197e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 28 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/profiling.md
View File

@ -10,6 +10,7 @@
- [Perf flame graph](#perf-flame-graph) - [Perf flame graph](#perf-flame-graph)
- [GPU runtime](#gpu-runtime) - [GPU runtime](#gpu-runtime)
- [Vendor tools](#vendor-tools) - [Vendor tools](#vendor-tools)
- [Xcode's Metal debugger](#xcodes-metal-debugger)
- [Tracy RenderQueue](#tracy-renderqueue) - [Tracy RenderQueue](#tracy-renderqueue)
- [Compile time](#compile-time) - [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. 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 ### Tracy RenderQueue
While it doesn't provide as much detail as vendor-specific tooling, Tracy can also be used to coarsely measure GPU performance. While it doesn't provide as much detail as vendor-specific tooling, Tracy can also be used to coarsely measure GPU performance.