Skip to content

Latest commit

 

History

History
105 lines (68 loc) · 3.38 KB

CONTRIBUTING.md

File metadata and controls

105 lines (68 loc) · 3.38 KB
Raw

Building the WebGPU/WGSL specs

See README.md for procedural information about contributing.

See wgsl/README.md for more details about building the WGSL spec.

Setting up a working environment

Using GitHub Codespaces

A GitHub Codespace is a very convenient way to make changes without setting up toolchains locally. It requires an internet connection and may be a little slower to build than your local machine.

The Free and Pro plans for personal accounts include free use of GitHub Codespaces up to a fixed amount of usage every month.

For more info on GitHub Codespaces billing, see this help page.

  1. Fork the repository at https://github.com/gpuweb/gpuweb/fork

  2. On your fork:

    1. Click the big green "Code" button
    2. Switch to the "Codespaces" tab
    3. Click the "+" to create a new Codespace

    This will open the Codespace in a tab. To get back to it:

    1. Click the big green "Code" button (on your fork or the upstream repository gpuweb/gpuweb)
    2. Switch to the "Codespaces" tab
    3. Click on the name of your Codespace

  3. Using the built-in terminal:

    1. Create a branch: git checkout -b my-new-change

    2. See the "Building"/"Previewing" instructions below.

    3. When you start a web server inside the Codespace, you'll get a notification on the editor page. Click on it to get to the web-visible URL for your server.

Using the Dev Container locally

Please see https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository.

Using your local system without the Dev Container

On a local system, you'll need to install dependencies. To install all tools, run:

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

(Alternatively, you can invoke pip3/npx directly, using the commands in that script.) More details:

The specifications are written using Bikeshed. Installing Bikeshed is optional; if Bikeshed is not installed locally, the Bikeshed API will be used to generate the specification (but this is generally slower).

Diagrams generated using Mermaid. This isn't required unless you're modifying or creating diagrams.

The WGSL spec uses some additional tools for language parsing; see wgsl/README.md if you want to know more.

Building this spec

To build all documents:

make -j

To build just the WebGPU specification (spec/index.html):

make -C spec index.html

To build just the WGSL specification (wgsl/index.html):

make -C wgsl index.html

Alternatively, cd into your target document's subdirectory, and call make or make -j.

Both spec and wgsl also have other targets in their Makefiles, which are documented inline.

The other documents in this repository (correspondence and explainer) can be built similarly.

Previewing the spec

Launch a local web server to preview your spec changes, for example:

python3 -m http.server

(Add -b localhost if developing locally so the port won't be exposed to your network.)

or:

npx http-server

(Add -a localhost if developing locally so the port won't be exposed to your network.)