Fetching and Building External 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 [--debug]

The --debug option will build the external libraries in Debug mode, which may be useful when debugging and tracing calls into those libraries.

Updating External Library Versions

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.

VulkanSamples: a GitHub repository commit identifier found in the ExternalRevisions/VulkanSamples_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.

Adding the cereal Library to the MoltenVK Xcode Project

The MoltenVKXcode 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 MoltenVKXcode project as follows:

In the Project Navigator panel, select the MoltenVKXcode 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"

Adding the SPIRV-Cross Library to the ExternalDependencies Xcode Project

The ExternalDependenciesXcode 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 ExternalDependenciesXcode 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:

In the Choose options for adding these files dialog that opens, select the Create groups option, add the files to both the SPIRV-Cross-macOS and SPIRV-Cross-iOS targets, and click the Finish button.

Regression Testing Your Changes to SPIRV-Cross

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.xcodeprojXcode project, and running the ExternalDependenciesXcode 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:

Adding the SPIRV-Tools Library to the ExternalDependencies Xcode Project

The ExternalDependenciesXcode 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 ExternalDependenciesXcode project as follows:

In the Project Navigator panel, select the ExternalDependenciesXcode 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:

Repeat Step 1 for the SPIRV-Tools-iOS target within the ExternalDependenciesXcode 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 both the SPIRV-Tools-macOS and SPIRV-Tools-iOS targets, and click the Finish button.

Remove the Group named fuzz from under the Group named External/SPIRV-Tools/source.

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 and a MoltenVK build.

Adding the glslang Library to the ExternalDependencies Xcode Project

The ExternalDependenciesXcode 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 ExternalDependenciesXcode project as follows:

In the Project Navigator panel, select the ExternalDependenciesXcode 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"

Repeat Step 1 for the glslang-iOS target within the ExternalDependenciesXcode 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/glslangGroup 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 glslang-macOS and glslang-iOS targets, and click the Finish button.

In the Project Navigator panel, remove the references to the following files and folders: