MoltenVK ======== 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 ----------------- - [About This Document](#about_this) - [Introduction](#intro) - [Installing **MoltenVK**](#install) - [Third-Party Components](#third-party) - [Building **MoltenVK**](#building) - [Using **MoltenVK** in Your Application](#using) - [Third-Party Credits](#credits) About This Document ------------------- This document describes how to use the **MoltenVK** open-source repository to build a **MoltenVK** runtime distribution package. To learn how to integrate the **MoltenVK** runtime into a game or application, see the [**MoltenVK Runtime User Guide**](Docs/MoltenVK_Runtime_UserGuide.md) document in the `Docs` directory. Introduction ------------ **MoltenVK** contains two products: - **MoltenVK** is an implementation of the [*Vulkan*](https://www.khronos.org/vulkan) graphics and compute API, that runs on Apple's [*Metal*](https://developer.apple.com/metal) graphics and compute framework on both *iOS* and *macOS*. - **MoltenVKShaderConverter** converts *SPIR-V* shader code to *Metal Shading Language (MSL)* shader source code, and converts *GLSL* shader source code to *SPIR-V* shader code and/or *Metal Shading Language (MSL)* shader source code, for use with **MoltenVK**. The converter can run at runtime as a component of the *MoltenVK* runtime, or it can be packaged into a stand-alone command-line *macOS* tool. The *Xcode* project contains several targets, reflecting this multi-use capability. Installing **MoltenVK** ----------------------- **MoltenVK** relies on several third-party open-source libraries, which are described in the [next section](#third-party). The easiest way to install **MoltenVK** is to recursively clone this `MoltenVK` repository, and then run the `External/makeAll` script to create necessary components within the third-party libraries. 1. Ensure you have `python3` and `asciidoctor` installed: brew install python3 sudo gem install asciidoctor 2. Recursively clone the `MoltenVK` repository: git clone --recursive https://github.com/KhronosGroup/MoltenVK.git 3. Run the third-party build script: cd MoltenVK/External ./makeAll See the [next section](#third-party) for more information about the third-party libraries, and how to work with them within the **MoltenVK** development environment. Third-Party Components ---------------------- **MoltenVK** makes use of several third-party open-source libraries. Development of some of these components is managed separately. If you used the `--recursive` option when cloning this repository, as described [above](#install), all third party libraries will have been retrieved. If you did not use the `--recursive` option when cloning this repository, you can retrieve and install these libraries into your `MoltenVK` repository environment as follows from within the `MoltenVK` repository: git submodule update --init --recursive cd External ./makeAll >***Note:*** Some of these libraries are maintained and updated regularly with new features. > See the documents listed just below here to learn how to update the version of each library as needed. **MoltenVK** uses the third-party libraries described in the following documents: - [`MoltenVK/ThirdPartyConfig.md`](MoltenVK/ThirdPartyConfig.md) - [`MoltenVKShaderConverter/ThirdPartyConfig.md`](MoltenVKShaderConverter/ThirdPartyConfig.md) Building **MoltenVK** ------------------- >***Note:*** Before attempting to build **MoltenVK**, be sure you have followed the instructions in the [*Third-Party Components*](#third-party) section above to retrieve and install the required third-party components. >***Note:*** At runtime, **MoltenVK** can run on *iOS 9* and *macOS 11.0* devices, >but it does reference advanced OS frameworks during building. *Xcode 9* >or above is required to build **MoltenVK**, and build and link **MoltenVK** projects. >***Note for Xcode 9 on macOS Sierra (10.12):*** There is currently an issue with *Xcode 9* when building **MoltenVK** on *macOS Sierra (10.12)*. When creating the `libMoltenVK.dylib` file for *macOS*, `libtool` is unable to link to the file `/usr/lib/system/libsystem_darwin.dylib` that *Xcode 9* indicates is required, because that file does not exist on *macOS Sierra (10.12)*. To work around this issue, add the following symlink: > ln -sfn /usr/lib/system/libsystem_coretls.dylib /usr/local/lib/libsystem_darwin.dylib The `MoltenVKPackaging.xcodeproj` *Xcode* project contains targets and schemes to build and package the entire **MoltenVK** runtime distribution package, or to build individual **MoltenVK** or **MoltenVKShaderConverter** components. To build a **MoltenVK** runtime distribution package, suitable for testing and integrating into an app, open `MoltenVKPackaging.xcodeproj` in *Xcode*, and use one of the following *Xcode Schemes*: - **MoltenVK (Release)** - build the entire **MoltenVK** runtime distribution package using the *Release* configuration. - **MoltenVK (Debug)** - build the entire **MoltenVK** runtime distribution package using the *Debug* configuration. Each of these`MoltenVKPackaging.xcodeproj` *Xcode* project *Schemes* puts the resulting packages in the `Package` directory, creating it if necessary. This directory contains separate `Release` and `Debug` directories, holding the most recent **Release** and **Debug** builds, respectively. A separate `Latest` directory links to the most recent build, regardless of whether it was a **Release** or **Debug** build. Effectively, the `Package/Latest` directory points to whichever of the `Package/Release` or `Package/Debug` directories was most recently updated. With this packaging structure, you can follow the [instructions below](#using) to link your application to the **MoltenVK** frameworks in the `Package/Latest` directory, to provide the flexibility to test your app with either a **Debug** build, or a higher-performance **Release** build. Once you have built the **MoltenVK** runtime distribution package, the **MoltenVK** demo apps can be accessed from the `Demos/Demos.xcworkspace` *Xcode* workspace. This is the same workspace that is included in the **MoltenVK** runtime distribution package, and you can use it to build and run the **MoltenVK** demo apps, or to add new demos to this **MoltenVK** repository. Using **MoltenVK** in Your Application -------------------------------------- Once you have compiled and built the **MoltenVK** runtime distribution package from this **MoltenVK** repository, as described in the [previous section](#building), follow the instructions in the installation section of the [**MoltenVK Runtime User Guide**](Docs/MoltenVK_Runtime_UserGuide.md#install) document in the `Docs` directory of the **MoltenVK** runtime distribution package found in the `Package/Latest` directory, to link the **MoltenVK** frameworks and libraries in the `Package/Latest` directory to your application. The runtime distribution package in the `Package/Latest` directory is a stand-alone package, and you can copy the contents of that directory out of this **MoltenVK** repository into your own application building environment. Third-Party Credits ------------------- **MoltenVK** uses technology from the following open-source frameworks: - [*Vulkan-Hpp*](https://github.com/KhronosGroup/Vulkan-Hpp) - [*Vulkan-Docs*](https://github.com/KhronosGroup/Vulkan-Docs) - [*tinyxml2*](https://github.com/leethomason/tinyxml2) **MoltenVKShaderConverter** uses technology from the following open-source frameworks: - [*SPIRV-Cross*](https://github.com/KhronosGroup/SPIRV-Cross) - [*SPIRV-Tools*](https://github.com/KhronosGroup/SPIRV-Tools) - [*glslang*](https://github.com/KhronosGroup/glslang)