From e27bd6d4df23a2cda7b4ccfe54464d82e7cdfb7d Mon Sep 17 00:00:00 2001 From: Nick Newson Date: Sat, 8 Aug 2026 12:37:56 +0100 Subject: [PATCH] The pin had drifted from the SDK installed on the dev machine again: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit vulkan-headers/vulkan-loader 1.4.350.1 against an SDK at 1.4.357. That gap is the mixed-vulkan-hpp trap documented in CLAUDE.md — two header versions in one binary, aborting on the first RAII call with no bad line of C++ behind it — kept out of reach only by the include-order guard. Aligning the pin to 1.4.357.0 removes the gap itself. Taken in the gap between items and BEFORE arc 2's static-scene CSM caching rather than after it: that item is justified by measured shadow-pass time, and a loader/ICD move underneath its before/after numbers would make them unattributable. What moved: vulkan-headers + vulkan-loader 1.4.350.1 -> 1.4.357.0, spirv-tools/spirv-headers likewise, glslang 16.4.0, glfw3 3.4 -> 3.5.1, imgui 1.92.8 port-version 1. shaderc, ktx, fastgltf, catch2 and VMA are unchanged. CI PROVISIONING, WHICH THE BUMP BROKE WITH NO SOURCE CHANGE glfw3 3.5.1 pulls `pthread-stubs` on Linux, and vcpkg builds that port with `vcpkg_make` rather than CMake: it refuses to configure without autoconf, autoconf-archive, automake and libtool. The Docker image did not have them, so the Linux leg failed with BUILD_FAILED — reproducibly, which is what separated it from the ftpmirror.gnu.org 502 that appeared in the same run's output (that download succeeded on the ftp.gnu.org fallback and was not the cause). The four packages are added to tools/ci/Dockerfile AND to both Linux jobs of .github/workflows/ci.yml, because autoconf-archive is not preinstalled on ubuntu-latest either — the hosted runner would have failed the same way. --- .github/workflows/ci.yml | 11 +++++++++-- CLAUDE.md | 27 ++++++++++++++++++++++----- README.md | 18 +++++++++++++++--- docs/onboarding.md | 3 +++ tools/ci/Dockerfile | 9 +++++++++ vcpkg-configuration.json | 2 +- 6 files changed, 59 insertions(+), 11 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ab2a7c14..cc40b203 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,8 +39,12 @@ jobs: - name: Install system packages run: | sudo apt-get update + # autoconf/autoconf-archive/automake/libtool are for ports vcpkg builds with `vcpkg_make`: + # glfw3 3.5.1 pulls `pthread-stubs` on Linux, which is autotools-only and refuses to + # configure without them. `autoconf-archive` is not preinstalled on ubuntu-latest. sudo apt-get install -y ninja-build cmake clang-tidy libvulkan-dev \ - xorg-dev libxinerama-dev libxcursor-dev libglu1-mesa-dev pkg-config + xorg-dev libxinerama-dev libxcursor-dev libglu1-mesa-dev pkg-config \ + autoconf autoconf-archive automake libtool - name: Checkout vcpkg uses: actions/checkout@v4 @@ -86,8 +90,11 @@ jobs: - name: Install system packages run: | sudo apt-get update + # See the clang-tidy job above for why autotools are here: glfw3 3.5.1's `pthread-stubs` + # dependency is autotools-only on Linux. sudo apt-get install -y ninja-build cmake libvulkan-dev \ - xorg-dev libxinerama-dev libxcursor-dev libglu1-mesa-dev pkg-config + xorg-dev libxinerama-dev libxcursor-dev libglu1-mesa-dev pkg-config \ + autoconf autoconf-archive automake libtool - name: Checkout vcpkg uses: actions/checkout@v4 diff --git a/CLAUDE.md b/CLAUDE.md index f9ba9393..d7c7e5c5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -73,7 +73,7 @@ Assets copied via `cmake/copy_assets.cmake`. ## Dependencies -vcpkg manifest (`vcpkg.json`; versions from the default-registry baseline in `vcpkg-configuration.json`): `vulkan-headers`, `vulkan-memory-allocator`, `shaderc` (provides the `glslc` tool under `//tools/shaderc`), `catch2`, `stb`, `fastgltf`, `ktx`, `imgui[glfw-binding,vulkan-binding]`. The Vulkan **loader** and `glfw3` arrive transitively, so Vulkan + GLFW + the shader compiler all build from vcpkg — **no system Vulkan SDK / GLFW / glslang-tools**. System requirement is just a C++23 toolchain + Ninja; a Vulkan ICD (MoltenVK on macOS) is needed only at *runtime* to render, not to build or run the headless tests. `fireengine` links Vulkan/GLFW directly; `cmake/fireengine_imgui.cmake` wraps vcpkg's ImGui archive without its transitive Vulkan/GLFW link interface to avoid duplicate static-library warnings. +vcpkg manifest (`vcpkg.json`; versions from the default-registry baseline in `vcpkg-configuration.json`): `vulkan-headers`, `vulkan-memory-allocator`, `shaderc` (provides the `glslc` tool under `//tools/shaderc`), `catch2`, `stb`, `fastgltf`, `ktx`, `imgui[glfw-binding,vulkan-binding]`. The Vulkan **loader** and `glfw3` arrive transitively, so Vulkan + GLFW + the shader compiler all build from vcpkg — **no system Vulkan SDK / GLFW / glslang-tools**. System requirement is a C++23 toolchain + Ninja on macOS; **on Linux, add X11 dev packages and autotools** (`xorg-dev`, `libxinerama-dev`, `libxcursor-dev`, `libglu1-mesa-dev`, `autoconf`, `autoconf-archive`, `automake`, `libtool`) — glfw3's X11 backend pulls ports that vcpkg builds with autotools rather than CMake, and they fail to configure without them. A Vulkan ICD (MoltenVK on macOS) is needed only at *runtime* to render, not to build or run the headless tests. `fireengine` links Vulkan/GLFW directly; `cmake/fireengine_imgui.cmake` wraps vcpkg's ImGui archive without its transitive Vulkan/GLFW link interface to avoid duplicate static-library warnings. **Pinned headers must beat `/usr/local/include`, and `-isystem` cannot do it.** Clang searches `/usr/local/include` ahead of every `-isystem` path, which is where CMake puts an imported target's @@ -90,10 +90,17 @@ include site** with a narrow `#pragma GCC diagnostic ignored` and a reason (see **Upgrade the vcpkg baseline after each major item lands**, not mid-arc. The baseline in `vcpkg-configuration.json` pins every dependency version, so it only moves when someone moves it — -and a stale pin quietly drifts from the SDK on the machine (it had sat on a Feb 2026 commit carrying -`vulkan-headers 1.4.335.0` while the installed SDK reached 1.4.357). Bumping it is its own branch -with its own verification: full rebuild, `tests-full` on both platforms, and the render smoke, since -a loader/ICD change can alter device capabilities. +and a stale pin quietly drifts from the SDK on the machine (it had once sat on a Feb 2026 commit +carrying `vulkan-headers 1.4.335.0` while the installed SDK reached 1.4.357). Bumping it is its own +branch with its own verification: full rebuild, `tests-full` on both platforms, and the render smoke, +since a loader/ICD change can alter device capabilities. **Do it in the gap BETWEEN items, and +before a perf item rather than after one** — measurements taken across a toolchain move cannot +attribute a change to the work. + +Current pin: `ea1a7396` (Aug 2026) — `vulkan-headers`/`vulkan-loader` **1.4.357.0**, matching the +SDK installed here, which is what keeps the mixed-vulkan-hpp trap below out of reach; plus `glfw3 +3.5.1`, `glslang 16.4.0`, `spirv-tools 1.4.357.0`, `imgui 1.92.8#1`, `shaderc 2026.2`, `ktx 4.4.2`, +`fastgltf 0.9.0`, `catch2 3.15.3`, `vulkan-memory-allocator 3.4.0`. **"Full rebuild" there means `--clean-first`, and that is not pedantry.** vcpkg preserves each port's *upstream* file timestamps, so an upgraded header can land with an mtime OLDER than the object @@ -191,6 +198,16 @@ working tree into volumes (host artifacts untouched), defaults to `linux/amd64` (`DOCKER_PLATFORM=linux/arm64` is faster but off-platform). Run the relevant one before committing anything that could trip the stricter warnings / clang-tidy / format gate. +**The Linux image needs system packages the manifest cannot supply**, so a baseline bump can break +the build with no source change: some vcpkg ports build with `vcpkg_make` rather than CMake and +refuse to configure without autotools. `glfw3 3.5.1` pulls `pthread-stubs` on Linux for exactly this +reason, which is why `autoconf autoconf-archive automake libtool` sit in `tools/ci/Dockerfile` **and** +in both Linux jobs of `.github/workflows/ci.yml` — `autoconf-archive` is not preinstalled on +`ubuntu-latest` either. macOS is unaffected: glfw3 uses the Cocoa backend and never reaches that +dependency chain, which is exactly why a green macOS run does not clear a bump. When a port fails to +build after a bump, read the error before assuming a flake — vcpkg prints the missing programs and +the `apt install` line for them. + **GoldenHash is platform-specific — re-baseline BOTH on a solver change.** `Determinism.GoldenHash` (`tests/physics/test_physics_determinism.cpp`) compares the physics end-state hash (raw float bits) to a recorded golden. macOS/arm64 and Linux/x86_64 diverge by a few last-bit contact-solver ops, so each diff --git a/README.md b/README.md index 6bfe0245..42f55e01 100644 --- a/README.md +++ b/README.md @@ -403,7 +403,10 @@ suppresses the *recording*, not only the sampling, so every family must read `sk ## Dependencies -Managed via the vcpkg manifest (`vcpkg.json`): +Managed via the vcpkg manifest (`vcpkg.json`); every version comes from the baseline pinned in +`vcpkg-configuration.json`, currently `ea1a7396` (Aug 2026) — Vulkan headers + loader **1.4.357.0**, +`glfw3 3.5.1`, `glslang 16.4.0`, `spirv-tools 1.4.357.0`, `imgui 1.92.8`, `shaderc 2026.2`, +`ktx 4.4.2`, `fastgltf 0.9.0`, `catch2 3.15.3`, `vulkan-memory-allocator 3.4.0`: - `vulkan-headers` — Vulkan API headers (the Vulkan **loader** + `glfw3` arrive transitively, so both come from vcpkg — no system Vulkan SDK / GLFW needed to build) @@ -426,8 +429,17 @@ broke the vcpkg builds of gtest/glfw3/imgui and forced classic-mode global insta a vendored imgui backend; the Clang switch removed all of that. Also requires a C++23 toolchain, CMake, and Ninja. Building and the headless test suite need no -system Vulkan — the loader, headers, GLFW, and `glslc` all come from vcpkg. To actually *run* the -app you additionally need a Vulkan ICD at runtime: **MoltenVK** on macOS, a GPU driver on Linux. +system Vulkan — the loader, headers, GLFW, and `glslc` all come from vcpkg. On **Linux** add the X11 +development packages and autotools, which vcpkg needs to build GLFW's X11 dependency chain (some of +those ports use autotools rather than CMake and stop with a clear message if they are absent): + +```bash +sudo apt install xorg-dev libxinerama-dev libxcursor-dev libglu1-mesa-dev pkg-config \ + autoconf autoconf-archive automake libtool +``` + +macOS needs none of that — GLFW uses the Cocoa backend there. To actually *run* the app you +additionally need a Vulkan ICD at runtime: **MoltenVK** on macOS, a GPU driver on Linux. The GPU must expose **Vulkan 1.4** (the renderer uses core 1.4 push descriptors); a device below that is rejected at startup with the version named in the log. Instance layers and platform diff --git a/docs/onboarding.md b/docs/onboarding.md index 65e8ee93..d551bae3 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -1111,6 +1111,9 @@ the same change — most have a test or guard that will catch you, but not all. preserves the lower set when the higher sets are bound. Keep `Renderer::recordDrawBucket` and `recordTransmissionDrawBucket` in lockstep: reversing this order exposes a Vulkan Validation Layers 1.4.350 first-use push-state defect in an all-blend pass with no preceding depth-prepass push. + (That version is the SDK's, not the manifest's — the layer ships with the installed Vulkan SDK + while vcpkg pins only the headers and loader, so bumping the baseline neither retires this note nor + re-tests it.) - **Platform-conditional Vulkan capabilities are *queried*, never `#ifdef`'d** — and the decisions come from **one** pure planner (`render/device_plan.hpp`, unit-tested in `tests/render/test_device_plan.cpp`; `render/device.cpp` only enumerates and obeys). One binary diff --git a/tools/ci/Dockerfile b/tools/ci/Dockerfile index 539a0e29..9c7f9c20 100644 --- a/tools/ci/Dockerfile +++ b/tools/ci/Dockerfile @@ -25,6 +25,15 @@ RUN apt-get update \ libxinerama-dev \ libxcursor-dev \ libglu1-mesa-dev \ + # Autotools, for ports vcpkg builds with `vcpkg_make` rather than CMake. glfw3 3.5.1 pulls + # `pthread-stubs` on Linux, which is autotools-only and refuses to configure without these — + # `autoconf-archive` in particular is NOT preinstalled on ubuntu-latest either, so the hosted + # runner needs the same four. Not needed on macOS: glfw3 there uses the Cocoa backend and + # never reaches the X11 dependency chain. + autoconf \ + autoconf-archive \ + automake \ + libtool \ && wget -qO - https://apt.llvm.org/llvm-snapshot.gpg.key \ | gpg --dearmor -o /usr/share/keyrings/apt.llvm.org.gpg \ && echo "deb [signed-by=/usr/share/keyrings/apt.llvm.org.gpg] http://apt.llvm.org/noble/ llvm-toolchain-noble-22 main" \ diff --git a/vcpkg-configuration.json b/vcpkg-configuration.json index f8611d72..d37d8b45 100644 --- a/vcpkg-configuration.json +++ b/vcpkg-configuration.json @@ -1,7 +1,7 @@ { "default-registry": { "kind": "git", - "baseline": "8586ecbf125a36cb372920bc58ea7e23ad83776c", + "baseline": "ea1a7396b05637a53bf23c078647ecc0edee4b80", "repository": "https://github.com/microsoft/vcpkg" }, "registries": [