Copyright (c) 2014-2017 [The Brenwill Workshop Ltd.](http://www.brenwill.com) *This document is written in [Markdown](http://en.wikipedia.org/wiki/Markdown) format. For best results, use a Markdown reader.* Table of Contents ----------------- - *SPIRV-Cross* - [Using the *SPIRV-Cross* library with **MoltenVKShaderConverter**](#install_spirv-cross) - [Updating the *SPIRV-Cross* library version](#update_spirv-cross) - [Adding the *SPIRV-Cross* library to a new *Xcode* project](#add_spirv-cross) - *SPIRV-Tools* - [Using the *SPIRV-Tools* library with **MoltenVKShaderConverter**](#install_spirv-tools) - [Updating the *SPIRV-Tools* library version](#update_spirv-tools) - [Adding the *SPIRV-Tools* library to a new *Xcode* project](#add_spirv-tools) - *glslang* - [Using the *glslang* library with **MoltenVKShaderConverter**](#install_glslang) - [Updating the *glslang* library version](#update_glslang) - [Adding the *glslang* library to a new *Xcode* project](#add_glslang) 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](#add_spirv-cross) 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 `glslangValidator`tools (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.py --msl shaders-msl 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](#install_spirv-cross) 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](#install_spirv-cross)) 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 3. 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](#add_spirv-tools) 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](#install_spirv) 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](#install_spirv)) 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](#add_glslang) 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](#install_glslang) 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](#install_glslang)) 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.