Vault/build_deps_headers_vs_runtime.md

Compile-Time Headers vs. Runtime Libraries

What we did

• Hit two build failures in a row while compiling llama.cpp with Vulkan support: first missing vulkan-headers, then missing spirv-headers — despite the Vulkan driver (vulkan-radeon) and loader (vulkan-icd-loader) already being installed and working fine (games, desktop compositor, etc.).
• Installed the missing header packages and the build proceeded cleanly.

Key distinction / Mental model

Two separate concerns get bundled under "I have Vulkan installed," but they're not the same thing:

• Runtime pieces (vulkan-icd-loader, vulkan-radeon) let an already-compiled program talk to the GPU right now.
• Build-time pieces (vulkan-headers, spirv-headers) are plain-text .h files with function/type declarations that the compiler needs to translate new source code calling those functions into machine code.

A working driver does not imply the headers are present, and vice versa — different packages, different points in the software lifecycle. This generalizes beyond Vulkan: any "-dev" / "-headers" package split (common across Linux libraries) follows the same pattern.

Commands / syntax

Command	What it does
pacman -Q <pkg>	Check if a package is installed (fails loudly if not — good for audits)
pacman -Ql <pkg>	List files a package provides, to see whether it's headers, a library, or both
sudo pacman -S vulkan-headers spirv-headers	Install Vulkan build-time dependencies on Arch

When to use this

When a build fails with "could not find X headers" or "unknown type/function" errors for a library you're sure is "installed" — check whether you have the runtime package, the headers package, or both.

Index line

build_deps_headers_vs_runtime.md — Compile-time headers vs. runtime libraries: why a working driver doesn't mean a package's headers are installed too (Vulkan/SPIRV example).