Improve readme for dawn.node
Fix paths, add note about coverage, and format. Change-Id: I7ac228bf880d6416e89b2f7a3324f9edac5c7a74 Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/117040 Kokoro: Kokoro <noreply+kokoro@google.com> Commit-Queue: Antonio Maiorano <amaiorano@google.com> Reviewed-by: Ben Clayton <bclayton@google.com>
This commit is contained in:
parent
f58ef99a15
commit
1fd40c1d81
|
@ -46,39 +46,48 @@ Currently, the node bindings can only be built with CMake:
|
||||||
```sh
|
```sh
|
||||||
mkdir <build-output-path>
|
mkdir <build-output-path>
|
||||||
cd <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
|
cmake <dawn-root-path> -GNinja -DDAWN_BUILD_NODE_BINDINGS=1
|
||||||
ninja dawn.node
|
ninja dawn.node
|
||||||
```
|
```
|
||||||
|
|
||||||
### Running WebGPU CTS
|
### Running WebGPU CTS
|
||||||
|
|
||||||
1. [Build](#build) the `dawn.node` NodeJS module.
|
1. [Build](#build) the `dawn.node` NodeJS module.
|
||||||
2. Checkout the [WebGPU CTS repo](https://github.com/gpuweb/cts)
|
2. Checkout the [WebGPU CTS repo](https://github.com/gpuweb/cts) or use the one in `third_party/webgpu-cts`.
|
||||||
- Run `npm install` from inside the CTS directory to install its dependencies
|
3. Run `npm install` from inside the CTS directory to install its dependencies.
|
||||||
|
|
||||||
|
Now you can run CTS:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
./src/tools/run run-cts --dawn-node=<path-to-dawn.node> [WebGPU CTS query]
|
./tools/run run-cts --dawn-node=<path-to-dawn.node> [WebGPU CTS query]
|
||||||
|
```
|
||||||
|
|
||||||
|
Or if you checked out your own CTS repo:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./tools/run run-cts --dawn-node=<path-to-dawn.node> --cts=<path-to-cts> [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.
|
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/tools/run run-cts` with `VK_ICD_FILENAMES=<swiftshader-cmake-build>/Linux/vk_swiftshader_icd.json`. For example:
|
To test against SwiftShader instead of the default Vulkan device, prefix `./tools/run run-cts` with `VK_ICD_FILENAMES=<swiftshader-cmake-build>/Linux/vk_swiftshader_icd.json`. For example:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
VK_ICD_FILENAMES=<swiftshader-cmake-build>/Linux/vk_swiftshader_icd.json ./src/tools/run run-cts --dawn-node=<path-to-dawn.node> [WebGPU CTS query]
|
VK_ICD_FILENAMES=<swiftshader-cmake-build>/Linux/vk_swiftshader_icd.json ./tools/run run-cts --dawn-node=<path-to-dawn.node> [WebGPU CTS query]
|
||||||
```
|
```
|
||||||
|
|
||||||
The `--flag` parameter must be passed in multiple times, once for each flag begin set. Here are some common arguments:
|
The `--flag` parameter must be passed in multiple times, once for each flag begin set. Here are some common arguments:
|
||||||
* `backend=<null|webgpu|d3d11|d3d12|metal|vulkan|opengl|opengles>`
|
|
||||||
* `adapter=<name-of-adapter>` - specifies the adapter to use. May be a substring of the full adapter name. Pass an invalid adapter name and `--verbose` to see all possible adapters.
|
- `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
|
- `adapter=<name-of-adapter>` - specifies the adapter to use. May be a substring of the full adapter name. Pass an invalid adapter name and `--verbose` to see all possible adapters.
|
||||||
* `enable-dawn-features=<features>` - enable [Dawn toggles](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/native/Toggles.cpp), e.g. `dump_shaders`
|
- `dlldir=<path>` - used to add an extra DLL search path on Windows, primarily to load the right d3dcompiler_47.dll
|
||||||
* `disable-dawn-features=<features>` - disable [Dawn toggles](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/native/Toggles.cpp)
|
- `enable-dawn-features=<features>` - enable [Dawn toggles](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/native/Toggles.cpp), e.g. `dump_shaders`
|
||||||
|
- `disable-dawn-features=<features>` - disable [Dawn toggles](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/native/Toggles.cpp)
|
||||||
|
|
||||||
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:
|
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:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
./src/tools/run 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"'
|
./tools/run 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.
|
Note that we pass `--verbose` above so that all test output, including the dumped shader, is written to stdout.
|
||||||
|
@ -93,40 +102,67 @@ You can write out an expectations file with the `--output <path>` command line f
|
||||||
|
|
||||||
Dawn needs to be built with clang and the `DAWN_EMIT_COVERAGE` CMake flag.
|
Dawn needs to be built with clang and the `DAWN_EMIT_COVERAGE` CMake flag.
|
||||||
|
|
||||||
Optionally, the `LLVM_SOURCE_DIR` CMake flag can also be specified to point the the `./llvm` directory of [an LLVM checkout](https://github.com/llvm/llvm-project), which will build [`turbo-cov`](../../../tools/src/cmd/turbo-cov/README.md) and dramatically speed up the processing of coverage data.
|
LLVM is also required, either [built from source](https://github.com/llvm/llvm-project), or downloaded as part of an [LLVM release](https://releases.llvm.org/download.html). Make sure that the subdirectory `llvm/bin` is in your PATH, and that `llvm-cov` and `llvm-profdata` binaries are present.
|
||||||
|
|
||||||
|
Optionally, the `LLVM_SOURCE_DIR` CMake flag can also be specified to point the the `./llvm` directory of [an LLVM checkout](https://github.com/llvm/llvm-project), which will build [`turbo-cov`](../../../tools/src/cmd/turbo-cov/README.md) and dramatically speed up the processing of coverage data. If `turbo-cov` is not built, `llvm-cov` will be used instead.
|
||||||
|
|
||||||
|
It may be helpful to write a bash script like `use.sh` that sets up your build environment, for example:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
#!/bin/bash
|
||||||
|
LLVM_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd )"
|
||||||
|
export CC=${LLVM_DIR}/bin/clang
|
||||||
|
export CXX=${LLVM_DIR}/bin/clang++
|
||||||
|
export MSAN_SYMBOLIZER_PATH=${LLVM_DIR}/bin/llvm-symbolizer
|
||||||
|
export PATH=${LLVM_DIR}/bin:${PATH}
|
||||||
|
```
|
||||||
|
|
||||||
|
Place this script in the LLVM root directory, then you can setup your build for coverage as follows:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
. ~/bin/llvm-15/use.sh
|
||||||
|
cmake <dawn-root-path> -GNinja -DDAWN_BUILD_NODE_BINDINGS=1 -DDAWN_EMIT_COVERAGE=1
|
||||||
|
ninja dawn.node
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that if you already generated the CMake build environment with a different compiler, you will need to delete CMakeCache.txt and generate again.
|
||||||
|
|
||||||
### Usage
|
### Usage
|
||||||
|
|
||||||
Run `./src/tools/run run-cts` like before, but include the `--coverage` flag.
|
Run `./tools/run run-cts` like before, but include the `--coverage` flag.
|
||||||
After running the tests, your browser will open with a coverage viewer.
|
After running the tests, your browser will open with a coverage viewer.
|
||||||
|
|
||||||
Click a source file in the left hand panel, then click a green span in the file source to see the tests that exercised that code.
|
Click a source file in the left hand panel, then click a green span in the file source to see the tests that exercised that code.
|
||||||
|
|
||||||
You can also highlight multiple lines to view all the tests that covered any of that highlighted source.
|
You can also highlight multiple lines to view all the tests that covered any of that highlighted source.
|
||||||
|
|
||||||
|
NOTE: if the left hand panel is empty, ensure that `dawn.node` was built with the same version of Clang that matches the version of LLVM being used to retrieve coverage info.
|
||||||
|
|
||||||
## Debugging TypeScript with VSCode
|
## Debugging TypeScript with VSCode
|
||||||
|
|
||||||
Open or create the `.vscode/launch.json` file, and add:
|
Open or create the `.vscode/launch.json` file, and add:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"version": "0.2.0",
|
"version": "0.2.0",
|
||||||
"configurations": [
|
"configurations": [
|
||||||
{
|
{
|
||||||
"name": "Debug with node",
|
"name": "Debug with node",
|
||||||
"type": "node",
|
"type": "node",
|
||||||
"request": "launch",
|
"request": "launch",
|
||||||
"outFiles": [ "./**/*.js" ],
|
"outFiles": ["./**/*.js"],
|
||||||
"args": [
|
"args": [
|
||||||
"-e", "require('./src/common/tools/setup-ts-in-node.js');require('./src/common/runtime/cmdline.ts');",
|
"-e",
|
||||||
"--", "placeholder-arg",
|
"require('./src/common/tools/setup-ts-in-node.js');require('./src/common/runtime/cmdline.ts');",
|
||||||
"--gpu-provider",
|
"--",
|
||||||
"[path-to-dawn.node]", // REPLACE: [path-to-dawn.node]
|
"placeholder-arg",
|
||||||
"[test-query]", // REPLACE: [test-query]
|
"--gpu-provider",
|
||||||
],
|
"[path-to-dawn.node]", // REPLACE: [path-to-dawn.node]
|
||||||
"cwd": "[cts-root]" // REPLACE: [cts-root]
|
"[test-query]" // REPLACE: [test-query]
|
||||||
}
|
],
|
||||||
]
|
"cwd": "[cts-root]" // REPLACE: [cts-root]
|
||||||
|
}
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue