MacOS Missing Vulkan Library Fix

[tomadamatkinson]

Description

On newer MacOS versions the VulkanHPP loader can no longer find Vulkan due to this issue KhronosGroup/Vulkan-Hpp#1975

This PR is a temporary patch until this is officially fixed in VulkanHPP. This PR proposes adjusting the RPATH of Vulkan Samples on MacOS if vulkan is found in /usr/local/lib

I have set this to Urgent as without this fix every sample will load with the following logs as VulkanSample will always use the VulkanHPP DynamicLoader

[info] Logger initialized
[info] Initializing Vulkan sample
[error] Error Message: Failed to load vulkan library!
[error] Failed when running application AFBC

General Checklist:

Please ensure the following points are checked:

• My code follows the coding style
• I have reviewed file licenses
• I have commented any added functions (in line with Doxygen)
• I have commented any code that could be hard to understand
• My changes do not add any new compiler warnings
• My changes do not add any new validation layer errors or warnings
• I have used existing framework/helper functions where possible
• My changes do not add any regressions
• I have tested every sample to ensure everything runs correctly
• This PR describes the scope and expected impact of the changes I am making

Note: The Samples CI runs a number of checks including:

• I have updated the header Copyright to reflect the current year (CI build will fail if Copyright is out of date)
• My changes build on Windows, Linux, macOS and Android. Otherwise I have documented any exceptions

If this PR contains framework changes:

• I did a full batch run using the batch command line argument to make sure all samples still work properly

Sample Checklist

If your PR contains a new or modified sample, these further checks must be carried out in addition to the General Checklist:

• I have tested the sample on at least one compliant Vulkan implementation
• If the sample is vendor-specific, I have tagged it appropriately
• I have stated on what implementation the sample has been tested so that others can test on different implementations and platforms
• Any dependent assets have been merged and published in downstream modules
• For new samples, I have added a paragraph with a summary to the appropriate chapter in the readme of the folder that the sample belongs to e.g. api samples readme
• For new samples, I have added a tutorial README.md file to guide users through what they need to know to implement code using this feature. For example, see conditional_rendering
• For new samples, I have added a link to the Antora navigation so that the sample will be listed at the Vulkan documentation site

[tomadamatkinson]

Hey @SRSaunders, Ive just seen your recent MacOS changes. I was seeing this issue prior to your changes and after your changes. Can you let me know your thoughts on this PR?

For a bit more context this is what my CMake logs say for my Vulkan installation

-- Vulkan library: /usr/local/lib/libvulkan.dylib
-- Vulkan headers: /Library/Frameworks/GStreamer.framework/Headers

Its possible on your system that you have Vulkan somewhere else?

[tomadamatkinson]

From PR #1177

Adds CMake config support for macOS builds using Xcode. This change ensures the correct Vulkan SDK environment variables are copied into Xcode's scheme and used when running or debugging from within Xcode. Previously this was a very manual and error-prone step. Without adding these env variables, the Vulkan libraries will not be found at runtime.

This is likely the same issue I was running into. However, as I do not use xcode on MacOS this fix didn't work for me (but likely does for others). Changing the RPATH through CMake worked for my case which is running Vulkan Samples from the command line or through vscode's debugger.

[SRSaunders]

Its possible on your system that you have Vulkan somewhere else?

I have installed the Vulkan SDK at the default location (i.e. <your_home_dir>/VulkanSDK/1.3.296.0). Using the instructions below you can install either with or without the System Global Installation option - it should not matter:

https://github.com/KhronosGroup/Vulkan-Samples/blob/main/docs/build.adoc#macos

Note that I have updated the instructions to recommend that you always source /PATH/TO/VULKAN/SDK/setup-env.sh prior to running cmake or running the examples. This will ensure the Vulkan environment variables are set in the shell prior to cmake configuring for Xcode or simply building/running from the command line. I figured this was the simplest and most consistent way to handle it for both command line and Xcode builds. It's also a supported mechanism from the SDK's perspective, and familiar to macOS Vulkan developers.

Note that I typically do not use the System Global Installation option since I often have multiple SDK versions installed at the same time for testing purposes. The above approach of sourcing setup-env.sh for the SDK version I want ensures that is the one picked up when testing. It also works when building for iOS vs. macOS (using <sdk_version>/iOS/setup-env.sh).

A small detail, but if you are building/running for macOS exclusively from the command line, you technically don't have to set the variables prior to the cmake config/build steps - the project carries its own version of Vulkan headers that are used during build. The cmake log will show vulkan not found, but will continue anyways (in fact this is exactly what happens during the github CI process). In this case you only need the environment variables for running the samples.

[SRSaunders]

Can you let me know your thoughts on this PR?

My main concern about your PR is that it sets the RPATH to a fixed Global Installation location (/usr/local/lib). This would remove the flexibility to set the Vulkan location to an SDK location of the user's choice, or in my case, to easily switch between SDK versions. If adopted, one could still work around this restriction by selectively uninstalling/reinstalling using the System Global Installation option of the Vulkan MaintenanceTool. However, this would have to be documented in the installation instructions, and would make System Global Installation mandatory. I am wondering whether the current documented approach using setup-env.sh is possibly simpler and more flexible.

Another side benefit of my recent PR is an undocumented feature: to allow running against local dev builds of MoltenVK. You can export VULKAN_SDK=/Users/<username>/MoltenVK/Package/Release/MoltenVK and set the cmake build option -DUSE_MoltenVK=ON to build against MoltenVK directly. Not needed to run within Xcode, but to run from the command line you will also need to export DYLD_LIBRARY_PATH=$VULKAN_SDK/lib:${DYLD_LIBRARY_PATH:-}. This is a bit of a developer detail only, but useful for people who work on both projects, and want to test the samples against newer MoltenVK features prior to SDK releases. You can look inside global_options.cmake to see how this works.

[SaschaWillems]

Removed myself as a reviewer. I have no Mac hardware to test this on.

[asuessenbach]

Same as Sascha: I have no Mac to test this on.

[jaidonlybbert]

As someone new to Vulkan on Mac, it did take some head scratching to figure out that source /PATH/TO/VULKAN/SDK/setup-env.sh was necessary, but it IS in the Vulkan/MoltenVK docs, and I think adding the instructions to the docs in this project is a fine fix

[jeroenbakker-atmind]

I added me as a reviewer. When running in batch mode there were some samples failing and some not. Could be related to HPP. I will list the samples that are failing to start so we can check what we need to do.

Normally I run using source setup-env.sh as mentioned above. We could clarify in the docs as there have been multiple issues around this. The cause is related to how MoltenVK is used and installed.

[SRSaunders]

Normally I run using source setup-env.sh as mentioned above. We could clarify in the docs as there have been multiple issues around this.

The docs were updated in merged PR #1177 to indicate the user should run source setup-env.sh. Hopefully this helps.

When running in batch mode there were some samples failing and some not. Could be related to HPP. I will list the samples that are failing to start so we can check what we need to do.

I have tried to fix a few of these in previous PRs. If there are any batch mode failures remaining on macOS, please let me know. There are a few that fail on iOS / iOS Sim (e.g. oit* samples) but those should be fixed in pending PR #1173.

[jaidonlybbert]

The samples in the performance and api categories worked fine in batch mode on my M3 Max. At least they seemed to... I didn't save the logs. the ray tracing extension isn't supported by MoltenVK so I would expect those to fail

[tomadamatkinson]

Just had chance to read through this. Happy with @SRSaunders documentation change. Sourcing setup-env.h works. It also looks like there is has been a change in VulkanHPP to search for Vulkan in different folders. In the next few version bumps of the Vulkan Headers this should be fixed without the need to source the env script