#MoltenVK External Dependencies
Copyright (c) 2015-2022 The Brenwill Workshop Ltd.
MoltenVK uses technology from the following external open-source libraries:
These external open-source libraries are maintained in the External
directory. To retrieve and build these libraries from their sources, run the fetchDependencies
script in the main repository directory:
./fetchDependencies --all [--debug]
The --debug
option will build the external libraries in Debug mode, which may be useful when debugging and tracing calls into those libraries.
To maintain consistency between the libraries, MoltenVK retrieves specific versions of each external library. The version of each external library is determined as follows:
cereal: a GitHub repository commit identifier found in the ExternalRevisions/cereal_repo_revision
file.
Vulkan-Headers: a GitHub repository commit identifier found in the ExternalRevisions/Vulkan-Headers_repo_revision
file.
SPIRV-Cross: a GitHub repository commit identifier found in the ExternalRevisions/SPIRV-Cross_repo_revision
file.
glslang: a GitHub repository commit identifier found in the ExternalRevisions/glslang_repo_revision
file.
SPIRV-Tools: automatically retrieved by the glslang repository.
SPIRV-Headers: automatically retrieved by the glslang repository.
Vulkan-Tools: a GitHub repository commit identifier found in the ExternalRevisions/Vulkan-Tools_repo_revision
file.
You can update which versions of the cereal, Vulkan-Headers, SPIRV-Cross, glslang, Vulkan-Tools, or VulkanSamples libraries are retrieved by changing the value held in the corresponding *_repo_revision
file listed above.
The version of the SPIRV-Tools and SPIRV-Headers libraries is automatically determined by the version of the glslang library you have retrieved.
Once you have made changes to the *_repo_revision
files, you can retrieve the updated library versions by running the fetchDependencies
script, as described above, again.
Note: If, after updating to new versions 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 MoltenVK
Xcode project is already configured to use the cereal library. However, after updating the version of cereal, as described above, if you encounter any building errors, you may need to re-add the cereal library to the MoltenVK
Xcode project as follows:
In the Project Navigator panel, select the MoltenVK
Xcode project, then the MoltenVK
project 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/cereal/include"
The ExternalDependencies
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 building errors, you may need to re-add the SPIRV-Cross library to the ExternalDependencies
Xcode project as follows:
In the Project Navigator, remove all of the files under the Group named External/SPIRV-Cross
.
Drag the following files from the External/SPIRV-Cross
directory to the External/SPIRV-Cross
group in the Project Navigator panel:
spirv_cfg.cpp spirv_cfg.hpp spirv_common.hpp spirv_cross_containers.hpp spirv_cross_error_handling.hpp spirv_cross_parsed_ir.cpp spirv_cross_parsed_ir.hpp spirv_cross_util.hpp spirv_cross.cpp spirv_cross.hpp spirv_glsl.cpp spirv_glsl.hpp spirv_msl.cpp spirv_msl.hpp spirv_parser.cpp spirv_parser.hpp spirv_reflect.cpp spirv_reflect.hpp spirv.hpp
In the Choose options for adding these files dialog that opens, select the Create groups option, add the files to all of the SPIRV-Cross-macOS
, SPIRV-Cross-iOS
, and SPIRV-Cross-tvOS
targets, and click the Finish button.
The SPIRV-Cross library plays an important part in providing features for MoltenVK, and if you are developing features for MoltenVK, you may end up making changes to SPIRV-Cross.
If you make changes to the SPIRV-Cross
repository, you can build a new version of the libSPIRVCross.a
static library by opening the ExternalDependencies.xcodeproj
Xcode project, and running the ExternalDependencies Xcode scheme. You can then rebuild MoltenVK to include the new library.
While makng 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 ./build_glslang_spirv_tools.sh
Build SPIRV-Cross
:
make
Run the regression tests:
./test_shaders.sh
The ExternalDependencies
Xcode project is already configured to use the SPIRV-Tools library. However, after updating the version of glslang (which adds SPIRV-Tools), as described above, if you encounter any building errors, you may need to re-add the SPIRV-Tools library to the ExternalDependencies
Xcode project as follows:
In the Project Navigator panel, select the ExternalDependencies
Xcode project, then select the SPIRV-Tools-macOS
target, and open the Build Settings tab. Locate the build setting entry Header Search Paths (HEADER_SEARCH_PATHS
) and add the following paths:
$(inherited) "$(SRCROOT)/External/glslang/External/spirv-tools/" "$(SRCROOT)/External/glslang/External/spirv-tools/include" "$(SRCROOT)/External/glslang/External/spirv-tools/external/spirv-headers/include" "$(SRCROOT)/External/glslang/External/spirv-tools/build"
Repeat Step 1 for the SPIRV-Tools-iOS
target within the ExternalDependencies
Xcode project
In the Project Navigator, remove the Group named source
from under the Group named External/SPIRV-Tools
.
Drag the External/glslang/External/spirv-tools/source
file folder to the External/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 all of the SPIRV-Tools-macOS
, SPIRV-Tools-iOS
, and SPIRV-Tools-tvOS
targets, and click the Finish button.
Remove the following Groups from under the Group named External/SPIRV-Tools/source
:
fuzz
wasm
In the Scripts
folder, run ./packagePregenSpirvToolsHeaders
, which will fetch and build the full SPIRV-Tools
library and will update Templates/spirv-tools/build.zip
from the *.h
and *.inc
files in External/glslang/External/spirv-tools/build
. Test by running ./fetchDependencies --all
and a MoltenVK build.
The ExternalDependencies
Xcode project is already configured to use the glslang library. However, after updating the version of glslang, as described above, if you encounter any building errors, you may need to re-add the glslang library to the ExternalDependencies
Xcode project as follows:
In the Project Navigator panel, select the ExternalDependencies
Xcode project, then select the glslang-macOS
target, and open the Build Settings tab. Locate the build setting entry Header Search Paths (HEADER_SEARCH_PATHS
) and add the following paths:
$(inherited) "$(SRCROOT)/External/glslang" "$(SRCROOT)/External/glslang/build/include"
Repeat Step 1 for the glslang-iOS
target within the ExternalDependencies
Xcode project
In the Project Navigator, remove all Groups from under the Group named External/glslang
.
Drag the following folders from the External/glslang
file folder to the External/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 all of the glslang-macOS
, glslang-iOS
, and glslang-tvOS
targets, and click the Finish button.
In the Project Navigator panel, remove the references to the following files and folders:
External/glslang/glslang/MachineIndependant/glslang.y External/glslang/glslang/OSDependent/Windows External/glslang/glslang/OSDependent/Web External/glslang/glslang/HLSL