macOS: Install instructions should include need to add /usr/local/lib to the library search paths.

[billhollings]

On macOS, the Vulkan SDK installer deposits the Vulkan and MoltenVK dylib files in /usr/local/lib. In order to run Vulkan Samples, this path needs to be included in the library search paths vulkan_samples runs under. Without this, Volk fails to initialize.

macOS does not include /usr/local/lib in the library search paths by default. It can be included a couple of different ways, including either of the following:

• Include /usr/local/lib in the LD_RUNPATH_SEARCH_PATHS build setting when building vulkan_samples on macOS. Although I am not a cmake expert, I assume this could probably be done by updating the build config files.

• Invoke export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH prior to launching vulkan_samples from the command line. Since this can be done by the user, this might just need some documentation in either the Usage or Build/macOS sections of the Vulkan Samples documentation.

Also, on a related note, the Build/macOS instructions includes a requirement:

Vulkan SDK ./install_vulkan.py

I suggest this could probably be reworded to just _"Installed Vulkan SDK"_, and removing the reference to ./install_vulkan.py. These days, Vulkan Installer App takes care of installing the dylibs automatically for most Vulkan SDK installations, and the referenced Vulkan SDK Getting Started guide already covers the details of both the installer app and ./install_vulkan.py, if a user wants to install from the command line instead of using the installer app.

[jeroenbakker-atmind]

Not sure, but just adding it here as it isn't mentioned and perhaps this case should also be considered/included in the docs.

I use source ./setup-env.sh from the Vulkan SDK folder. This adds DYLD_LIBRARY_PATH=/Users/jeroen/VulkanSDK/1.3.275.0/macOS/lib to the environment variables.

[gpx1000]

That's the correct solution, it also would work to use iOS/setup-env.sh for the iOS libs.

[SRSaunders]

Agree with @jeroenbakker-atmind above. Futhermore, when using Xcode I find the following cmake snippet useful for setting things up properly. This of course assumes you have done source ./setup-env.sh prior to generation.

Note this approach avoids having to use the Global System Installation option of the SDK, which simplifies testing against multiple SDK versions without reinstallation.

Note: In spite of the comments above, DYLD_LIBRARY_PATH does not have to be explicitly defined if CMakeLists.txt sets link_libraries(${Vulkan_LIBRARY} ...) or target_link_libraries(<target_name> ${Vulkan_LIBRARY} ...). In that case the rpaths are explicitly defined and the library will be found automatically. It just so happens this project does not do this in CMakeLists.txt and thus the problem is evident.

IF (CMAKE_GENERATOR MATCHES "Xcode")
    # Suppress regeneration for Xcode since environment variables will be lost if not set in Xcode locations/custom paths
    set(CMAKE_SUPPRESS_REGENERATION ON)
    set(CMAKE_XCODE_GENERATE_SCHEME ON)

    # If the Vulkan loader's environment variables are defined, make them available within Xcode schemes
    IF (DEFINED ENV{DYLD_LIBRARY_PATH})
        set(CMAKE_XCODE_SCHEME_ENVIRONMENT "${CMAKE_XCODE_SCHEME_ENVIRONMENT};DYLD_LIBRARY_PATH=$ENV{DYLD_LIBRARY_PATH}")
    ENDIF()
    IF (DEFINED ENV{VK_ADD_LAYER_PATH})
        set(CMAKE_XCODE_SCHEME_ENVIRONMENT "${CMAKE_XCODE_SCHEME_ENVIRONMENT};VK_ADD_LAYER_PATH=$ENV{VK_ADD_LAYER_PATH}")
    ENDIF()
    IF (DEFINED ENV{VK_ICD_FILENAMES})
        set(CMAKE_XCODE_SCHEME_ENVIRONMENT "${CMAKE_XCODE_SCHEME_ENVIRONMENT};VK_ICD_FILENAMES=$ENV{VK_ICD_FILENAMES}")
    ENDIF()
    IF (DEFINED ENV{VK_DRIVER_FILES})
        set(CMAKE_XCODE_SCHEME_ENVIRONMENT "${CMAKE_XCODE_SCHEME_ENVIRONMENT};VK_DRIVER_FILES=$ENV{VK_DRIVER_FILES}")
    ENDIF()
ENDIF()

[jaidonlybbert]

I think we can close this, source ./setup-env.sh addressed in documentation additions in this PR #1177