Skip to content

A tool used to test the Dawn and wgpu WebGPU APIs, and their respective WGSL compilers Tint and naga, by inputting WGSL code and validating outputs.

License

Notifications You must be signed in to change notification settings

hanawatson/wgslrunner

Repository files navigation

wgslrunner

This tool combines the wgslgenerator WGSL code generator with the testing harness from the wgslsmith project, as well as external validation tools like spirv-val and glslang. It is used to test the Dawn and wgpu WebGPU APIs, and their respective WGSL compilers Tint and naga. An external script, dawn-build, is also used to build Dawn.

Prerequisites

wgslrunner can be cloned using:

$ git clone --recurse-submodules https://github.com/hanawatson/wgslrunner wgslrunner

wgslrunner makes use of several tools and submodules. These will be cloned with the recurse-submodules flag in the above command. The various tools can then be built by running the build_external_tools.sh script included in wgslrunner. Use of the script is recommended to save space on the user's machine, rather than re-download large projects like Tint.

If any tool or repository is already located in a different directory on a user's machine, they can indicate this by setting the relevant environment variable (see the Enviroment variables section below). If the variables corresponding to dawn-build and/or wgslsmith are set when running the external tool-building script, the tools will be built as normal in these specified locations.

Note: due to compatibility issues, wgslrunner uses a previous version of wgslsmith. If the user provides a non-default path for wgslsmith, it must be at commit 3db5017509 or earlier. If a later version is used, the harness tests run by wgslrunner will always fail, but other tests will function as normal.

Usage instructions

wgslrunner can be used by running its associated shell script, wgslrun.sh. Several flags may be specified.

Flag Meaning Default value
-h, --help Print help message None
-s <argument>, --input-shader <argument> The path of the WGSL shader that should be inputted into the various tools tested by wgslrunner None - if unspecified, wgslgenerator will be used to generate a random shader
-b <argument>, --input-bindings <argument> The path of the bindings JSON file that should be provided to the harness (more details about which can be found in the wgslsmith documentation) None - if unspecified, default bindings compatible with wgslgenerator's output will be used
-c <argument>, --input-config <argument> The path of the configuration JSON file that should be provided to wgslgenerator during shader generation (more details about which can be found in wgslgenerator documentation) None - if unspecified, wgslgenerator will use its default configuration
-j, --use-generator-jar Enable usage of the standalone wgslgenerator.jar jar (see the relevant wgslgenerator README section), which must be located in the top-level wgslrunner directory Disabled
-(e/E), --(enable/disable)-log-on-error Enable/disable logging of the relevant shader, bindings and output of wgslrunner if any test fails Enabled
-(o/O), --(enable/disable)-log-on-ok Enable/disable logging of the relevant shader, bindings and output of wgslrunner if all tests pass Disabled
-(p/P), --(enable/disable)-print-error-detail Enable/disable printing error output to the console if any tests fail Disabled
-(t/T), --(enable/disable)-terminate-after-error Enable/disable termination if any test fails, rather than continuing with the rest Enabled

Note: both input-shader and input-bindings must be provided, or neither.

Environment variables

The following environment variables are used by wgslrunner to locate various external tools, and should be set if different. The variable corresponding to dawn-build is relevant to the external tool-building script, but not to wgslrun itself.

Variable Tool Default path (relative to wgslrunner directory)
$WGSLGENERATOR_PATH wgslgenerator wgslgenerator
$WGSLSMITH_PATH wgslsmith wgslsmith
$DAWN_BUILD_PATH dawn-build dawn-build
$DAWN_PATH Dawn $DAWN_BUILD_PATH/dawn
$TINT_PATH Tint external_tools/tint
$SPIRV_VAL_PATH SPIRV-Tools $DAWN_PATH/third_party/vulkan-deps/spirv-tools/src/build/tools
$GLSLANG_PATH glslang $DAWN_PATH/third_party/vulkan-deps/glslang/src/build/install/bin

Requirements

  • JDK with Java version >= 1.8
  • Bash
  • Make
  • Cmake and Ninja for building Dawn
  • depot_tools in PATH (instructions for the installation of which can be found here for building Dawn

About

A tool used to test the Dawn and wgpu WebGPU APIs, and their respective WGSL compilers Tint and naga, by inputting WGSL code and validating outputs.

Topics

Resources

License

Stars

Watchers

Forks