Skip to content

Conversation

@derek-gerstmann
Copy link
Contributor

Also, add HL_VK_LOADER_LIB env var to override search paths.
Add docs for HL_VK_LOADER_LIB env var.

This PR makes it easier to locate the Vulkan loader library when running inside an emulated environment, or in a sandbox, or to test a developmental version of the Vulkan loader lib.

    Also, add HL_VK_LOADER_LIB env var to override search paths.
    Add docs for HL_VK_LOADER_LIB env var.
Copy link
Member

@alexreinking alexreinking left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a couple library-ordering nits

@derek-gerstmann
Copy link
Contributor Author

Thanks! Yes, I agree ... I'll change the ordering for dynamic linking to match the docs for the Vulkan Application Interface:
https://vulkan.lunarg.com/doc/sdk/1.4.321.1/windows/LoaderApplicationInterface.html

Windows:

  • vulkan-1.dll (first choice)

Linux:

  • libvulkan.so.1 (first choice)

OSX:

  • libvulkan.1.dylib (first choice)
Windows Dynamic Library Usage
On Windows, the loader library encodes the ABI version in its name such that multiple ABI incompatible versions of the loader can peacefully coexist on a given system. The Vulkan loader library file name is vulkan-<ABI version>.dll. For example, for Vulkan version 1.X on Windows the library filename is vulkan-1.dll. This library file can typically be found in the windows\system32 directory (on 64-bit Windows installs, the 32-bit version of the loader with the same name can be found in the windows\sysWOW64 directory).

Linux Dynamic Library Usage
For Linux, shared libraries are versioned based on a suffix. Thus, the ABI number is not encoded in the base of the library filename as on Windows.

On Linux, applications that have a hard dependency on Vulkan should request linking to the unversioned name libvulkan.so in their build system. For example by importing the CMake target Vulkan::Vulkan or by using the output of pkg-config --cflags --libs vulkan as compiler flags. As usual for Linux libraries, the compiler and linker will resolve this to a dependency on the correct versioned SONAME, currently libvulkan.so.1. Linux applications that load Vulkan-Loader dynamically at runtime do not benefit from this mechanism, and should instead make sure to pass the versioned name such as libvulkan.so.1 to dlopen(), to ensure that they load a compatible version.

MacOs Dynamic Library Usage
MacOs linking is similar to Linux, with the exception being that the standard dynamic library is named libvulkan.dylib and the ABI versioned library is currently named libvulkan.1.dylib.

@alexreinking alexreinking self-requested a review December 8, 2025 23:26
@derek-gerstmann derek-gerstmann merged commit 573a271 into main Dec 10, 2025
15 of 19 checks passed
@alexreinking alexreinking deleted the dg/hl_vk_loader branch December 11, 2025 16:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants