Build Guides

Contents

• CMake Options
  • [VKB_](#vkb_sample_name)
  • VKB_BUILD_SAMPLES
  • VKB_BUILD_TESTS
  • VKB_VALIDATION_LAYERS
    • VKB_VALIDATION_LAYERS_GPU_ASSISTED
    • VKB_WARNINGS_AS_ERRORS
  • VKB_VULKAN_DEBUG
  • VKB_WARNINGS_AS_ERRORS
• Quality Assurance
• 3D models
• Performance data
• Windows
  • Dependencies
  • Clang Format and Visual Studio
  • Build with CMake
• Linux
  • Dependencies
  • Build with CMake
• macOS
  • Dependencies
  • Build with CMake
• Android
  • Dependencies
  • Build with Gradle

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

• Doxygen Doxygen Repository
• Clang Format / Clang Tidy Clang Tools Repository
• Snake Case Check Snake Case Check Repository
• Android NDK Android NDK Repository

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

• CMake v3.12+
• Python 3
• Visual Studio 2017 or above
• CMake Options
• 3D models

Clang Format and Visual Studio

Visual Studio comes with clang-format-6 which is incompatible with some of the styles we use in our .clang-format file. It is recommended to point to a clang-format-8.exe binary within the in-built clang formatter, or disable it and use a third party extension that is more up to date.

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" -H. -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

• CMake v3.12+
• C++14 Compiler
• CMake Options
• 3D models

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" -H. -Bbuild/linux -DCMAKE_BUILD_TYPE=Release

Step 2. Build the project

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

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

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

Use the provided script for the platform you are building on by running the following command:

Windows

bldsys\scripts\generate_android_gradle.bat

Linux

./bldsys/scripts/generate_android_gradle.sh

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/camke/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.