Build Guides

CMake Options

The following options are used to change the build configuration

VKB_

Choose whether to include a sample at build time.

  • ON - Build Sample

  • OFF - Exclude Sample

Default: ON

VKB_BUILD_SAMPLES

Choose whether to build the samples.

  • ON - Build All Samples

  • OFF - Skip building Samples

Default: ON

VKB_BUILD_TESTS

Choose whether to build the tests

  • ON - Build All Tests

  • OFF - Skip building Tests

Default: OFF

VKB_VALIDATION_LAYERS

Enable Validation Layers

Default: OFF

VKB_VALIDATION_LAYERS_GPU_ASSISTED

Enable GPU assisted validation layers, used primarily for VK_EXT_descriptor_indexing.

Default: OFF

VKB_VALIDATION_LAYERS_BEST_PRACTICES

Enable best practices validation layers.

Default: OFF

VKB_VALIDATION_LAYERS_SYNCHRONIZATION

Enable synchronization validation layers.

Default: OFF

VKB_VULKAN_DEBUG

Enable VK_EXT_debug_utils or VK_EXT_debug_marker, if supported. This enables debug names for Vulkan objects, and markers/labels in command buffers. + See the debug utils sample for more information.

Default: ON

VKB_WARNINGS_AS_ERRORS

Treat all warnings as errors

Default: ON

Quality Assurance

We use a small set of tools to provide a level of quality to the project. These tools are part of our CI/CD process. If your local environment does not have the same versions of the tools we use in the CI you may see some errors or warnings pop-up when pushing.

For up-to date version information please see the repositories for the individual tools

3D models

Most of the samples require 3D models downloaded from https://github.com/KhronosGroup/Vulkan-Samples-Assets. That repository is referenced as a git submodule by this project so if you followed the clone instructions in the project readme you will already have the models locally under ./assets/.

On Android, Gradle will run CMake which will sync assets to the device if there has been a change.

However, to sync them manually you may run the following command to ensure up to date assets are on the device:

adb push --sync assets /sdcard/Android/data/com.khronos.vulkan_samples/files/
adb push --sync shaders /sdcard/Android/data/com.khronos.vulkan_samples/files/

Performance data

In order for performance data to be displayed, profiling needs to be enabled on the device. Some devices may disable it by default.

Profiling can be enabled via adb:

adb shell setprop security.perf_harden 0

Performance data is captured using HWCPipe. For details on this project and how to integrate it in your pipeline, visit: https://github.com/ARM-software/HWCPipe

Windows

Dependencies

Clang Format and Visual Studio

It is recommended to use clang-format-15, which is compatible with the styles in our .clang-format file. It is also used by CI and is a basic version installed with Visual Studio 2022. The minimum version that supports our current .clang-format file is clang-format-9.

Go to the LLVM downloads page to get clang.

Build with CMake

Please make sure, when running any sample, that you either:

  • Enable Developer Mode

  • Run Command Prompt or Visual Studio as administrator

Step 1. The following command will generate the VS project

cmake -G"Visual Studio 15 2017 Win64" -S . -Bbuild/windows

(Prior to CMake v3.13)

cmake -G"Visual Studio 15 2017 Win64" . -Bbuild/windows

(New in CMake v3.14. Visual Studio 2019 must be installed)

 cmake -G "Visual Studio 16 2019" -A x64 -S . -Bbuild/windows

(New in CMake v3.21. Visual Studio 2022 must be installed)

 cmake -G "Visual Studio 17 2022" -A x64 -S . -Bbuild/windows

Step 2. Build the Visual Studio project

cmake --build build/windows --config Release --target vulkan_samples

Step 3. Run the Vulkan Samples application

build\windows\app\bin\Release\AMD64\vulkan_samples.exe

Linux

Dependencies

sudo apt-get install cmake g++ xorg-dev libglu1-mesa-dev

Build with CMake

Step 1. The following command will generate the project

cmake -G "Unix Makefiles" -Bbuild/linux -DCMAKE_BUILD_TYPE=Release

Step 2. Build the project

cmake --build build/linux --config Release --target vulkan_samples -j$(nproc)

Step 3. Run the Vulkan Samples application to display the help message

./build/linux/app/bin/Release/x86_64/vulkan_samples --help

macOS

Dependencies

  • CMake v3.12+ (Apple Silicon requires at least 3.19.2)

  • XCode v12 for Apple Silicon

  • Command Line Tools (CLT) for Xcode xcode-select --install

  • Vulkan SDK ./install_vulkan.py

  • CMake Options

  • 3D models

Build with CMake

Step 1. The following command will generate the project

cmake -Bbuild/mac -DCMAKE_BUILD_TYPE=Release

Step 2. Build the project

cmake --build build/mac --config Release --target vulkan_samples -j4

Step 3. Run the Vulkan Samples application to display the help message

./build/mac/app/bin/Release/x86_64/vulkan_samples --help

iOS

Dependencies

  • CMake v3.28+ (Apple xcframeworks require at least 3.28)

  • XCode v12 for Apple Silicon

  • Command Line Tools (CLT) for Xcode xcode-select --install

  • Vulkan SDK ./install_vulkan.py

  • Vulkan at least version 1.3.278 to get the frameworks

  • CMake Options

  • 3D models

Set your environment variable

Step 1. edit ~/.bash_profile Step 2. add the environment variable

export VULKAN_SDK=/PATH/TO/VULKAN/SDK

Step 3. reload the bash_profile

source ~/.bash_profile

Build with CMake

Step 1. The following command will generate the project

cmake -Bbuild/mac -DCMAKE_BUILD_TYPE=Release -G Xcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_DEPLOYMENT_TARGET=13.0 -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=YES -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_IOS_INSTALL_COMBINED=NO -DCMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM="XXXX"

NB: You MUST change the XXXX in the above to your TeamID for code signing. iOS will Not allow the application to run without code signing setup.

Step 2. Build the project

cmake --build build/mac --config Release --target vulkan_samples -- -j 6 -sdk iphoneos -allowProvisioningUpdates

It’s recommended to open the XCode project that is generated inside build/mac; building can be handled with command-B.

Step 3. Run the Vulkan Samples application

To run Vulkan Samples, one must have an iOS device provisioned and working with XCode. Open the XCode project and ensure that can build/install to a device through XCode normally. Once the bundle is created from the build command in Step 2, use the edit-scheme selection in XCode and set the arguments to have --help Click the "Play" button and you should see the help output in the terminal. For convenience, the default setting is to run the hello_triangle sample; just edit that to your desired sample to run

Android

Dependencies

For all dependencies set the following environment variables:

  • JDK 8+ JAVA_HOME=<SYSTEM_DIR>/java

  • Android SDK ANDROID_HOME=<WORK_DIR>/android-sdk

  • CMake v3.16+

  • Android NDK r23+ ANDROID_NDK_HOME=<WORK_DIR>/android-ndk

  • CMake Options

  • 3D models

  • Performance data

We use this environment in the CI Android NDK Repository

It is highly recommended to install Android Studio to build, run and trace the sample project. Android Studio uses the following plugins/tools to build samples:

  • Android Gradle Plugin

  • CMake Plugin, which installs and uses Ninja

  • NDK

Their versions are configured in the build.gradle.in and app.build.gradle.in files; when updating these versions, refer to the official documentation for the recommended combinations.

Build with Gradle

Generate the gradle project

To generate the gradle project, run the following command:

./scripts/generate.py android

A new folder will be created in the root directory at build\android_gradle

Install dependencies

Android Gradle Plugin (used by Android Studio) may not auto install dependencies. You will need to install them if they have not been installed:

  • Find the configured versions in build/android_gradle/app/build.gradle, or its template file bldsys/cmake/template/gradle/app.build.gradle.in

  • Install them with Android Studio or sdkmanager command line tool. For example, to install AGP port CMake 3.22.1 and NDK version 25.1.8937393 on Linux, do the following:

     yes | ${your-sdk}/cmdline-tools/latest/bin/sdkmanager --licenses
 ${your-sdk}/cmdline-tools/latest/bin/sdkmanager --install "ndk;25.1.8937393" --channel=3
 ${your-sdk}/cmdline-tools/latest/bin/sdkmanager --install "cmake;3.22.1" --channel=3

Build the project

cd build/android_gradle

Prefer a release build for better performance unless you want to actively debug the application.

For a release build:

gradle assembleRelease

For a debug build:

gradle assembleDebug

Install the apk on the device

You can now install the apk on a connected device using the Android Debug Bridge:

For a release build:

adb install app/build/outputs/apk/release/vulkan_samples-release.apk

For a debug build:

adb install app/build/outputs/apk/debug/vulkan_samples-debug.apk

Build with Android Studio

With Android Studio you can open the build/android_gradle/build.gradle project, compile and run the project from here. The lastest Android Studio release is recommended.

If you have agreed with the licenses previously on your development system, Android Studio will automatically install, at the start up time, CMake and NDK with the version configured in your build/android-gradle/build.gradle. Otherwise (or if the installation failed), you need to install the required CMake and NDK manually, refer to the official instructions for the detailed steps. The default installed locations are:

  • $SDK-ROOT-DIR/ndk/$ndkVersion for NDK.

  • $SDK-ROOT-DIR/cmake/$cmake-version for CMake.

Android Studio will use the above default locations without any environment variable requirement; if you want to use the same NDK and CMake versions for other purpose, you can simply configure your environment variables to these locations. If you do set up the NDK and CMake environment variables, Android Studio will use them instead of the default locations.