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).