wgpu/documentation/debugging/
xcode.rs

1#![doc = crate::macros::doc_image!("xcode-new-project.webp")]
2#![doc = crate::macros::doc_image!("xcode-project-type.webp")]
3#![doc = crate::macros::doc_image!("xcode-build-tool.webp")]
4#![doc = crate::macros::doc_image!("xcode-edit-scheme.webp")]
5#![doc = crate::macros::doc_image!("xcode-scheme-options.webp")]
6#![doc = crate::macros::doc_image!("xcode-scheme-arguments.webp")]
7#![doc = crate::macros::doc_image!("xcode-select-binary.webp")]
8#![doc = crate::macros::doc_image!("xcode-play-button.webp")]
9#![doc = crate::macros::doc_image!("xcode-attached.webp")]
10#![doc = crate::macros::doc_image!("xcode-start-capture.webp")]
11/*!
12# Debugging with Xcode (Metal GPU Capture)
13
14Xcode provides powerful Metal GPU capture and shader debugging tools. This
15page walks through attaching Xcode to a `wgpu` application so you can enable
16Metal validation and capture frames.
17
18A Chinese version is also available:
19[使用 Xcode 调试 wgpu 程序](https://jinleili.github.io/learn-wgpu-zh/integration-and-debugging/ios/#xcode-%E4%B8%8E-metal).
20
21First we'll start by opening Xcode and creating a new project using the menu
22or "Create a new Xcode project" in the startup dialog.
23
24![Xcode startup dialog][xcode-new-project.webp]
25
26Select "External Build System" as the project type.
27
28![Xcode project type][xcode-project-type.webp]
29
30Choose which build tool to use in the "Build Tool" field. This will be
31called whenever we build in Xcode.
32
33We can write our `cargo` build command here if we'd like Xcode to run it,
34but we could also skip the build step to avoid Xcode building the project
35for us.
36
37It's possible to skip the build step by specifying our build command as
38`ls`, `echo`, or anything else that exits successfully (note: `:` doesn't
39appear to work here).
40
41The rest of the fields don't actually matter to us, so we can put any values
42there.
43
44![Xcode build tool][xcode-build-tool.webp]
45
46Click on the project name and then click "Edit Scheme".
47
48![Xcode edit scheme][xcode-edit-scheme.webp]
49
50Under the "Options" tab we can choose the level of validation for Metal and
51whether to enable GPU frame capture.
52
53![Xcode scheme options][xcode-scheme-options.webp]
54
55Under the "Arguments" tab we'll choose which executable to run. We want this
56to be the binary created by `cargo`. We'll select "Other" and then find the
57binary in the target directory.
58
59![Xcode scheme arguments][xcode-scheme-arguments.webp]
60
61![Xcode select binary][xcode-select-binary.webp]
62
63Next we'll click the play button to run our binary and attach Xcode to it.
64
65![Xcode play button][xcode-play-button.webp]
66
67Now we should see our application running and some output telling us that
68Metal validation has been enabled.
69
70![Xcode attached][xcode-attached.webp]
71
72To start a GPU capture, click the camera button while Xcode is attached to
73our running application.
74
75![Xcode start capture][xcode-start-capture.webp]
76
77After a frame has been captured, we will be able to use all the regular
78Metal tools (e.g. shader debugging, GPU statistics, etc.).
79
80*/
wgpu/documentation/debugging/xcode.rs

wgpu/documentation/debugging/
xcode.rs
