33. 9.1 Visual Studio集成

3天前发布

引言：当施工程队长遇上”老牌监理”

在前面的章节里，我们的 CMake “施工程队长”已经走南闯北：从本地盖楼到海外工程（交叉编译），从手工砌砖到自动化质检（测试与静态分析），可谓是身经百战。但队长再厉害，终究需要一张办公桌、一套顺手的工具才能高效指挥。对于许多 Windows 平台上的 C++ 开发者来说，这张办公桌往往就是 Visual Studio。

Visual Studio 不只是一个代码编辑器，它是 Windows 世界里经验最丰富的”工程监理”——它熟悉本地的每一条建筑法规（Windows SDK）、每一种施工机械（MSVC 编译器工具集），还自带了图纸管理（解决方案资源管理器）、工时统计（性能分析器）和故障排查（调试器）。如果能让 CMake 队长和这位监理默契配合，而不是互相拆台，你的 Windows 开发体验将会产生质的飞跃。

这一节，我们就来搭建 CMake 与 Visual Studio 之间的”沟通桥梁”。你不需要手动去点选项目属性页里的各种开关，而是让 CMake 在生成 .sln 和 .vcxproj 文件时，就把一切安排得明明白白。

要点1：Visual Studio 生成器使用——不同 VS 版本的选择

生成器是什么？

在 CMake 的世界里，生成器（Generator）是连接 CMake 抽象构建描述与具体构建工具之间的翻译官。当你运行 cmake -G "..." 时，你就是在指定：”队长，请把咱们的施工计划翻译成这位监理能听懂的语言。”

对于 Visual Studio，CMake 提供了多个对应的生成器，命名规则通常是 Visual Studio [版本号] [年份]。选择合适的生成器，就像是为项目挑选正确年份的监理手册——用错了版本，可能会遇到不认识的施工符号。

版本选择指南

截至目前，CMake 支持的 Visual Studio 生成器包括但不限于：

Visual Studio 17 2022：对应 VS 2022，推荐用于新项目
Visual Studio 16 2019：对应 VS 2019，目前仍广泛使用的 LTS 版本
Visual Studio 15 2017：对应 VS 2017，老旧项目维护时使用

在命令行中，你可以这样指定：

# 使用 VS 2022 生成器，生成 64 位项目
cmake -G "Visual Studio 17 2022" -A x64 -B build

# 使用 VS 2019 生成器，生成 32 位项目
cmake -G "Visual Studio 16 2019" -A Win32 -B build

注意，从 VS 2019 开始，CMake 已经成为 Visual Studio 的”一等公民”——你可以直接在 VS IDE 中打开包含 CMakeLists.txt 的文件夹，VS 会自动调用 CMake 并选择合适的生成器。但对于需要精确控制生成过程的场景（比如 CI/CD 流水线），显式指定 -G 仍然是最佳实践。

架构与工具集

Visual Studio 生成器支持通过 -A 参数指定目标平台架构：

x64：最常见的 64 位桌面应用（默认推荐）
Win32：传统的 32 位应用
ARM / ARM64：Windows on ARM 设备

如果你需要使用特定的 MSVC 工具集（例如 VS 2022 中仍想使用 v142 工具集以保持与旧库兼容），可以通过 -T 参数指定：

cmake -G "Visual Studio 17 2022" -A x64 -T v142 -B build

这就好比告诉监理：”虽然您拿的是 2022 版手册，但请按照 2019 版的焊接标准（工具集）来验收。”

要点2：解决方案与项目映射——CMake 目标到 VS 项目的转换

从 CMake 到 .sln 的转换

当你使用 Visual Studio 生成器时，CMake 会把你的构建描述翻译成两套文件：

解决方案文件（.sln）：对应整个构建树，相当于整个工地的总览图。
项目文件（.vcxproj + .vcxproj.filters）：对应 CMake 中的每一个目标（Target），相当于每一栋具体建筑的施工详图。

映射关系非常直观：

add_executable(my_app ...) → 生成 my_app.vcxproj（可执行项目）
add_library(my_lib ...) → 生成 my_lib.vcxproj（库项目）
target_link_libraries(my_app PRIVATE my_lib) → 在 .sln 中建立项目依赖关系，确保编译顺序正确

保持目录结构：source_group

默认情况下，Visual Studio 的解决方案资源管理器会按照磁盘上的物理路径显示文件。但在大型项目中，我们通常希望按照逻辑模块分组（比如把 src/core/ 和 src/utils/ 分别显示为”核心模块”和”工具模块”）。

CMake 提供了 source_group 命令来控制这种映射：

# 假设有以下文件
set(CORE_SOURCES src/core/engine.cpp src/core/renderer.cpp)
set(UTIL_SOURCES src/utils/logger.cpp src/utils/timer.cpp)

add_executable(my_app main.cpp ${CORE_SOURCES} ${UTIL_SOURCES})

# 在 VS 中创建逻辑文件夹
source_group("Core" FILES ${CORE_SOURCES})
source_group("Utils" FILES ${UTIL_SOURCES})

生成的 .vcxproj.filters 文件会记录这些分组信息，开发者在 VS 中看到的将是整洁的逻辑树，而非混乱的扁平文件列表。这相当于队长给监理递交了一份”按功能分区”的图纸索引，而不是按仓库堆放顺序罗列的物料清单。

目标属性的映射

现代 CMake 中基于目标设置的许多属性，都会自动映射到 VS 的项目属性页中：

target_compile_features(my_app PRIVATE cxx_std_17) → VS 项目属性 → C/C++ → 语言 → C++ 语言标准
target_include_directories(my_app PRIVATE include) → VS 项目属性 → C/C++ → 常规 → 附加包含目录
target_compile_definitions(my_app PRIVATE MY_MACRO=1) → VS 项目属性 → C/C++ → 预处理器 → 预处理器定义
target_link_libraries(my_app PRIVATE some.lib) → VS 项目属性 → 链接器 → 输入 → 附加依赖项

这意味着，只要你坚持”以目标为中心”的现代 CMake 写法，团队成员就完全不需要手动去点选 VS 里那些繁琐的属性页——CMake 在生成阶段就已经填好了所有表单。

要点3：多配置特性利用——Debug/Release 在 VS 中的体现

VS 的多配置基因

如果你之前主要使用 Makefile 或 Ninja，你可能已经习惯了”单配置生成器”的模式：配置阶段选定 CMAKE_BUILD_TYPE（如 Release），然后整个构建目录就只能产出这一种配置的可执行文件。

但 Visual Studio 是原生支持多配置（Multi-Config）的 IDE。你在 VS 工具栏看到的那个下拉框（Debug / Release / RelWithDebInfo / MinSizeRel）不是摆设——它允许你在同一个构建目录中自由切换配置，而无需重新运行 CMake。

当你使用 Visual Studio 生成器时，CMake 会自动把 CMAKE_CONFIGURATION_TYPES 设置为包含多种配置的列表。你可以在 CMakeLists.txt 中对这个列表进行裁剪：

# 只保留 Debug 和 Release，去掉其他两种
set(CMAKE_CONFIGURATION_TYPES "Debug;Release" CACHE STRING "" FORCE)

生成器表达式：多配置的钥匙

在多配置环境下，传统的 ${CMAKE_BUILD_TYPE} 变量在配置阶段是空的（因为配置还未确定）。这时候，生成器表达式（Generator Expressions）就成了必备工具——我们在 3.3 节已经详细介绍过它，在 VS 集成中它尤为重要。

举个例子，假设你想在 Debug 模式下链接调试版本的第三方库，Release 模式下链接优化版本：

# 错误示范：CMAKE_BUILD_TYPE 在 VS 生成器配置阶段为空
# target_link_libraries(my_app PRIVATE debug/libd.lib optimized/lib.lib)

# 正确做法：使用生成器表达式
target_link_libraries(my_app PRIVATE
    $<$:debug/libd.lib>
    $<$:optimized/lib.lib>
)

同理，编译选项也可以按配置区分：

target_compile_options(my_app PRIVATE
    $<$:/Od /Zi>
    $<$:/O2 /Ob2 /DNDEBUG>
)

这些带有 $<CONFIG:...> 的指令，会被 CMake 翻译成 VS 项目文件中每个配置对应的独立段落。当你在 IDE 中从 Debug 切换到 Release 时，VS 会自动使用正确的编译参数，无需重新生成项目。

输出目录管理

为了避免不同配置的产物互相覆盖，建议在多配置生成器中使用内置的生成器表达式来管理输出路径：

set_target_properties(my_app PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin"
    RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}/bin/Debug"
    RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/bin/Release"
)

或者更优雅地，利用 VS 默认行为：如果不指定，VS 会自动在构建目录下创建 Debug/ 和 Release/ 子目录。通常，接受默认行为是最省心的选择。

要点4：VS 特定属性传递——VS_GLOBAL 等属性

VS_GLOBAL_ 前缀属性

有时，你需要设置一些只有 Visual Studio 才关心的”监理内部表格”——比如解决方案的 GUID、项目关键字、根命名空间，或者是一些 VS 特有的调试启动参数。CMake 提供了 VS_GLOBAL_<name> 这种特殊的目标属性，可以把任意值写入生成的 .vcxproj 文件中对应的全局属性节点。

语法如下：

set_target_properties(my_app PROPERTIES
    VS_GLOBAL_KEYWORD "Win32Proj"
    VS_GLOBAL_ROOTNAMESPACE "MyAwesomeApp"
)

这会在 my_app.vcxproj 中生成如下 XML 节点：

<PropertyGroup>
  <Keyword>Win32Proj</Keyword>
  <RootNamespace>MyAwesomeApp</RootNamespace>
</PropertyGroup>

设置 Windows SDK 版本

在某些企业环境中，团队需要锁定特定的 Windows SDK 版本以确保构建一致性。虽然这可以通过全局变量设置，但更现代的做法是通过目标属性或系统变量控制：

# 在配置阶段指定 Windows SDK（例如 10.0.19041.0）
set(CMAKE_SYSTEM_VERSION "10.0.19041.0" CACHE INTERNAL "")

# 或者通过 VS 属性传递
set_target_properties(my_app PROPERTIES
    VS_GLOBAL_TARGET_PLATFORM_VERSION "10.0.19041.0"
)

调试启动配置：VS_DEBUGGER_ 属性

一个极其实用的技巧是预配置 VS 的调试启动参数，让团队成员双击 .sln 打开后就能直接按 F5 运行，无需手动去设置命令行参数或工作目录：

set_target_properties(my_app PROPERTIES
    VS_DEBUGGER_COMMAND_ARGUMENTS "--config ${CMAKE_SOURCE_DIR}/data/config.json"
    VS_DEBUGGER_WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}/bin"
    VS_DEBUGGER_ENVIRONMENT "PATH=%PATH%;${CMAKE_SOURCE_DIR}/third_party/bin"
)

这些属性会映射到 VS 项目属性的”调试”页面中。对于拥有复杂运行时依赖（如 DLL 搜索路径、配置文件路径）的项目，这能极大降低新成员的上手门槛。

隐藏目标的构建：EXCLUDE_FROM_DEFAULT_BUILD

在大型解决方案中，你可能有一些辅助工具（如代码生成器、资源打包器），它们需要在安装时存在，但不应该在开发者按 F7（构建解决方案）时自动编译，以免拖慢日常编译速度。CMake 提供了：

add_executable(code_generator generator.cpp)
set_target_properties(code_generator PROPERTIES 
    EXCLUDE_FROM_DEFAULT_BUILD TRUE
)

虽然这不是以 VS_ 开头的属性，但它在 VS 中的效果尤为明显：该项目仍会出现在解决方案中，但默认不会被构建。当你需要它时，可以右键单独生成。

小结

Visual Studio 与 CMake 的集成，本质上是让”施工程队长”学会用”监理”的语言和工具链来管理工地。通过本节的学习，你应该掌握了：

选对生成器：根据团队安装的 VS 版本和需要的架构（x64/Win32/ARM），在命令行或 CI 中显式指定 -G 和 -A。
理解映射关系：CMake 的 Target 会变成 VS 的 .vcxproj，解决方案则是整个构建树的容器。善用 source_group 能让资源管理器井井有条。
拥抱多配置：不要试图在 VS 生成器中用 CMAKE_BUILD_TYPE 做单配置控制，而要学会使用生成器表达式 $<CONFIG:> 来编写配置无关的构建脚本。
传递 VS 专属属性：通过 VS_GLOBAL_* 和 VS_DEBUGGER_* 等属性，把 VS 才能理解的”本地化表格”在 CMake 中提前填好，实现真正的”一次编写，到处生成”。

下一节，我们将把目光转向 JetBrains 家的 CLion——这位以”智能”著称的跨平台 IDE，又是如何与 CMake 深度握手，并为远程开发场景提供支持的。

测试标签

评分

欢迎为Ta评分