zig/0.17: merge main (40 commits, to #469)

.github/workflows/ci.yml

@@ -184,6 +184,17 @@ jobs:
       - name: Fetch dependencies (with retries)
         shell: bash
         run: bash scripts/ci-retry.sh zig build --fetch
+      # Every test binary is compiled before any of them runs, so no compiler is alive beside a
+      # running test. On Windows, Zig 0.16 spawns each child inheriting every inheritable handle
+      # the build runner holds, the pipes it is making for its other children included. A
+      # compiler spawned while a test's pipes exist keeps a copy of that test's stdout: the test
+      # passes and exits, but its stdout reaches EOF only when the compiler exits, and the runner
+      # gives up after a minute with "test runner failed to respond", on whichever tiny test was
+      # unlucky, about one run in thirty. `check` is exactly the compiles `test` needs, so the
+      # step after it spawns only test binaries, which live for milliseconds.
+      - name: Compile tests
+        shell: bash
+        run: bash scripts/ci-retry.sh zig build check --summary all
       - name: Run tests
         shell: bash
         run: bash scripts/ci-retry.sh zig build test --summary all
@@ -211,6 +222,12 @@ jobs:
         if: matrix.name == 'macOS'
         run: bash scripts/ci-retry.sh zig build -Dnative-backend=sdl3 -Dno-emit --summary all
 
+      # A link-only app (`-Ddynamic-plugins=false`): its gates on loading plugins at runtime are
+      # comptime, so only a build with it off shows that build still compiles.
+      - name: Compile a link-only app
+        if: matrix.name == 'Linux'
+        run: bash scripts/ci-retry.sh zig build -Ddynamic-plugins=false -Dno-emit --summary all
+
       # The suites for SDL's patches on macOS (FizzyGPU's Metal tests; the rest are Linux's), when
       # SDL's patches or pins changed: see the `sdl` job. Is there a Metal device? The probe says,
       # and the suite then requires Metal, so a runner with one can't skip the Metal tests. (On

.github/workflows/shaders.yml

@@ -0,0 +1,133 @@
+# The SPIR-V and DXIL fizzy's native backend embeds (Vulkan, D3D12), compiled from their HLSL here
+# rather than on someone's machine, and checked against what is committed.
+#
+# Each `X.hlsl` beside compiled forms of it (`compiled/{spv,dxil,msl,glsl}/X.*`) is compiled by
+# `scripts/compile-shaders.sh` and compared byte for byte. A difference fails the job and uploads the fresh
+# files as the `compiled-shaders` artifact, laid out as the repository has them: download it and
+# commit them. Before this, nothing noticed when the HLSL changed and the compiled files did not,
+# and Windows and Linux quietly drew the previous glass (#242, #373).
+#
+# The toolchain: SDL_shadercross, pinned, with the DirectXShaderCompiler release it pins itself
+# (Microsoft's prebuilt v1.9.2602, by SHA-256), as shadercross's own CI builds it. Nothing heavy is
+# built here: SPIRV-Cross and shadercross, a few minutes, cached by the pin. The shaders that had
+# not changed since they were compiled (the backend's defaults) reproduce with it byte for byte,
+# SPIR-V and DXIL: it is the toolchain they were made with.
+
+name: Shaders
+
+on:
+  pull_request:
+    paths:
+      - "**/*.hlsl"
+      - "**/shaders/compiled/**"
+      - "scripts/compile-shaders.sh"
+      - ".github/workflows/shaders.yml"
+  push:
+    branches: [main]
+    paths:
+      - "**/*.hlsl"
+      - "**/shaders/compiled/**"
+      - "scripts/compile-shaders.sh"
+      - ".github/workflows/shaders.yml"
+  workflow_dispatch:
+
+env:
+  SHADERCROSS_REPO: libsdl-org/SDL_shadercross
+  # Its build-scripts/download-prebuilt-DirectXShaderCompiler.cmake pins DXC v1.9.2602.
+  SHADERCROSS_SHA: 1ff05bec573988a98ef9e0260b4da44f512b8367
+
+jobs:
+  compile:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 150
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cached shadercross
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: ~/shadercross
+          key: shadercross-${{ env.SHADERCROSS_SHA }}-prebuilt-dxc-1
+
+      - name: Toolchain
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y ninja-build cmake spirv-tools
+
+      # Every run: shadercross links SDL, cached or not (setup-sdl caches its own build).
+      - name: SDL
+        id: sdl
+        uses: libsdl-org/setup-sdl@main
+        with:
+          version: 3-latest
+          cmake-generator: Ninja
+          install-linux-dependencies: true
+
+      - name: Build shadercross (prebuilt DXC)
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          git clone --filter=blob:none "https://github.com/$SHADERCROSS_REPO" sc
+          git -C sc checkout "$SHADERCROSS_SHA"
+          git -C sc submodule update --init --depth 1 external/SPIRV-Cross
+          # Microsoft's release of DXC, as shadercross pins it (version and SHA-256).
+          cmake -P sc/build-scripts/download-prebuilt-DirectXShaderCompiler.cmake
+          dxc_root="$PWD/sc/external/DirectXShaderCompiler-binaries"
+          cmake -S sc/external/SPIRV-Cross -B spirv_cross_build -GNinja \
+            -DCMAKE_BUILD_TYPE=Release -DSPIRV_CROSS_SHARED=ON -DSPIRV_CROSS_STATIC=ON \
+            -DCMAKE_INSTALL_PREFIX="$HOME/shadercross"
+          cmake --build spirv_cross_build
+          cmake --install spirv_cross_build
+          cmake -S sc -B sc/build -GNinja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DSDLSHADERCROSS_VENDORED=OFF \
+            -DSDLSHADERCROSS_CLI=ON \
+            -DSDLSHADERCROSS_SHARED=ON \
+            -DSDLSHADERCROSS_STATIC=OFF \
+            -DSDLSHADERCROSS_WERROR=OFF \
+            -DSDLSHADERCROSS_INSTALL=ON \
+            -DSDLSHADERCROSS_INSTALL_RUNTIME=ON \
+            -DDirectXShaderCompiler_ROOT="$dxc_root" \
+            -Dspirv_cross_c_shared_ROOT="$HOME/shadercross:$HOME/shadercross/share/spirv_cross_c_shared" \
+            -DCMAKE_INSTALL_PREFIX="$HOME/shadercross"
+          cmake --build sc/build --parallel
+          cmake --install sc/build
+          # The compiler shadercross loads at run time, beside it.
+          find "$dxc_root" -name 'lib*.so*' -exec cp -L {} "$HOME/shadercross/lib/" \;
+          ls "$HOME/shadercross/lib"
+
+      - name: Compile and compare
+        run: |
+          export PATH="$HOME/shadercross/bin:$PATH"
+          export LD_LIBRARY_PATH="$HOME/shadercross/lib:${{ steps.sdl.outputs.prefix }}/lib:$LD_LIBRARY_PATH"
+          shadercross --help > /dev/null 2>&1 || { echo "shadercross does not run"; ldd "$HOME/shadercross/bin/shadercross"; exit 1; }
+          command -v spirv-cross
+          failed=0
+          bash scripts/compile-shaders.sh out || failed=1
+          stale=0
+          while IFS= read -r fresh; do
+            committed=${fresh#out/}
+            if cmp -s "$committed" "$fresh"; then
+              echo "ok      $committed"
+            else
+              echo "::error file=$committed::$committed is not what its HLSL compiles to: download the compiled-shaders artifact and commit it"
+              echo "        committed $(stat -c %s "$committed") bytes, compiled $(stat -c %s "$fresh")"
+              stale=1
+            fi
+            case $fresh in
+              *.spv) spirv-val "$fresh" || { echo "::error file=$committed::$fresh does not validate"; failed=1; } ;;
+            esac
+          done < <(find out -type f | sort)
+          echo "stale=$stale" >> "$GITHUB_ENV"
+          echo "failed=$failed" >> "$GITHUB_ENV"
+
+      - name: Upload the fresh compiled shaders
+        if: env.stale == '1' || env.failed == '1'
+        uses: actions/upload-artifact@v4
+        with:
+          name: compiled-shaders
+          path: out/
+
+      - name: Fail on stale or broken compiled shaders
+        if: env.stale == '1' || env.failed == '1'
+        run: exit 1

AGENTS.md

@@ -62,9 +62,16 @@ Full contract: **[`docs/PLUGINS.md`](docs/PLUGINS.md)**. Living reshape plan: **
 
 Which plugins an executable links in is build data: `build/sdk.zig`'s `bundledPluginsModule`
 generates `bundled_plugins` (`pub const modules = .{ @import("workbench"), … }`) and the
-runtime iterates it — nothing in `app/` or `src/` names a plugin except the workbench (its
-state still lives on the Editor). An app built on fizzy adds its own with `defer-app` +
-`fizzy.buildApp(fizzy_dep, &.{ .{ .name, .module = dep.module("plugin") } })`; see
+runtime iterates it. Nothing in `app/` or `src/` registers a plugin by name, though two are
+imported as libraries and so always built: workbench (its state still lives on the Editor, so
+every list must include it) and markdown (the store draws READMEs with it). An app built on
+fizzy lists every plugin it links with `defer-app` + `fizzy.buildApp(fizzy_dep, &.{
+fizzy.plugins.workbench, fizzy.plugins.text, .{ .name, .module = dep.module("plugin") } })`:
+fizzy's own are entries with no module, built for each executable (`build/plugins.zig`'s
+`link`), and only those listed register or get a dylib. `.@"dynamic-plugins" = false` (or
+`-Ddynamic-plugins=false`) makes an app link-only: no plugin dylib is built, and nothing loads
+at runtime (fizzy's dylibs, the user plugins directory, the store, a web page's `?plugin=`),
+all decided at comptime (`App.loads_plugins`). See
 [`fizzyedit/example-app`](https://github.com/fizzyedit/example-app), which bundles
 `fizzyedit/example-plugin`.
 

CONTRIBUTING.md

@@ -150,6 +150,13 @@ maintainer makes the SDK **live** on the site (below).
 | Plans | private, in [`fizzyedit/plans`](https://github.com/fizzyedit/plans): issues, and a long design as `plans/<NAME>_PLAN.md` opening with a status line (`Status: proposed`, `in progress, fizzyedit/fizzy#N`, or `done`) |
 | The forks fizzy builds on | `docs/DEPENDENCIES.md` |
 | Releases | `RELEASING.md` |
+| Licensing, and the name | `LICENSING.md`, `TRADEMARKS.md` |
+
+## Licensing contributions
+
+Fizzy is MIT (`LICENSING.md`), and a contribution comes in under the license it goes out under:
+opening a PR offers its change under MIT. There is no contributor license agreement. Code
+copied from elsewhere must carry a license compatible with MIT, and keeps its notice.
 
 ## Habits reviewers ask for