feat(devcontainer): add Mesa Dozen WSLg runtime (#41)

.github/workflows/publish-linux.yml

@@ -23,7 +23,7 @@ concurrency:
 jobs:
   publish:
     runs-on: ubuntu-26.04
-    timeout-minutes: 60
+    timeout-minutes: 180
     steps:
       - name: Check out image sources
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/validate.yml

@@ -38,11 +38,16 @@ jobs:
             .dockerignore | .github/actionlint.yaml | \
                 .github/workflows/* | linux/* | \
                 audio-toolchain.json | audio-toolchain.spdx.json | \
+                classic-vulkan-toolchain.json | \
+                classic-vulkan-toolchain.spdx.json | \
+                classic-vulkan-packages.lock | \
                 toolchains.json | tools/audio/* | \
                 tools/build-sdl3-mixer.sh | \
+                tools/install_classic_vulkan_toolchain.py | \
                 tools/require-image-checks.sh | \
                 tools/test-require-image-checks.sh | \
-                tools/validate-toolchains.sh)
+                tools/validate-toolchains.sh | \
+                tools/validate-vulkan-toolchain.sh)
               linux=true
               ;;
             esac
@@ -53,13 +58,19 @@ jobs:
                 classic-packages.lock | classic-toolchain.json | \
                 classic-shader-toolchain.json | \
                 classic-shader-toolchain.spdx.json | \
+                classic-vulkan-toolchain.json | \
+                classic-vulkan-toolchain.spdx.json | \
+                classic-vulkan-packages.lock | \
                 tools/audio/* | tools/build-sdl3-mixer.sh | \
                 tools/require-image-checks.sh | \
                 tools/test-require-image-checks.sh | \
                 tools/validate-classic-check.sh | \
                 tools/validate-classic-image.sh | \
                 tools/install_classic_shader_toolchain.py | \
-                tools/tests/test_install_classic_shader_toolchain.py)
+                tools/tests/test_install_classic_shader_toolchain.py | \
+                tools/install_classic_vulkan_toolchain.py | \
+                tools/validate-vulkan-toolchain.sh | \
+                tools/tests/test_install_classic_vulkan_toolchain.py)
               classic=true
               ;;
             esac
@@ -98,12 +109,15 @@ jobs:
       - name: Test Classic shader toolchain installer
         run: python3 -m unittest tools/tests/test_install_classic_shader_toolchain.py
 
+      - name: Test Classic Vulkan toolchain installer
+        run: python3 -m unittest tools/tests/test_install_classic_vulkan_toolchain.py
+
   linux:
     name: Linux image
     needs: changes
     if: needs.changes.outputs.linux == 'true'
     runs-on: ubuntu-26.04
-    timeout-minutes: 60
+    timeout-minutes: 180
     permissions:
       attestations: read
       contents: read
@@ -336,7 +350,7 @@ jobs:
     needs: changes
     if: needs.changes.outputs.classic == 'true'
     runs-on: ubuntu-26.04
-    timeout-minutes: 60
+    timeout-minutes: 180
     steps:
       - name: Check out image sources
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

AGENTS.md

@@ -23,8 +23,11 @@
 - The public Classic image's shader contract is defined by
   `classic-shader-toolchain.json`: retain the exact DXC/SPIRV-Cross archive and
   source checksums, upstream licenses, and `/usr/local/bin` tool paths. Its
-  pinned Lavapipe/Xvfb packages provide the equivalent public environment for
-  fork-safe GPU coverage; consumers still pin a released image digest.
+  `classic-vulkan-toolchain.json` contract builds the pinned Mesa Dozen driver
+  from `classic-vulkan-packages.lock`, carries only the dzn library and ICD
+  into both Linux images, and records the WSLg host mounts/environment. Its
+  pinned Lavapipe/Xvfb packages remain the fork-safe headless path; consumers
+  still pin a released image digest and supply WSLg adapter selection.
 - Keep a stable numeric runner UID when restoring a Classic ccache directory;
   the mode-1777 mount root supports non-root initialization but does not make
   ccache's owner-writable nested directories reusable across different UIDs.

README.md

@@ -112,7 +112,9 @@ docker run --rm atrinik-classic-build dxc --version
 docker run --rm atrinik-classic-build spirv-cross --help
 docker run --rm atrinik-classic-build \
   sh -c 'test -f /usr/share/vulkan/icd.d/lvp_icd.json && \
-    VK_DRIVER_FILES=/usr/share/vulkan/icd.d/lvp_icd.json vulkaninfo --summary'
+    test -f /usr/share/vulkan/icd.d/dzn_icd.x86_64.json && \
+    VK_DRIVER_FILES=/usr/share/vulkan/icd.d/lvp_icd.json \
+      xvfb-run -a vulkaninfo --summary'
 docker run --rm atrinik-linux-build \
   atrinik-sdl3-mixer-probe \
   /usr/local/share/atrinik/audio/opus-probe.opus
@@ -179,6 +181,40 @@ Classic digest can serve both the shader-producing build and fork-safe GPU
 coverage jobs. The Classic consumer must update its separate workflow to pin
 that released digest; this image change does not rewrite consumer source.
 
+The public Linux and Classic images also carry the Mesa Dozen Vulkan runtime
+described by [`classic-vulkan-toolchain.json`](classic-vulkan-toolchain.json).
+Mesa 26.0.8 is built once from its checksum-pinned source archive with only
+the Wayland/D3D12 Vulkan path enabled; the build-only package closure is
+recorded in [`classic-vulkan-packages.lock`](classic-vulkan-packages.lock) and
+the source provenance in
+[`classic-vulkan-toolchain.spdx.json`](classic-vulkan-toolchain.spdx.json).
+Only those two custom-built artifacts—`/usr/lib/x86_64-linux-gnu/libvulkan_dzn.so`
+and `/usr/share/vulkan/icd.d/dzn_icd.x86_64.json`—enter the runtime images
+from the Mesa build stage. CI continues to select Lavapipe explicitly through
+Xvfb. A WSLg consumer can
+select Dozen after providing `/dev/dxg`, `/usr/lib/wsl`, and the WSLg runtime
+mounts plus its adapter name:
+
+```sh
+docker run --rm --gpus=all \
+  --device=/dev/dxg \
+  --volume /usr/lib/wsl:/usr/lib/wsl:ro \
+  --volume /mnt/wslg:/mnt/wslg:ro \
+  --env DISPLAY= \
+  --env WAYLAND_DISPLAY=wayland-0 \
+  --env XDG_RUNTIME_DIR=/mnt/wslg/runtime-dir \
+  --env LD_LIBRARY_PATH=/usr/lib/wsl/lib \
+  --env GALLIUM_DRIVER=d3d12 \
+  --env MESA_D3D12_DEFAULT_ADAPTER_NAME=NVIDIA \
+  --env VK_DRIVER_FILES=/usr/share/vulkan/icd.d/dzn_icd.x86_64.json \
+  atrinik-classic-build vulkaninfo --summary
+```
+
+The adapter name is deliberately consumer-supplied; non-WSLg CI never selects
+an NVIDIA device. The image validator runs the existing Lavapipe/Xvfb probe
+and runs the Dozen probe only when all WSLg mounts/libraries and the consumer
+adapter variable are present.
+
 Classic runs as the unprivileged `ubuntu` user by default. `/cache/ccache` is a
 mode-1777 mount contract so CI can run with its own numeric UID and persist the
 directory without granting root. Consumers must still select ccache explicitly
@@ -205,8 +241,9 @@ the digest, never a rolling tag. To update that pin:
 1. Update the matching Ubuntu base digest and snapshot value in both
    `linux/Dockerfile` and `classic-toolchain.json`, refresh the exact direct
    versions in `classic-packages.lock`, and update the tool versions, shader
-   coordinates in `classic-shader-toolchain.json`, and pinned Classic
-   validation commit in `classic-toolchain.json`.
+   coordinates in `classic-shader-toolchain.json`, Mesa Dozen source
+   coordinates in `classic-vulkan-toolchain.json`, the Vulkan build lock, and
+   pinned Classic validation commit in `classic-toolchain.json`.
 2. Build `classic-validation` and `classic-final`, run the repository checks,
    and compare compressed image size plus local client/server timings with the
    prior digest.

classic-packages.lock

@@ -11,6 +11,7 @@ gcovr=7.2+really-2
 git=1:2.53.0-1ubuntu1
 jq=1.8.1-4ubuntu2
 libcurl4-openssl-dev=8.18.0-1ubuntu2.3
+libdrm2=2.4.131-1
 libgd-dev=2.3.3-13ubuntu2
 libidn2-dev=2.3.8-4build1
 libminiupnpc-dev=2.3.3-2build1
@@ -21,7 +22,9 @@ libsdl3-ttf-dev=3.2.2+ds-1build1
 libssl-dev=3.5.5-1ubuntu3.3
 libssl3t64=3.5.5-1ubuntu3.3
 libsubunit-dev=1.4.4+1-1
+libudev1=259.5-0ubuntu3.3
 libvulkan1=1.4.341.0-1
+libwayland-client0=1.24.0-2
 libxml2-dev=2.15.2+dfsg-0.1ubuntu0.1
 mesa-vulkan-drivers=26.0.3-1ubuntu1
 ninja-build=1.13.2-1
@@ -33,4 +36,5 @@ python3-dev=3.14.3-0ubuntu2
 vulkan-tools=1.4.341.0+dfsg1-1
 xauth=1:1.1.2-1.1build1
 xvfb=2:21.1.22-1ubuntu1
+zlib1g=1:1.3.dfsg+really1.3.1-1ubuntu3
 zlib1g-dev=1:1.3.dfsg+really1.3.1-1ubuntu3

classic-vulkan-packages.lock

@@ -0,0 +1,23 @@
+bison=2:3.8.2+dfsg-1build4
+build-essential=12.12ubuntu2.26.04.2
+ca-certificates=20260601~26.04.1
+directx-headers-dev=1.619.1-1
+flex=2.6.4-8.2build2
+libdrm-dev=2.4.131-1
+libssl3t64=3.5.5-1ubuntu3.3
+libudev-dev=259.5-0ubuntu3.3
+libvulkan-dev=1.4.341.0-1
+libwayland-dev=1.24.0-2
+meson=1.10.1-1ubuntu2
+ninja-build=1.13.2-1
+openssl=3.5.5-1ubuntu3.3
+openssl-provider-legacy=3.5.5-1ubuntu3.3
+pkgconf=2.5.1-4
+python3=3.14.3-0ubuntu2
+python3-dev=3.14.3-0ubuntu2
+python3-mako=1.3.10-3build1
+python3-markupsafe=3.0.3-1build1
+python3-setuptools=78.1.1-0.1build1
+python3-yaml=6.0.3-1build1
+wayland-protocols=1.47-1
+zlib1g-dev=1:1.3.dfsg+really1.3.1-1ubuntu3

classic-vulkan-toolchain.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": 1,
+  "platform": "linux/amd64",
+  "target": "classic-final",
+  "image": "ghcr.io/atrinik/classic-build",
+  "base": {
+    "image": "ubuntu:26.04",
+    "digest": "sha256:678c6550cc43645e08669028bc177f50be4e7c5b8cca677067b1914d4afc7a03",
+    "apt_snapshot": "20260810T000000Z"
+  },
+  "source": {
+    "repository": "mesa/mesa",
+    "tag": "mesa-26.0.8",
+    "version": "26.0.8",
+    "commit": "60e95b787857afbc9a00b693b91c0d9c8923a430",
+    "url": "https://archive.mesa3d.org/mesa-26.0.8.tar.xz",
+    "sha256": "caf1c0061a68e88dfa74967a7e780c0e85d65b6c4e334cd69095a5dc54ad78bc",
+    "archive_root": "mesa-26.0.8"
+  },
+  "build": {
+    "system": "meson",
+    "version": "1.10.1",
+    "package_lock": "classic-vulkan-packages.lock",
+    "configure": {
+      "buildtype": "release",
+      "libdir": "lib/x86_64-linux-gnu",
+      "prefix": "/usr",
+      "wrap_mode": "nodownload"
+    },
+    "options": {
+      "build-tests": false,
+      "display-info": "disabled",
+      "egl": "disabled",
+      "expat": "disabled",
+      "gallium-d3d12-graphics": "enabled",
+      "gallium-d3d12-video": "disabled",
+      "gallium-drivers": ["d3d12"],
+      "gallium-rusticl": false,
+      "gallium-va": "disabled",
+      "gbm": "disabled",
+      "glx": "disabled",
+      "gles1": "disabled",
+      "gles2": "disabled",
+      "html-docs": "disabled",
+      "install-mesa-clc": false,
+      "libunwind": "disabled",
+      "llvm": "disabled",
+      "lmsensors": "disabled",
+      "mesa-clc": "auto",
+      "opengl": false,
+      "perfetto": false,
+      "platforms": ["wayland"],
+      "shared-glapi": "disabled",
+      "spirv-tools": "disabled",
+      "teflon": false,
+      "valgrind": "disabled",
+      "vulkan-drivers": ["microsoft-experimental"],
+      "vulkan-manifest-per-architecture": true,
+      "xmlconfig": "disabled",
+      "zstd": "disabled"
+    }
+  },
+  "install": {
+    "library": "/usr/lib/x86_64-linux-gnu/libvulkan_dzn.so",
+    "icd": "/usr/share/vulkan/icd.d/dzn_icd.x86_64.json",
+    "icd_library": "libvulkan_dzn.so",
+    "icd_api_version": "1.1.335"
+  },
+  "runtime": {
+    "packages": [
+      {"name": "libdrm2", "version": "2.4.131-1"},
+      {"name": "libudev1", "version": "259.5-0ubuntu3.3"},
+      {"name": "libvulkan1", "version": "1.4.341.0-1"},
+      {"name": "libwayland-client0", "version": "1.24.0-2"},
+      {"name": "mesa-vulkan-drivers", "version": "26.0.3-1ubuntu1"},
+      {"name": "vulkan-tools", "version": "1.4.341.0+dfsg1-1"},
+      {"name": "zlib1g", "version": "1:1.3.dfsg+really1.3.1-1ubuntu3"}
+    ],
+    "shared_library_sonames": [
+      "libc.so.6",
+      "libdrm.so.2",
+      "libgcc_s.so.1",
+      "libm.so.6",
+      "libudev.so.1",
+      "libwayland-client.so.0",
+      "libz.so.1"
+    ],
+    "headless": {
+      "vulkan_icd": "/usr/share/vulkan/icd.d/lvp_icd.json",
+      "display_server": "Xvfb",
+      "commands": ["vulkaninfo", "Xvfb", "xvfb-run"]
+    },
+    "wslg": {
+      "vulkan_icd": "/usr/share/vulkan/icd.d/dzn_icd.x86_64.json",
+      "required_mounts": [
+        "/dev/dxg",
+        "/mnt/wslg/runtime-dir",
+        "/usr/lib/wsl"
+      ],
+      "required_host_libraries": [
+        "/usr/lib/wsl/lib/libd3d12.so",
+        "/usr/lib/wsl/lib/libdxcore.so"
+      ],
+      "fixed_environment": {
+        "DISPLAY": "",
+        "GALLIUM_DRIVER": "d3d12",
+        "LD_LIBRARY_PATH": "/usr/lib/wsl/lib",
+        "VK_DRIVER_FILES": "/usr/share/vulkan/icd.d/dzn_icd.x86_64.json",
+        "WAYLAND_DISPLAY": "wayland-0",
+        "XDG_RUNTIME_DIR": "/mnt/wslg/runtime-dir"
+      },
+      "consumer_environment": ["MESA_D3D12_DEFAULT_ADAPTER_NAME"],
+      "probe": ["vulkaninfo", "--summary"]
+    }
+  }
+}

classic-vulkan-toolchain.spdx.json

@@ -0,0 +1,36 @@
+{
+  "spdxVersion": "SPDX-2.3",
+  "dataLicense": "CC0-1.0",
+  "SPDXID": "SPDXRef-DOCUMENT",
+  "name": "Atrinik Classic WSLg Vulkan Dozen runtime",
+  "documentNamespace": "https://github.com/atrinik/devcontainer/sbom/classic-vulkan-toolchain/60e95b787857afbc9a00b693b91c0d9c8923a430",
+  "creationInfo": {
+    "created": "2026-08-31T00:00:00Z",
+    "creators": ["Tool: Atrinik devcontainer vulkan-toolchain inventory"]
+  },
+  "packages": [
+    {
+      "SPDXID": "SPDXRef-Package-Mesa",
+      "name": "Mesa",
+      "versionInfo": "26.0.8",
+      "downloadLocation": "https://archive.mesa3d.org/mesa-26.0.8.tar.xz",
+      "filesAnalyzed": false,
+      "checksums": [
+        {
+          "algorithm": "SHA256",
+          "checksumValue": "caf1c0061a68e88dfa74967a7e780c0e85d65b6c4e334cd69095a5dc54ad78bc"
+        }
+      ],
+      "licenseConcluded": "NOASSERTION",
+      "licenseDeclared": "NOASSERTION",
+      "copyrightText": "NOASSERTION"
+    }
+  ],
+  "relationships": [
+    {
+      "spdxElementId": "SPDXRef-DOCUMENT",
+      "relationshipType": "DESCRIBES",
+      "relatedSpdxElement": "SPDXRef-Package-Mesa"
+    }
+  ]
+}