MoltenVK

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

About This Document
Introduction
Installing MoltenVK
Third-Party Libraries
- Updating the Third-Party Library Versions
Building MoltenVK
Using MoltenVK in Your Application
Third-Party 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 document in the Docs directory.

Introduction

MoltenVK contains two products:

MoltenVK is an implementation of the Vulkan graphics and compute API, that runs on Apple's 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. 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.

Ensure you have python3 installed:
```
 brew install python3
```
Optional: If you want to generate a Vulkan specification document for inclusion in the final MoltenVK distribution package, ensure you have asciidoctor installed (you can skip this otherwise):
```
 brew install asciidoctor
```

Recursively clone the MoltenVK repository:

 git clone --recursive https://github.com/KhronosGroup/MoltenVK.git

Run the third-party build script:
```
 cd MoltenVK/External
 ./makeAll
```

See the next section for more information about the third-party libraries, and how to work with them within the MoltenVK development environment.

Third-Party Libraries

MoltenVK makes use of several third-party open-source libraries. Development of some of these components is managed separately, and are retrieved into MoltenVK as submodule repositories.

If you used the --recursive option when cloning this repository, as described above, 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

Updating the Third-Party Library Versions

If you are developing enhancements to MoltenVK, you can update the versions of the Third-Party libraries used by MoltenVK to the latest versions available by re-cloning and re-building the submodules using the getLatestAll script:

cd External
./getLatestAll

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

This procdure updates all of the Third-Party library submodules. To update only a single submodule, or for more information about the various Third-Party libraries and submodules used by MoltenVK, please refer to the Docs/ThirdPartyConfig.md document.

Building MoltenVK

Note: Before attempting to build MoltenVK, be sure you have followed the instructions in the Third-Party Components section above to retrieve and install the required third-party components.

At development time, MoltenVK references advanced OS frameworks during building.

Xcode 9 or above is required to build and link MoltenVK projects.

Once built, MoltenVK can be run on iOS or macOS devices that support Metal.

MoltenVK requires at least macOS 10.11 or iOS 9.
Information on macOS devices that are compatible with Metal can be found in this article.
Information on compatible iOS devices that are compatible with Metal can be found in this article.

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 theseMoltenVKPackaging.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 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, follow the instructions in the installation section of the MoltenVK Runtime User Guide 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:

MoltenVKShaderConverter uses technology from the following open-source frameworks:

SquarePants1991 / MoltenVK