#MoltenVK External Dependencies
Copyright (c) 2014-2018 The Brenwill Workshop Ltd.
This document is written in Markdown format. For best results, use a Markdown reader.
MoltenVK uses technology from the following external open-source libraries:
These external open-source libraries are maintained in the External directory. To retrieve these libraries from their sources, run the fetchDependencies script in that directory:
cd External ./fetchDependencies [-sdk]
The -sdk option tells the script that MoltenVK is being installed as part of the LunarG Vulkan SDK, and that MoltenVK can find some of the required libraries already loaded in the SDK, instead of retrieving them from their repositories again. If you are using MoltenVK outside of the LunarG Vulkan SDK, do not use the -sdk option, so that all of the required external libraries will be retrieved.
To maintain consistency between the libraries, MoltenVK retrieves specific versions of each external library. The version of each external library is determined as follows:
SPIRV-Cross: a GitHub repository commit identifier found in the External/SPIRV-Cross_repo_revision file.
VulkanSamples: a GitHub repository commit identifier found in the External/VulkanSamples_repo_revision file.
Vulkan-LoaderAndValidationLayers: a GitHub repository commit identifier found in the External/Vulkan-LoaderAndValidationLayers_repo_revision file.
glslang: a GitHub repository commit identifier found in the retrieved Vulkan-LoaderAndValidationLayers repository.
SPIRV-Tools: automatically retrieved by the glslang repository.
SPIRV-Headers: automatically retrieved by the glslang repository.
You can update which version of the SPIRV-Cross, VulkanSamples, and Vulkan-LoaderAndValidationLayers libraries are retrieved, by changing the value held in the corresponding *_repo_revision file listed above.
The version of the glslang, SPIRV-Tools, and SPIRV-Headers libraries is automatically determined by the version of the Vulkan-LoaderAndValidationLayers library you have retrieved.
Once you have made changes, you can retrieve the updated library versions by running the fetchDependencies script again.
Note: If, after updating to new verions of the external libraries, you encounter build errors when building MoltenVK, review the instructions in the sections below to ensure all necessary external library files are included in the MoltenVK builds.
The MoltenVKShaderConverter Xcode project is already configured to use the SPIRV-Cross library. However, after updating the version of SPIRV-Cross, as described above, if you encounter any linking errors, may need to re-add the SPIRV-Cross library to the MoltenVKShaderConverter Xcode project as follows:
In the Project Navigator, remove all of the files under the Group named MoltenVKSPIRVToMSLConverter/SPIRV-Cross.
Add the following files from the SPIRV-Cross file folder to the SPIRV-Cross group in the Project Navigator panel:
spirv_cfg.cpp spirv_cfg.hpp spirv_common.hpp spirv_cross.cpp spirv_cross.hpp spirv_glsl.cpp spirv_glsl.hpp spirv_msl.cpp spirv_msl.hpp
In the Choose options for adding these files dialog that opens, select the Create groups option, add the files to both the MoltenVKSPIRVToMSLConverter-iOS and MoltenVKSPIRVToMSLConverter-macOS targets, and click the Finish button.
(Optional) To simplify the paths used within Xcode to reference the added files, perform the following steps:
MoltenVKShaderConverter.xcodeproj file and select Show Package Contents.project.pbxproj file in a text editor.path-to-SPIRV-Cross-repo-folder from the paths to the files added above.If you make changes to the SPIRV-Cross repository, you can regression test your changes using the following steps:
Load and build the versions of SPRIV-Tools and glslang that are used by the SPIRV-Cross tests:
cd External/SPIRV-Cross ./checkout_glslang_spirv_tools.sh
Run the regression tests:
./test_shaders.sh
If your changes result in different expected output for a reference shader, and the new results are correct, you can update the reference shader for a particular regression test by deleting that reference shader, in either External/SPIRV-Cross/reference/shaders-msl or External/SPIRV-Cross/reference/opt/shaders-msl, and running the test again. The test will replace the deleted reference shader.
The MoltenVKShaderConverter Xcode project is already configured to use the SPIRV-Tools library. However, after updating the version of SPIRV-Tools, as described above, if you encounter any linking errors, may need to re-add the SPIRV-Tools library to the MoltenVKShaderConverter Xcode project as follows:
In the Project Navigator, remove the Group named source from under the Group named MoltenVKSPIRVToMSLConverter/SPIRV-Tools.
Drag the SPIRV-Tools/source file folder to the SPIRV-Tools group in the Project Navigator panel. In the Choose options for adding these files dialog that opens, select the Create groups option, add the files to both the MoltenVKSPIRVToMSLConverter-iOS and MoltenVKSPIRVToMSLConverter-macOS targets, and click the Finish button.
In the Project Navigator panel, select your application's target, and open the Build Settings tab. Locate the build setting entry Header Search Paths (HEADER_SEARCH_PATHS) and add the following paths:
"$(SRCROOT)/../External/glslang/External/spirv-tools/include" "$(SRCROOT)/../External/glslang/External/spirv-tools/source" "$(SRCROOT)/../External/glslang/External/spirv-tools/external/spirv-headers/include" "$(SRCROOT)/../External/glslang/build/External/spirv-tools"
(Optional) To simplify the paths used within Xcode to reference the added files, perform the following steps:
MoltenVKShaderConverter.xcodeproj file and select Show Package Contents.project.pbxproj file in a text editor.path-to-SPIRV-Tools-repo-folder from the paths to the source directory added above.The MoltenVKShaderConverter Xcode project is already configured to use the glslang library. However, after updating the version of glslang, as described above, if you encounter any linking errors, may need to re-add the glslang library to the MoltenVKShaderConverter Xcode project as follows:
In the Project Navigator, remove all Groups from under the Group named MoltenVKGLSLToSPIRVConverter/glslang.
Add the following folders from the glslang file folder to the glslang Group in the Project Navigator panel:
glslang OGLCompilersDLL SPIRV
In the Choose options for adding these files dialog that opens, select the Create groups option, add the files to both the MoltenVKGLSLToSPIRVConverter-iOS and MoltenVKGLSLToSPIRVConverter-macOS targets, and click the Finish button.
In the Project Navigator panel, remove the references to the following files and folders:
glslang/glslang/MachineIndependant/glslang.y glslang/glslang/OSDependent/Windows
(Optional) To simplify the paths used within Xcode to reference the added files, perform the following steps:
MoltenVKShaderConverter.xcodeproj file and select Show Package Contents.project.pbxproj file in a text editor.path-to-glslang-repo-folder from the paths to the glslang, OGLCompilersDLL, and SPIRV directories added above.