Visual Studio 中的 CMake 项目

CMake 是一种跨平台开源工具，用于定义在多个平台上运行的生成过程。 本文假定你熟悉 CMake。 有关 CMake 的详细信息，请参阅 CMake 文档。 建议从 CMake 教程 开始了解详细信息。

注意

在过去的几个版本中，CMake 已越来越多地与 Visual Studio 集成在一起。 若要查看 Visual Studio 首选项的文档，请使用“版本”选择器控件。 它位于此页面上目录表的顶部。

借助 Visual Studio 对 CMake 的本机支持，你可在 Windows、适用于 Linux 的 Windows 子系统 (WSL) 和远程系统上基于同一 Visual Studio 实例编辑、生成和调试 CMake 项目。 出于 IntelliSense 和浏览的目的，CMake 项目文件（例如 ）直接由 Visual Studio 使用CMakeLists.txt。 Visual Studio 会直接调用 cmake.exe 来配置和生成 CMake。

安装

“用于 Windows 的 C++ CMake 工具”作为“使用 C++ 的桌面开发”和“使用 C++ 的 Linux 开发”工作负载的一部分进行安装。 跨平台 CMake 开发需要适用于 Windows 的 C++ CMake 工具和“使用 C++ 的 Linux 开发”。

在安装程序中，“使用 C++ 进行桌面开发”下拉列表处于选中状态，并且“用于 Windows 的 C++ CMake 工具”也处于选中状态。

有关详细信息，请参阅在 Visual Studio 中安装 C++ Linux 工作负载。

IDE 集成

打开包含 CMakeLists.txt 文件的文件夹时，将发生以下情况。

此对话框包含以下选项：“克隆存储库”、“打开项目或解决方案”、“打开本地文件夹”，或“创建新项目”。 屏幕截图中已标记出“打开本地文件夹”。

• Visual Studio 将“CMake”项添加到“项目”菜单，其中包含用于查看和编辑 CMake 脚本的命令。

• 解决方案资源管理器会显示文件夹结构和文件。

• Visual Studio 会运行 CMake，并为默认配置生成 CMake 缓存文件 ()CMakeCache.txt。 “输出窗口”中显示 CMake 命令行以及 CMake 的其他输出。

• 在后台，Visual Studio 开始对源文件编制索引，以启用 IntelliSense、浏览信息和重构等等。 随着工作进行，Visual Studio 监视器在编辑器和磁盘中随之发生变化，以保持其索引与源同步。

注意

从 Visual Studio 2022 版本 17.1 预览版 2 开始，如果顶级 CMakeLists.txt 存在于子文件夹中，而不是位于工作区根目录中，系统会提示是否要启用 CMake 集成。 有关详细信息，请参阅 CMake 部分激活。

成功生成 CMake 缓存后，还可按目标以逻辑方式查看项目。 在“解决方案资源管理器”工具栏上选择“选择视图”按钮。 在“解决方案资源管理器 - 视图”的列表中，选择“CMake 目标视图”，然后按 Enter 打开目标视图：

选择“解决方案资源管理器”顶部的“显示所有文件”按钮，以查看 out/build/<config> 文件夹中 CMake 生成的所有输出。

如同在任意 CMake 项目中一样，使用每个项目文件夹中的 文件CMakeLists.txt。 可以指定源文件、查找库、设置编译器和链接器选项，以及指定其他与生成系统相关的信息。 若要详细了解 Visual Studio 提供的 CMake 语言服务，请参阅编辑 CMakeLists.txt 文件。

Visual Studio 使用 CMake 配置文件来促使生成和构建 CMake 缓存。 有关详细信息，请参阅配置 CMake 项目和生成 CMake 项目。

若要在调试时将参数传递给可执行文件，可以使用另一个名为 的文件launch.vs.json。 若要详细了解如何在 Visual Studio 中调试跨平台 CMake 项目，请参阅调试 CMake 项目。

Visual Studio 中的 CMake 项目支持大多数 Visual Studio 和 C++ 语言功能。 示例包括：

• CMake 项目的“编辑并继续”功能
• CMake 项目的 Incredibuild 集成
• 对 CMake 项目的 AddressSanitizer 支持
• Clang/LLVM 支持

注意

对于其他类型的“打开文件夹”项目，将使用另外一个 JSON 文件 CppProperties.json。 此文件与 CMake 项目无关。

配置 CMake 项目

可通过 CMake 配置步骤获得项目生成系统。 这等效于从命令行调用 cmake.exe。 若要详细了解 CMake 配置步骤，请参阅 CMake 文档。

Visual Studio 使用 CMake 配置文件来促使生成和构建 CMake。 Visual Studio 2019 版本 16.10 或更高版本支持 CMakePresets.json，它也是推荐的 CMake 配置文件。 CMakePresets.json 受到 CMake 直接支持，它可用于促使通过 Visual Studio、VS Code、持续集成管道和 Windows、Linux 与 Mac 上的命令行来生成和构建 CMake。 若要详细了解 CMakePresets.json，请参阅使用 CMake 预设进行配置和生成。 CMakeSettings.json 适用于使用早期版本的 Visual Studio 的客户。 若要详细了解 CMakeSettings.json，请参阅自定义 CMake 生成设置。

对 CMake 配置文件或 文件进行重大更改时，Visual Studio 会自动运行 CMake 配置步骤CMakeLists.txt。 可以手动调用配置步骤：从工具栏中选择“项目”>“配置缓存”。 还可在“工具”>“选项”>“CMake”>“常规”中更改配置首选项。

已标记出“CMake 配置设置”。“显示 CMake 缓存通知”处于选中状态。 在“缓存过期时:”下，“从不自动运行配置步骤”选项处于选中状态。

如果配置步骤完成且未出错，可用的信息将促进使用 C++ IntelliSense 和语言服务。 这些信息也可在生成和调试操作中使用。

还可在 Visual Studio 中打开现有的 CMake 缓存。 有关详细信息，请参阅打开现有缓存。

自定义配置反馈和通知

默认情况下，除非出现错误，否则将禁止显示大多数配置消息。 若要查看所有消息，请选择“工具”>“选项”>“CMake”>“启用详细 CMake 诊断输出”。

还可取消选择“显示 CMake 缓存通知”来禁用所有 CMake 缓存通知（金色栏）。

排查 CMake 缓存错误

如果需要有关 CMake 缓存状态的详细信息来诊断问题，请打开“项目”主菜单或“解决方案资源管理器”中的 CMakeLists.txt 上下文菜单，运行以下某个命令：

• View CMakeCache.txt 在编辑器中从生成目录打开 CMakeCache.txt 文件。 如果清除缓存，会擦除在此处对 进行的任何编辑CMakeCache.txt。 若要在清除缓存后保留更改，请参阅自定义 CMake 设置或使用 CMake 预设进行配置和生成。

• “删除缓存并重新配置”功能会删除生成目录，然后从干净缓存重新配置。

• “配置缓存”会强制运行生成步骤，即使 Visual Studio 认为环境是最新也是如此。

生成 CMake 项目

可通过 CMake 生成步骤获得一个已生成的项目二叉树。 这等效于从命令行调用 cmake --build。 若要详细了解 CMake 生成步骤，请参阅 CMake 文档。

要生成 CMake 项目，可选择执行以下操作：

1. 在工具栏中，找到“启动项”下拉列表。 选择首选目录，然后按 F5 或选择工具栏上的“运行”按钮。 项目首先自动生成，就像 Visual Studio 解决方案一样。

2. 在解决方案资源管理器中，右键单击 CMake 目标视图处于活动状态的 CMake 目标，然后从上下文菜单选择“生成”。

3. 从主菜单中，选择“生成”>“全部生成”。 请确保已在工具栏的“启动项”下拉列表中选择了 CMake 目标。

生成结果按预期显示在“输出窗口”和“错误列表”中。

可看见有关可能导致数据丢失（例如从浮点转换为整数）的转换的 CMake 生成警告。 :::image-end:::

编辑生成设置

Visual Studio 使用 CMake 配置文件来促使生成 CMake。 CMake 配置文件封装了本机生成工具开关和环境变量等生成选项。 如果 CMakePresets.json 是活动配置文件，请参阅使用 CMake 预设进行配置和生成。 如果 CMakeSettings.json 是活动配置文件，请参阅自定义 CMake 生成设置。 可在 Visual Studio 2019 版本 16.10 或更高版本使用 CMakePresets.json，它是推荐的 CMake 配置文件。

调试 CMake 项目

所有可执行的 CMake 目标都显示在工具栏的“启动项”下拉列表中。 若要开始调试，请选择一个项并在工具栏中按“调试”>“开始调试”按钮。 在 CMake 项目中，“当前文档”选项只对 .cpp 文件有效。

此下拉列表包含以下选项：“显示/隐藏调试目标”、“当前文档”、“示例”（已突出显示）、box2d_tests 和 samples-noGUI。

如果在上次生成后进行了更改，则“调试”或“F5”命令会先生成项目。 如果更改 CMake 配置文件（CMakePresets.json 或 CMakeSettings.json）或 CMakeLists.txt，则会重新生成 CMake 缓存。

可设置 文件中的属性来自定义 CMake 调试会话launch.vs.json。 若要自定义特定目标的调试设置，请在“启动项”下拉列表中选择目标，然后按“调试”>“调试并启动 <活动目标> 的设置”。 若要详细了解 CMake 调试会话，请参阅配置 CMake 调试会话。

CMake 项目的“仅我的代码”

使用 MSVC 编译器为 Windows 生成时，CMake 项目支持“仅我的代码”调试。 若要更改“仅我的代码”设置，请转到“工具”>“选项”>“调试”>“常规”。 有关“仅我的代码”调试的详细信息，请参阅使用“仅我的代码”仅调试用户代码。

CMake 项目的“编辑并继续”功能

使用 MSVC 编译器对 Windows 进行生成时，CMake 项目支持“编辑并继续”功能。 将以下代码添加到 文件中可启用“编辑并继续”功能CMakeLists.txt。 有关“编辑并继续”的详细信息，请参阅配置“编辑并继续”（C#、VB、C++）。

if(MSVC)
  target_compile_options(<target> PUBLIC "/ZI")
  target_link_options(<target> PUBLIC "/INCREMENTAL")
endif()

附加到在 Linux 上运行的 CMake 项目

通过 Visual Studio，可调试在远程 Linux 系统或 WSL 上运行的进程，并使用 GDB 调试程序来调试它。 若要开始，请选择“调试”>“附加到进程…”，将“连接类型”设置为“SSH”，然后从连接管理器中的连接列表中选择你的连接目标。 从可用进程列表中选择一个进程，然后按“附加”。 必须在 Linux 计算机上安装 GDB。 有关 SSH 连接的详细信息，请参阅连接管理器

该对话框中提供了以下选项：“连接类型”（设置为 SSH）、“连接目标”（设置为 demo@ 172. 20. 60. 6），以及可附加到的可用进程列表。

CMake 部分激活

在 Visual Studio 2022 版本 17.1 及更高版本中，如果根文件夹中不包含 CMakeLists.txt 文件，则不会自动启用 CMake 功能。 相反，对话框将提示你是否要为项目启用 CMake 功能。 如果拒绝，CMake 缓存生成不会启动，CMake 配置（CMakeSettings.json 或 CMakePresets.json 中）不会显示在配置下拉列表中。 如果接受，会看到工作区级别的配置文件 CMakeWorkspaceSettings.json（存储在 .vs 目录中），用于指定要为其启用 CMake 的文件夹。 （这些文件夹包含根 CMakeLists.txt 文件）。

接受的属性包括：

properties	说明
enableCMake	为此工作区启用 Visual Studio 的集成。
sourceDirectory	通过 CMakeLists.txt 指定一个或多个目录的字符串或字符串数组。 允许宏（例如 ${workspaceRoot}）。 相对路径基于工作区根目录。 将忽略当前工作区外部的目录。

可以随时通过“项目”>“CMake 工作区设置”菜单命令访问 CMakeWorkspaceSettings.json，即使当前禁用 CMake 功能也是如此。

打开现有缓存

打开现有 CMake 缓存文件 () 时，Visual Studio 不会尝试为你管理缓存和生成树CMakeCache.txt。 自定义或首选工具会完全控制 CMake 配置项目的方式。

可以将现有 CMake 缓存添加到打开的项目中。 执行该操作的方式与添加新配置相同。 有关详细信息，请参阅关于在 Visual Studio 中打开现有缓存的博客文章。

注意

默认的现有缓存体验依赖于 cmake-server，后者已从版本 3.20 中的 CMake 中删除。 若要继续使用 Visual Studio 2019 版本 16.10 及更高版本中的现有缓存功能，请执行以下步骤之一：

• 手动安装 CMake 版本 3.19 或更低版本。 然后，在现有缓存配置中设置 cmakeExecutable 属性，以使用该版本的 CMake。
• 在现有缓存配置中，设置 cacheGenerationCommand 属性，以便让 Visual Studio 请求必要的基于 CMake 文件的 API 文件。 有关该设置的详细信息，请参阅 CMakeSettings.json 引用。
• 在生成缓存时，使用查询文件请求基于 CMake 文件的 API 文件，然后才在 Visual Studio 中将其打开。 如需查询文件说明，请参阅下一节：高级 CMake 缓存故障排除。

高级 CMake 缓存故障排除

Visual Studio 使用 CMake 基于文件的 API（在版本 3.14 及更高版本中）在编辑器中填充特定于项目结构的信息。 有关详细信息，请参阅有关多根目录工作区和基于文件的 API 的 C++ 团队博客文章。

在生成 CMake 缓存之前，自定义或首选工具可能需要在生成输出文件夹（该文件夹包含 CMakeCache.txt）中创建一个名为 .cmake/api/v1/query/client-MicrosoftVS/query.json 的查询文件。 查询文件应包含以下内容：

{"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]}

当自定义或首选工具生成缓存时，CMake 将文件置于 下，Visual Studio 使用它在编辑器中填充特定于项目结构的信息.cmake/api/v1/response。

编辑 CMakeLists.txt 文件

若要编辑 CMakeLists.txt 文件，请右键单击“解决方案资源管理器”中的文件，并选择“打开”。 如果对文件进行更改，会显示一个黄色的状态栏，通知用户 IntelliSense 将更新。 可以选择取消该更新操作。 有关 的信息，请参阅 CMake 文档CMakeLists.txt。

该文件包含以下行：project (hello-cmake)、add_subdirectory (tests)、add_executable (hello hello.cpp) 和 install (TARGETS hello DESTINATION hello/bin)。 窗口顶部的消息显示，C++ IntelliSense 信息将在 CMake 生成完缓存后刷新。

保存文件后，配置步骤立即自动再次运行，并在“输出”窗口中显示信息。 错误和警告显示在“错误列表”或“输出”窗口中。 双击“错误列表”中的错误可导航到 CMakeLists.txt 中出现问题的行。

突出显示了 CMakeLists.txt 第 3 行的 CMake 错误消息。 详细信息是 CMake 找不到 sqlite3 提供的包配置文件。 CMake 在 CMAKE_MODULE_PATH 中查找了该配置文件，但未找到。 提供的建议是将安装前缀“sqlite3”添加到 CMAKE_PREFIX_PATH 或将 sqlite3_DIR 设置为包含 sqlite3Config.cmake 和/或 sqlitet3-config.cmake 的目录。

CMake 的语言服务

可在 Visual Studio 2019 版本 16.5 或更高版本中使用 CMake 的语言服务。 它通过 CMake 脚本文件中的 CMake 变量、函数和目标支持“转到定义”、“速览定义”和“查找所有引用”等代码导航功能。 有关详细信息，请参阅 CMake 脚本的代码导航。

显示了找到 SUPERTUX_SOURCES_CXX 的结果。 例如，在 list(SORT SSUPERTUX_SOURCES_CXX)、file(GLOB SUPERTUX_SOURCES_CXX) 等中。

CMake 项目操作

在 Visual Studio 2019 版本 16.5 或更高版本中使用 CMake 项目操作。 通过项目操作，无需手动编辑 CMake 脚本即可添加、删除和重命名 CMake 项目中的源文件和目标。 在解决方案资源管理器中添加或删除文件时，Visual Studio 会自动编辑 CMake 项目。 可以在多个位置添加或删除对 CMake 脚本的引用。 如果是这样，Visual Studio 会询问你想要在何处进行更改，并显示建议的更改预览。 有关分步说明，请参阅添加、删除和重命名 CMake 项目中的文件和目标。

树视图显示了 CMakeLists.txt，其下有两个项：add_executable 和 set。 已选中“set”。 预览窗口显示了将进行更改的位置。 突出显示了行 set (PROJECT_SRC "CmakeProject4.cpp" "CMakeProject4.h" "Demo.cpp") 中的 "Demo.cpp"。 可按“应用”按钮以接受更改，或按“取消”按钮以取消。

CMake 项目的 IntelliSense

默认情况下，Visual Studio 会使用与活动 CMake 配置指定的编译器和目标体系结构匹配的 IntelliSense 模式。

如果 CMakePresets.json 是活动的 CMake 配置文件，则可在 Visual Studio 设置供应商映射中使用 intelliSenseMode 和 intelliSenseOptions 指定 IntelliSense 选项。 有关详细信息，请查看 Visual Studio 设置供应商映射参考。

如果 CMakeSettings.json 是活动的 CMake 配置文件，则可以使用 CMakeSettings.json 中的 intelliSenseMode 指定 IntelliSense 选项。 有关详细信息，请参阅 CMakeSettings.json 参考。

使用 CMake 工具链文件配置 IntelliSense

在 Visual Studio 2019 版本 16.9 及更高版本中，使用 CMake 工具链文件时，Visual Studio 会根据 CMake 变量在 CMake 项目中自动配置 IntelliSense。 有关详细信息，请参阅使用 CMake 工具链文件配置 IntelliSense。

Vcpkg 集成

在 Visual Studio 中打开的 CMake 项目与跨平台 C/C++ 依赖项管理器 vcpkg 进行集成。 在将 vcpkg 和 Visual Studio 配合使用之前，必须运行 vcpkg integrate install。 有关 vcpkg 的说明和详细信息，请参阅：

• 在 Visual Studio 中使用 CMake 安装和管理包
• CMake 项目中的 vcpkg

如果 CMakeSettings.json 是活动的配置文件，Visual Studio 会自动将 vcpkg 工具链文件 (vcpkg.cmake) 传递至 CMake。 在 CMake 设置配置中指定任何其他工具链时，此行为会自动禁用。

如果 CMakePresets.json 是活动的配置文件，则需要在 CMakePresets.json 中将路径设置为 vcpkg.cmake。 建议使用环境变量 VCPKG_ROOT 而不是绝对路径来保持文件可共享。 有关详细信息，请参阅启用 vcpkg 与 CMake 预设的集成。 可在 Visual Studio 2019 版本 16.10 或更高版本使用 CMakePresets.json，它是推荐的 CMake 配置文件。

从命令行运行 CMake

如果 CMakePresets.json 是活动的 CMake 配置文件，可在 Visual Studio 之外轻松重现本地生成。 有关详细信息，请参阅通过命令行或 CI 管道运行 CMake。 Visual Studio 2019 版本 16.10 或更高版本中支持 CMakePresets.json，它也是推荐的 CMake 配置文件。

如果 CMakeSettings.json 是活动的 CMake 配置文件，则需要手动将 CMakeSettings.json 文件中编码的参数传递给 CMake。 如果已从 Visual Studio 安装程序安装 CMake，可以通过执行以下步骤从命令行运行它：

1. 运行相应的 文件 (x86/x64)vsdevcmd.bat。 有关详细信息，请参阅在命令行上生成。

2. 切换到输出文件夹。

3. 运行 CMake 以生成或配置应用。

另请参阅

教程：在 Visual Studio 中创建 C++ 跨平台项目
配置 Linux CMake 项目
连接到远程 Linux 计算机
自定义 CMake 生成设置
CMakeSettings.json 架构参考
配置 CMake 调试会话
部署、运行和调试 Linux 项目
CMake 预定义配置引用
CMake 项目中的 vcpkg
在 Visual Studio 中使用 CMake 安装和管理包