构建指南

CMake 选项

以下选项用于更改构建配置

VKB_

选择是否在构建时包含示例。

  • ON - 构建示例

  • OFF - 排除示例

默认： ON

VKB_BUILD_SAMPLES

选择是否构建示例。

  • ON - 构建所有示例

  • OFF - 跳过构建示例

默认： ON

VKB_BUILD_TESTS

选择是否构建测试

  • ON - 构建所有测试

  • OFF - 跳过构建测试

默认： OFF

VKB_VALIDATION_LAYERS

启用验证层

默认： OFF

VKB_VALIDATION_LAYERS_GPU_ASSISTED

启用 GPU 辅助验证层，主要用于 VK_EXT_descriptor_indexing。

默认： OFF

VKB_VALIDATION_LAYERS_BEST_PRACTICES

启用 最佳实践验证层。

默认： OFF

VKB_VALIDATION_LAYERS_SYNCHRONIZATION

启用 同步验证层。

默认： OFF

VKB_VULKAN_DEBUG

启用 VK_EXT_debug_utils 或 VK_EXT_debug_marker（如果支持）。这将启用 Vulkan 对象的调试名称，以及命令缓冲区中的标记/标签。+ 有关更多信息，请参阅调试实用程序示例。

默认： ON

VKB_WARNINGS_AS_ERRORS

将所有警告视为错误

默认： ON

VKB_PROFILING

使用 Tracy 分析器启用性能分析。

如果您没有使用正确的 Tracy 分析器版本作为示例中使用的 Tracy 客户端版本，我们目前使用 Tracy v0.10.0，您将收到协议不匹配错误。

Windows 用户可以从 Tracy v0.10.0 发布页面下载分析器。其他平台需要用户从源代码构建分析器，有关如何为您的平台构建的更多信息，请参阅 Tracy 文档 (pdf)。

Tracy 目前未为 Android 构建启用。未来，我们可能会添加对此的支持。

默认： OFF

质量保证

我们使用一小组工具为项目提供一定程度的质量保证。这些工具是我们 CI/CD 流程的一部分。如果您的本地环境没有与我们在 CI 中使用的工具相同的版本，则在推送时可能会看到一些错误或警告弹出。

有关最新的版本信息，请参阅各个工具的存储库

3D 模型

大多数示例都需要从 https://github.com/KhronosGroup/Vulkan-Samples-Assets 下载的 3D 模型。该存储库被此项目引用为 git 子模块，因此如果您按照项目自述文件中的克隆说明进行操作，则您已经将模型本地存储在 ./assets/ 下。

在 Android 上，Gradle 将运行 CMake，如果发生更改，CMake 会将资产同步到设备。

但是，要手动同步它们，您可以运行以下命令以确保设备上的资源是最新的

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

性能数据

为了显示性能数据，需要在设备上启用性能分析。某些设备可能默认禁用此功能。

可以通过 adb 启用性能分析

adb shell setprop security.perf_harden 0

性能数据是使用 HWCPipe 捕获的。有关此项目以及如何将其集成到您的管道中的详细信息，请访问：https://github.com/ARM-software/HWCPipe

Windows

依赖项

Clang Format 和 Visual Studio

建议使用 clang-format-15，它与我们的 .clang-format 文件中的样式兼容。它也被 CI 使用，并且是 Visual Studio 2022 中安装的基本版本。

请转到 LLVM 下载页面获取 clang。

使用 CMake 和 Visual Studio 构建

请确保在运行任何示例时，您要么

  • 启用开发者模式

  • 以管理员身份运行命令提示符或 Visual Studio

步骤 1. 以下命令将生成 VS 项目

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

（在 CMake v3.13 之前）

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

（CMake v3.14 中的新增功能。必须安装 Visual Studio 2019）

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

（CMake v3.21 中的新增功能。必须安装 Visual Studio 2022）

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

在 build/windows 中打开 vulkan_samples.sln VS 项目，并使用 Ctrl-Shift-B 进行构建。要运行 Vulkan 示例，请使用 Visual Studio 的“调试属性”选择，并将“调试命令参数”设置为 --help。单击“本地 Windows 调试器”按钮，您应该会在终端中看到帮助输出。为了方便起见，默认设置是运行 hello_triangle 示例；只需将其编辑为您想要运行的示例即可。

或者，对于命令行构建，请使用以下步骤

步骤 2. 构建 Visual Studio 项目

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

步骤 3. 运行 Vulkan Samples 应用程序

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

Linux

依赖项

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

使用 CMake 构建

步骤 1. 以下命令将生成项目

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

步骤 2. 构建项目

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

步骤 3. 运行 Vulkan Samples 应用程序以显示帮助消息

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

macOS

依赖项

  • CMake v3.12+（Apple Silicon 至少需要 3.19.2）

  • 适用于 Apple Silicon 的 Xcode v12

  • 适用于 Xcode 的命令行工具 (CLT) xcode-select --install

  • Vulkan SDK - 下载并安装具有默认选项的 Vulkan SDK

  • CMake 选项

  • 3D 模型

设置您的环境变量

source /PATH/TO/VULKAN/SDK/setup-env.sh

使用 CMake 和 Xcode 构建

步骤 1. 以下命令将生成项目

cmake -G Xcode -Bbuild/mac-xcode -DCMAKE_BUILD_TYPE=Release

在 build/mac-xcode 中打开 vulkan_samples Xcode 项目，并使用 command-B 进行构建。要运行 Vulkan 示例，请使用 Xcode 的“编辑方案”选择，并将参数设置为 --help。单击“播放”按钮，您应该会在终端中看到帮助输出。为了方便起见，默认设置是运行 hello_triangle 示例；只需将其编辑为您想要运行的示例即可。

或者，对于命令行构建，请使用以下步骤

cmake -Bbuild/mac -DCMAKE_BUILD_TYPE=Release

步骤 2. 构建项目

cmake --build build/mac --config Release --target vulkan_samples -j$(sysctl -n hw.ncpu)

步骤 3. 运行 Vulkan Samples 应用程序以显示帮助消息

./build/mac/app/bin/Release/<arm64|x86_64>/vulkan_samples --help

iOS

依赖项

  • CMake v3.28+（Apple xcframeworks 至少需要 3.28）

  • 适用于 Apple Silicon 的 Xcode v12

  • 适用于 Xcode 的命令行工具 (CLT) xcode-select --install

  • Vulkan SDK - 下载并安装 Vulkan SDK，确保选中“适用于 iOS 的开发库”

  • 至少需要 1.3.278 版本的 Vulkan 才能获取框架

  • CMake 选项

  • 3D 模型

设置您的环境变量

注意：对于 iOS，您必须运行位于 Vulkan SDK 的 iOS 目录中的 setup-env.sh

source /PATH/TO/VULKAN/SDK/iOS/setup-env.sh

使用 CMake 和 Xcode 构建

步骤 1. 以下命令将生成项目

cmake -G Xcode -Bbuild/ios -DCMAKE_BUILD_TYPE=Release -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" -DMACOSX_BUNDLE_GUI_IDENTIFIER="com.YYYY.vulkansamples"

注意：您必须将上面的 XXXX 更改为您的 TeamID（或您的 Apple 开发证书中的组织单位标识符）以进行代码签名，并将 YYYY 更改为您的捆绑包标识符。如果没有代码签名和捆绑包标识符设置，iOS 将不允许应用程序运行。

或者，您可以为 iOS 模拟器构建，而无需代码签名或指定捆绑包标识符（将使用默认捆绑包 ID）。但是，根据您的主机架构，您必须在下面的命令中选择 arm64（Apple Silicon）或 x86_64

cmake -G Xcode -Bbuild/ios-sim -DCMAKE_BUILD_TYPE=Release -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_DEPLOYMENT_TARGET=13.0 -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=YES -DCMAKE_OSX_ARCHITECTURES=<arm64|x86_64> -DCMAKE_IOS_INSTALL_COMBINED=NO

步骤 2. 构建项目

建议打开 build/ios 或 build/ios-sim 中生成的 vulkan_samples Xcode 项目，并使用 command-B 进行构建。

或者，您可以使用此处所示的 cmake 进行构建

cmake --build build/ios --config Release --target vulkan_samples -j$(sysctl -n hw.ncpu) -- -sdk iphoneos -allowProvisioningUpdates

步骤 3. 运行 Vulkan Samples 应用程序

要运行 Vulkan 示例，必须配置一个 iOS 物理或模拟器设备，并使其与 Xcode 一起工作。打开 Xcode 项目，并确保可以正常通过 Xcode 构建/安装到设备。一旦从步骤 2 中的构建命令创建了捆绑包，请使用 Xcode 中的“编辑方案”选择，并将参数设置为 --help。单击“播放”按钮，您应该会在终端中看到帮助输出。为了方便起见，默认设置是运行 hello_triangle 示例；只需将其编辑为您想要运行的示例即可。

Android

依赖项

对于所有依赖项，请设置以下环境变量

  • 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 选项

  • 3D 模型

  • 性能数据

我们在 CI 中使用此环境 Android NDK 存储库

Android Studio（推荐）

强烈建议安装 Android Studio 来构建、运行和跟踪示例项目。通过 Android Studio 构建至少需要 Ladybug 2024.2.1。

Android Studio 使用以下插件/工具来构建示例

  • Android Gradle 插件

  • CMake 插件，它安装并使用 Ninja

  • NDK

它们的版本在 build.gradle.in 和 app.build.gradle.in 文件中配置；更新这些版本时，请参考 官方文档以获取推荐的组合。

使用 Gradle 构建

生成 gradle 项目

要生成 gradle 项目，请运行以下命令

./scripts/generate.py android

将在根目录的 build\android_gradle 中创建一个新文件夹

安装依赖项

Android Gradle 插件（由 Android Studio 使用）可能不会自动安装依赖项。如果尚未安装，您将需要安装它们

  • 在 build/android_gradle/app/build.gradle 或其模板文件 bldsys/cmake/template/gradle/app.build.gradle.in 中查找已配置的版本

  • 使用 Android Studio 安装它们或 sdkmanager 命令行工具。例如，要在 Linux 上安装 AGP 端口 CMake 3.22.1 和 NDK 版本 25.1.8937393，请执行以下操作

     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

构建项目

cd build/android_gradle

除非您想积极调试应用程序，否则为了获得更好的性能，请优先使用发布版本构建。

对于发布版本构建

gradle assembleRelease

对于调试版本构建

gradle assembleDebug

在设备上安装 apk

现在你可以使用 Android 调试桥 (Android Debug Bridge) 在已连接的设备上安装 apk。

对于发布版本构建

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

对于调试版本构建

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

使用 Android Studio 构建

使用 Android Studio，你可以打开 build/android_gradle/build.gradle 项目，并从这里编译和运行该项目。建议使用最新的 Android Studio 版本。

如果你之前在你的开发系统上同意了许可协议，Android Studio 将在启动时自动安装 CMake 和 NDK，其版本配置在你的 build/android-gradle/build.gradle 中。否则（或如果安装失败），你需要手动安装所需的 CMake 和 NDK，有关详细步骤，请参考 官方说明。默认安装位置为：

  • $SDK-ROOT-DIR/ndk/$ndkVersion (NDK)。

  • $SDK-ROOT-DIR/cmake/$cmake-version (CMake)。

Android Studio 将使用上述默认位置，无需任何环境变量要求；如果你想将相同的 NDK 和 CMake 版本用于其他目的，你可以简单地将你的环境变量配置到这些位置。如果你设置了 NDK 和 CMake 环境变量，Android Studio 将使用它们而不是默认位置。