README.md

WebGPU Shading Language Specification

For general instructions on building, see CONTRIBUTING.md.

Dependencies

The following tools are used:

• For building the specification HTML from source: Bikeshed
  • If Bikeshed is not installed locally, the Bikeshed web API will be used to generate the specification. This is generally slower, and requires a connection to the internet.
• For building diagrams from source: Mermaid
  • The generated files are checked in. If Mermaid is not installed, regeneration will be skipped.
• For validating the grammar and code samples:
  • Python 3
  • Tree-sitter
  • py-tree-sitter
  • npm
  • node.js
  • A C/C++ compiler

To install the necessary tools, run:

./tools/install-dependencies.sh bikeshed diagrams wgsl

Alternatively, invoke pip3/npx directly, using the commands in that script.

Building the specification

When the specification is generated, it is written to index.html.

Generating specification, validating the grammar and code samples (recommended)

make

Generating the specification only

To generate the specification only, run:

make index.html

Validating the code samples can be parsed

make validate-examples

This extracts the grammar from the specification source in index.bs, creates a Tree-sitter parser from the grammar, and then ensures that code samples from the specification can be parsed correctly.

Validating the grammar is LALR(1)

make lalr

This produces an LALR(1) parse table for the WGSL grammar in an ad-hoc textual format. It will fail if it finds a conflict.

Tree-sitter's JSON representation of the WGSL grammar is used as an input to this step, so this step will execute the Tree-sitter step if required.