zig-aerie
Windows, a GPU renderer and text for Zig programs that draw their own interface.
Star
Fork
Watch
zig-aerie CONTRIBUTING.md
3.0 kB · 75 lines
Markdown
at main

Contributing to zig-aerie #

Issues and pull requests go to the Tangled mirror.

Setting up #

Everything needed is in the Nix development shell: Zig 0.17.0, the Vulkan loader and validation layer, spirv-val, reuse, and zon2nix.

$ nix develop
$ zig build test --summary all
$ zig build run

zig build check compiles everything, the tests and the demo, without running anything.

Before sending a change #

Each of these is checked by the workflow on every push:

  • reuse lint passes. A new file carries an SPDX header; one that cannot hold a header gets an entry in REUSE.toml.
  • zig fmt --check --exclude zig-pkg . passes.
  • zig build test passes. Tests that want fonts skip where there are none, as in a build sandbox, so run them on a machine with fonts as well.
  • zig build check -Dtarget=x86_64-windows-gnu passes: the Windows platform and swapchain compile only for Windows, so nothing else notices when they stop.

A change to build.zig.zon regenerates build.zig.zon.nix in the same commit:

$ nix develop -c zon2nix --17 --nix=build.zig.zon.nix build.zig.zon

How it is laid out #

  • src/platform/ — the window system. Event.zig is what a platform tells the application, in terms that do not name the window system; wayland/Platform.zig is the one platform there is.
  • src/gpu/ — the Vulkan device, the renderer, where finished frames go (Target.zig, wayland/), Canvas.zig, which builds a frame, and cpu.zig, which draws one without a GPU.
  • src/text/ — Fonts, scanned once; Family, a fallback list in four styles; Shaper, lines of text into placed glyphs; Glyphs and Atlas, the rasterized glyphs the renderer draws from.
  • src/decor/ — the title bar and frame.
  • src/desktop/ — the desktop's settings: settings.zig, the snapshot and the appearance read out of it; Watcher.zig, which reads them from the portal over D-Bus and follows their changes.
  • dbus/ — the D-Bus interfaces used, from which the build generates Zig.
  • shaders/cell.zig — the one vertex and fragment shader, in Zig, compiled to SPIR-V by Zig's own backend.
  • examples/demo.zig — a whole program using all of it.

Conventions #

  • Much of this came out of harrier, and harrier will be moved onto it. A change that only makes sense for one program belongs in that program; a name here does not mention a terminal, a pane or a commit.
  • An Io and an allocator are passed in, never reached for.
  • The application owns its loop. Nothing here starts a thread that calls back into it, or waits on anything but what it is asked to.
  • Doc comments carry the explanation: why a thing is the way it is, what went wrong when it was otherwise. They are published as the API documentation.