zig/mach
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

all: move standalone libraries to libs/ subdirectory

Browse source 
The root dir of our repository has grown quite a lot the past few months.

I'd like to make it more clear where the bulk of the engine lives (`src/`) and
also make it more clear which Mach libraries are consumable as standalone projects.

As for the name of this directory, `libs` was my first choice but there's a bit of
a convention of that being external libraries in Zig projects _today_, while these
are libraries maintained as part of Mach in this repository - not external ones.

We will name this directory `libs`, and if we have a need for external libraries
we will use `external` or `deps` for that directory name. I considered other names
such as `components`, `systems`, `modules` (which are bad as they overlap with
major ECS / engine concepts), and it seems likely the official Zig package manager
will break the convention of using a `libs` dir anyway.

Performed via:

```sh
mkdir libs/
git mv freetype libs/
git mv basisu libs/
git mv gamemode libs/
git mv glfw libs/
git mv gpu libs/
git mv gpu-dawn libs/
git mv sysaudio libs/
git mv sysjs libs/
git mv ecs libs/
```

git-subtree-dir: glfw
git-subtree-mainline: 0d5b853443
git-subtree-split: 572d1144f11b353abdb64fff828b25a4f0fbb7ca

Signed-off-by: Stephen Gutekanst <stephen@hexops.com>

git mv ecs libs/

Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
This commit is contained in:
Stephen Gutekanst 2022-08-26 13:29:04 -07:00 • committed by Stephen Gutekanst
parent 79ec61396f
commit 0645429df9
240 changed files with 6 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

85
libs/gpu-dawn/README.md Normal file
View file

@ -0,0 +1,85 @@
# mach/gpu-dawn, WebGPU/Dawn built with Zig <a href="https://hexops.com"><img align="right" alt="Hexops logo" src="https://raw.githubusercontent.com/hexops/media/master/readme.svg"></img></a>
`mach/gpu-dawn` builds [Dawn](https://dawn.googlesource.com/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 `zig` and `git`!
* Builds a single static `libdawn.a` with everything you need.
This repository is a separate copy of the same library in the [main Mach repository](https://github.com/hexops/mach), 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:
```sh
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 -Ddawn-from-source=true
```
(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, you just need to specify `-Ddawn-from-source=true` and wait. Since waiting is no fun, we also have binary releases produced by our GitHub actions:
**[View binary releases](https://github.com/hexops/mach-gpu-dawn/releases/latest)**
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 static `libdawn.a` and `dawn.lib` (Windows) gzippped and distributed. These are provided as individual downloads so there is no need to extract a tarball.
## 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.](https://github.com/hexops/dawn/tree/main/mach) 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](https://github.com/hexops/mach/issues/168) which we plan to upstream soon, as well as some [patches to build the DirectXShaderCompiler with Zig](https://github.com/hexops/mach/issues/151).
## Join the community
Join the Mach engine community [on Matrix chat](https://matrix.to/#/#hexops:matrix.org) to discuss this project, ask questions, get help, etc.
## Issues
Issues are tracked in the [main Mach repository](https://github.com/hexops/mach/issues?q=is%3Aissue+is%3Aopen+label%3Agpu-dawn).
## 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](https://github.com/hexops/dawn/blob/main/LICENSE).