macOS: Vulkan renderer cannot find MoltenVK in a flat .install layout (staged path != probed path)

[rebelancap]

Summary

prepare_macos_moltenvk.sh stages libMoltenVK.dylib into a Frameworks/ subdirectory, but SDL3_PinBundledMoltenVKLibrary never probes that location for a flat package root. Running .install/ directly — which BUILDING.md instructs — leaves SDL with no Vulkan library, so r_renderApi vulkan fails at window creation.

Environment

• macOS 27.0, Apple M4 Pro, Xcode 26.6
• openQ4 227ee810 (main), release build, platform_backend=sdl3
• MoltenVK v1.4.1 staged via tools/build/prepare_macos_moltenvk.sh

Reproduce

bash tools/build/meson_setup.sh install -C builddir --no-rebuild --skip-subprojects
bash tools/build/prepare_macos_moltenvk.sh --output-dir .install/Frameworks
cd .install && ./openQ4-client_arm64 +set r_renderApi vulkan

Result (from qconsole.log):

----- VK_InitRenderDevice -----
WARNING: Vulkan: window creation failed
FATAL: Vulkan renderer device initialization failed

Note the absence of any SDL3: bundled MoltenVK pinned at ... line — the hint was never set.

Cause

SDL3_PinBundledMoltenVKLibrary (src/sys/sdl3/sdl3_backend.cpp:5615) probes exactly two paths relative to the executable:

"/../Frameworks/libMoltenVK.dylib",   // .app bundle layout
"/libMoltenVK.dylib",                 // flat, next to the executable

In the flat .install/ root the executable is at .install/openQ4-client_arm64, so:

• candidate 1 resolves to <repo>/Frameworks/libMoltenVK.dylib — outside .install, where nothing was staged
• candidate 2 is .install/libMoltenVK.dylib — not where the script put it

Neither matches, no SDL_HINT_VULKAN_LIBRARY is set, and SDL_CreateWindow(SDL_WINDOW_VULKAN) fails. The staging script's default output directory and the backend's probe list simply do not agree for any non-.app layout.

Workaround

cp .install/Frameworks/libMoltenVK.dylib .install/libMoltenVK.dylib

Then the expected line appears and Vulkan initialises correctly:

SDL3: bundled MoltenVK pinned at .../.install/libMoltenVK.dylib
Vulkan: device 0 'Apple M4 Pro' (queue family 0)
Vulkan: portability subset active
Vulkan renderer initialized: Apple M4 Pro (Vulkan 1.3.334)

Suggested fix

Have prepare_macos_moltenvk.sh stage to a location the backend actually probes for the layout in use (or stage to both), and/or add <exeDir>/Frameworks/libMoltenVK.dylib to the probe list so the flat .install case is covered.

Related

The failure is much harder to diagnose than it should be, because the FatalError path taken on Vulkan init failure crashes before printing the reason — filed separately as #96.

Incidentally: the pinned MoltenVK digest is confirmed good

prepare_macos_moltenvk.sh notes that MOLTENVK_TAR_SHA256 was taken from the GitHub API and "has NOT been confirmed by hashing a local download (this project has no macOS host)". It downloaded and verified cleanly here on real hardware:

moltenvk_provenance: version=v1.4.1
tar_sha256=5ea0c259df7ded9a275444820f09cced54d6e5a7c7a31d262de62a5cdb7e15cf
dylib_sha256=542cf7a91ed2c677ccbd2988e496d853f3f1b7d1f3ffce584066414cde801a0a
archs="arm64 x86_64" minos=11.0,11.0 signature=valid