LunarG

Getting Started with the Vulkan SDK

Version for Linux

Copyright © 2015-2018 LunarG, Inc.

Creative Commons

This guide describes the requirements and procedure for installing the LunarG Vulkan SDK for Linux. It also includes compilation and runtime instructions for demo Vulkan applications. Refer to the LunarG Vulkan SDK, Documentation, and Known Issues at Vulkan.LunarG.com for the most up to date SDK information.

The Vulkan API is a low overhead, explicit, cross-platform graphics API that provides applications with direct control over the GPU, maximizing application performance. For more information on the Vulkan specification and API, refer to Khronos.org. For tutorial-level information, refer to LunarG's Vulkan tutorial, which can be found in the SDK in the samples/API-Samples/Tutorial directory and on the LunarXchange website.

This SDK does NOT include a Vulkan driver. Please contact your GPU hardware vendor for a Vulkan Installable Client Driver (ICD). This SDK will allow you to build Vulkan applications but you will need a Vulkan driver (ICD) to execute them.

Versioning

The LunarG Vulkan SDK provides the development and runtime components required to build, run, and debug Vulkan applications. This SDK is based on the Khronos Vulkan API header, whose version is reflected in the Vulkan SDK version number (for example, SDK version 1.1.70.0 indicates the SDK uses Vulkan header revision 1.1.70). The SDK also includes certain Vulkan extensions for window system integration and debug extensions (refer to the release notes for further details).

Note: This version number does not indicate an application cannot be developed for earlier Vulkan versions. As such, a 1.1 SDK can still be used to develop Vulkan 1.0 applications but cannot be used to develop applications for future versions of Vulkan. Furthermore, the presence of a 1.1 SDK does not necessarily indicate a system can actually run Vulkan 1.1. A Vulkan 1.1 driver is required for applications to use most Vulkan 1.1 functionality. For more information on how to query Vulkan versions programmatically, see the 1.1 samples in the SDK.

Terminology

Term Description
ICD Installable Client Driver — A Vulkan-compatible display driver
GLSL OpenGL Shading Language
Layer A library designed to work as a plug-in for the loader. It usually serves to provide validation and debugging functionality to applications
Loader A library which implements the Vulkan API entry points and manages layers, extensions, and drivers. It can be found in the SDK as well as independent hardware vendor driver installs
SPIR‑V Standard Portable Intermediate Representation — A cross-API intermediate language that natively represents parallel compute and graphics programs
Vulkan A low overhead, explicit graphics API developed by the Khronos Group and member companies
WSI Window System Integration

System requirements

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

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

Other Linux distributions may work but have not been verified.

For other distributions of Linux, we recommend you search your distribution's package repository for Vulkan development libraries. Otherwise you may download and build from publicly available repositories.

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

Administrator privileges (for older SDKs)

Beginning with SDK version 1.0.13, the SDK installer no longer installs files to system locations that require administrator privileges. Administrator privileges are not required to install the SDK if you are installing version 1.0.13 or later and there are no pre-1.0.13 SDK versions installed on the system.

If you have a version of the SDK on your system that is prior to 1.0.13 and you install version 1.0.13 or later, you will need administrator privileges in order to uninstall the older SDK from your system.

Packages

Ubuntu distributions (16.04 and newer)

Upgrade your system to be current on package updates.

sudo apt-get update
sudo apt-get dist-upgrade

If you want to build and run the samples or develop other Vulkan applications, install the following prerequisite packages:

sudo apt-get install libglm-dev cmake libxcb-dri3-0 libxcb-present0 libpciaccess0 \
libpng-dev libxcb-keysyms1-dev libxcb-dri3-dev libx11-dev \
libmirclient-dev libwayland-dev libxrandr-dev libxcb-ewmh-dev

CMake 3.4.1 or newer is required for the SDK. Git and Python2 are required to build shaderc. This can be built with the included build_tools.sh script. Be sure python2 is in your PATH. (See Helper Build Scripts for more information.)

sudo apt-get install git libpython2.7

Fedora core distributions (25 and newer)

Update your system to be current on package updates.

sudo dnf update

If you want to build and run the samples or develop other Vulkan applications, install the following prerequisite packages:

sudo dnf install 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

Git and Python2 are required to build shaderc. This can be built with the included build_tools.sh script. Be sure python2 is in your PATH. (See Helper Build Scripts for more information.)

sudo dnf install git python

Download the SDK

Download the LunarG Vulkan SDK from Vulkan.LunarG.com. The SDK download file is named vulkansdk-linux-x86_64-1.1.xx.y.tar.gz. "xx" refers to the "patch level" of the Vulkan API. "y" refers to the LunarG SDK revision number for an SDK series for the Vulkan API version "1.1.xx".

SDK contents

The LunarG Vulkan SDK provides the development and runtime components to create, trace, and replay Vulkan applications. The SDK also includes the runtime components to run Vulkan Application Validation and Debug Layers.

Install the SDK

Note: Packaging of the Linux 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 file now simply expands the SDK into a directory of the form 1.1.xx.y.

The SDK installation process consists of extracting the tar file into a desired directory. This directory 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 zxf $HOME/Downloads/vulkansdk-linux-x86_64-1.1.xx.y.tar.gz

Tar file contents

The table below describes the filesystem unpacked from the SDK tar file, which appears under the top-level 1.1.xx.y 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/vulkan Header files required to compile and link your Vulkan application
x86_64/lib Vulkan loader library and layer runtime libraries
x86_64/etc/explicit_layer.d .json manifest files for Vulkan validation layers
config Sample layer settings file, system config instructions
doc Khronos SPIRV, Vulkan, Loader, and WSI specifications
examples Example Vulkan applications
samples Sample code from the Vulkan Samples Kit
source Source and debug libraries for glslang and selected Vulkan components

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 in one of the following locations:

Directory Description
/etc/vulkan/icd.d/ or /usr/share/vulkan/icd.d Vulkan driver .json manifest file, which is 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.

Uninstalling the SDK

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

rm -rf ~/vulkan/1.1.xx.y

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.1.xx.y/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/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.1.xx.y/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.1.xx.y/x86_64
export PATH=$VULKAN_SDK/bin:$PATH
export LD_LIBRARY_PATH=$VULKAN_SDK/lib:$LD_LIBRARY_PATH
export VK_LAYER_PATH=$VULKAN_SDK/etc/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.

Verify the installation

Verify the installation of the LunarG Vulkan SDK by running a few things:

  1. Run a demo Vulkan application such as Vulkan Info. (See the vulkaninfo page for more information)
  2. Run LunarG's Vulkan Installation Analyzer (VIA) to determine if it believes everything can execute properly.
    • The VIA executable vkvia does not come prebuilt in the Linux SDK. See Helper Build Scripts for the build_tools.sh script.
    • See the VIA page for more information.

Build and run the example applications

The LunarG Vulkan SDK includes the source for two example applications: Vulkan Info and Vulkan Cube. There are two versions of Vulkan Cube: one written in C using vulkan.h and another written in C++11 using vulkan.hpp. The vulkan.hpp header file is a low-level C++11 API for Vulkan.

To build and run the example applications, change your current directory to the top of the SDK directory, and:

cd $VULKAN_SDK/../examples
mkdir build
cd build
cmake ..
make

If you wish to make a debug build, use instead:

cmake -DCMAKE_BUILD_TYPE=Debug .. ; make

Look at the generated files with:

ls -l

and verify the executables named vkcube, vkcubepp, and vulkaninfo are present.

Notice the cube.vert.inc and cube.frag.inc files. These are SPIR-V shader binaries (in hexadecimal format) generated from GLSL shaders by the glslangValidator tool. The GLSL shader source code can be found in the examples directory in the files cube.vert and cube.frag. Refer to the SPIR-V Toolchain section for detailed information on glslangValidator.

Execute vkcube:

./vkcube

Press the window close button to exit the application.

Helper build scripts

The root SDK directory contains three helper scripts to aid building the examples, samples, and tools. The scripts are appropriately named: build_examples.sh, build_samples.sh, and build_tools.sh respectively. Be sure you have the necessary requirements (see Packages) for running these scripts.

After successfully running build_examples.sh or build_samples.sh, the binaries will be located under the 'build' directory in 'examples' or 'samples' folders. Be sure your environmental variables are set before running the example or sample binaries, see Set up the Runtime Environment.

Build SPIRV-Tools, SPIRV-Cross, and LunarG's Vulkan Installation Analyzer (VIA)

LunarG's Vulkan SDK includes a build_tools.sh script to build SPIRV-Tools, SPIRV-Cross, and LunarG's Vulkan Installation Analyzer (VIA). Once built the tools will automatically be placed in the $VULKAN_SDK/x86_64/bin directory. Be sure to have your environmental variables set, see how to Set up the Runtime Environment.

LunarG's VIA is a tool used to analyze your Vulkan installation. The VIA tool creates an HTML file that describes your system and setup for help with bug submissions on LunarXchange.

Trace and replay

The LunarG Vulkan SDK supports tracing and replaying Vulkan applications.

Refer to the Vulkan Trace and Replay Tools guide for detailed information on Vulkan trace and replay.

Before proceeding with the next steps, be sure you have sourced the setup-env.sh script, which will enable you to use the trace tools in the SDK bin directory.

Change your current directory to the examples/build directory you created when building the Vulkan Cube demo earlier in this guide.

Create a trace file for the Vulkan Cube program:

vktrace -p vkcube -o vkcube_trace.vktrace -a "--c 250"

The program will close on it's own after a few seconds. Do not stop the program by using ctrl+c as doing so may result in a corrupted trace file. Notice the trace options used in the command above.

-p, --Program <string> — name of the program to trace
-o, --OutputTrace <string> — path/name of the generated trace file
-a, --Arguments <string> — arguments to pass to the program

In this case we passed the --c 250 argument to Vulkan Cube, which tells it to exit after 250 frames

The generated trace file, vkcube_trace.vktrace, is written to the current directory.

ls -als vkcube_trace.vktrace

Replay the vkcube trace file you just generated.

vkreplay -o vkcube_trace.vktrace -l 2

Notice the options used in the vkreplay command above.

-o, --Open <string> — name of trace file to replay; [required]
-l, --NumLoops <uint> — number of times to replay the trace

The -l 2 option replays the trace twice.

Enable validation and utility layers

The LunarG Vulkan SDK includes runtime support for validation and utility layers. These layers can be explicitly enabled for an application run or trace replay by setting the VK_INSTANCE_LAYERS environment variable to a colon-separated list of layer or extension names as found in the layer manifest files. Refer to the Vulkan Validation and Utility Layers document for more information on layer manifest files.

The LunarG Vulkan SDK includes the following layers:

Layer Name Layer Type Description
VK_LAYER_LUNARG_api_dump utility print API calls and their parameters and values
VK_LAYER_LUNARG_core_validation validation print and validate the descriptor set, pipeline state, and dynamic state; validate the interfaces between SPIR-V modules and the graphics pipeline; track and validate GPU memory and its binding to objects and command buffers; validate texture formats and render target formats
VK_LAYER_LUNARG_device_simulation utility allows modification of an actual device's reported features, limits, and capabilities
VK_LAYER_LUNARG_monitor utility outputs the frames-per-second of the target application in the applications title bar
VK_LAYER_LUNARG_object_tracker validation track all Vulkan objects and flag invalid objects and object memory leaks
VK_LAYER_LUNARG_parameter_validation validation validate API parameter values
VK_LAYER_LUNARG_screenshot utility outputs specified frames to an image file as they are presented
VK_LAYER_GOOGLE_threading validation check validity of multi-threaded API usage
VK_LAYER_GOOGLE_unique_objects utility wrap all Vulkan objects in a unique pointer at create time and unwrap them at use time

In addition to these layers, there is a built-in meta-layer definition which will load a standard set of validation layers in the optimal order:

VK_LAYER_LUNARG_standard_validation

Loading this meta-layer definition is equivalent to specifying the following layers in this order:

VK_LAYER_GOOGLE_threading
VK_LAYER_LUNARG_parameter_validation
VK_LAYER_LUNARG_object_tracker
VK_LAYER_LUNARG_core_validation
VK_LAYER_GOOGLE_unique_objects

Refer to the Vulkan Validation and Utility Layers document for detailed information.

Enable other layers

The Vulkan SDK also contains layers other than the validation layers. One example is the API Dump layer which outputs a textual report of the Vulkan API calls and parameters.

The layers can be enabled either by using the graphical tool, Vulkan Configurator, or by setting environment variables. As an example, this section will show how to enable the API dump layer with Vulkan Configurator. The API dump layer will allow you to examine the Vulkan API calls from an application.

  1. If you haven't already, run the build_tools.sh script to build Vulkan Configurator. Your system must have Qt5 installed, specifically the development Qt5 Core, GUI, and Widgets packages.

  2. Execute vkconfig from the x86_64/bin directory.

  3. Check the "Use custom layer paths" box on the top left. Then click the "Search" button and navigate to the SDK in the popup window. Select the SDK's directory. A popup will ask you to confirm the layers that were found by the SDK. Click ok on this popup.

  4. Find the pane labeled "Disabled Explicit Layers". One of the layers in that pane should read "LunarG: Api Dump". Selected this layer by clicking on it.

  5. Click the left arrow directly to the left of the "Disabled Explicit Layers" pane. The API dump layer should now move to the "Enabled Layers" pane.

  6. Click the save button at the bottom left of the window.

  7. Run the Vulkan Cube program from a console:

    VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump ./vkcube
  8. Deactivate the layers you just enabled from Vulkan Configurator by clicking the "Clear" button at the bottom of the window.

The API dump layer output should appear on the screen as the application runs, showing the API calls and parameter values.

Debug an example application with gdb

LunarG's Vulkan SDK includes debug libraries and source code for the loader and layer providing a rudimentary gdb debug environment for Vulkan applications. The source code for these components is found in the source directory. Note: The code shown in the sample debugger session below may not exactly match the code you see in your session.

Component/Directory Name Description
layers layer source and generated code
lib debuggable shared libraries
loader loader source and generated code

Follow these steps to debug the Vulkan Cube example application built in a previous section. You should change back to the examples/build directory and make sure you have sourced the setup-env.sh script.

Make sure the Vulkan Cube program is built as a debuggable application:

cmake -DCMAKE_BUILD_TYPE=Debug ..
make

Start the gdb debugger, specifying the source directories included in the SDK:

gdb -d $VULKAN_SDK/../examples -d $VULKAN_SDK/../source/loader \
    -d $VULKAN_SDK/../source/layers ./vkcube

Set a breakpoint at the vkCreateDevice() function and begin execution. The debugger stops at the breakpoint in the loader.

Note: gdb may display a message saying the breakpoint needs to be deferred because it is being set in a shared library that is not yet loaded. If such a prompt appears, respond 'y' to continue.

(gdb) b vkCreateDevice
Breakpoint 1 at 0x402d40
(gdb) r
Starting program: /home/dev/sdk/1.1.70.1/examples/build/vkcube
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

Breakpoint 1, vkCreateDevice (physicalDevice=0x760210,
    pCreateInfo=0x7fffffffcef0, pAllocator=0x0, pDevice=0x7fffffffd108)
    at /tmp/SDK-DEV/Build/Vulkan-LoaderAndValidationLayers/loader/trampoline.c:753
753    struct loader_physical_device_tramp *phys_dev = NULL;

Examine the backtrace and source.

(gdb) bt
#0  vkCreateDevice (physicalDevice=0x760210, pCreateInfo=0x7fffffffcef0,
    pAllocator=0x0, pDevice=0x7fffffffd108)
    at /tmp/SDK-DEV/Build/Vulkan-LoaderAndValidationLayers/loader/trampoline.c:753
#1  0x000000000040c21c in demo_create_device (demo=0x7fffffffd090)
    at /home/dev/sdk/1.1.70.1/examples/cube.c:3297
#2  0x000000000040c53e in demo_init_vk_swapchain (demo=0x7fffffffd090)
    at /home/dev/sdk/1.1.70.1/examples/cube.c:3416
#3  0x000000000040d3e1 in main (argc=1, argv=0x7fffffffde98)
    at /home/dev/sdk/1.1.70.1/examples/cube.c:3930
(gdb) list
748 }
749
750 LOADER_EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateDevice(VkPhysicalDevice physicalDevice, const VkDeviceCreateInfo *pCreateInfo,
751                                                             const VkAllocationCallbacks *pAllocator, VkDevice *pDevice) {
752     VkResult res;
753     struct loader_physical_device_tramp *phys_dev = NULL;
754     struct loader_device *dev = NULL;
755     struct loader_instance *inst = NULL;
756
757     assert(pCreateInfo->queueCreateInfoCount >= 1);

This shows you are stopped in the loader at the vkCreateDevice() function.

Finish execution of the current stack frame and return to the caller, which is the Vulkan Cube program.

 (gdb) finish
Run till exit from #0  vkCreateDevice (physicalDevice=0x760210,
    pCreateInfo=0x7fffffffcef0, pAllocator=0x0, pDevice=0x7fffffffd108)
    at /tmp/SDK-DEV/Build/Vulkan-LoaderAndValidationLayers/loader/trampoline.c:753
0x000000000040c21c in demo_create_device (demo=0x7fffffffd090)
    at /home/dev/sdk/1.1.70.1/examples/cube.c:3297
3297     err = vkCreateDevice(demo->gpu, &device, NULL, &demo->device);
Value returned is $1 = VK_SUCCESS
(gdb) list
3292         queues[1].queueCount = 1;
3293         queues[1].pQueuePriorities = queue_priorities;
3294         queues[1].flags = 0;
3295         device.queueCreateInfoCount = 2;
3296     }
3297     err = vkCreateDevice(demo->gpu, &device, NULL, &demo->device);
3298     assert(!err);
3299 }
3300
3301 static void demo_init_vk_swapchain(struct demo *demo) {

This shows the call to vkCreateDevice() was successful and displays the next few lines of the Vulkan Cube program.

To continue execution:

(gdb) c

Exit the debugger (press CTRL-C to return to the gdb prompt) and enter "q" to quit.

Examine Vulkan sample code

The LunarG Vulkan SDK includes the Vulkan Samples Kit. This set of Vulkan code Samples is a work in progress. Refer to the Vulkan Samples Kit guide for information about building and running the sample programs.

Contact LunarG if you are interested in contributing to this effort.

Using Vulkan in CMake projects

CMake is a convenient way to set up build files (e.g., Makefiles) for Vulkan applications.

CMake versions 3.7 and later ship with a FindVulkan.cmake module that uses the VULKAN_SDK environment variable to locate the Vulkan include files and libraries needed for building Vulkan applications. The FindVulkan.cmake module is also able to locate these components if they are installed in system directories. This module makes it easy to add the Vulkan support files to your application. For example, this CMakeLists.txt file can be used to build the Vulkan Info application:

cmake_minimum_required(VERSION 3.7)
project(vulkaninfo)
find_package(Vulkan REQUIRED)
add_executable(vulkaninfo vulkaninfo.c)
target_link_libraries(vulkaninfo Vulkan::Vulkan)

Create a CMakeLists.txt file with the above contents and copy vulkaninfo.c from the SDK into the same location as the CMakeLists.txt file.

Generate the build files for the project:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..

Now you can build the application with:

make

Or you can build the application with:

cmake --build .

When using versions of CMake prior to 3.7, the FindVulkan.cmake module can be downloaded from the CMake GitHub site.

Put this newer version in the same directory as CMakeLists.txt and add the following line to CMakeLists.txt after the project statement:

set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}" ${CMAKE_MODULE_PATH})

You'll also have to change the cmake_minimum_required version to suit your CMake version.

Next steps

This guide provides an introduction to the main components and tools in LunarG's Vulkan SDK. Refer to Vulkan.LunarG.com for the most up to date SDK information, including the complete set of SDK documentation.