vello/doc/shader_compilation.md

# How shader compilation works

We use git branches to support shader compilation in the cloud. The `dev` branch contains only shader source files (in GLSL format), while the `main` branch contains generated shaders. On every push to the `dev` branch, a GitHub action runs which compiles the shaders and pushes those to `main`.

Thus, you can run piet-gpu from the `main` branch without requiring any shader compilation tools. Also, the `dev` branch has a relatively clean history, and PRs can be made against it without having to worry about merge conflicts in the generated shader files.

If you do want to make changes to the shaders, you'll need some tools installed:

* [Ninja]
* [Vulkan SDK] (mostly for glslangValidate, spirv-cross)
* [DirectX Shader Compiler][DXC]

The GitHub action runs on Windows so the DXC signing can succeed (note that [hassle-rs] may provide an alternate solution). We currently only compile to MSL on Metal, not AIR, due to tooling friction. The Metal shader compiler is available on Windows, but a barrier to running in CI is that downloading it appears to require an Apple account. Longer term we will want to figure out a solution to this, because the piet-gpu vision involves ahead-of-time compilation of shaders as much as possible.

Right now the scripts for compiling shaders are done in hand-written ninja files. This is likely to change, as the number of permutations will increase, and we also may want access to metadata from the shader compilation process.

Following a few general rules should hopefully keep things running smoothly:

* Prepare all PRs against the `dev` branch, not `main`.
* Don't commit generated shaders in the PR.
* Don't commit directly to `main`, it will cause divergence.

[Ninja]: https://ninja-build.org/
[Vulkan SDK]: https://www.lunarg.com/vulkan-sdk/
[DXC]: https://github.com/microsoft/DirectXShaderCompiler