Google’s Dawn WebGPU implementation, cross-compiled with Zig into a single static library, requiring nothing more than zig
and git
to build and cross-compile a static Dawn library for every OS:
- No cmake
- No ninja
- No
gn
- No system dependencies (xcode, etc.)
- Automagic cross compilation out of the box with nothing more than
zig
andgit
! - Builds a single static
libdawn.a
Building from source
This will take ~10 minutes to finish, so by default when using this package a prebuilt binary version of Dawn (see the ‘binary releases’ section below) but you can always build Dawn from source using:
DAWN_FROM_SOURCE=true zig build
Binary releases
Dawn (specifically all the shader compilers, and the DirectXShaderCompiler) is a large C++ codebase and takes 5-10 minutes to build on a modern laptop. Since waiting is no fun, we also have binary releases produced by our GitHub actions:
Here’s how to read the downloads provided:
_debug.tar.gz
and_release-fast.tar.gz
are tarballs of the static library + headers for each OS and debug/release mode, respectively.headers.json.gz
is a JSON archive of all the Dawn/WebGPU headers.- Files ending in
.a.gz
and.lib.gz
are the individual staticlibdawn.a
anddawn.lib
(Windows) gzippped and distributed. These are provided as individual downloads so there is no need to extract a tarball.
Important: Building WebGPU API symbols
Dawn and other WebGPU implementations (like the Rust one) do not agree on a standard webgpu.h
API. Aspirationally, they aim to target the same https://github.com/webgpu-native/webgpu-headers header, but in practice they expose different APIs which are not ABI compatible.
When you call a Dawn webgpu.h
function, Dawn internally diverts this call through a vtable which must be initialized using a call to dawnProcSetProcs
.
mach/gpu-dawn
builds since Oct 17th 2022 no longer include the webgpu.h
symbols by default. If you intend to actually call the WebGPU API, you should build these two source files as part of your application:
And call dawnProcSetProcs
to set up the proc table.
A warning about API stability
You should be aware:
- WebGPU’s API is not formalized yet.
- Dawn’s API is still changing.
- The
webgpu.h
API is still changing - Dawn and gfx-rs/wgpu, although both try to implement
webgpu.h
, do not exactly implement the same interface. There are subtle differences in device discovery & creation for example.
Generated code
Dawn itself relies on a fairly large amount of dependencies, generated code, etc. To avoid having any dependency on Google build tools, code generation, etc. we maintain a minor fork of Dawn which has generated code and third-party dependencies comitted in “generated” branches. We are usually up-to-date with the upstream within a few weeks on average.
It also provides a few small patches to enable building Dawn with the Zig compiler which we plan to upstream soon, as well as some patches to build the DirectXShaderCompiler with Zig.
Getting started
Create a build.zig.zon
in your project (replace LATEST_COMMIT
with the latest commit hash):
.{
.name = "mypkg",
.version = "0.1.0",
.dependencies = .{
.mach_gpu_dawn = .{
.url = "https://pkg.machengine.org/mach-gpu-dawn/LATEST_COMMIT.tar.gz",
},
},
}
Run zig build
in your project, and the compiler will instruct you to add a .hash = "..."
field next to .url
:
note: expected .hash = "12209838fcfb7a77d2d6931efdc7448c033a1b7dad11d082c94bbeeba9d1038cd311",
Then use the dependency in your build.zig
:
pub fn build(b: *std.Build) void {
...
exe.addModule("mach-gpu-dawn", b.dependency("mach_gpu_dawn", .{
.target = target,
.optimize = optimize,
}).module("mach-gpu-dawn"));
}
You can now use it in your src/main.zig
file:
const gpu_dawn = @import("mach-gpu-dawn");
Ran into trouble?
Triple-check you followed the build.zig.zon
instructions correctly, it’s easy to mess that part up.
Feel free to join the Mach Discord community for help.