moltenvk/Docs/ThirdPartyConfig.md

Copyright (c) 2014-2017 The Brenwill Workshop Ltd.

This document is written in Markdown format. For best results, use a Markdown reader.

Table of Contents

• Vulkan-Hpp

  • Using the Vulkan-Hpp Spec Repository with MoltenVK
  • Updating the Vulkan-Hpp library version

• Vulkan-LoaderAndValidationLayers

  • Using the Vulkan-LoaderAndValidationLayers Repository with MoltenVK
  • Updating the Vulkan-LoaderAndValidationLayers library version

• SPIRV-Cross

  • Using the SPIRV-Cross library with MoltenVKShaderConverter
  • Updating the SPIRV-Cross library version
  • Adding the SPIRV-Cross library to a new Xcode project

• SPIRV-Tools

  • Using the SPIRV-Tools library with MoltenVKShaderConverter
  • Updating the SPIRV-Tools library version
  • Adding the SPIRV-Tools library to a new Xcode project

• glslang

  • Using the glslang library with MoltenVKShaderConverter
  • Updating the glslang library version
  • Adding the glslang library to a new Xcode project

Using the Vulkan-Hpp Spec Repository with MoltenVK

MoltenVK uses the official Khronos Vulkan specification repository to provide the standard Vulkan API header files and Vulkan Specification documentation.

To add the Khronos Vulkan specification repository to MoltenVK, open a Terminal session and perform the following command-line steps:

1. Ensure you have python3 and asciidoctor installed:

    brew install python3
    sudo gem install asciidoctor
   

2. If you used the --recursive option when cloning the MoltenVK repository, you should already have the Vulkan-Hpp submodule, and you can skip to Step 3 below. If you did not use the --recursive option when cloning the MoltenVK repository, retrieve the Vulkan-Hpp submodule into the External directory as follows, from within the MoltenVK repository directory:

    git submodule update --init --recursive External/Vulkan-Hpp
   

3. In the Externals folder within the MoltenVK repository, build the spec and header files as follows from the main directory of this MoltenVK repository:

    cd External
    ./makeVulkanSpec
   

Updating the Vulkan-Hpp library version

If you are developing enhancements to MoltenVK, you can update the version of Vulkan-Hpp used by MoltenVK to the latest version available by re-cloning and re-building the Vulkan-Hpp submodule using the getLatestVulkanSpec script:

cd External
./getLatestVulkanSpec

The updated version will then be "locked in" the next time the MoltenVK repository is committed to git.

Using the Vulkan-LoaderAndValidationLayers Spec Repository with MoltenVK

MoltenVK uses the Khronos Vulkan Loader and Validation Layers repository to allow MoltenVK to act as an Installable Client Driver to support the Vulkan Loader API.

If you used the --recursive option when cloning the MoltenVK repository, you should already have the Vulkan-LoaderAndValidationLayers submodule. If you did not use the --recursive option when cloning the MoltenVK repository, retrieve the Vulkan-LoaderAndValidationLayers submodule into the External directory as follows, from within the MoltenVK repository directory:

git submodule update --init External/Vulkan-LoaderAndValidationLayers

Updating the Vulkan-LoaderAndValidationLayers library version

If you are developing enhancements to MoltenVK, you can update the version of Vulkan-LoaderAndValidationLayers used by MoltenVK to the latest version available by re-cloning and re-building the Vulkan-LoaderAndValidationLayers submodule using the getLatestVulkanLVL script:

cd External
./getLatestVulkanLVL

The updated version will then be "locked in" the next time the MoltenVK repository is committed to git.

Using the SPIRV-Cross library with MoltenVKShaderConverter

MoltenVKShaderConverter uses SPIRV-Cross to convert SPIR-V code to Metal Shading Language (MSL) source code.

If you used the --recursive option when cloning the MoltenVK repository, you should already have the SPIRV-Cross submodule. If you did not use the --recursive option when cloning the MoltenVK repository, retrieve the SPIRV-Cross submodule into the External directory as follows, from within the MoltenVK repository directory:

git submodule update --init External/SPIRV-Cross

Updating the SPIRV-Cross library version

If you are developing enhancements to MoltenVKShaderConverter, you can update the version of SPIRV-Cross used by MoltenVKShaderConverter to the latest version available by re-cloning and re-building the SPIRV-Cross submodule using the getLatestSPIRVCross script:

cd External
./getLatestSPIRVCross

The updated version will then be "locked in" the next time the MoltenVK repository is committed to git.

Note: If after updating to a new verions of SPIRV-Cross, you encounter build errors when building MoltenVKShaderConverter, review the instructions below to ensure all necessary SPIRV-Cross files are included in the MoltenVKShaderConverter builds.

Note: As new features are added to MoltenVK, many are powered by the ability to convert sophisticated SPIRV code into MSL code. Sometimes new MoltenVK features and capabilities are provided solely via new SPIRV-Cross features. If you are developing enhancements for MoltenVKShaderConverter, be sure to update the SPIRV-Cross submodule often.

Regression Testing Your Changes to SPIRV-Cross

If you make changes to the SPIRV-Cross submodule, you can regression test your changes by building the spirv-cross executable and running the test_shaders.py regression test script, using the following steps:

1. If you did not run the External/makeAll script, build the SPIRV-Tools and glslangValidatortools (you should only need to do this once):

    cd External
    ./makeSPIRVTools
    ./makeglslang
   

2. Set your PATH environment variable so that the spirv-cross tool can find the glslangValidator and SPIRV-Tools tools:

    export PATH=$PATH:"../glslang/build/StandAlone:../SPIRV-Tools/build/tools"
   

3. Build the spirv-cross executable:

    cd External/SPIRV-Cross
    make
   

4. Run the regression tests:

    ./test_shaders.sh
   

5. If your changes result in different expected output for a reference shader, you can update the reference shader for a particular regression test:

   1. Termporarily rename the existing reference shader file in External/SPIRV-Cross/reference/shaders-msl.
   2. Run the regression tests. A new reference shader will be automatically generated.
   3. Compare the new reference shader to the old one using a tool like Xcode Version Editor, or Xcode FileMerge, or equivalent.
   4. Delete the old copy of the reference shader.

Adding the SPIRV-Cross library to a new Xcode project

The MoltenVKShaderConverter project is already configured to use the SPIRV-Cross library. However, to add the SPIRV-Cross library to a new Xcode project:

1. Follow the instructions above to create a symlink from your project to the location of your local clone of the SPIRV-Cross repository.

2. In the project navigator, add a new Group named SPIRV-Cross.

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

4. (Optional) If you want Xcode to reference the added files through symlinks (to increase portability) instead of resolving them, perform the following steps:

   1. Create a backup of your project! This is an intrusive and dangerous operation!
   2. In the Finder, right-click your MyApp.xcodeproj file and select Show Package Contents.
   3. Open the project.pbxproj file in a text editor.
   4. Replace all occurrences of the path-to-SPIRV-Cross-repo-folder (as defined by the symlink added above) with simply SPIRV-Cross (the name of the symlink). Be sure you only replace the part of the path that matches the path-to-SPIRV-Cross-repo-folder. Do not replace any part of the path that indicates a subfolder within that repository folder.

Using the SPIRV-Tools library with MoltenVKShaderConverter

MoltenVKShaderConverter uses SPIRV-Tools to log SPIR-V code during conversion to Metal Shading Language (MSL) source code. The SPIRV-Tools also requires the SPIRV-Headers library.

To add the SPIRV-Tools and SPIRV-Headers libraries to MoltenVK, open a Terminal session and perform the following command-line steps:

1. If you used the --recursive option when cloning the MoltenVK repository, you should already have the SPIRV-Tools and SPIRV-Headers submodules, and you can skip to Step 2 below. If you did not use the --recursive option when cloning the MoltenVK repository, retrieve the SPIRV-Tools and SPIRV-Headers submodules into the External directory as follows, from within the MoltenVK repository directory:

    git submodule update --init External/SPIRV-Headers
    git submodule update --init External/SPIRV-Tools
   

2. In the Externals folder within the MoltenVK repository, build SPIRV-Tools as follows from the main directory of this MoltenVK repository:

    cd External
    ./makeSPIRVTools
   

Updating the SPIRV-Tools library version

If you are developing enhancements to MoltenVKShaderConverter, you can update the version of SPIRV-Tools used by MoltenVKShaderConverter to the latest version available by re-cloning and re-building the SPIRV-Tools submodule using the getLatestSPIRVTools script:

cd External
./getLatestSPIRVTools

The updated version will then be "locked in" the next time the MoltenVK repository is committed to git.

Note: If after updating to a new verions of SPIRV-Tools, you encounter build errors when building MoltenVKShaderConverter, review the instructions below to ensure all necessary SPIRV-Tools files are included in the MoltenVKShaderConverter builds.

Adding the SPIRV-Tools library to a new Xcode project

The MoltenVKShaderConverter project is already configured to use the SPIRV-Tools library. However, to add the SPIRV-Tools library to a new Xcode project:

1. Follow the instructions above to create a symlink from your project to the location of your local clone of the SPIRV-Tools repository.

2. In the project navigator, add a new Group named SPIRV-Tools.

3. Drag the SPIRV-Tools/source 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.

4. 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)/MoltenVKSPIRVToMSLConverter/SPIRV-Tools/include"
    "$(SRCROOT)/MoltenVKSPIRVToMSLConverter/SPIRV-Tools/source"
    "$(SRCROOT)/MoltenVKSPIRVToMSLConverter/SPIRV-Tools/build"
    "$(SRCROOT)/MoltenVKSPIRVToMSLConverter/SPIRV-Headers/include"
   

5. (Optional) If you want Xcode to reference the added files through symlinks (to increase portability) instead of resolving them, perform the following steps:

   1. Create a backup of your project! This is an intrusive and dangerous operation!
   2. In the Finder, right-click your MyApp.xcodeproj file and select Show Package Contents.
   3. Open the project.pbxproj file in a text editor.
   4. Replace all occurrences of the path-to-SPIRV-Tools-repo-folder (as defined by the symlink added above) with simply SPIRV-Tools (the name of the symlink). Be sure you only replace the part of the path that matches the path-to-SPIRV-Tools-repo-folder. Do not replace any part of the path that indicates a subfolder within that repository folder.

Using the glslang library with MoltenVKShaderConverter

MoltenVKShaderConverter uses glslang, the Khronos GLSL reference compiler, to parse GLSL source code and convert it to SPIR-V.

If you used the --recursive option when cloning the MoltenVK repository, you should already have the glslang submodule. If you did not use the --recursive option when cloning the MoltenVK repository, retrieve the glslang submodule into the External directory as follows, from within the MoltenVK repository directory:

git submodule update --init External/glslang

Updating the glslang library version

If you are developing enhancements to MoltenVKShaderConverter, you can update the version of glslang used by MoltenVKShaderConverter to the latest version available by re-cloning and re-building the glslang submodule using the getLatestglslang script:

cd External
./getLatestglslang

The updated version will then be "locked in" the next time the MoltenVK repository is committed to git.

Note: If after updating to a new verions of glslang, you encounter build errors when building MoltenVKShaderConverter, review the instructions below to ensure all necessary glslang files are included in the MoltenVKShaderConverter builds.

Adding the glslang library to a new Xcode project

The MoltenVKShaderConverter project is already configured to use the glslang library. However, to add the glslang library to a new Xcode project:

1. Follow the instructions above to create a symlink from your project to the location of your local clone of the glslang repository, and make the required modifications to the glslang code.

2. In the project navigator, add a new Group named glslang.

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

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

    glslang/glslang/MachineIndependant/glslang.y
    glslang/glslang/OSDependent/Windows
   

5. (Optional) If you want Xcode to reference the added files through symlinks (to increase portability) instead of resolving them, perform the following steps:

   1. Create a backup of your project! This is an intrusive and dangerous operation!
   2. In the Finder, right-click your MyApp.xcodeproj file and select Show Package Contents.
   3. Open the project.pbxproj file in a text editor.
   4. Replace all occurrences of the path-to-glslang-repo-folder (as defined by the symlink added above) with simply glslang (the name of the symlink). Be sure you only replace the part of the path that matches the path-to-glslang-repo-folder. Do not replace any part of the path that indicates a subfolder within that repository folder.