# Getting Started with the Vulkan SDK

#### Version for Linux

Copyright © 2015-2018 LunarG, Inc.

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 that 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 that this version number does not indicate that 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 that 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
--- | ---
DRI3 | Direct Rendering Infrastructure 3 — A Linux X-Windows extension for direct rendering
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:

- Ubuntu 14.04 and 16.04
- Fedora Core (25 and newer)
- Arch Linux

Other Linux distributions may work but have not been verified.

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

- Loader and layers source: https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers
- Tools source: https://github.com/LunarG/VulkanTools
- Samples source: https://github.com/LunarG/VulkanSamples

You will find instructions to build all three in their respective repositories.

### Administrator Privileges

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 SDK versions installed on the system that are prior to 1.0.13.

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 (14.04 and newer)

Upgrade your system to be current on package updates.

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

If all you want to do is install the SDK to look at the documentation, install the following packages and skip ahead to the "Download the SDK" section in this guide.

    sudo apt-get install graphviz

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 graphviz libxcb-dri3-0 libxcb-present0 libpciaccess0 cmake \
    libpng-dev libxcb-keysyms1-dev libxcb-dri3-dev libx11-dev libmirclient-dev libwayland-dev libxrandr-dev

CMake 3.2 or newer is required for the SDK. Ubuntu 14.04 will not install this version by default, so additional steps may be needed to install CMake 3.2. In addition, git and Python2 is 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 all you want to do is install the SDK to look at the documentation, install the following packages and skip ahead to the "Download the SDK" section in this guide.

    sudo dnf install graphviz

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

    sudo dnf install glm-devel graphviz cmake libpng-devel wayland-devel libpciaccess-devel \
    libX11-devel libXpresent libxcb xcb-util libxcb-devel libXrandr-devel \
    xcb-util-keysyms-devel.x86_64

Git and Python2 is 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-``version``.run`.

Make note of the directory to which the file was downloaded. The rest of these instructions assume that you have downloaded the file to `$HOME/Downloads`.

## 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

The SDK installation process installs the software into a local directory. This directory can be placed anywhere on your system.

The LunarG Vulkan SDK for Linux is a self-extracting installer. The installer will create a local SDK directory of the form `VulkanSDK/<``version``>` in the current working directory. Starting with version 1.0.13.0, the installer will no longer copy the Vulkan development and runtime headers, libraries, and binaries to system locations. You must correctly configure the environment variables `LD_LIBRARY_PATH` and `VK_LAYER_PATH` (see below). This is so Vulkan applications can find the loader and layers in your local SDK directory.

1. Create a work directory. These instructions assume that you want to install the SDK under a folder called `vulkan` in your home directory.

       cd ~
       mkdir vulkan
       cd vulkan

2. Copy the self-extracting installer to your work directory. You may need to change the installer file permissions to include execute. In the following commands, replace `<``version``>` with the `1.0.xx.y` version number of the SDK.

       cp $HOME/Downloads/vulkansdk-linux-x86_64-<version>.run ./
       chmod ugo+x vulkansdk-linux-x86_64-<version>.run

3. Run the self-extracting installer. You may also be prompted for your sudo password for removal of a previously installed version of the `vulkan-sdk-runtime`.

       ./vulkansdk-linux-x86_64-<version>.run
       Creating directory VulkanSDK
       Verifying archive integrity... All good.
       Uncompressing LunarG Vulkan SDK  100%

### Local Install Locations

The table below identifies specific SDK local install directories and their content. The local install location refers to the place where you installed the SDK, usually under the `VulkanSDK/<``version``>` folder created by the self-extracting installer. 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 Locations

Starting with version 1.0.13.0, the installer will no longer copy the Vulkan development and runtime headers, libraries, and binaries to system locations. Since these files are not installed to the default system search locations, you must configure the environment variables `LD_LIBRARY_PATH` and `VK_LAYER_PATH` (see below) in order for Vulkan applications to locate the loader and layer modules. If you have installed a Vulkan driver from a GPU vendor, you may wish to verify that there is a JSON file 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 Common Loader guide, Linux section, for detailed information on ICD and layer library search paths and order for this platform.

## Uninstalling the SDK

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

    rm -rf /path/to/VulkanSDK/<version>

## Set up the Runtime Environment

Because you installed the Vulkan SDK in a location of your choice, you need to set environment variables to help 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 (`x86_64` for example). 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 root directory of your SDK installation to help you easily set these environment variables. If you have installed the SDK in your `~/vulkan` directory as described above, execute the setup script at a shell prompt:

    source ~/vulkan/VulkanSDK/1.0.xx.0/setup-env.sh

Of course, you should replace 'xx' with the actual SDK version number.

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

    export VULKAN_SDK=~/vulkan/VulkanSDK/1.0.xx.0/x86_64

again replacing the 'xx' with the version you are installing.

and then:

    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 running the above setup script or shell export commands set the environment variables only 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 LunarG's Vulkan Installation Analyzer (VIA) to determine if it believes everything can execute properly.

- `via` does not come prebuilt in the Linux SDK, and requires building tools first before you can use it
  - See Helper Build Scripts for useful scripts to build the required dependencies
- More information on VIA can be found here

2. Run a demo Vulkan application like `vulkaninfo`. (See the Vulkan Info webpage for more information about the `vulkaninfo` application and how to use it.)

## Build and Run the Example Applications

The LunarG Vulkan SDK includes the source for two example applications: `vulkaninfo` and `cube`. There are two versions of the cube example: 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:

1. Configure the example application build system for a release build and a debug build.

       cd examples
       cmake -H. -Bbuild
       cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug

2. Compile the example applications for both release and debug build environments.

       make -C build
       make -C dbuild

3. Verify the build artifacts.

       ls -l build dbuild

   `cube`, `cubepp`, and `vulkaninfo` executables should exist in both directories.

   Notice the `cube-vert.spv` and `cube-frag.spv` files. These are SPIR-V form shaders generated from GLSL shaders by the `glslangValidator` tool. Refer to the SPIR-V Toolchain section for detailed information on `glslangValidator`.

4. Run the cube program. Press the window close button to exit the application.

       cd build
       ./cube

## 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 that you have the necessary requirements (see Packages) for running these scripts.

After successfully running `build_examples.sh` or `build_samples`, 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. See Build SPIRV-Tools, SPIRV-Cross, and VIA for more information on `build_tools.sh`.

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

Refer to SPIR-V Toolchain for more information on SPIRV-Tools. 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, see VIA.

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

1. Trace the `cube` example program. Press the window close button to exit the application when you want to stop tracing.

       vktrace -p cube -o cube_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` arguments to cube, which tells it to exit after 250 frames

2. The generated trace file, `cube_trace.vktrace`, is written to the current directory.

       ls -als cube_trace.vktrace

3. Replay the cube trace file you just generated.

       vkreplay -o cube_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 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.

You can explicitly activate the `VK_LAYER_LUNARG_api_dump` layer by setting the layer environment variables as described below. This example activates the API dump layer while running the `cube` application that you built in the previous section:

    VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump ./cube

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 that the code shown in the sample debugger output 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 `cube` example application built in a previous section.

1. Identify the location of the Vulkan application and framework source code to `gdb` by creating or adding to `$HOME/.gdbinit`. Include the following lines. (Substitute the complete path name to the SDK local install `source` directory for `$SOURCEDIR`. )

       directory $SOURCEDIR/layers
       directory $SOURCEDIR/loader
       directory $SOURCEDIR/../examples

2. Set up the Vulkan debug environment to use the debug shared libraries.

       export LD_LIBRARY_PATH=$SOURCEDIR/lib:$LD_LIBRARY_PATH
       export VK_LAYER_PATH=$VULKAN_SDK/etc/explicit_layer.d

3. Initiate debugging the `cube` example application from the debug build executable.

       cd $SOURCEDIR/../examples/dbuild
       gdb ./cube

4. 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 that 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 0x4028d0
       (gdb) r
       Starting program: /home/dev/1.0.13.0/examples/dbuild/cube
       [Thread debugging using libthread_db enabled]
       Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

       Breakpoint 1, vkCreateDevice (physicalDevice=0x63e5d0, pCreateInfo=0x7fffffffcf20, pAllocator=0x0,
           pDevice=0x7fffffffd140)
           at /home/lunarg/Development/LinuxSDK/Vulkan-LoaderAndValidationLayers/loader/trampoline.c:655
       655       assert(pCreateInfo->queueCreateInfoCount >= 1);

5. Examine the backtrace and source.

       (gdb) bt
       #0  vkCreateDevice (physicalDevice=0x63e5d0, pCreateInfo=0x7fffffffcf20, pAllocator=0x0, pDevice=0x7fffffffd140)
           at /home/lunarg/Development/LinuxSDK/Vulkan-LoaderAndValidationLayers/loader/trampoline.c:655
       #1  0x0000000000407faa in demo_init_device (demo=0x7fffffffd100) at /home/dev/1.0.13.0/examples/cube.c:2205
       #2  0x000000000040820a in demo_init_vk_swapchain (demo=0x7fffffffd100) at /home/dev/1.0.13.0/examples/cube.c:2299
       #3  0x0000000000408f79 in main (argc=1, argv=0x7fffffffde58) at /home/dev/1.0.13.0/examples/cube.c:2668
       (gdb) list
       650       VkResult res;
       651       struct loader_physical_device_tramp *phys_dev;
       652       struct loader_device *dev;
       653       struct loader_instance *inst;
       654
       655       assert(pCreateInfo->queueCreateInfoCount >= 1);
       656
       657       loader_platform_thread_lock_mutex(&loader_lock);
       658
       659       phys_dev = (struct loader_physical_device_tramp *)physicalDevice;

6. Step through a few lines and then resume execution.

       (gdb) n
       657       loader_platform_thread_lock_mutex(&loader_lock);
       (gdb) n
       659       phys_dev = (struct loader_physical_device_tramp *)physicalDevice;
       (gdb) n
       660       inst = (struct loader_instance *)phys_dev->this_instance;
       (gdb) n
       664       if (!loader_init_generic_list(inst, (struct loader_generic_list *)&icd_exts,
       (gdb) c
       Continuing.

7. Exit the debugger (press CTRL-C to return to the gdb prompt).

       (gdb) q

## 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 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 generating build files. 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 `vulkaninfo` application.

    cmake_minimum_required(VERSION 3.7 FATAL_ERROR)
    project(vulkaninfo)
    find_package(Vulkan)
    add_executable(vulkaninfo vulkaninfo.c)
    target_include_directories(vulkaninfo PRIVATE Vulkan::Vulkan)
    target_link_libraries(vulkaninfo Vulkan::Vulkan)

Copy `vulkaninfo.c` from the SDK into the same location as the `CMakeLists.txt` file.

When using versions of CMake prior to 3.7, the `FindVulkan.cmake` module can be downloaded from the CMake GitHub site. Add the location of the downloaded module with a command like this one:

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

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