VSG + static Vulkan or MoltenVK

[nolankramer]

This is a bit of a complex subject, and the title implies that we may be discussing two separate issues depending on how people think they should be solved - but they aren't entirely mutually exclusive of each-other.

The first, and likely overarching subject - is static linkage of Vulkan itself. The reasons a user may want to do this vary and could be vast, but from self-contained libraries, executables, or modified Vulkan build are all on the table.

From my (paltry) knowledge of Vulkan and graphics programming - it's not uncommon practice to have a large function pointer resolution step before calling any Vulkan/graphics API. For example, with vkCreateInstance, one might do this:

    PFN_vkGetInstanceProcAddr fpGetInstanceProcAddr = vkGetInstanceProcAddr;
    PFN_vkCreateInstance m_fpCreateInstance = (PFN_vkCreateInstance)fpGetInstanceProcAddr(VK_NULL_HANDLE, "vkCreateInstance");
    
    ... do stuff ...
    m_fpCreateInstance(...); // call this instead of vkCreateInstance!

Which allows intermediary libraries to inject custom versions of these functions, to provide... well whatever they provide. I'm really not an expert here, I just know it's common practice. Perhaps someone here knows more about why it's done. I think it's something to do pluggable symbol resolution to enable other implementations of vkCreateInstance to be used based on drivers.

I do know however, that it does allow resolving the required function pointers to symbols that can be defined wherever the user needs them to be defined (for example, statically built-in to a library, or provided by another library).

---

Now I also brought up MoltenVK - because it's required to do something as above to use a statically linked MoltenVK. This is because if the user is statically linking in MoltenVK, they need to swap out the call to vkCreateInstance to the MoltenVK version. Again - only if statically linking. From what I can tell, this is the best way to avoid going through the Vulkan Loader which will just dynamically link to the system MoltenVK.

This becomes especially important if the user wants to use a more recent version of MoltenVK that isn't shipped on macOS by default (Apple usually lags behind here by quite a bit - my system ships with a MoltenVK that supports up to version 1.2.269 of Vulkan, but more recent MoltenVK from source or release already supports up to 1.4).

... let me know if I'm making any sense here, anyone with more knowledge on these issues please feel free to chime in and call me out on my ramblings.

While statically linking in a custom Vulkan is likely an edge case that might be rarely used in-practice, I think discussing static linkage caveats like this might be good to have anyway. Might help someone in the future.

[AnyOldName3]

Vulkan implementations are typically specific to the graphics hardware, so if it were hypothetically to statically link with it on one machine, you'd end up with an application that wouldn't work on a different machine with the same operating system but a different GPU. The point of APIs like Vulkan or OpenGL before it is that you don't need to have a hardware-specific interface to the hardware, and instead have something that you know will be present at runtime that will handle the hardware-specific parts for you. You can only achieve that with a dynamic/shared library which is loaded and linked at runtime.

MoltenVK is an odd duck here as it's not hardware-specific, and really is just another library. It translates Vulkan calls to Metal calls which also aren't hardware-specific and get handled by the Metal runtime provided by MacOS that handles the hardware-specific parts. In principle, this means that you can statically link with MoltenVK. However, this can still have some downsides as you can't use layers like the validation layers and API dump layer if there's no way for their functions to be used at runtime. If you've already got an app that works perfectly, that might not be a problem, but until you're certain of that, you can more-or-less get the best of both worlds by providing MoltenVK as a .so/.dylib so it's still left until runtime, but doesn't need to be the old version the OS provides.

[AnyOldName3]

It looks like they changed the terminology a little from OpenGL as an OpenGL loader used to be a separate library you could optionally link to automatically set up extension function pointers for you, whereas in Vulkan, it's the thing that loads the core functions, so some of what I said earlier will be a little off.

Vulkan::Vulkan is a CMake target, but CMake targets aren't necessarily static libraries. E.g. interface libraries can be used to just set some compiler flags and include directories without affecting the linker at all. In this specific case, it sets up the include paths so the Vulkan headers are visible and makes the application link with either an import library that causes the application to load the real dynamic/shared library for Vulkan provided by driver at runtime (if your Vulkan SDK is set up that way) or (if you've got an old version of the Vulkan SDK before they removed this option) a static library that has code to find known Vulkan drivers that might be present at runtime and extract function pointers from them. That then makes the basic Vulkan 1.0 functions available, but doesn't load anything from extensions or later Vulkan versions.

If you want to use newer Vulkan functions, you can either get function pointers by calling vkGetInstanceProcAddr manually (which is what the VSG does), or you can use a library that sets up the function pointers for you like Volk.

Whichever you choose to do, you still can't link with Vulkan itself until runtime - it's only code that finds the real Vulkan implementation that you'd be linking.

[nolankramer]

or (if you've got an old version of the Vulkan SDK before they removed this option) a static library that has code to find known Vulkan drivers that might be present at runtime and extract function pointers from them

Ah I didn't know this piece of legacy behavior. That's cool.

and makes the application link with either an import library that causes the application to load the real dynamic/shared library for Vulkan provided by driver at runtime

This is the key piece - it's a PUBLIC cmake dependency. It causes users of VSG to include the SDK headers on their system. BUT more importantly, it also puts an import entry in the binary the user is building. This causes their binary to link to whatever vulkan loader the system decides to link them to (of course dependent on dynamic load order which is system-defined). Users can easily ship their vulkan loader of choice with their library/executable if they desire. Which is neat.

But, correct me if my understanding here is wrong:

1. vsg has target_link_library(... PUBLIC Vulkan::Vulkan), which tells CMake that vsg depends on Vulkan::Vulkan
2. User adds target_link_library( ... vsg) to their build config
3. CMake takes care of setting up header inclusion and adding import entry to resulting binary (assuming user is building a binary, and not a static archive or object code)
4. At runtime, dynamic linker links their binary to the loader
5. Loader dynamically links to the right vulkan driver for the system, and boom, vulkan is ready to go

---

Under this framework of understanding (if it's correct) - couldn't step (1.) be potentially modified to link to a static vulkan loader? Essentially allowing the user to ship their application without needing to worry about if a vulkan loader is present on the systems they ship to. Idk if that's an issue anyone would need to worry about. And I guess this would be basically reverting to the legacy linking behavior?

[AnyOldName3]

If you have a Vulkan SDK with a static loader (which historically was a rarely-used option, and now it's removed), then CMake's modules/FindVulkan.cmake could find it and make it the thing that Vulkan::Vulkan referred to. Vulkan::Vulkan refers to the import library for the dynamic loader on your machine because that's what's provided by the Vulkan SDK on your machine.

The VSG has to publicly link with Vulkan::Vulkan as otherwise, if the VSG itself is a static library, the import entry for the Vulkan loader is forgotten.

It's safe to just have an import entry for the dynamic Vulkan loader as it is mandatory that Vulkan implementations provide a dynamic Vulkan loader. On most platforms, it's provided by the graphics driver, but on Android, it's provided by the OS. If you don't have a dynamic Vulkan loader at runtime, it's because you're running on a machine that doesn't have Vulkan, so your application wouldn't work even if you provided your own loader.

Kronos dropped support for statically linking the loader because it was unreliable. For example, if a new graphics vendor appeared, or one of the existing ones changed its name (e.g. Nvidia becoming HuangCorp or AMD becoming Lisa Ltd.) and changed the filenames for their driver to match, the static loader wouldn't know about the new filenames, so wouldn't be able to load the driver anymore.

Now support has been dropped, there's no way to statically link because there's no static library to statically link to anymore.

[nolankramer]

This makes sense.

I guess MoltenVK is a sort of special exception like you said - since it just translates metal calls, and really sort of replaces the loader?

I found that I actually wanted to statically link in MoltenVK to ensure that a library shipped with a more recent Vulkan compatibility level, without needing to ship libMoltenVK.dylib with the library. But I wonder if there's a better way. I could do a similar thing VSG does with Vulkan::Vulkan, and add a PUBLIC dependency on MoltenVK somehow. Or would it even make sense to add something to FindVulkan.cmake in VSG to do that for users?

[AnyOldName3]

CMake's modules/FindVulkan.cmake already looks for MoltenVK if you're on MacOS, and that's what Vulkan::Vulkan refers to. If the first copy of MoltenVK in the CMake search path is a static library, that's what it'll find.

[michaelaeriksen]

Not really sure what the issue is here, but on my Mac I just did

brew install vulkan-tools

and everything builds and works fine for me

[nolankramer]

Just having a friendly discussion about static linkage w/Vulkan and MoltenVK! :)