Vulkan Samples 项目构建指南：跨平台编译与配置详解

前言

Vulkan Samples 是 Khronos Group 官方维护的一套 Vulkan API 示例代码集合，旨在帮助开发者学习和掌握 Vulkan 图形编程。本文将全面解析该项目的构建过程，涵盖 Windows、Linux、macOS、iOS 和 Android 五大平台的详细构建指南。

核心 CMake 配置选项

在构建 Vulkan Samples 项目前，开发者需要了解以下关键 CMake 配置选项：

示例选择与控制

• VKB_<sample_name>：控制是否构建特定示例（默认 ON）
• VKB_BUILD_SAMPLES：控制是否构建所有示例（默认 ON）
• VKB_BUILD_TESTS：控制是否构建测试用例（默认 OFF）

验证层配置

• VKB_VALIDATION_LAYERS：启用 Vulkan 验证层（默认 OFF）
• VKB_VALIDATION_LAYERS_GPU_ASSISTED：启用 GPU 辅助验证（默认 OFF）
• VKB_VALIDATION_LAYERS_BEST_PRACTICES：启用最佳实践验证（默认 OFF）
• VKB_VALIDATION_LAYERS_SYNCHRONIZATION：启用同步验证（默认 OFF）

调试与优化

• VKB_VULKAN_DEBUG：启用调试工具（默认 ON）
• VKB_WARNINGS_AS_ERRORS：将警告视为错误（默认 ON）
• VKB_PROFILING：启用性能分析（使用 Tracy 分析器，默认 OFF）

资源准备

3D 模型资源

项目中的大多数示例需要从 Vulkan-Samples-Assets 仓库获取 3D 模型资源。这些资源通过 Git 子模块管理，克隆主项目时使用 --recursive 参数即可自动获取。

在 Android 平台上，Gradle 会在 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 shell setprop security.perf_harden 0

项目使用 HWCPipe 进行性能数据采集，开发者可参考相关文档进行集成。

各平台构建指南

Windows 平台构建

前置要求

• CMake 3.12+
• Python 3
• Visual Studio 2017 或更高版本

推荐工具配置

建议使用 clang-format-15 进行代码格式化，该版本与项目中的 .clang-format 文件兼容。

构建步骤

1. 生成 VS 项目（根据 CMake 版本选择相应命令）：

   # CMake 3.13 之前
   cmake -G "Visual Studio 15 2017 Win64" . -Bbuild/windows
   
   # CMake 3.14+ (VS 2019)
   cmake -G "Visual Studio 16 2019" -A x64 -S . -Bbuild/windows
   
   # CMake 3.21+ (VS 2022)
   cmake -G "Visual Studio 17 2022" -A x64 -S . -Bbuild/windows
   

2. 构建项目：

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

3. 运行示例：

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

Linux 平台构建

前置要求

• CMake 3.12+
• C++17 编译器
• 基础开发工具包

安装依赖：

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

构建步骤

1. 生成项目：

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

2. 构建项目：

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

3. 运行示例：

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

macOS 平台构建

前置要求

• CMake 3.12+（Apple Silicon 需 3.19.2+）
• Xcode 12+（Apple Silicon）
• Vulkan SDK

环境配置

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

构建步骤

1. 生成 Xcode 项目：

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

2. 构建项目：

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

3. 运行示例：

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

iOS 平台构建

前置要求

• CMake 3.28+
• Xcode 12+
• Vulkan SDK 1.3.278+

环境配置

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

构建步骤

1. 生成 Xcode 项目：

   cmake -G Xcode -Bbuild/ios -DCMAKE_BUILD_TYPE=Release -DCMAKE_SYSTEM_NAME=iOS ...
   

2. 构建项目：

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

Android 平台构建

前置要求

• JDK 8+
• Android SDK
• CMake 3.16+
• Android NDK r23+

推荐构建方式

强烈建议使用 Android Studio 进行构建，至少需要 Ladybug 2024.2.1 版本。

Gradle 构建步骤

1. 生成 Gradle 项目：

   ./scripts/generate.py android
   

2. 安装依赖（如未自动安装）：

   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
   

3. 构建项目：

   cd build/android_gradle
   gradle assembleRelease
   

4. 安装 APK：

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

质量保证工具

项目使用以下工具确保代码质量：

• Doxygen：文档生成
• Clang Format/Clang Tidy：代码格式化和静态分析
• Snake Case Check：命名规范检查
• Android NDK：Android 原生开发

结语

本文详细介绍了 Vulkan Samples 项目在各平台的构建流程和关键配置选项。通过合理使用这些构建选项，开发者可以灵活地定制自己的开发环境，专注于 Vulkan 图形编程的学习和实践。建议开发者根据目标平台选择合适的构建方式，并充分利用验证层和性能分析工具来提升开发效率。