自定义 CMake 生成设置

项目
10/21/2023

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 文件进行 CMake 生成配置的项目，Visual Studio 2019 及更高版本提供 CMake 设置编辑器。使用该编辑器，可以添加 CMake 配置并轻松自定义其设置。它旨在成为手动编辑 CMakeSettings.json 文件的更简单替代方法。但是，如果喜欢直接编辑该文件，可以选择编辑器右上角的“编辑 JSON”链接。

若要打开 CMake 设置编辑器，请选择主工具栏的“配置”下拉列表，然后选择“管理配置”。

Screenshot of the CMake configuration drop-down. Manage Configurations is highlighted.

现在可以看到“设置编辑器”左侧显示了已安装的配置。

Screenshot of the CMake settings editor.

默认情况下，Visual Studio 提供一个 x64-Debug 配置。可以通过选择绿色加号来添加更多配置。在编辑器中看到的设置可能会因所选配置而异。

在编辑器中选择的选项会写入名为 CMakeSettings.json 的文件。此文件提供生成项目时传递到 CMake 的命令行参数和环境变量。 Visual Studio 绝不会自动修改 CMakeLists.txt；使用 CMakeSettings.json，可通过 Visual Studio 自定义生成，同时使 CMake 项目文件保持不变，以便团队中的其他人可以使用当前工具进行处理。

CMake 常规设置

“常规”标题下提供了以下设置：

配置名称

对应于“名称”设置。此名称显示在 C++ 配置下拉列表中。可以使用 ${name} 宏编写其他属性值（如路径）。

配置类型

对应于“configurationType”设置。定义所选生成器的生成配置类型。当前支持的值为 Debug、MinSizeRel、Release 和 RelWithDebInfo。它映射到 CMAKE_BUILD_TYPE。

工具集

对应于“inheritedEnvironments”设置。定义用于生成所选配置的编译器环境。支持的值取决于配置类型。若要创建自定义环境，请选择“设置编辑器”右上角的“编辑 JSON”链接，然后直接编辑 CMakeSettings.json 文件。

CMake 工具链文件

CMake 工具链文件的路径。此路径以“-DCMAKE_TOOLCHAIN_FILE = <filepath>”的形式传递给 CMake。工具链文件指定编译器和工具链实用程序的位置，以及其他目标平台和编译器相关信息。默认情况下，如果未指定此设置，Visual Studio 将使用 vcpkg 工具链文件。

生成根目录

对应于“buildRoot”。映射到 CMAKE_BINARY_DIR，并指定在何处创建 CMake 缓存。如果指定的文件夹不存在，则创建该文件夹。

命令参数

“命令参数”标题下提供了以下设置：

CMake 命令参数

对应于“cmakeCommandArgs”。指定传递给 CMake 的任何其他命令行选项。

生成命令参数

对应于“buildCommandArgs”。指定传递给基础生成系统的更多开关。例如，在使用 Ninja 生成器时，传递 -v 会强制 Ninja 输出命令行。

CTest 命令参数

对应于“ctestCommandArgs”。指定运行测试时传递给 CTest 的更多命令行选项。

远程生成的常规设置

对于使用远程生成的配置（如 Linux），还提供以下设置：

`rsync` 命令参数

传递给 rsync（一种快速通用的文件复制工具）的其他命令行选项。

CMake 变量和缓存

通过这些设置，可设置 CMake 变量并将其保存在 CMakeSettings.json 中。它们在生成时传递给 CMake，并替代 CMakeLists.txt 文件中的任何值。你可以按照此部分所述使用 CMakeGUI 来查看可编辑的所有 CMake 变量列表相同。选择“保存并生成缓存”按钮以查看所有可编辑的 CMake 变量列表，包括高级变量（根据 CMakeGUI）。可以按变量名称筛选列表。

对应于“variables”。包含以 -D name=value 的形式传递给 CMake 的 CMake 变量名称/值对。如果 CMake 项目生成指令指定将任何变量直接添加到 CMake 缓存文件，那么建议改为在这里添加它们。

高级设置

CMake 生成器

对应于“generator”。映射到 CMake-G 开关，并指定要使用的 CMake 生成器。编写其他属性时，此属性也可用作宏 ${generator}。 Visual Studio 当前支持下列 CMake 生成器：

"Ninja"
“Unix 生成文件”
“Visual Studio 16 2019”
“Visual Studio 16 2019 Win64”
“Visual Studio 16 2019 ARM”
"Visual Studio 15 2017"
"Visual Studio 15 2017 Win64"
"Visual Studio 15 2017 ARM"
"Visual Studio 14 2015"
"Visual Studio 14 2015 Win64"
"Visual Studio 14 2015 ARM"

由于 Ninja 旨在加快生成速度，而不是提高灵活性和功能，因此它被设为默认生成器。但是，某些 CMake 项目可能无法使用 Ninja 正确地进行生成。如果发生这种情况，可以指示 CMake 改为生成 Visual Studio 项目。

IntelliSense 模式

IntelliSense 引擎使用的 IntelliSense 模式。如果未选择任何模式，Visual Studio 将从指定的工具集继承模式。

安装目录

CMake 安装目标所在的目录。映射到 CMAKE_INSTALL_PREFIX。

CMake 可执行文件

CMake 程序可执行文件的完整路径，包括文件名和扩展名。它允许你在 Visual Studio 中使用 CMake 的自定义版本。对于远程生成，请在远程计算机上指定 CMake 位置。

对于使用远程生成的配置（如 Linux），还提供以下设置：

远程 CMakeLists.txt 根目录

远程计算机上包含根 CMakeLists.txt 文件的目录。

远程安装根目录

远程计算机上 CMake 在其中安装目标的目录。映射到 CMAKE_INSTALL_PREFIX。

远程复制源

指定是否将源文件复制到远程计算机，并允许你指定是使用 rsync 还是 sftp。

直接编辑 CMakeSettings.json

还可以直接编辑 CMakeSettings.json 以创建自定义配置。 “设置编辑器”的右上角有一个“编辑 JSON”按钮，单击该按钮可打开文件进行编辑。

下面的示例演示了一个示例配置，可将该配置用作起点：

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

可借助 JSON IntelliSense 编辑 CMakeSettings.json 文件：

Screenshot of the CMake JSON IntelliSense pop-up in the editor.

当你选择的设置不兼容时，JSON 编辑器还会进行提示。

有关文件中每个属性的详细信息，请参阅 CMakeSettings.json 架构引用。

Visual Studio 2017 提供多个 CMake 配置，这些配置定义如何调用 CMake 来创建给定项目的 CMake 缓存。若要添加新的配置，请选择工具栏中的配置下拉列表，然后选择“管理配置”：

Screenshot of Manage configurations selected in the drop-down.

可从预定义配置列表中进行选择：

Add Configuration to CMake Settings dialog list of predefined configurations.

第一次选择配置时，Visual Studio 会在项目的根文件夹里创建一个 CMakeSettings.json 文件。此文件用于重新创建 CMake 缓存文件，例如，在“清除”操作后重新创建。

要添加其他配置，请右键单击 CMakeSettings.json，然后选择“添加配置”。

Screenshot of the shortcut menu with Add configuration selected.

也可使用“CMake 设置编辑器”来编辑文件。右键单击“解决方案资源管理器”中的 CMakeSettings.json，然后选择“编辑 CMake 设置”。或者，从顶部的编辑器窗口的配置下拉列表中选择“管理配置”。

还可以直接编辑 CMakeSettings.json 以创建自定义配置。下面的示例演示了一个示例配置，可将该配置用作起点：

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

可借助 JSON IntelliSense 编辑 CMakeSettings.json 文件：

Screenshot of the CMake JSON IntelliSense pop-up in the editor.

有关文件中每个属性的详细信息，请参阅 CMakeSettings.json 架构引用。

另请参阅

Visual Studio 中的 CMake 项目
 配置 Linux CMake 项目
 连接到远程 Linux 计算机
 配置 CMake 调试会话
 部署、运行和调试 Linux 项目
 CMake 预定义配置引用

自定义 CMake 生成设置

CMake 常规设置

配置名称

配置类型