Update how to debug C++ in the dawn.node readme
Describe how to use --verbose to get the debugging args.
Also explain enabling support for debugging child processes.
Change-Id: I1daef117d425f795b83d02049f89bc108731e660
Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/155941
Reviewed-by: Ben Clayton <bclayton@google.com>
Kokoro: Kokoro <noreply+kokoro@google.com>
Commit-Queue: Antonio Maiorano <amaiorano@google.com>
diff --git a/src/dawn/node/README.md b/src/dawn/node/README.md
index 77183b5..a15ef6e 100644
--- a/src/dawn/node/README.md
+++ b/src/dawn/node/README.md
@@ -190,9 +190,9 @@
- `[cts.js]` this is the path to the `cts.js` file that should be copied to the output directory by the [build step](#build)
- `test-query` with the test query string. Example: `webgpu:shader,execution,builtin,abs:*`
-## Debugging dawn-node issues in gdb/lldb
+## Debugging C++
-It is possible to run the CTS with dawn-node directly similarly to Debugging TypeScript with VSCode:
+It is possible to run the CTS with dawn-node from the command line:
```sh
cd <cts-root-dir>
@@ -204,7 +204,52 @@
[test-query]
```
-This command is then possible to run in your debugger of choice.
+You can use this to configure a debugger (gdb, lldb, MSVC) to launch the CTS, and be able to debug Dawn's C++ source,
+including the dawn-node C++ bindings layer, dawn_native, Tint, etc.
+
+To make this easier, executing `run-cts` with the `--verbose` flag will output the command it runs, along with
+the working directory. It also conveniently outputs the JSON fields that you can copy directly into VS Code's
+launch.json. For example:
+
+```sh
+./tools/run run-cts --verbose --isolate --bin=./build-clang 'webgpu:shader,execution,flow_control,
+loop:nested_loops:preventValueOptimizations=false'
+<SNIP>
+Running:
+ Cmd: /home/user/src/dawn/third_party/node/node-linux-x64/bin/node -e "require('./out-node/common/runtime/cmdline.js');" -- placeholder-arg --gpu-provider /home/user/src/dawn/build-clang/cts.js --verbose --quiet --gpu-provider-flag verbose=1 --colors --unroll-const-eval-loops --gpu-provider-flag enable-dawn-features=allow_unsafe_apis "webgpu:shader,execution,flow_control,loop:nested_loops:preventValueOptimizations=false"
+ Dir: /home/user/src/dawn/third_party/webgpu-cts
+
+ For VS Code launch.json:
+ "program": "/home/user/src/dawn/third_party/node/node-linux-x64/bin/node",
+ "args": [
+ "-e",
+ "require('./out-node/common/runtime/cmdline.js');",
+ "--",
+ "placeholder-arg",
+ "--gpu-provider",
+ "/home/user/src/dawn/build-clang/cts.js",
+ "--verbose",
+ "--quiet",
+ "--gpu-provider-flag",
+ "verbose=1",
+ "--colors",
+ "--unroll-const-eval-loops",
+ "--gpu-provider-flag",
+ "enable-dawn-features=allow_unsafe_apis",
+ "webgpu:shader,execution,flow_control,loop:nested_loops:preventValueOptimizations=false"
+ ],
+ "cwd": "/home/user/src/dawn/third_party/webgpu-cts",
+
+webgpu:shader,execution,flow_control,loop:nested_loops:preventValueOptimizations=false - pass:
+<SNIP>
+```
+
+Note that as in the example above, we also pass in `--isolate`, otherwise the output command will be the one
+used to run CTS in server mode, requiring a client to send it the tests to run.
+
+Also note that the debugger must support debugging forked child processes. You may need to enable this
+feature depending on your debugger (see [here for gdb](https://ftp.gnu.org/old-gnu/Manuals/gdb/html_node/gdb_25.html)
+and [this extension for MSVC](https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerTool)).
## Recipes for building software GPUs
