之前在 Podman 和 Dev Containers 配置记录里,把编译器和大型依赖放进 Linux 开发镜像。这次回到 Windows,准备一个使用 OCCT、SDL3、Dear ImGui 和 Vulkan 的 C++ 项目,选择在本机用 vcpkg 管理依赖。

我希望项目只维护少量配置:vcpkg.json 声明依赖,CMakeLists.txt 描述编译和链接,CMakePresets.json 保存构建类型和路径。VS Code 直接使用同一份 preset,clangd 从构建目录读取编译参数。

主项目使用 clang-cl 和 C++23,vcpkg 依赖使用 x64-windows。Vulkan 头文件、loader 和着色器编译器 slangc 都由 vcpkg 提供。Debug 和 Release 分目录构建,各自生成可执行文件和 SPIR-V。

1 准备 Windows 工具链 #

1.1 用 Build Tools 自带的 LLVM #

这次使用的环境如下。版本用于记录本次构建,安装路径需要按自己的机器调整。

工具 本次版本或配置
Visual Studio Build Tools 2026 18.12.0
MSVC 工具集 14.52.37025,x64/x86
Windows SDK 10.0.26100.0
LLVM / clang-cl / clangd / clang-tidy / clang-format 22.1.3,Build Tools 自带
主项目入口 CMake 4.3.1-msvc1,来自 Build Tools
Ninja、vcpkg 使用 Build Tools 自带版本

clang-cl 接受 MSVC 风格的编译参数,配合微软的 C++ 标准库、运行库开发文件和 Windows SDK 使用。LLVM 工具由 Build Tools 的 C++ Clang tools for Windows 可选组件提供,位于 VC\Tools\Llvm\x64\bin。本机目录中有 clang-cl、clangd、clang-tidy、clang-format、clang-scan-deps、lld-link 和 LLVM 的归档、分析、符号工具。参见 Clang 的 Windows 使用说明。

没有必要为了这套配置安装完整 Visual Studio IDE。已有 Build Tools 时,在 Visual Studio Installer 的「单个组件」中勾选 C++ Clang tools for Windows 即可安装 LLVM 编译工具和相关工具。这个组件会随 Build Tools 更新。

本文使用的 LLVM 目录和版本如下:

powershell
$llvmBin = 'C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Tools\Llvm\x64\bin'
Get-ChildItem $llvmBin -Filter 'clang*.exe' | Select-Object -ExpandProperty Name
& "$llvmBin\clang-cl.exe" --version
& "$llvmBin\clangd.exe" --version

这次显示 clang-cl 和 clangd 都是 22.1.3。CMake Presets 和 VS Code clangd 设置使用完整路径,不依赖 PATH 顺序。

1.2 使用 Build Tools 自带的 CMake、Ninja 和 vcpkg #

本机 Build Tools 安装在:

text
C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools

以下路径均相对于该目录:

工具 路径
vcpkg VC\vcpkg\vcpkg.exe
vcpkg 的 CMake 集成 VC\vcpkg\scripts\buildsystems\vcpkg.cmake
CMake Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe
Ninja Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja\ninja.exe

可以在 PowerShell 中先保存 CMake 路径:

powershell
$cmake = 'C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe'
& $cmake --version

如果 cmake 已在 PATH 中,也可以直接调用。使用完整路径便于区分机器上不同来源的版本。

2 用三个文件描述工程 #

2.1 在 manifest 中选择依赖和 features #

项目放在 C:\Users\Yoimiya\occt-lab。源码、构建配置和生成目录按下面组织:

text
occt-lab/
├── vcpkg.json
├── CMakeLists.txt
├── CMakePresets.json
├── .clangd
├── src/
│   └── main.cpp
├── shaders/
│   └── triangle.slang
├── build-debug/
└── build-release/

vcpkg.json:

json
{
  "name": "occt-lab",
  "version-string": "0.1.0",
  "builtin-baseline": "4702e381dbbd9b54d3f7e1eb565cd8981c1814cd",
  "dependencies": [
    "opencascade",
    {
      "name": "sdl3",
      "features": ["vulkan"]
    },
    {
      "name": "imgui",
      "features": ["sdl3-binding", "vulkan-binding", "docking-experimental"]
    },
    "vulkan",
    {
      "name": "shader-slang",
      "host": true
    }
  ]
}

OCCT 的包名是 opencascade。SDL3 启用 Vulkan 支持,ImGui 则选择 SDL3 平台后端、Vulkan 渲染后端和 docking。后端由 vcpkg 构建并接入其导出的 imgui::imgui target,应用不需要再把同一份后端 .cpp 重复加入编译。

项目直接包含 Vulkan 头文件并链接 loader,所以在 manifest 里显式列出 vulkan。ImGui 的 Vulkan 后端也依赖这个包,两条依赖会解析到同一个 vulkan:x64-windows。这个包带入 vulkan-headers 和 vulkan-loader。Vulkan port 的依赖声明

shader-slang 使用 "host": true,因为 slangc 是构建时运行的工具。这个 baseline 下的 port 下载 Slang 2026.22 的官方预编译包,并将 slangc 放到安装树的 tools/shader-slang 目录。shader-slang port

builtin-baseline 记录包注册表的版本基准。这次使用的提交是 4702e381…,提交时间为北京时间 2026 年 11 月 14 日。将 hash 写进 manifest 后,更新 vcpkg 工具本身不会直接改变这项声明;需要升级依赖时,再调整 baseline 并重新配置。参见 vcpkg 版本管理。

2.2 在 CMake 中链接库并编译着色器 #

CMakeLists.txt:

cmake
cmake_minimum_required(VERSION 3.21)
project(occt_lab LANGUAGES C CXX)

find_package(OpenCASCADE CONFIG REQUIRED)
find_package(SDL3 CONFIG REQUIRED)
find_package(imgui CONFIG REQUIRED)
find_package(Vulkan REQUIRED)
find_package(slang CONFIG REQUIRED)

add_library(occt_lab_dependencies INTERFACE)
target_compile_features(occt_lab_dependencies INTERFACE cxx_std_23)
target_include_directories(occt_lab_dependencies SYSTEM INTERFACE
    "${OpenCASCADE_INCLUDE_DIR}"
)
target_link_libraries(occt_lab_dependencies INTERFACE
    ${OpenCASCADE_LIBRARIES}
    SDL3::SDL3
    imgui::imgui
    Vulkan::Vulkan
)

add_executable(occt_lab src/main.cpp)
target_link_libraries(occt_lab PRIVATE occt_lab_dependencies)
set_target_properties(occt_lab PROPERTIES CXX_EXTENSIONS OFF)

set(triangle_shader "${CMAKE_CURRENT_SOURCE_DIR}/shaders/triangle.slang")
set(shader_output_dir "${CMAKE_CURRENT_BINARY_DIR}/shaders")
set(triangle_spv "${shader_output_dir}/triangle.vert.spv")

add_custom_command(
    OUTPUT "${triangle_spv}"
    COMMAND "${CMAKE_COMMAND}" -E make_directory "${shader_output_dir}"
    COMMAND "${SLANG_EXECUTABLE}" "${triangle_shader}"
        -entry vertexMain -target spirv -o "${triangle_spv}"
    DEPENDS "${triangle_shader}" "${SLANG_EXECUTABLE}"
    COMMENT "Compiling triangle.slang to SPIR-V"
    VERBATIM
)

add_custom_target(occt_lab_shaders DEPENDS "${triangle_spv}")
add_dependencies(occt_lab occt_lab_shaders)

这里用一个 interface target 汇总依赖和 C++23 要求,程序目标只链接它。OCCT 暂时使用配置包导出的库列表;后续明确需要哪些模块,再缩小链接范围。

cxx_std_23 作用于消费这个 target 的主项目源码。第三方库仍按各自 port 的规则构建。

find_package(slang CONFIG REQUIRED) 从 vcpkg 安装树找到 slangc,把路径写入 SLANG_EXECUTABLE。Ninja 按 OUTPUT 和 DEPENDS 跟踪 triangle.vert.spv,在产物缺失或输入更新时执行编译。也可以单独构建 occt_lab_shaders 来检查着色器。Slang 命令行编译说明

2.3 用 preset 固定编译器和构建目录 #

CMakePresets.json:

json
{
  "version": 3,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 21,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "base",
      "hidden": true,
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build-${presetName}",
      "cmakeExecutable": "C:/Program Files (x86)/Microsoft Visual Studio/18/BuildTools/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe",
      "architecture": { "value": "x64", "strategy": "external" },
      "toolset": { "value": "host=x64", "strategy": "external" },
      "toolchainFile": "C:/Program Files (x86)/Microsoft Visual Studio/18/BuildTools/VC/vcpkg/scripts/buildsystems/vcpkg.cmake",
      "cacheVariables": {
        "CMAKE_C_COMPILER": "C:/Program Files (x86)/Microsoft Visual Studio/18/BuildTools/VC/Tools/Llvm/x64/bin/clang-cl.exe",
        "CMAKE_CXX_COMPILER": "C:/Program Files (x86)/Microsoft Visual Studio/18/BuildTools/VC/Tools/Llvm/x64/bin/clang-cl.exe",
        "CMAKE_MAKE_PROGRAM": "C:/Program Files (x86)/Microsoft Visual Studio/18/BuildTools/Common7/IDE/CommonExtensions/Microsoft/CMake/Ninja/ninja.exe",
        "CMAKE_EXPORT_COMPILE_COMMANDS": true,
        "VCPKG_TARGET_TRIPLET": "x64-windows",
        "VCPKG_HOST_TRIPLET": "x64-windows"
      }
    },
    {
      "name": "release",
      "displayName": "Release (clang-cl x64)",
      "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    },
    {
      "name": "debug",
      "displayName": "Debug (clang-cl x64)",
      "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "release",
      "configurePreset": "release"
    },
    {
      "name": "debug",
      "configurePreset": "debug"
    }
  ]
}

隐藏的 base 保存公共配置,release 和 debug 只覆盖 CMAKE_BUILD_TYPE。${presetName} 在继承后按当前 preset 展开,分别得到 build-release 和 build-debug。

这份配置记录了我的本机工具路径,换机器时检查对应位置即可。如果多人共用工程,可以把路径覆盖移到 CMakeUserPresets.json;个人实验项目先集中保存在一份文件里。cmakeExecutable 供支持它的 IDE 使用,命令行中的 CMake 仍由实际调用路径决定。CMake Presets 文档

这里有两个编译器选择:主项目的 CMAKE_CXX_COMPILER 是 Build Tools 自带的 clang-cl 22.1.3;vcpkg 的 x64-windows 依赖仍由 MSVC 构建。两套工具使用相同架构和 MSVC 运行库,省去了自定义 triplet 与工具链文件。

architecture 和 toolset 使用 external,供编辑器识别所需的 VS 开发环境。命令行 CMake 不会根据这两个字段自动运行环境初始化脚本;若出现 Windows SDK 或 CRT 查找失败,应在 x64 开发者命令行中重试并核对环境。

3 配置、构建与编辑器接入 #

3.1 configure 阶段就会准备依赖 #

在项目目录运行:

powershell
cd C:\Users\Yoimiya\occt-lab

& $cmake --preset release
& $cmake --build --preset release

& $cmake --preset debug
& $cmake --build --preset debug

vcpkg 工具链会在 CMake 配置阶段读取 manifest 并安装依赖。因此,第一次 cmake --preset release 可能已经开始下载、解压和编译 OCCT;主项目的 build 命令还没执行,终端也可能忙很久。vcpkg CMake 集成说明

依赖构建时出现:

text
-- Configuring x64-windows
-- Building x64-windows-dbg
-- Building x64-windows-rel

这是默认 triplet 同时构建 Debug 和 Release 依赖。主项目选择 Release,并不会让依赖只生成 Release。考虑到后面也需要调试,我保留了默认行为。Triplet 变量说明

更新 baseline 后,还遇到了工具版本提示:

text
A suitable version of cmake was not found (required v4.4.3).
Downloading ... cmake-4.4.3-windows-x86_64.zip

当时主入口 CMake 是 4.3.1-msvc1,vcpkg 自动下载 4.4.3 用于依赖构建。该版本保存在 vcpkg 下载缓存中,由 vcpkg 按路径调用,不覆盖 Build Tools 的 CMake,也不修改系统 PATH。

3.2 用 C++23 的 std::println 检查环境 #

最初的 src/main.cpp 只打印库的头文件版本:

cpp
#include <Standard_Version.hxx>
#include <SDL3/SDL_version.h>
#include <imgui.h>
#include <vulkan/vulkan_core.h>

#include <print>

auto main() -> int
{
    std::println("Library header versions");
    std::println("OCCT: {}", OCC_VERSION_COMPLETE);
    std::println("SDL3: {}.{}.{}", SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_MICRO_VERSION);
    std::println("Dear ImGui: {}", IMGUI_VERSION);
    std::println("Vulkan: {}.{}.{}",
                 VK_API_VERSION_MAJOR(VK_HEADER_VERSION_COMPLETE),
                 VK_API_VERSION_MINOR(VK_HEADER_VERSION_COMPLETE),
                 VK_API_VERSION_PATCH(VK_HEADER_VERSION_COMPLETE));

    return 0;
}

构建完成后分别运行:

powershell
.\build-release\occt_lab.exe
.\build-debug\occt_lab.exe

两份程序都成功输出:

text
Library header versions
OCCT: 8.0.1
SDL3: 3.4.20
Dear ImGui: 1.93.0
Vulkan: 1.4.363

到这里,项目已经可以开始添加正式源码,日常修改后执行对应的 build 命令即可。

分别使用 cmake --fresh --preset debug 和 cmake --fresh --preset release 配置并构建两套 preset。两个 CMakeCache 都指向 VC/Tools/Llvm/x64/bin/clang-cl.exe,compile_commands.json 中也包含对应的 std.pcm 和 vulkan.pcm 路径。Debug 和 Release 各自生成 39 MB 左右的 std.pcm、56 MB 左右的 vulkan.pcm,并链接对应的模块 .obj。

Debug 和 Release 程序都成功运行,输出 OCCT、SDL3、Dear ImGui 和 Vulkan 的头文件版本。两种配置都生成了 752 字节的 triangle.vert.spv,SPIR-V 文件头有效。CMakeCache 和编译数据库都记录了这套工具链与 PCM 路径。

3.3 检查 Slang 生成的 SPIR-V #

shaders/triangle.slang 用顶点编号选出三角形的三个坐标。

hlsl
static const float2 positions[3] = {
    float2(0.0, -0.5),
    float2(0.5, 0.5),
    float2(-0.5, 0.5),
};

[shader("vertex")]
float4 vertexMain(uint vertexIndex : SV_VertexID) : SV_Position
{
    return float4(positions[vertexIndex], 0.0, 1.0);
}

构建后检查两个输出文件。

powershell
Get-Item .\build-debug\shaders\triangle.vert.spv, .\build-release\shaders\triangle.vert.spv |
    Select-Object FullName, Length

这次两个文件都是 752 字节,SPIR-V 版本为 1.5,SHA-256 相同。CMake 缓存中的 Vulkan 头文件、vulkan-1.lib 和 slangc.exe 都来自各自的 vcpkg_installed。

3.4 用自定义命令生成 C++ 模块文件 #

Build Tools 的 MSVC 标准库提供 modules/std.ixx,vcpkg 安装的 Vulkan-Headers 提供 include/vulkan/vulkan.cppm。CMake 4.3.1 不负责扫描这组 clang-cl 模块依赖,因此我在 CMakeLists.txt 中为两个模块各加一条自定义命令。

cmake
set(MSVC_STD_IXX "" CACHE FILEPATH "Path to the MSVC STL std.ixx")
if(NOT EXISTS "${MSVC_STD_IXX}")
    message(FATAL_ERROR "Set MSVC_STD_IXX to the MSVC STL std.ixx file")
endif()

set(std_pcm "${CMAKE_CURRENT_BINARY_DIR}/modules/std.pcm")
set(std_obj "${CMAKE_CURRENT_BINARY_DIR}/modules/std.obj")
set(vulkan_pcm "${CMAKE_CURRENT_BINARY_DIR}/modules/vulkan.pcm")
set(vulkan_obj "${CMAKE_CURRENT_BINARY_DIR}/modules/vulkan.obj")
set(module_output_dir "${CMAKE_CURRENT_BINARY_DIR}/modules")

add_custom_command(
    OUTPUT "${std_pcm}" "${std_obj}"
    COMMAND "${CMAKE_COMMAND}" -E make_directory "${module_output_dir}"
    COMMAND "${CMAKE_CXX_COMPILER}" /nologo /c /EHsc
        "$<IF:$<CONFIG:Debug>,/MDd,/MD>"
        -clang:-std=c++23
        -clang:-Wno-include-angled-in-module-purview
        -clang:-Wno-reserved-module-identifier
        "-clang:-fmodule-output=${std_pcm}" "/Fo${std_obj}"
        -xc++-module "${MSVC_STD_IXX}"
    DEPENDS "${MSVC_STD_IXX}" "${CMAKE_CXX_COMPILER}"
    COMMENT "Compiling MSVC STL std module"
    VERBATIM
)

add_custom_command(
    OUTPUT "${vulkan_pcm}" "${vulkan_obj}"
    COMMAND "${CMAKE_CXX_COMPILER}" /nologo /c /EHsc
        "$<IF:$<CONFIG:Debug>,/MDd,/MD>"
        -clang:-std=c++23
        "-clang:-fmodule-file=std=${std_pcm}"
        "-clang:-fmodule-output=${vulkan_pcm}" "/Fo${vulkan_obj}"
        "/I${Vulkan_INCLUDE_DIR}"
        "${Vulkan_INCLUDE_DIR}/vulkan/vulkan.cppm"
    DEPENDS "${std_pcm}" "${MSVC_STD_IXX}" "${CMAKE_CXX_COMPILER}"
    COMMENT "Compiling Vulkan-Hpp module"
    VERBATIM
)

set_source_files_properties(
    "${std_obj}" "${vulkan_obj}"
    PROPERTIES GENERATED TRUE EXTERNAL_OBJECT TRUE
)
target_sources(occt_lab PRIVATE "${std_obj}" "${vulkan_obj}")
target_compile_options(occt_lab PRIVATE
    "-clang:-fmodule-file=std=${std_pcm}"
    "-clang:-fmodule-file=vulkan=${vulkan_pcm}"
)
set_property(SOURCE src/main.cpp APPEND PROPERTY OBJECT_DEPENDS "${std_pcm};${vulkan_pcm}")

std.ixx 先生成 std.pcm 和 std.obj。Vulkan-Hpp 的 vulkan.cppm 自己也写了 import std;,所以第二条命令依赖 std.pcm,并通过 -fmodule-file 告诉 clang-cl 在哪里读取它。主程序同样接收两个 PCM 路径;OBJECT_DEPENDS 让 Ninja 在编译 main.cpp 前先生成模块。模块对象文件也加入可执行目标,链接时提供模块定义。

标准库模块要和程序使用相同的 MSVC 运行库。配置命令里的生成器表达式为 Debug 选择 /MDd,其余配置选择 /MD。CMakePresets.json 将 MSVC_STD_IXX 指向 Build Tools 内的标准库模块接口文件。MSVC 升级后若该路径变化,要同步更新 preset。

main.cpp 保留 ImGui 和 Vulkan C 头文件,再导入模块:

cpp
#include <Standard_Version.hxx>
#include <SDL3/SDL_version.h>
#include <imgui.h>
#include <vulkan/vulkan_core.h>

import std;
import vulkan;

<print> 可以删除,因为 std::println 由 import std; 提供。这里仍保留 vulkan_core.h,因为下面打印 Vulkan 头文件版本时使用了预处理宏。C++ 模块不会导出这些宏。

这份 Vulkan-Headers 版本会在编译模块时打印两条警告。一条说明 Vulkan-Hpp 目前将模块实现标为实验性;另一条说明头文件采用了 Clang 提示的非标准模块实现方式。这是头文件自身发出的提示,不影响本次生成模块和链接。需要压掉实验性提示时,可以按头文件建议,在编译 vulkan.cppm 前定义 VULKAN_HPP_CXX_MODULE_EXPERIMENTAL_WARNING,但我保留默认信息以便之后留意实现变化。Vulkan-Hpp 模块接口

构建后,Debug 和 Release 的 modules 目录中各有 std.pcm、std.obj、vulkan.pcm 和 vulkan.obj。两个配置使用不同的运行库设置,PCM 文件因此也分别生成。clangd 从 build-debug/compile_commands.json 读取 -fmodule-file 参数,直接打开对应 PCM;VS Code 中的跳转和诊断由用户检查。

3.5 CMake Tools 沿用已有 preset #

安装扩展:

powershell
code --install-extension ms-vscode.cmake-tools
code --install-extension llvm-vs-code-extensions.vscode-clangd

打开项目后,在命令面板执行 CMake: Select Configure Preset,选择 debug 或 release,再选择对应的 Build Preset。后续使用 CMake: Configure 和 CMake: Build。

CMake Tools 的 cmake.useCMakePresets 默认值为 auto,根目录存在 CMakePresets.json 时会使用它,不需要再让扩展生成 kits 或另一套构建目录。若用户设置中曾禁用 presets,可以改回 auto 或 always。CMake Tools 文档

Build Tools 内置的 CMake、Ninja 不一定在普通终端 PATH 中。本文已经写明工具路径;若扩展仍找不到 VS 工具环境,可执行 CMake: Scan for Compilers,或从开发者命令行启动 VS Code。

3.6 clangd 固定读取 Debug 编译数据库 #

在 VS Code 用户设置中指定已安装的 clangd:

json
{
  "clangd.path": "C:\\Program Files (x86)\\Microsoft Visual Studio\\18\\BuildTools\\VC\\Tools\\Llvm\\x64\\bin\\clangd.exe",
  "clangd.arguments": ["--background-index", "--clang-tidy"]
}

clangd.path 要手动填写 clangd.exe 的完整路径。这里指向 Build Tools 内的 VC\Tools\Llvm\x64\bin\clangd.exe,VS Code 扩展不会因为 CMake Presets 指定了 clang-cl 就自动选择这个 clangd。

preset 中的 CMAKE_EXPORT_COMPILE_COMMANDS 会让 Ninja 生成器输出 compile_commands.json。它记录每个源文件的语言标准、头文件路径、宏定义和编译命令,clangd 据此解析代码,不必手工维护 include 路径。

clangd 默认向源码的上级目录查找数据库,也会检查名为 build 的子目录。本文使用 build-debug 和 build-release,在项目根目录的 .clangd 中指定 Debug 目录。

yaml
CompileFlags:
  CompilationDatabase: build-debug

路径相对于 .clangd 文件。日常补全固定使用 Debug 参数;切换 CMake Tools 的 preset 不会自动切换这项配置。需要检查 Release 特有宏分支时,再改成 build-release。clangd 配置文档

完成 cmake --preset debug 的配置和生成后,数据库就已存在。若编辑器仍提示找不到依赖,先检查 build-debug/compile_commands.json,再执行 clangd: Restart language server。

4 PowerShell 版本变化让缓存失效 #

4.1 同一个项目,第二次却恢复了 0 个包 #

Release 依赖准备完成后,我让 agent 接着配置 Debug。两边使用相同 baseline、相同 x64-windows,预期能够复用已经生成的二进制缓存,但日志显示:

text
Restored 0 package(s) from C:\Users\Yoimiya\AppData\Local\vcpkg\archives

随后 vcpkg 开始重新构建依赖。检查 vcpkg-cmake 的 ABI 信息文件,发现其中一项不同:

text
# Existing Release build
cmake 4.4.3
powershell 7.7.0
triplet x64-windows

# First Debug attempt
cmake 4.4.3
powershell 7.6.9
triplet x64-windows

原来的终端使用 PowerShell 7.7.0;agent 的执行环境把自带的 7.6.9 放在 PATH 前面,vcpkg 找到的是后者。

vcpkg 的二进制缓存根据 ABI hash 匹配。参与计算的不只有源码版本和编译器,还包括 port 脚本、依赖、triplet 及部分构建工具版本,Windows 上的 PowerShell 也在其中。官方缓存排错文档

4.2 核对工具路径,再重试 #

从项目根目录可以查看两次构建记录中的工具版本:

powershell
$abiRelativePath = 'vcpkg_installed\vcpkg\blds\vcpkg-cmake\x64-windows.vcpkg_abi_info.txt'

Get-Content (Join-Path '.\build-release' $abiRelativePath) |
    Select-String '^(cmake|powershell|triplet) '

Get-Content (Join-Path '.\build-debug' $abiRelativePath) |
    Select-String '^(cmake|powershell|triplet) '

这个路径对应本文使用的 VS 自带 vcpkg。检查当前终端和 PATH 中的 PowerShell:

powershell
$PSVersionTable.PSVersion
Get-Command pwsh -All | Select-Object Source
pwsh -NoProfile -Command '$PSVersionTable.PSVersion.ToString(); $PSHOME'

当前 Shell 的版本与子进程通过 PATH 找到的 pwsh 需要分别看。IDE、agent 或其他工具可以给子进程设置不同的 PATH。

停止那次重复构建后,只在重试进程的 PATH 前面加入本机 PowerShell 7.7.0 所在目录:

powershell
$savedPath = $env:Path
try {
    $env:Path = 'C:\Program Files\WindowsApps\Microsoft.PowerShell_7.7.0.0_x64__8wekyb3d8bbwe;' + $savedPath
    & $cmake --preset debug
}
finally {
    $env:Path = $savedPath
}

路径来自本机实际的 $PSHOME,其他安装方式和版本需要替换。这里不修改用户或系统 PATH。

重试后,日志变为:

text
Restored 16 package(s) from C:\Users\Yoimiya\AppData\Local\vcpkg\archives in 15 s.
...
All requested installations completed successfully in: 3.9 s

全部 16 个包从缓存恢复,后续完成安装;包含编译器检测在内,Debug 配置总耗时约 50.5 秒。接着构建并运行 Debug 程序,输出与 Release 一致。

以后遇到同样的重编现象,可以先比较 ABI 信息和实际工具路径。保留现有缓存有助于验证原因,直接清空缓存反而失去了可以恢复的包。

5 缓存在哪里,怎样清理 #

5.1 VS 自带 vcpkg 使用只读安装布局 #

这次使用的 vcpkg 位于 Program Files (x86),其 bundle 配置标记为只读。它把下载缓存放在用户目录,将依赖构建临时文件放在项目安装树中。独立克隆的普通 vcpkg 通常把 downloads、buildtrees、packages 放在自己的根目录,不能直接套用同一张路径表。vcpkg 路径实现

本项目没有设置缓存位置覆盖,默认路径如下:

位置 保存内容
%LOCALAPPDATA%\vcpkg\downloads 下载的源码归档和其他资源
%LOCALAPPDATA%\vcpkg\downloads\tools 解压后的辅助工具,如 vcpkg 下载的 CMake
%LOCALAPPDATA%\vcpkg\archives 已构建的二进制包缓存
%LOCALAPPDATA%\vcpkg\registries 包注册表、port 和版本信息缓存
build-debug\vcpkg_installed\x64-windows Debug 构建目录使用的依赖安装树,包含两套库
build-debug\vcpkg_installed\vcpkg\blds 依赖源码、中间产物、日志和 ABI 信息
build-debug\vcpkg_installed\vcpkg\pkgs 打包暂存目录

Release 使用同样的布局,将 build-debug 换成 build-release。两份构建目录各自安装依赖,但共享用户级二进制缓存。默认缓存位置及可用配置见 vcpkg 二进制缓存文档。

5.2 先清中间产物,保留可复用的包 #

依赖编译结束后,blds 和 pkgs 是优先检查的清理对象。排错时先保留日志,尤其是编译失败或缓存不命中的情况。archives 值得保留,后面重新配置目录时,OCCT 这类大型库能直接恢复。

清理范围可以按需要选择:

清理对象 下次使用时的成本
blds、pkgs 需要重新构建时,再生成源码工作目录和中间文件
downloads 对应源码和工具可能需要重新下载
archives 缺少已安装依赖时,可能需要重新编译
整个 build-debug 或 build-release 重新配置、恢复依赖、构建主项目

安装树里的 vcpkg/info 等文件记录包的安装状态,不要单独删除。清理时先结束相关构建进程,再确认目录属于当前项目。

源码和配置提交到仓库,生成目录可以加入 .gitignore:

gitignore
/build-debug/
/build-release/
/.cache/

日常开发使用已有 preset 构建;调整依赖或工具链时重新 configure;缓存未命中时先查工具版本和 ABI 信息。clangd 则固定读取 Debug 编译数据库,编辑器和命令行都沿用同一套工程配置。