Dawn bindings for NodeJS

Note: This code is currently WIP. There are a number of known issues.

Building

System requirements

• CMake 3.10 or greater
• Go 1.13 or greater

Install depot_tools

Dawn uses the Chromium build system and dependency management so you need to install depot_tools and add it to the PATH.

Fetch dependencies

First, the steps are similar to doc/building.md, but instead of the Get the code step, run:

# Clone the repo as "dawn"
git clone https://dawn.googlesource.com/dawn dawn && cd dawn

# Bootstrap the NodeJS binding gclient configuration
cp scripts/standalone-with-node.gclient .gclient

# Fetch external dependencies and toolchains with gclient
gclient sync

Optionally, on Linux install X11-xcb support:

sudo apt-get install libx11-xcb-dev

If you don't have those supporting libraries, then you must use the -DDAWN_USE_X11=OFF flag on Cmake.

Build

Currently, the node bindings can only be built with CMake:

mkdir <build-output-path>
cd <build-output-path>
cmake <dawn-root-path> -GNinja -DDAWN_BUILD_NODE_BINDINGS=1 -DDAWN_ENABLE_PIC=1 -DDAWN_USE_X11=OFF
ninja dawn.node

Running WebGPU CTS

1. Build the dawn.node NodeJS module.
2. Checkout the WebGPU CTS repo

• Run npm install from inside the CTS directory to install its dependencies

./src/dawn/node/tools/run-cts --cts=<path-to-webgpu-cts> --dawn-node=<path-to-dawn.node> [WebGPU CTS query]

If 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.

To 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:

VK_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]

The --flag parameter must be passed in multiple times, once for each flag begin set. Here are some common arguments:

• dawn-backend=<null|webgpu|d3d11|d3d12|metal|vulkan|opengl|opengles>
• dlldir=<path> - used to add an extra DLL search path on Windows, primarily to load the right d3dcompiler_47.dll
• enable-dawn-features=<features> - enable Dawn toggles, e.g. dump_shaders
• disable-dawn-features=<features> - disable Dawn toggles

For 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:

./src/dawn/node/tools/run-cts --verbose --dawn-node=/c/src/dawn/build/Debug/dawn.node --cts=/c/src/webgpu-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"'

Note that we pass --verbose above so that all test output, including the dumped shader, is written to stdout.

Testing against a run-cts expectations file

You can write out an expectations file with the --output <path> command line flag, and then compare this snapshot to a later run with --expect <path>.

Debugging TypeScript with VSCode

Open or create the .vscode/launch.json file, and add:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug with node",
            "type": "node",
            "request": "launch",
            "outFiles": [ "./**/*.js" ],
            "args": [
                "-e", "require('./src/common/tools/setup-ts-in-node.js');require('./src/common/runtime/cmdline.ts');",
                "--", "placeholder-arg",
                "--gpu-provider",
                "[path-to-dawn.node]", // REPLACE: [path-to-dawn.node]
                "[test-query]", // REPLACE: [test-query]
            ],
            "cwd": "[cts-root]" // REPLACE: [cts-root]
        }
    ]
}

Replacing:

• [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}.
• [path-to-dawn.node] this the path to the dawn.node module built by the build step
• test-query with the test query string. Example: webgpu:shader,execution,builtin,abs:*

Debugging dawn-node issues in gdb/lldb

It is possible to run the CTS with dawn-node directly similarly to Debugging TypeScript with VSCode:

cd <cts-root-dir>
[path-to-node] \ # for example <dawn-root-dir>/third_party/node/<arch>/node
    -e "require('./src/common/tools/setup-ts-in-node.js');require('./src/common/runtime/cmdline.ts');" \
    -- \
    placeholder-arg \
    --gpu-provider [path to dawn.node] \
    [test-query]

This command is then possible to run in your debugger of choice.

Known issues

• Many WebGPU CTS tests are currently known to fail
• Dawn uses special token values for some parameters / fields. These are currently passed straight through to dawn from the JavaScript. discussions: 1, 2, 3
• Backend validation is currently always set to ‘full’ to aid in debugging. This can be extremely slow. discussion
• Attempting to call new T in JavaScript, where T is an IDL interface type, should result in a TypeError “Illegal constructor”. discussion
• GPUDevice currently maintains a list of “lost promises”. This should return the same promise. discussion

Remaining work

• Investigate CTS failures that are not expected to fail.
• Generated includes live in src/ for dawn/node, but outside for Dawn. discussion
• Hook up to presubmit bots (CQ / Kokoro)
• binding::GPU will require significant rework once Dawn implements the device / adapter creation path properly.