Khronos Vulkan

Getting Started with the Linux Tarball 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

System requirements

Your Linux development and host systems must meet specific hardware and software requirements to install the Vulkan SDK and create Vulkan applications. You will need a Vulkan ICD to execute Vulkan applications.

The Vulkan SDK is supported on 64-bit Linux systems. This guide provides instructions for the following Linux distributions:

LunarG does extensive testing on the Ubuntu distributions and touch testing on the other Linux distributions. Additional Linux distributions may work but have not been verified. If the pre-built binaries don't run on your system we provide the source and a helper script to build these components (See Helper Build Script. Also, you can search your distribution's package manager for Vulkan development libraries.

Otherwise you may download and build from publicly available repositories. Everything provided in the SDK is open source. The following list are the core repositories that the SDK is composed of:

You will find instructions to build all of the above in their respective repositories.

Ubuntu distributions (20.04 and 18.04)

Upgrade your system to be current on package updates:

sudo apt update
sudo apt upgrade

If you want to clone and build any of the repositories using the vulkansdk script, install the following prerequisite packages:

sudo apt install libglm-dev cmake libxcb-dri3-0 libxcb-present0 libpciaccess0 \
libpng-dev libxcb-keysyms1-dev libxcb-dri3-dev libx11-dev g++ gcc g++-multilib \
libmirclient-dev libwayland-dev libxrandr-dev libxcb-randr0-dev libxcb-ewmh-dev \
git python python3 bison libx11-xcb-dev liblz4-dev libzstd-dev python3-distutils \
qt5-default ocaml-core ninja-build pkg-config libxml2-dev wayland-protocols

Minimum CMake 3.10.2 version is required.

Fedora core distributions (25 and newer)

Update your system to be current on package updates:

sudo dnf update

If you want clone and build any of the repositories using the vulkansdk script, install the following prerequisite packages:

sudo dnf install @development-tools glm-devel cmake libpng-devel wayland-devel \
libpciaccess-devel libX11-devel libXpresent libxcb xcb-util libxcb-devel libXrandr-devel \
xcb-util-keysyms-devel xcb-util-wm-devel python3 git lz4-devel libzstd-devel python3-distutils-extra qt
gcc-g++ wayland-protocols-devel ninja-build

Minimum CMake 3.14.0 version is required.

Raspbian (Raspberry Pi OS)

You can now build the Vulkan SDK on a Raspberry Pi 4 device runing the latest Raspbian operating system. First you must update your system and install the Vulkan ICD.

sudo apt update
sudo apt upgrade

sudo apt install mesa-vulkan-drivers vulkan-tools

If you want to clone and build any of the repositories using the vulkansdk script, install the following prerequisite packages:

sudo apt install libglm-dev cmake libxcb-dri3-0 libxcb-present0 libpciaccess0 \
libpng-dev libxcb-keysyms1-dev libxcb-dri3-dev libx11-dev g++ gcc \
libmirclient-dev libwayland-dev libxrandr-dev libxcb-randr0-dev libxcb-ewmh-dev \
git python python3 bison libx11-xcb-dev liblz4-dev libzstd-dev python3-distutils \
ocaml-core ninja-build pkg-config libxml2-dev wayland-protocols qtcreator \
qtbase5-dev qt5-qmake qtbase5-dev-tools

Run the vulkansdk script with the following arguments to restirct building to one CPU:

./vulkan_sdk -j 1

It is important that you include the “-j 1” as that will limit the build to just one CPU. You may be able to get away with two CPUs with 8GB of RAM, but on smaller devices, there is not enough memory to support using all CPUs. Also, on an SD card, the build will be painfully slow. As it is, it will likely run overnight and complete by morning. Booting from an external SSD is recommended for developent work.

Building on the 2GB Pi will require a larger swap file. Edit /etc/dphys-swapfile, setting CONF_SWAPSIZE=2048, and reboot.

You will find the working SDK in the /aarch64 folder.

Arch linux distributions (latest)

Update your system to be current on package updates:

sudo pacman -Syu

If you want clone any of the repositories using the vulkansdk script, install the following prerequisite packages:

sudo pacman -S base-devel glm cmake libpng wayland libpciaccess libx11 libxpresent \
libxcb xcb-util libxrandr xcb-util-keysyms xcb-util-wm python git lz4 zstd python-distlib qt5-base

These packages are located in a mix between the core, extra, and community repositories. If any of those are disabled, you won't find the packages. More info on repositories is available here. The minimum required CMake version is CMake 3.14.0. The default version from Arch will be more than sufficient.

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

Once you have installed a Vulkan driver on your system, there is a version for your Vulkan Loader, and a version for each physical device.

  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.

  2. For each physical device, there is an apiVersion. The apiVersion is the version of your Vulkan driver. 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 latest Vulkan SDK from vulkan.LunarG.com.

Install the SDK

The Vulkan SDK installation process consists of extracting the tar file into a desired directory. The extracted file is a folder in the form 1.x.yy.z and can be placed anywhere on your system.

  1. Create a work directory. These instructions assume you want to install the SDK under a folder called vulkan, which can be placed anywhere on your system. In this case, it is your HOME directory.

    cd ~
mkdir vulkan
cd vulkan

  2. Extract the SDK package. Assuming you had downloaded the package to $HOME/Downloads:

    tar xf $HOME/Downloads/vulkansdk-linux-x86_64-1.x.yy.z.tar.gz

Note: Packaging of the Linux Vulkan SDK has changed from a .run file to a .tar.gz file starting from release version 1.1.77.0 and forward. The run file previously created a VulkanSDK directory and then expanded the SDK into the VulkanSDK/1.1.xx.y directory. The .tar.gz file now simply extracts the SDK into a directory of the form 1.x.yy.z.

Tar file contents

The table below describes the filesystem unpacked from the SDK tar file, which appears under the top-level 1.x.yy.z directory created when the SDK was extracted. The top-level SDK directory contains a platform-specific folder; for 64-bit Intel CPU targets, it is named x86_64.

Directory Description
x86_64/bin Vulkan tools and commands
x86_64/include Header files useful for your Vulkan application. Includes Vulkan, shader tools, etc.
x86_64/lib Vulkan loader library and layer runtime libraries
x86_64/etc/vulkan/explicit_layer.d .json manifest files for Vulkan validation layers
x86_64/share/vulkan Configurations for profiles and Vulkan registry information
config Sample layer settings file
source Source files

System file locations

If you have installed a Vulkan driver from a GPU vendor, you may wish to verify there is a .json manifest file for that driver installed. This will normally be located in either /etc/vulkan/icd.d/ or /usr/share/vulkan/icd.d (though other locations are possible). These directories will contain one or more Vulkan driver .json manifest files, which are not modified by the SDK installer. Refer to the Vulkan Loader guide in the "ICD Discovery on Linux" section for detailed information on ICD and layer library search order and paths for this platform.

Set up the runtime environment

Because you installed the Vulkan SDK in a location of your choice, you need to set environment variables to locate the Vulkan SDK components. These variables are identified in the table below. The VULKAN_SDK environment variable is set to the platform-specific directory in your SDK installation (e.g. ~/vulkan/1.x.yy.z/x86_64). The rest of the variables are set using paths relative to VULKAN_SDK:

Environment Variable File/Path to Include
PATH $VULKAN_SDK/bin
LD_LIBRARY_PATH $VULKAN_SDK/lib
VK_LAYER_PATH $VULKAN_SDK/etc/vulkan/explicit_layer.d

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

source ~/vulkan/1.x.yy.z/setup-env.sh

Of course, you would replace "xx" and "y" with the actual SDK version numbers.

Alternatively you can setup your paths by setting these environment variables yourself:

export VULKAN_SDK=~/vulkan/1.x.yy.z/x86_64
export PATH=$VULKAN_SDK/bin:$PATH
export LD_LIBRARY_PATH=$VULKAN_SDK/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
export VK_LAYER_PATH=$VULKAN_SDK/etc/vulkan/explicit_layer.d

Environment variable persistence

Note that sourcing the setup-env.sh script or running export commands only set the environment variables for your current shell session. They do not permanently "setup" any of this configuration for other shell sessions or future logins.

If you desire these variables to be setup for you for future sessions, consult your shell or desktop graphical environment documentation for instructions on how to configure your system to define these environment variables for you.

For example, on most Ubuntu desktop systems, adding a line to your .profile file to source the setup-env.sh file sets up the environment variables for you for both shells and programs started from the graphical environment in a desktop session. This should make the environment variables available to desktop tools such as cmake-gui, Qt Creator, or Android Studio.

Copying SDK Files to System Directories

The binaries included in the SDK are all built from public repositories. You can build each repository from source or it may just be easier to copy the files from the SDK into your system paths. There are also Ubuntu packages that makes installing these files even easier (see packages).

If you want to install SDK files to your system directories, here are some examples to do so. (Note: some system paths could be different depending on what Linux distro you use)

You may need to run sudo ldconfig to refresh system loader search cache.

Uninstalling the SDK

To uninstall the SDK simply remove your local installation directory. e.g.

rm -rf ~/vulkan/1.x.yy.z

Verify the SDK Installation

Verify the installation of the Vulkan SDK by running:

~$ vkvia
`~$ vulkaninfo
`~$ vkcube

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 includes the following layers:

Layer Name Description
VK_LAYER_KHRONOS_validation Vulkan API validation and error checking
VK_LAYER_LUNARG_gfxreconstruct Capturing application Vulkan commands for GFXReconstruct
VK_LAYER_LUNARG_api_dump Print API calls and their parameters and values
VK_LAYER_KHRONOS_profiles Helps test across a wide range of hardware capabilities without physical access to every device.
VK_LAYER_LUNARG_device_simulation Allows modification of an actual device's reported features, limits, and capabilities
VK_LAYER_LUNARG_monitor Outputs the frames-per-second of the target application in the applications title bar
VK_LAYER_LUNARG_screenshot Outputs specified frames to an image file as they are presented
VK_LAYER_KHRONOS_synchronization2 Implements the VK_KHR_synchronization2 extension, for use on systems without a driver that implements it.

Use Vulkan Layers

Layers can be enabled in an application's code or by configuring a system's environment before an application is run. The methods of enabling layers that do not require modifying an application are outlined below.

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

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_gfxreconstruct

Debug 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 applications correct use of the Vulkan API.

Vulkan API Capture and Replay with GFXReconstruct

The GFXReconstruct project provides tools for the capture and replay of Vulkan API calls. The VK_LAYER_LUNARG_gfxreconstruct layer allows recording to a file the graphics commands executed by a Vulkan application that may later be replayed with gfxrecon-replay to reconstruct the graphics-specific behavior of the captured application.

Helper build script

The root SDK directory contains a script named vulkansdk to aid with building binaries. There may be some rare instances when the pre-built binaries provided in the Linux SDK will not work with your system. This script will build all the binaries included in the SDK. Be sure you have the necessary requirements (see Download and Install Packages for building binaries) before running this script.

After successfully running vulkansdk the files will be located under the "x86_64" directory. If you ran source setup-env.sh to set up your environment variables the binaries will be in your path (see Set up the Runtime Environment).

The vulkansdk script helps with building the following repositories: glslang, Vulkan Loader, Vulkan validation layer, Vulkan tools, shaderc, *spirv-tools, and spirv-cross.

Each option will build a corresponding repository. Depending on the repository multiple tools will be built. Here is a list of tools corresponding to the repository that will be built:

Any or all of these script's options can be used separated by spaces. Run ./vulkansdk help for available options. Running ./vulkansdk with no options will build everything.

Repository vulkansdk script option Resulting Build Components
Khronos' Vulkan-Loader vulkan-loader libvulkan.so
Khronos' Vulkan-ValidationLayer vulkan-validationlayer Khronos Vulkan validation layer
Khronos' Vulkan-ExtensionLayer vulkan-extensionlayer Khronos Vulkan extension layer
Khronos' Vulkan-Tools vulkan-tools vulkaninfo, vkcube, vkcubepp
LunarG's VulkanTools lunarg-tools layers, VIA, Vulkan Configurator
LunarG's gfxreconsruct gfxreconstruct GFXReconstruct capture/replay/tools
Google's shaderc shaderc glslc and shaderc libraries
Khronos' glslang glslang glslangValidator and glslang libraries
Khronos' SPIRV-Tools spirv-tools SPIR-V tools binaries and libraries
Khronos' SPIRV-Cross spirv-cross SPIR-V Cross binary and libraries
Khronos' SPIRV-Reflect spirv-reflect SPIR-V Reflect binary and source files
All Repositories all Builds All Repositories

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.