Visual Studio 中的 CMake 项目

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

备注

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

“用于 Windows 的 C++ CMake 工具”组件使用“打开文件夹”功能,以直接将 CMake 项目文件(例如 CMakeLists.txt)用于 IntelliSense 和浏览。 支持 Ninja 和 Visual Studio 生成器。 如果使用 Visual Studio 生成器,则它会生成临时项目文件,并将它传递给 MSBuild。 但是,从不会加载项目来用于 IntelliSense 或浏览。 还可以导入现有 CMake 缓存。

安装

“用于 Windows 的 C++ CMake 工具”作为“使用 C++ 的桌面开发”和“使用 C++ 的 Linux 开发”工作负载的一部分进行安装。 有关详细信息,请参阅跨平台 CMake 项目

已选中“C++”下拉列表且已调用“用于 Windows 的 C++ C Make 工具”选项的桌面开发的屏幕截图。

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

IDE 集成

选择“文件”>“打开”>“文件夹”打开一个包含 CMakeLists.txt 文件的文件夹时,将发生以下情况:

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

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

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

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

可以打开包含任意数量 CMake 项目的文件夹。 Visual Studio 检测并配置工作区中的所有“根”CMakeLists.txt 文件。 CMake 操作(配置、生成、调试)、C++ IntelliSense 和浏览可用于工作区中的所有 CMake 项目。

包含多个根的 CMake 项目。

还可按目标查看经过逻辑组织的项目。 在“解决方案资源管理器”工具栏中,从下拉列表中选择“目标视图” :

“CMake 目标视图”按钮。

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

Visual Studio 使用名为 CMakeSettings.json 的配置文件。 此文件使你可以定义和存储多个生成配置,并且可在 IDE 中方便地切换它们。 配置是一种 Visual Studio 构造,用于封装特定于给定生成类型的设置。 这些设置用于配置 Visual Studio 传递给 CMake 的默认命令行选项。 还可以在此处指定其他 CMake 选项,并定义所需的所有其他变量。 所有选项都作为内部或外部变量写入 CMake 缓存。 在 Visual Studio 2019 中,CMake 设置编辑器 提供一种简便方法来编辑设置。 有关详细信息,请参阅自定义 CMake 设置

一个设置 (intelliSenseMode) 不会传递给 CMake,而是仅供 Visual Studio 使用。

如同在任意 CMake 项目中一样,使用每个项目文件夹中的 CMakeLists.txt 文件。 可以指定源文件、查找库、设置编译器和链接器选项,以及指定其他与生成系统相关的信息。

若要在调试时将参数传递给可执行文件,可以使用另一个名为 launch.vs.json 的文件。 在某些情况中,Visual Studio 会自动生成这些文件。 可以手动编辑它们,甚至可以自己创建文件。

备注

对于其他类型的“打开文件夹”项目,将使用另外两个 JSON 文件:CppProperties.jsontasks.vs.json 。 这些都与 CMake 项目无关。

打开现有缓存

打开现有 CMake 缓存文件 (CMakeCache.txt) 时,Visual Studio 不会尝试为你管理缓存和生成树。 自定义或首选工具会完全控制 CMake 配置项目的方式。 若要在 Visual Studio 中打开现有缓存,请选择“文件”>“打开”>“CMake”。 然后,导航到现有 CMakeCache.txt 文件。

可以将现有 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 将文件置于 .cmake/api/v1/response 下,Visual Studio 使用它在编辑器中填充特定于项目结构的信息。

生成 CMake 项目

要生成 CMake 项目,可选择执行以下操作:

  1. 在“常规”工具栏中,找到“配置”下拉菜单。 默认情况下,它可能显示“x64-Debug”。 选择首选配置,然后按 F5 或选择工具栏上的“运行”(绿色三角形)按钮 。 项目首先自动生成,就像 Visual Studio 解决方案一样。

  2. 右键单击 CMakeLists.txt,并从上下文菜单中选择“生成”。 如果在文件夹结构中有多个目标,可以选择生成所有目标或仅生成某个特定目标。

  3. 从主菜单中选择“生成”>“全部生成”(F7 或 Ctrl+Shift+B) 。 请确保已在“常规”工具栏的“启动项”下拉列表中选择了 CMake 目标 。

CMake 生成菜单命令。

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

CMake 生成错误。

在包含多个生成目标的文件夹中,可以指定要生成的 CMake 目标:在“CMake”菜单或 CMakeLists.txt 上下文菜单上选择“生成”项 。 如果在 CMake 项目中按 Ctrl+Shift+B,则会生成当前活动文档。

调试 CMake 项目

若要调试 CMake 项目,请选择首选配置并按 F5,或按工具栏中的“运行”按钮 。 如果“运行”按钮提示“选择启动项”,请选择下拉箭头。 选择要运行的目标。 (在 CMake 项目中,“当前文档”选项只对 .cpp 文件有效。)

CMake 运行按钮。

如果在上次生成后进行了更改,则“运行”或“F5”命令会先生成项目 。 对 CMakeSettings.json 进行更改会导致重新生成 CMake 缓存。

可设置 launch.vs.json 文件中的属性来自定义 CMake 调试会话。 有关更多信息,请参阅配置 CMake 调试会话

CMake 项目的“仅我的代码”

使用 MSVC 编译器为 Windows 生成时,CMake 项目支持“仅我的代码”调试。 若要更改“仅我的代码”设置,请转到“工具” > “选项” > “调试” > “常规”。

Vcpkg 集成

如果已安装 vcpkg,则在 Visual Studio 中打开的 CMake 项目将自动集成 vcpkg 工具链文件。 这意味着,无需其他配置即可将 vcpkg 与 CMake 项目结合使用。 此支持适用于本地 vcpkg 安装和所面向的远程系统上的 vcpkg 安装。 在 CMake 设置配置中指定任何其他工具链时,此行为会自动禁用。

自定义配置反馈

默认情况下,除非出现错误,否则将禁止显示大多数配置消息。 可以通过在“工具” > “选项” > “CMake”中启用此功能来查看所有消息。

配置 CMake 诊断选项。

编辑 CMakeLists.txt 文件

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

CMakeLists.txt 文件编辑。

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

CMakeLists.txt 文件错误。

CMake 配置步骤

如果对 CMakeSettings.jsonCMakeLists.txt 文件进行了重大更改,Visual Studio 会自动重新运行 CMake 配置步骤 。 如果配置步骤正确完成,则可在 C++ IntelliSense 和语言服务使用所收集的信息。 这些信息也可在生成和调试操作中使用。

排查 CMake 缓存错误

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

  • “查看缓存”功能会从编辑器的生成根文件夹中打开 CMakeCache.txt 文件。 (如果清除缓存,则将擦除在此处对 CMakeCache.txt 进行的任何编辑。 若要在清除缓存后依然保留更改,请参阅自定义 CMake 设置。)

  • 打开缓存文件夹:打开生成根文件夹的资源管理器窗口。

  • 清理缓存:删除生成根文件夹,使下一个 CMake 配置步骤从清理缓存开始。

  • 生成缓存:即使 Visual Studio 认为环境是最新的,也强制运行生成步骤。

可在“工具”>“选项”>“CMake”>“常规”对话框中禁用自动缓存生成。

从命令行运行 CMake

如果已从 Visual Studio 安装程序安装 CMake,可以通过执行以下步骤从命令行运行它:

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

  2. 切换到输出文件夹。

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

Visual Studio 2017 具有对 CMake 的丰富支持,包括跨平台 CMake 项目。 “Visual C++ Tools for CMake”组件使用“打开文件夹”功能,让 IDE 能够直接将 CMake 项目文件(例如 CMakeLists.txt)用于 IntelliSense 和浏览 。 支持 Ninja 和 Visual Studio 生成器。 如果使用 Visual Studio 生成器,则它会生成临时项目文件,并将它传递给 MSBuild。 但是,从不会加载项目来用于 IntelliSense 或浏览。 还可以导入现有 CMake 缓存。

安装

“Visual C++ Tools for CMake”作为“使用 C++ 的桌面开发”和“使用 C++ 的 Linux 开发”工作负载的一部分进行安装。

已调用“适用于 C make 的 Visual C++ 工具”选项的“单个组件”选项卡的屏幕截图。

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

IDE 集成

选择“文件”>“打开”>“文件夹”打开一个包含 CMakeLists.txt 文件的文件夹时,将发生以下情况:

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

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

  • Visual Studio 运行 CMake 并根据需要生成默认配置(即 x86 Debug)的 CMake 缓存。 “输出窗口”中显示 CMake 命令行以及 CMake 的其他输出。

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

可以打开包含任意数量 CMake 项目的文件夹。 Visual Studio 检测并配置工作区中的所有“根”CMakeLists.txt 文件。 CMake 操作(配置、生成、调试)、C++ IntelliSense 和浏览可用于工作区中的所有 CMake 项目。

包含多个根的 CMake 项目。

还可按目标查看经过逻辑组织的项目。 在“解决方案资源管理器”工具栏中,从下拉列表中选择“目标视图” :

“CMake 目标视图”按钮。

Visual Studio 使用名为 CMakeSettings.json 的文件存储 CMake 的环境变量或命令行选项。 借助 CMakeSettings.json 还可定义和存储多个 CMake 生成配置。 可以在 IDE 中方便地切换它们。

否则,请使用 CMakeLists.txt 来指定源文件、查找库、设置编译器和链接器选项(就像在任何 CMake 项目中进行操作一样),以及指定其他与生成系统相关的信息。

如果需要在调试时将参数传递给可执行文件,可以使用另一个名为 launch.vs.json 的文件。 在某些情况中,Visual Studio 会自动生成这些文件。 可以手动编辑它们,甚至可以自己创建文件。

备注

对于其他类型的“打开文件夹”项目,将使用另外两个 JSON 文件:CppProperties.jsontasks.vs.json 。 这些都与 CMake 项目无关。

<a name="import-an-existing-cache">导入现有缓存

导入现有 CMakeCache.txt 文件时,Visual Studio 自动提取自定义的变量,并基于这些变量创建一个预填充的 CMakeSettings.json 文件 。 不会以任何方式修改原始缓存。 仍可从命令行或者借助用于生成原始缓存的任何工具或 IDE 使用该原始缓存。 新的 CMakeSettings.json 文件与项目的根 CMakeLists.txt 放在一起 。 Visual Studio 基于设置文件生成新的缓存。 可在“工具”>“选项”>“CMake”>“常规”对话框中替代自动缓存生成。

并非缓存中的所有内容都会被导入。 生成器和编译器的位置等属性替换为已知适合用于 IDE 的默认值。

导入现有缓存

  1. 从主菜单中选择“文件”>“打开”>“CMake”:

    ![打开 CMake。](media/cmake-file-open.png "文件、打开、CMake")

    此命令会显示“从缓存导入 CMake”向导。

  2. 导航到要导入的 CMakeCache.txt 文件,然后选择“确定”。 “从缓存导入 CMake 项目”向导随即显示:

    导入 CMake 缓存。

    在向导完成时,可在“解决方案资源管理器”中看到新的 CMakeCache.txt 文件,位于项目中的根 CMakeLists.txt 文件旁边。

生成 CMake 项目

要生成 CMake 项目,可选择执行以下操作:

  1. 在“常规”工具栏中,找到“配置”下拉菜单。 默认情况下,它可能显示“Linux-Debug”或“x64-Debug”。 选择首选配置,然后按 F5 或选择工具栏上的“运行”(绿色三角形)按钮 。 项目首先自动生成,就像 Visual Studio 解决方案一样。

  2. 右键单击“解决方案资源管理器”中的 CMakeLists.txt,并从上下文菜单中选择“生成” 。 如果在文件夹结构中有多个目标,可以选择生成所有目标或仅生成某个特定目标。

  3. 从主菜单中选择“生成”>“生成解决方案”(F7 或 Ctrl+Shift+B) 。 请确保已在“常规”工具栏的“启动项”下拉列表中选择了 CMake 目标 。

CMake 生成菜单命令。

可以在 CMakeSettings.json 文件中自定义生成配置、环境变量、命令行参数和其他设置。 由此可进行更改,而无需修改 CMakeLists.txt 文件。 有关详细信息,请参阅自定义 CMake 设置

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

CMake 生成错误。

在包含多个生成目标的文件夹中,可以指定要生成的 CMake 目标:在“CMake”菜单或 CMakeLists.txt 上下文菜单上选择“生成”项 。 如果在 CMake 项目中按 Ctrl+Shift+B,则会生成当前活动文档。

调试 CMake 项目

若要调试 CMake 项目,请选择首选配置并按 F5。 或按工具栏中的“运行”按钮。 如果“运行”按钮提示“选择启动项”,请选择向下箭头并选择要运行的目标。 (在 CMake 项目中,“当前文档”选项只对 .cpp 文件有效。)

CMake 运行按钮。

如果在上次生成后进行了更改,则“运行”或“F5”命令会先生成项目 。

可设置 launch.vs.json 文件中的属性来自定义 CMake 调试会话。 有关更多信息,请参阅配置 CMake 调试会话

编辑 CMakeLists.txt 文件

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

CMakeLists.txt 文件编辑。

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

CMakeLists.txt 文件错误。

CMake 配置步骤

如果对 CMakeSettings.jsonCMakeLists.txt 文件进行了重大更改,Visual Studio 会自动重新运行 CMake 配置步骤 。 如果配置步骤正确完成,则可在 C++ IntelliSense 和语言服务使用所收集的信息。 这些信息也可在生成和调试操作中使用。

多个 CMake 项目可以使用相同的 CMake 配置名称(例如,x86-Debug)。 在选择该配置时会配置并生成所有这些项目(在其自己的生成根文件夹中)。 可以调试参与该 CMake 配置的所有 CMake 项目中的目标。

CMake“仅生成”菜单项。

可以将生成和调试会话限制为工作区中的项目子集。 在 CMakeSettings.json 文件中创建具有唯一名称的新配置。 然后,将该配置仅应用于这些项目。 如果选择了该配置,则 IntelliSense 以及生成和调试命令仅应用于这些指定项目。

排查 CMake 缓存错误

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

  • “查看缓存”功能会从编辑器的生成根文件夹中打开 CMakeCache.txt 文件。 (如果清除缓存,则将擦除在此处对 CMakeCache.txt 进行的任何编辑。 若要在清除缓存后依然保留更改,请参阅自定义 CMake 设置。)

  • 打开缓存文件夹:打开生成根文件夹的资源管理器窗口。

  • 清理缓存:删除生成根文件夹,使下一个 CMake 配置步骤从清理缓存开始。

  • 生成缓存:即使 Visual Studio 认为环境是最新的,也强制运行生成步骤。

可在“工具”>“选项”>“CMake”>“常规”对话框中禁用自动缓存生成。

单个文件编译

若要在 CMake 项目中编译单个文件,可在“解决方案资源管理器”中右键单击该文件。 从弹出菜单中选择“编译”。 通过使用 CMake 主菜单,还可生成当前在编辑器中打开的文件:

CMake 单个文件编译。

从命令行运行 CMake

如果已从 Visual Studio 安装程序安装 CMake,可以通过执行以下步骤从命令行运行它:

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

  2. 切换到输出文件夹。

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

在 Visual Studio 2015 中,Visual Studio 用户可使用 CMake 生成器生成 MSBuild 项目文件,IDE 之后可将该项目文件用于 IntelliSense、浏览和编译。

请参阅

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