Skip to content

Latest commit

 

History

History
341 lines (232 loc) · 9.09 KB

build.md

File metadata and controls

341 lines (232 loc) · 9.09 KB
Raw

Build Guides

Contents

CMake Options

The following options are used to change the build configuration

VKB_<sample_name>

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

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

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

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.10+ (known to work with 3.10.2; 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.

  • CMake v3.10+
  • JDK 8+ JAVA_HOME=<SYSTEM_DIR>/java
  • Android NDK r18+ ANDROID_NDK_ROOT=<WORK_DIR>/android-ndk
  • Android SDK ANDROID_HOME=<WORK_DIR>/android-sdk
  • Gradle 5+ GRADLE_HOME=<WORK_DIR>/gradle
  • CMake Options
  • 3D models
  • Performance data

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

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 build/outputs/apk/release/vulkan_samples-release.apk

For a debug build:

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

Build with Android Studio

Alternatively, you may import the build/android_gradle folder in Android Studio and run the project from here

If you are using a newer version of cmake then 3.13, you might get this error:

Execution failed for task ':externalNativeBuildDebug'. Expected output file at <PATH> for target <sample> but there was none

In this case, update the version of the gradle plugin in "bldsys/cmake/template/gradle/build.gradle.in" to 3.5.0, remove the content of build folder and repeat the build process from Step 1. This is known to work with Gradle 6.3 and NDK 20.0.55

If you are using Android Studio, you can simply do these changes after importing the build/android_gradle folder, opening File->Project Structure, and doing the following changes: On the Project tab, change the Android Gradle Plugin version to 3.5.0 and the Gradle version to 6.3.(this also requires NDK 20.0.55)