• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Dawn bindings for NodeJS
2
3Note: This code is currently WIP. There are a number of [known issues](#known-issues).
4
5## Building
6
7## System requirements
8
9- [CMake 3.10](https://cmake.org/download/) or greater
10- [Go 1.13](https://golang.org/dl/) or greater
11
12## Install `depot_tools`
13
14Dawn uses the Chromium build system and dependency management so you need to [install depot_tools] and add it to the PATH.
15
16[install depot_tools]: http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up
17
18### Fetch dependencies
19
20First, the steps are similar to [`doc/building.md`](../../docs/building.md), but instead of the `Get the code` step, run:
21
22```sh
23# Clone the repo as "dawn"
24git clone https://dawn.googlesource.com/dawn dawn && cd dawn
25
26# Bootstrap the NodeJS binding gclient configuration
27cp scripts/standalone-with-node.gclient .gclient
28
29# Fetch external dependencies and toolchains with gclient
30gclient sync
31```
32
33### Build
34
35Currently, the node bindings can only be built with CMake:
36
37```sh
38mkdir <build-output-path>
39cd <build-output-path>
40cmake <dawn-root-path> -GNinja -DDAWN_BUILD_NODE_BINDINGS=1 -DDAWN_ENABLE_PIC=1
41ninja dawn.node
42```
43
44### Running WebGPU CTS
45
461. [Build](#build) the `dawn.node` NodeJS module.
472. Checkout the [WebGPU CTS repo](https://github.com/gpuweb/cts)
48  - Run `npm install` from inside the CTS directory to install its dependencies
49
50```sh
51./src/dawn_node/tools/run-cts --cts=<path-to-webgpu-cts> --dawn-node=<path-to-dawn.node> [WebGPU CTS query]
52```
53
54If this fails with the error message `TypeError: expander is not a function or its return value is not iterable`, try appending `--build=false` to the start of the `run-cts` command line flags.
55
56To test against SwiftShader instead of the default Vulkan device, prefix `./src/dawn_node/tools/run-cts` with `VK_ICD_FILENAMES=<swiftshader-cmake-build>/Linux/vk_swiftshader_icd.json` and append `--flag=dawn-backend=vulkan` to the start of run-cts command line flags. For example:
57
58```sh
59VK_ICD_FILENAMES=<swiftshader-cmake-build>/Linux/vk_swiftshader_icd.json ./src/dawn_node/tools/run-cts --cts=<path-to-webgpu-cts> --dawn-node=<path-to-dawn.node> --flag=dawn-backend=vulkan [WebGPU CTS query]
60```
61
62The `--flag` parameter must be passed in multiple times, once for each flag begin set. Here are some common arguments:
63* `dawn-backend=<null|webgpu|d3d11|d3d12|metal|vulkan|opengl|opengles>`
64* `dlldir=<path>` - used to add an extra DLL search path on Windows, primarily to load the right d3dcompiler_47.dll
65* `enable-dawn-features=<features>` - enable [Dawn toggles](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn_native/Toggles.cpp), e.g. `dump_shaders`
66* `disable-dawn-features=<features>` - disable [Dawn toggles](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn_native/Toggles.cpp)
67
68For example, on Windows, to use the d3dcompiler_47.dll from a Chromium checkout, and to dump shader output, we could run the following using Git Bash:
69
70```sh
71./src/dawn_node/tools/run-cts --verbose --dawn-node=/c/src/dawn/build/Debug/dawn.node --cts=/c/src/gpuweb-cts --flag=dlldir="C:\src\chromium\src\out\Release" --flag=enable-dawn-features=dump_shaders 'webgpu:shader,execution,builtin,abs:integer_builtin_functions,abs_unsigned:storageClass="storage";storageMode="read_write";containerType="vector";isAtomic=false;baseType="u32";type="vec2%3Cu32%3E"'
72```
73
74Note that we pass `--verbose` above so that all test output, including the dumped shader, is written to stdout.
75
76## Debugging TypeScript with VSCode
77
78Open or create the `.vscode/launch.json` file, and add:
79
80```json
81{
82    "version": "0.2.0",
83    "configurations": [
84        {
85            "name": "Debug with node",
86            "type": "node",
87            "request": "launch",
88            "outFiles": [ "./**/*.js" ],
89            "args": [
90                "-e", "require('./src/common/tools/setup-ts-in-node.js');require('./src/common/runtime/cmdline.ts');",
91                "--", "dummy-arg",
92                "--gpu-provider",
93                "[path-to-dawn.node]", // REPLACE: [path-to-dawn.node]
94                "[test-query]", // REPLACE: [test-query]
95            ],
96            "cwd": "[cts-root]" // REPLACE: [cts-root]
97        }
98    ]
99}
100```
101
102Replacing:
103
104- `[cts-root]` with the path to the CTS root directory. If you are editing the `.vscode/launch.json` from within the CTS workspace, then you may use `${workspaceFolder}`.
105- `[path-to-dawn.node]` this the path to the `dawn.node` module built by the [build step](#Build)
106- `test-query` with the test query string. Example: `webgpu:shader,execution,builtin,abs:*`
107
108
109## Known issues
110
111- Many WebGPU CTS tests are currently known to fail
112- Dawn uses special token values for some parameters / fields. These are currently passed straight through to dawn from the JavaScript. discussions: [1](https://dawn-review.googlesource.com/c/dawn/+/64907/5/src/dawn_node/binding/Converter.cpp#167), [2](https://dawn-review.googlesource.com/c/dawn/+/64907/5/src/dawn_node/binding/Converter.cpp#928), [3](https://dawn-review.googlesource.com/c/dawn/+/64909/4/src/dawn_node/binding/GPUTexture.cpp#42)
113- Backend validation is currently always set to 'full' to aid in debugging. This can be extremely slow. [discussion](https://dawn-review.googlesource.com/c/dawn/+/64916/4/src/dawn_node/binding/GPU.cpp#25)
114- Attempting to call `new T` in JavaScript, where `T` is an IDL interface type, should result in a TypeError "Illegal constructor". [discussion](https://dawn-review.googlesource.com/c/dawn/+/64902/9/src/dawn_node/interop/WebGPU.cpp.tmpl#293)
115- `GPUDevice` currently maintains a list of "lost promises". This should return the same promise. [discussion](https://dawn-review.googlesource.com/c/dawn/+/64906/6/src/dawn_node/binding/GPUDevice.h#107)
116
117## Remaining work
118
119- Investigate CTS failures that are not expected to fail.
120- Generated includes live in `src/` for `dawn_node`, but outside for Dawn. [discussion](https://dawn-review.googlesource.com/c/dawn/+/64903/9/src/dawn_node/interop/CMakeLists.txt#56)
121- Hook up to presubmit bots (CQ / Kokoro)
122- `binding::GPU` will require significant rework [once Dawn implements the device / adapter creation path properly](https://dawn-review.googlesource.com/c/dawn/+/64916/4/src/dawn_node/binding/GPU.cpp).
123