From 1fd40c1d8172b541650952cc1c53150a25b072d6 Mon Sep 17 00:00:00 2001 From: Antonio Maiorano <amaiorano@google.com> Date: Fri, 13 Jan 2023 19:10:47 +0000 Subject: [PATCH] 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> --- src/dawn/node/README.md | 98 ++++++++++++++++++++++++++++------------- 1 file changed, 67 insertions(+), 31 deletions(-) diff --git a/src/dawn/node/README.md b/src/dawn/node/README.md index 552fde91ca..8c1932e7be 100644 --- a/src/dawn/node/README.md +++ b/src/dawn/node/README.md @@ -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] + } + ] } ```