Building Emdawnwebgpu

Emdawnwebgpu is easiest to use as a pre-built package from https://github.com/google/dawn/releases. For information on using those, and other general information, read pkg/README.md instead.

This README discusses building the pre-packaged emdawnwebgpu_pkg, building the in-tree Dawn samples/tests for Wasm, and using our CMake or GN build files to link either Dawn (for native) or Emdawnwebgpu (for Wasm).

Setting up a CMake project that automatically chooses Dawn or Emdawnwebgpu

Please read https://developer.chrome.com/docs/web-platform/webgpu/build-app.

Building emdawnwebgpu and emdawnwebgpu_pkg

First, get the Dawn code and its dependencies. See building.md.

To build the package, you‘ll build Dawn’s emdawnwebgpu_pkg target using Emscripten. out/yourbuild/emdawnwebgpu_pkg combines files from:

• src/emdawnwebgpu
• third_party/emdawnwebgpu
• out/yourbuild/gen

Set up Emscripten

Get an emsdk toolchain (at least Emscripten 4.0.3, which includes the necessary tools in the package release). There are two options to do this:

• Set the dawn_wasm gclient variable (use standalone-with-wasm.gclient as your .gclient), and gclient sync. This installs emsdk in //third_party/emsdk.
• Install it manually following the official instructions.

Standalone with CMake

Set up the build directory using emcmake:

mkdir out/cmake-wasm
cd out/cmake-wasm

path/to/emsdk/upstream/emscripten/emcmake cmake ../..

# Package
make -j8 emdawnwebgpu_pkg

Samples and tests:

# Samples (for a list of samples, see ENABLE_EMSCRIPTEN targets in src/dawn/samples/CMakeLists.txt)
make -j8 HelloTriangle

# Tests
make -j8 emdawnwebgpu_tests_asyncify emdawnwebgpu_tests_jspi

(To use Ninja instead of Make, for better parallelism, add -GNinja to the cmake invocation, and build using ninja.)

Samples and tests produce HTML files which can be served and viewed in a compatible browser.

Standalone with GN

• Set up Emscripten as per instructions above using dawn_wasm.

• Build the emdawnwebgpu and samples GN build targets.

Samples and tests produce HTML files in out/<dir>/wasm which can be served and viewed in a compatible browser.

Appendix: Bits of Emscripten we depend on

(Internal docs for coordination between Emscripten and Emdawnwebgpu.)

Emdawnwebgpu depends on a lot of random bits of Emscripten that aren‘t usually public. We assume they’re “mostly stable” for now and will update this (and roll into Emscripten) as needed if they change. Most, but not all, incompatible changes will be detected on Emscripten‘s CI, because it tests Emdawnwebgpu. This list is a best effort to enumerate them, but definitely isn’t complete.

• Remote ports
• In emdawnwebgpu.port.py:
  • Ports API in general
  • Modifying various settings in linker_setup()
  • tools.diagnostics.error
• In package build:
  • tools/gen_struct_info.py
• In library_webgpu.js:
  • Various items from parseTools and jsifier
    • *__i53abi: true
    • makeGetValue
    • runtimeKeepalivePush/runtimeKeepalivePop
  • Public settings:
    • ASSERTIONS
    • ASYNCIFY
    • USE_WEBGPU
    • MEMORY64, WASM_BIGINT
  • settings_internal.js settings:
    • CAN_ADDRESS_2GB
  • Public preamble:
    • assert, abort
  • Internal library functions:
    • stackSave, stackRestore
    • stringToUTF8OnStack, UTF8ToString, stringToNewUTF8, lengthBytesUTF8
    • callUserCallback
    • warnOnce
    • readI53FromI64/writeI53ToI64
    • findCanvasEventTarget
• In webgpu.cpp:
  • Public APIs:
    • emscripten_has_asyncify