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:
Antonio Maiorano
Dawn LUCI CQ
parent
f58ef99a15
commit
1fd40c1d81
|
|
@ -46,39 +46,48 @@ Currently, the node bindings can only be built with CMake:
|
|||
```sh
|
||||
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
|
||||
cmake <dawn-root-path> -GNinja -DDAWN_BUILD_NODE_BINDINGS=1
|
||||
ninja dawn.node
|
||||
```
|
||||
|
||||
### Running WebGPU CTS
|
||||
|
||||
1. [Build](#build) the `dawn.node` NodeJS module.
|
||||
2. Checkout the [WebGPU CTS repo](https://github.com/gpuweb/cts)
|
||||
- Run `npm install` from inside the CTS directory to install its dependencies
|
||||
2. Checkout the [WebGPU CTS repo](https://github.com/gpuweb/cts) or use the one in `third_party/webgpu-cts`.
|
||||
3. Run `npm install` from inside the CTS directory to install its dependencies.
|
||||
|
||||
Now you can run CTS:
|
||||
|
||||
```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.
|
||||
|
||||
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
|
||||
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:
|
||||
* `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.
|
||||
* `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](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)
|
||||
|
||||
- `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.
|
||||
- `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](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:
|
||||
|
||||
```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.
|
||||
|
|
@ -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.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
Open or create the `.vscode/launch.json` file, and add:
|
||||
|
||||
```json
|
||||
{
|
||||
"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]
|
||||
}
|
||||
]
|
||||
"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]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue