Khronos Vulkan

Getting Started with the macOS Vulkan SDK

Creative Commons

Vulkan SDK Introduction

This guide describes the content, the requirements and procedure for getting started with the Vulkan SDK.

The Khronos Vulkan API is an explicit, low-overhead, cross-platform graphics and compute API. Vulkan provides applications with control over the system execution and the system memory to maximize application efficiency on a wide variety of devices from PCs and consoles to mobile phones and embedded platforms.

The Vulkan SDK enables Vulkan developers to develop Vulkan applications. The Vulkan SDK includes:

All documentation for the SDK can be found and downloaded online at vulkan.lunarg.com.

Looking for Validation Layer Binaries for Android?

With each SDK release, a release of the Khronos Validation Layer binaries for Android are released on the Validation layer Repository. The Android binaries are not included in this SDK.

Terminology

Term Description
ICD Installable Client Driver: A Vulkan compatible display driver
GLSL OpenGL Shading Language
Vulkan Instance The Vulkan API object that stores all per-application states
Vulkan Layer A library designed to work as a plug-in for the loader. It usually serves to provide validation and debugging functionality to applications
Vulkan Loader A library which implements the Vulkan API entry points and manages layers, extensions, and drivers. It is found in the independent hardware vendor driver installs
SPIR‑V Standard Portable Intermediate Representation is a cross-API intermediate language (IL) that natively represents parallel compute and graphics programs

MoltenVK

This SDK provides partial Vulkan support through the use of the MoltenVK library which is a "translation" or "porting" library that maps most of the Vulkan functionality to the underlying graphics support (via Metal) on macOS, iOS, and tvOS platforms. It is NOT a fully-conforming Vulkan driver for macOS, iOS, or tvOS devices.

There are two ways to make use of MoltenVK in your shipping Vulkan-based applications. One is to link directly to the MoltenVK static or dynamic library, which will give you direct access to the Vulkan API, and allows for some mixed use with Vulkan and low-level Metal capabilities. This option is not practical if you wish to maintain portability of your Vulkan rendering code accross platforms. You will also sacrifice the ability to use the Vulkan Validation layers. However, this is currently the only way to use MoltenVK on mobile devices, and an XCFramework is provided as a static library that can be linked directly to your application. Please see the MoltenVK Runtime User Guide on the MoltenVK GitHub for more information about MoltenVK specifics.

For desktop applications, the recommended usage model is to use the MoltenVK dynamic library in conjunction with the Vulkan Loader. In this scenario the MoltenVK library takes on the role of the ICD from the point of view of the application and the Vulkan Loader. In this mode, you link only to the Vulkan Loader, and not the MoltenVK library directly. You will include the MoltenVK and the Vulkan Loader dynamic libraries in your application's bundle when distributing your software. When the Vulkan SDK is installed on macOS, these runtime components are placed in system directories and can be easily used during development without embedding them in the app bundle. Even if you decide to ship your application linked to the static MoltenVK library, during development we recommend you make use of the Vulkan Loader and Vulkan Validation Layers as they are a tremendous boon for debugging your Vulkan-based rendering code.

Regardless of the method used, your applications are distributed with everything they need to use Vulkan over Metal all included in your application's bundle. No additional system files or runtime components are needed by the end users of your applications.

System Requirements

Use of the Vulkan SDK

SDK Versioning

The components in this SDK are built with a specific version of Khronos Vulkan API header, whose version is reflected in the SDK's version number. For example, SDK version v.w.xx.0 indicates the SDK uses the Vulkan header revision where:

The last number in the SDK version indicates the revision of an SDK for the given Vulkan header revision. It is used in case it is necessary to release multiple SDKs for the same version of Vulkan.

For example, SDK version 1.1.70.0 indicates the SDK uses Vulkan header revision 1.1.70.

Note: A more recent SDK version number does not indicate an application cannot be developed for earlier Vulkan versions. As well, an older SDK version can not be used to develop applications for a newer version of Vulkan. For example, the 1.1.130.0 SDK can be used to develop Vulkan 1.0 applications but cannot be used to develop applications for Vulkan 1.2. Furthermore, the presence of a 1.2.xx SDK does not necessarily indicate a system can actually run Vulkan 1.2. A Vulkan 1.2 driver is required for applications to use most Vulkan 1.2 functionality.

Note: On macOS, iOS, and tvOS, the Vulkan header number is not a true reflection of the underlying support from MoltenVK (which is currently at Vulkan version 1.1).

Note that there is a version for your Vulkan Loader, and a separate supported version for each physical device on your system.

  1. Vulkan Instance Version. This is the version of your Vulkan Loader. If you run vulkaninfo, the Vulkan Instance version is the first item reported. The Vulkan Loader is delivered with your driver update package on most operating systems, but on macOS the loader is shipped as part of the SDK, or is included directly in the MoltenVK library. Most developers will include these files in their macOS application bundles.
  2. For each physical device, there is an apiVersion. The apiVersion is the version of Vulkan supported by that device. You can find the apiVersion for each physical device from your vulkaninfo output under the section labeled "Device Properties and Extensions".

Download the SDK

Download the Vulkan SDK from the Download Site. The SDK download file is named with the pattern:

vulkansdk-macos-v.w.xx.0.dmg

Install the SDK

Installing is a simple operation involving mounting a disk image file and running the InstallVulkan application. If using Finder, navigate to the downloaded file and double-click the file to mount it. Once the dmg file is mounted double-click the InstallVulkan icon to start the installer. The Vulkan installer program will ask you for the destination folder to install the Vulkan SDK. It will prompt you for your user password as well as it needs administrative access in order to copy the Vulkan Loader and SDK tools to system folders where your terminal path can locate them. The macOS SDK is intended to be installed anywhere the user can place files such as the user's $HOME directory. An uninstaller is also created and placed in the SDK installation folder.

SDK System Paths

macOS allows the installation of files to /usr/local which are then in the standard system paths and the loader's search paths for ICD's. The Vulkan installer program will copy the loader, command line tools, and the MoltenVK ICD to these folders. This eliminates the need to set PATH, DYLD_LIBRARY_PATH, VK_LAYER_PATH, and VK_ICD_FILENAMES environment variables in order to use SDK components during development. You should note that macOS does not easily provide support for allowing environment variables to affect the behavior of GUI applications. For developers who rely on the command line for much of their work, these environment variables behave as expected and can be used to override the default behavior.

You can manually uninstall and re-install these system files by using the same install scripts that the installer and uninstaller uses and that are provided with the SDK. These are named install_vulkan.py and uninstall.sh To run these scripts, in your terminal navigate to the directory you installed the SDK files into and run:

sudo ./install_vulkan.py

This will copy the SDK files to the appropriate system directories and generate a log file named VULKAN_INSTALL.log in /tmp. To run the uninstall script, navigate to the root directory of the SDK in your terminal and run:

sudo ./uninstall.sh

Note: Since SDK components are copied directly to the /usr/local tree, only a single version of the Vulkan SDK can be active at a time. Using this method, it is possible to switch manually back and forth between SDK versions without having to re-run the installer. You should be aware that if System Integrity Protection is enabled (it normally is), you may need to reboot before the kernel will recognize the new code signatures from these updated files.

Vulkan SDK contents

This section describes how the SDK contents are organized.

Directory Description
Applications Standalone Vulkan demos and tools
MoltenVK MoltenVK frameworks and libraries for macOS, iOS, and tvOS
macOS VULKAN_SDK tree; "System tree" with traditional bin, include, lib structure
macOS/bin Vulkan and shader tool executables
macOS/share/vulkan/explicit_layer.d Explicit layers that can be referenced with the VULKAN_LAYER_PATH environment variable
macOS/share/vulkan/icd.d MoltenVK ICD manifest JSON file
macOS/share/vulkan/registry Home of the vk.xml validusage.json and files
macOS/Frameworks Vulkan loader framework for Xcode
macOS/include Vulkan and shader tool header files
macOS/lib Vulkan and shader tool libraries

VULKAN_SDK Tree

The macOS directory is the root of a "system tree" containing Vulkan executables, include files, and libraries in the traditional bin, include, lib structure. This tree contains the Vulkan components such as the loader library and layer libraries.

This tree also contains executables, include files, and libraries for various Vulkan-related tools such as glslang, SPIRV-Tools, and others.

It is often useful to point system environment variables (e.g., PATH, DYLD_LIBRARY_PATH) and Vulkan-related environment variables (e.g., VK_LAYER_PATH) to directories in this directory to locate the components found in this tree. In addition VK_ICD_FILENAMES can point to the latest MoltenVK ICD included in the SDK instead of using the system paths.

This can be done with the setup-env.sh script. Remember, these environment variables are not seen by GUI applicaitons launched from Finder or the graphical shell in macOS, even if you put them in the system startup script.

Options for Using Vulkan Support Components

The Vulkan SDK is flexible in the sense that it can support various workflows. Some of these workflows are summarized here.

Create a Bundled Application

Your Xcode project copies all required components from the SDK and places them in the application bundle. This results in a standalone application that can be copied or published anywhere and does not require the user to have an SDK installed.

Using Xcode, add the various components from the SDK to your Xcode project. Configure your project so all required components are in your bundle.

Xcode with SDK Side-Install

Your Xcode project has references to the SDK and requires an SDK be installed on your system. This workflow might be used in a development phase that eventually leads to the bundled application workflow. The SDK installer will copy the appropriate files to your /usr/bin paths so that the Vulkan Loader and MoltenVK ICD are available when you run your project from Xcode.

Set up the runtime environment

If the SDK is not installed to system directories you may need to set environment variables inside the Xcode interface when working with Xcode projects that use SDK components. You may also need to set environment variables in your command shell when running some non-bundled Vulkan applications or other SDK tools from the command line.

A setup script is provided in the top-level directory of your SDK installation to help you easily set the environment variables. Use the source command to load that script into your current shell:

source setup-env.sh

See the note below about environmet variables and GUI applications.

Set up the runtime environment manually

Note that on macOS, shell environment variables are not seen by GUI applications launched from the Apple launch services (such as double-clicking an apps icon). In addition, the DYLD_LIBRARY_PATH is considered a security violation and will not function unless SIP (System Integrity Protection) is disabled. This is not recommended, but can be useful during development (but not for a shipping application). Best practice on macOS is to include the Vulkan Loader and/or MoltenVK directly in the application's .app bundle and not disable SIP.

If you are developing on the command line and wish to launch applications primarily from the command line, you can set up the environment using the Terminal application:

Set a convenience variable to point to the SDK:

export VULKAN_SDK=$vulkansdk/macOS

Replace the "$vulkansdk" above with the actual path to your SDK but include the /macOS part.

Add the bin directory to your PATH to make it easy to run Vulkan Info and the various glslang and SPIRV-Tools installed there:

export PATH=$VULKAN_SDK/bin:$PATH

Add the lib directory to your DYLD_LIBRARY_PATH so that programs find the Vulkan Loader library:

export DYLD_LIBRARY_PATH=$VULKAN_SDK/lib:$DYLD_LIBRARY_PATH

Tell the Vulkan Loader where to find a Vulkan driver:

export VK_ICD_FILENAMES=$VULKAN_SDK/etc/vulkan/icd.d/MoltenVK_icd.json

Tell the Vulkan Loader where to find the Vulkan SDK Layers:

export VK_LAYER_PATH=$VULKAN_SDK/etc/vulkan/explicit_layer.d

Verify the SDK Installation

Verify the installation of the Vulkan SDK by running:

~$ vkvia
`~$ vulkaninfo

Note: There's a bundled version of Vulkan Info in the SDK's Applications directory.

Working with Xcode

For macOS desktop development, the Vulkan header files and loader are provided in a framework (macOS/Frameworks/vulkan.framework), it is fairly easy to add these to your Xcode project, just like any other framework. The included framework is a Universal Binary, containing both x86_64 and Apple Silicon binaries.

Using the loader gives your application run-time access to the MoltenVK ICD (or potentially load other Vulkan implementations dynamically) and the Vulkan Khronos Validation layer.

Configuring Xcode with Environment Variables

If you want your Xcode project to refer to components residing in an SDK instead of bundling these components, you can set environment variables in your Xcode project to point to these components instead of bundling them.

This may be a technique suitable for developers whose workflows are compatible with "pointing" to a specific SDK during their work. It is unlikely that anyone would want to deploy an application that requires an SDK to be present.

Here are some approaches for setting these variables:

Set Variables in Xcode

Xcode has an interface for setting environment variables in the "Scheme" panel. This is a fairly common and straightforward approach.

Inherit Variables From Environment

If you are new to macOS development, it may suprise you that environment variables set in your shell will not be seen by Xcode if Xcode is launched from Launchpad or other desktop GUI. You may be able to pass shell environment settings into Xcode by starting Xcode with open from a bash shell command line where the environment variables are set.

With Xcode versions 7 and later, you may need to enable this behavior:

defaults write com.apple.dt.Xcode UseSanitizedBuildSystemEnvironment -bool NO

System-wide Preferences

Configure the system-wide Preferences for Xcode by adding Custom Paths in the Preference's Locations tab.

Using the Vulkan Loader

As an alternative to using the framework, you can add Vulkan Loader support to your application by adding the Vulkan header files and Vulkan Loader library file individually to your project:

Add the SDK's macOS/include directory to the project's Header Search Paths. Add both the libvulkan.1.dylib and the libvulkan.1.x.yyy.dylib to your application's folder in the Project Navigator. You may have to add a Copy Files step to copy these two files into the compiled project.

libvulkan.1.dylib and libvulkan.dylib are both symbolic links to libvulkan.1.x.yyy.dylib. You may prefer to link only to libvulkan.1.x.yyy.dylib or rename libvulkan.1.x.yyy.dylib to libvulkan.1.dylib or libvulkan.dylib in your project.

Mobile Device Development

At this time Vulkan Loader support is not available on iOS or tvOS devices, so you will need to link directly to the MoltenVK library. The Vulkan SDK for macOS includes an XCFramework that will link directly to the (static) MoltenVK library and supports simultaneous development on macOS (x86_64 or Apple Silicon), iOS (hardware or simulator), and tvOS (hardware or simulator) all with one single framework. Note if you are developing for both mobile and desktop platforms that linking directly to MoltenVK in this way bypasses the Vulkan Loader and does not allow the use of implicit Vulkan Layers (see below) on macOS. Add the MoltenVK.xcframework (located in the /MoltenVK folder of the SDK) to your Xcode project as you would any other framework. Unlike some frameworks, the MoltenVK XCFramework does not include the Vulkan Headers, and you will need to add the header path yourself from the SDK.

Vulkan SDK Layers

Vulkan Layers aim at helping Vulkan developers building Vulkan applications by providing Vulkan API usage validation and Vulkan debugging tools.

A Vulkan Layer can intercept all or any subset of Vulkan API entry points. Multiple layers can be chained together to cascade their functionality in the appearance of a single, larger layer.

Vulkan SDK Layers list

The Vulkan SDK for macOS includes the following layers:

Layer Name Description
VK_LAYER_KHRONOS_validation Vulkan API validation and error checking.
VK_LAYER_LUNARG_api_dump Print API calls and their parameters and values.
VK_LAYER_LUNARG_device_simulation Allows modification of an actual device's reported features, limits, and capabilities.
VK_LAYER_KHRONOS_synchronization2 Implements the VK_KHR_synchronization2VK_KHR_synchronization2 extension, for use on systems without a driver that implements it.

Use Vulkan Layers

Vulkan Configurator

Vulkan Configurator is a GUI application designed to make Vulkan Layers features and settings more accessible and intuitive to use, and to improve development iteration time.

A Vulkan application may configure layers when creating a Vulkan Instance. This layers configuration may be overridden using Vulkan Configurator globally or for a selected list of Vulkan applications.

Finally Vulkan Configurator allows using Vulkan Layers from user-defined directories.

Main window Layers window
Main window Layers window

Note: This is the recommended approach to use or override Vulkan Layers.

VK_INSTANCE_LAYERS environment variable

Remember that on macOS, envornment variables are not seen by GUI applications. However, if working from the command line the Vulkan Layers can be enabled by setting the VK_INSTANCE_LAYERS environment variable to a colon-separated list of layer or extension names, as found in the Vulkan SDK Layers list or within the manifest files.

$ export VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation:VK_LAYER_LUNARG_api_dump

Debugging Vulkan applications

Vulkan API Validation with Khronos Validation layer

By design, minimal error checking is done inside a Vulkan driver to avoid API overhead. Applications have full control and responsibility for correct operation. Any errors in how Vulkan is used can result in a crash. The Khronos Validation layer VK_LAYER_KHRONOS_validation can be enabled to assist development by enabling developers to verify their application's correct use of the Vulkan API.

Troubleshooting

Loader Messages

To get debug messages from the loader, export VK_LOADER_DEBUG=all and run your app or vulkaninfo. You will get debugging messages from the loader on stdout when this is set. This is even easier and not required at all when using vkConfig to run your apps with valiation layers.

Common Problems

Encountered VK_ERROR_INITIALIZATION_FAILED: This problem can occur when the loader is unable to find an ICD to use. There are a few ways to fix this:

Encountered "Could not start Vulkan Info" message in "Vulkan Info" tab of vkconfig.app: To use the "Vulkan Info" tab in vkconfig.app the SDK files must be copied to your system folders. If your installation has become corrupted ,you can run sudo ./install_vulkan.py from the SDK folder or re-run the SDK installation program.

Loader Search Paths for ICD and Layers

The Vulkan Loader for macOS searches the same paths for ICDs and Layers as the Vulkan Loader for Linux. These paths are described in The Loader And Layer Interface document.

The macOS loader also looks in the application's bundle for ICD and layer JSON files. It looks in the bundle's Resources/vulkan/icd.d directory for ICD JSON files and in the bundle's Resources/vulkan/explicit_layer.d directory for layer JSON files. The ICD JSON file (MoltenVK_icd.json) can be seen in the bundle shown above.

If the executable is in a bundle, the loader searches the bundle first before searching the system directories.

If you wish to bundle the MoltenVK ICD into your application, you need to put a modified version of the MoltenVK_icd.json file in your bundle's Resources/vulkan/icd.d folder to allow the loader to find the MoltenVK library in your bundle. Assuming that you intend to ship the MoltenVK library in the Frameworks directory, you would make a copy of the file vulkansdk/macOS/etc/icd.d/MoltenVK_icd.json from the SDK.

Edit this copy to modify the library_path:

Original:

{
    "file_format_version" : "1.0.0",
    "ICD": {
        "library_path": "./libMoltenVK.dylib",
        "api_version" : "1.1.0"
    }
}

Modified:

{
    "file_format_version" : "1.0.0",
    "ICD": {
        "library_path": "../../../Frameworks/libMoltenVK.dylib",
        "api_version" : "1.1.0"
    }
}

Then use this modifed file when creating your application bundle.

Application Bundle Structure

For example, the application bundle for Vulkan Cube (vkcube.app) is laid out as follows:

vkcube.app
    Contents
        CodeResources
        Frameworks
            libMoltenVK.dylib
            libvulkan.1.[version number].dylib
            libvulkan.1.dylib -> libvulkan.1.[version number].dylib
        Info.plist
        MacOS
            vkcube
        Resources
            VulkanIcon.icns
            Main.storyboardc
            vulkan
                icd.d
                    MoltenVK_icd.json

Note: All required components are in the bundle. Signed apps will also have the _CodeSignature and CodeResources assets.

The SDK also provides the Vulkan Loader as a Framework in addition to a standalone library. This allows you to add the Vulkan Loader support to your application as a Framework if you wish.

Next Steps

This guide provided an introduction to the main components and tools in the Vulkan SDK. Refer to the Vulkan SDK Download Site for the most up-to-date SDK information, including the complete set of SDK documentation.