a1fe671db8
* all: build: fix sdkPath for relative @src.file
Prior to this commit, the build system heavily assumed that the result
`@src.file` would always be absolute, but this is no longer
guaranteed, likely due to there being no such thing as an "absolute
path" in WASI.
It appears that for normal invocations of `zig build`, it is safe to
assume that `@src.file` is absolute. However, when ZLS uses a custom
`build_runner.zig` to collect build configuration, `@src.file` is
actually relative to the current working directory, at least on my
system. For a while, this led to ZLS completions breaking entirely,
but presently it actually causes ZLS to crash!
The solution is not as simple as using relative `sdkPath` results
as-is, because the build system may attempt to resolve these paths
relative to build root, when the paths are actually relative to the
current working directory.
This leads to a sticky situation: the current working directory is a
runtime concept, but `@src.file` is resolved at compile time. However,
it appears that the build runner does not change current working
directory in between compilation and execution, so it is probably safe
to calculate `sdkPath` using runtime current working directory.
Still, this requires major changes with how `sdkPath` works, since
runtime computation and allocations are required. So pretty much
anything that relied on `sdkPath` being comptime-known has been
refactored in this commit.
The most severe result of this is that, for example, `gpu.pkg` can no
longer be a comptime-known constant: it has to be a runtime function
that takes a `*Builder` and returns a `Pkg`.
This commit deals with usages of `*.pkg` and `sdkPath` within Mach
itself, but projects that depend on Mach such as `mach-examples` will
almost certainly require changes as well.
* all: update README to reflect change in pkg usage
For details on updating your code to use this version, see:
|
||
|---|---|---|
| .. | ||
| .github | ||
| dev | ||
| libs | ||
| src | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| build.zig | ||
| LICENSE | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| README.md | ||
| sdk.zig | ||
mach/gpu-dawn, WebGPU/Dawn built with Zig 
mach/gpu-dawn builds Dawn, Google Chrome's WebGPU implementation, 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
zigandgit! - Builds a single static
libdawn.awith everything you need.
This repository is a separate copy of the same library in the main Mach repository, and is automatically kept in sync, so that anyone can use this library in their own project / engine if they like!
Building from source
Building Dawn from source using this method is simple:
git clone https://github.com/hexops/mach-gpu-dawn
cd mach-gpu-dawn
rm -rf libs/mach-glfw
git clone https://github.com/hexops/mach-glfw libs/mach-glfw
zig build
(Please make sure to use Zig nightly, e.g. v0.10, not v0.9, which you can get a binary release of at the very top of this page: https://ziglang.org/download/)
This will take ~10 minutes to finish (see the 'binary releases' section below.) You can add the following options:
| Option | Description |
|---|---|
-Drelease-fast=true |
Build a release binary instead of a debug binary (default) |
-Dtarget=x86_64-macos.12 |
Cross compile to macOS (Intel chipsets) |
-Dtarget=aarch64-macos.12 |
Cross compile to macOS (Apple Silicon) |
-Dtarget=x86_64-linux-gnu |
Cross compile to x86_64 Linux (glibc) |
-Dtarget=x86_64-linux-musl |
Cross compile to x86_64 Linux (musl libc) |
-Dtarget=x86_64-windows-gnu |
Cross compile to x86_64 Windows |
The following platforms are not yet supported, but we hope to support soon:
- iOS (Dawn does not officially support it yet)
- Android (Dawn does not officially support it yet)
- ARM Linux (aarch64)
- Windows msvc target (Zig targets MinGW libc on Windows currently, msvc support should not be hard to add.)
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.gzand_release-fast.tar.gzare tarballs of the static library + headers for each OS and debug/release mode, respectively.headers.json.gzis a JSON archive of all the Dawn/WebGPU headers.- Files ending in
.a.gzand.lib.gzare the individual staticlibdawn.aanddawn.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.hAPI 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.
Join the community
Join the Mach engine community on Matrix chat to discuss this project, ask questions, get help, etc.
Issues
Issues are tracked in the main Mach repository.
License
All Mach code (this repository) is under the Apache and MIT license at your choosing described in the LICENSE file. Dawn itself is similarly permissively licensed.