moltenvk/ExternalRevisions/README.md

<a class="site-logo" href="https://github.com/KhronosGroup/MoltenVK" title="MoltenVK">
	<img src="../Docs/images/MoltenVK-Logo-Banner.png" alt="MoltenVK" style="width:256px;height:auto">
</a>


#MoltenVK External Dependencies

Copyright (c) 2014-2019 [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
-----------------

- [Fetching and Building External Libraries](#fetching)
- [Updating External Library Versions](#updating)
- [Adding the *cereal* Library to the *MoltenVK Xcode* Project](#add_cereal)
- [Adding the *SPIRV-Cross* Library to the *ExternalDependencies Xcode* Project](#add_spirv-cross)
- [Adding the *SPIRV-Tools* Library to the *ExternalDependencies Xcode* Project](#add_spirv-tools)
- [Adding the *glslang* Library to the *ExternalDependencies Xcode* Project](#add_glslang)



<a name="fetching"></a>
Fetching and Building External Libraries
----------------------------------------

**MoltenVK** uses technology from the following external open-source libraries:

- [*cereal*](https://github.com/USCiLab/cereal)
- [*Vulkan-Headers*](https://github.com/KhronosGroup/Vulkan-Headers)
- [*SPIRV-Cross*](https://github.com/KhronosGroup/SPIRV-Cross)
- [*glslang*](https://github.com/KhronosGroup/glslang)
- [*SPIRV-Tools*](https://github.com/KhronosGroup/SPIRV-Tools)
- [*SPIRV-Headers*](https://github.com/KhronosGroup/SPIRV-Headers)
- [*Vulkan-Tools*](https://github.com/KhronosGroup/Vulkan-Tools)
- [*VulkanSamples*](https://github.com/LunarG/VulkanSamples)

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.


<a name="updating"></a>
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.



<a name="add_cereal"></a>
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](#updating), 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"


<a name="add_spirv-cross"></a>
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](#updating),
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_parsed_ir.cpp
		spirv_cross_parsed_ir.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

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



<a name="add_spirv-tools"></a>
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](#updating), 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*, remove the *Group* named `source` from under the *Group* named
   `External/SPIRV-Tools`.

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

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

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

4. Repeat *Step 3* for the `SPIRV-Tools-iOS` target within the `ExternalDependencies` *Xcode* project

5. Update `Templates/spirv-tools/build.zip` from the contents of `External/glslang/External/spirv-tools/build`,
   and test by running `./fetchDependencies --skip-spirv-tools-build`, and a **MoltenVK** build.



<a name="add_glslang"></a>
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](#updating),
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*, remove all *Groups* from under the *Group* named
   `External/glslang`.

2. 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 *both* the `glslang-macOS` and `glslang-iOS` targets, and click the ***Finish*** button.

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