Skip to content

Latest commit

 

History

History
263 lines (179 loc) · 10.9 KB

README.md

File metadata and controls

263 lines (179 loc) · 10.9 KB
Raw
MoltenVK

#MoltenVK External Dependencies

Copyright (c) 2015-2024 The Brenwill Workshop Ltd.

Table of Contents

Fetching and Building External Libraries

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.

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.

  • 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.

  • SPIRV-Cross: a GitHub repository commit identifier found in the ExternalRevisions/SPIRV-Cross_repo_revision file.

  • volk: a GitHub repository commit identifier found in the ExternalRevisions/Volk_repo_revision file.

  • Vulkan-Headers: a GitHub repository commit identifier found in the ExternalRevisions/Vulkan-Headers_repo_revision file.

  • Vulkan-Tools: a GitHub repository commit identifier found in the ExternalRevisions/Vulkan-Tools_repo_revision file.

You can update which versions of the external libraries are retrieved by changing the value held in the corresponding *_repo_revision file listed above.

The versions of the SPIRV-Tools and SPIRV-Headers libraries are 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.

Note: Vulkan-Tools and volk are not used by MoltenVK itself, but are used by the Cube demo app included in the MoltenVK repository.

Adding the cereal Library to the MoltenVK Xcode Project

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:

  1. 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"

Adding the glslang Library to the ExternalDependencies Xcode Project

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:

  1. 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"

  2. Repeat Step 1 for the glslang-iOS target within the ExternalDependencies Xcode project

  3. In the Project Navigator, remove all Groups from under the Group named External/glslang.

  4. Drag the following folders from the External/glslang file folder to the External/glslang Group in the Project Navigator panel:

     glslang
 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.

  5. 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

Adding the SPIRV-Tools Library to the ExternalDependencies Xcode Project

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:

  1. 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"

  2. Repeat Step 1 for the SPIRV-Tools-iOS target within the ExternalDependencies Xcode project

  3. In the Project Navigator, remove the Group named source from under the Group named External/SPIRV-Tools.

  4. 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.

  5. Remove the following Groups from under the Group named External/SPIRV-Tools/source:

    • fuzz
    • wasm

  6. 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.

Adding the SPIRV-Cross Library to the ExternalDependencies Xcode Project

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:

  1. In the Project Navigator, remove all of the files under the Group named External/SPIRV-Cross.

  2. 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.

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.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:

  1. 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

  2. Build SPIRV-Cross:

     make

  3. Run the regression tests:

     ./test_shaders.sh