自定义 CMake 生成设置Customize CMake build settings

在 Visual Studio 2019 及更高版本中,可以使用“CMake 设置编辑器”添加配置并自定义其设置 。In Visual Studio 2019 and later, you can add configurations and customize their settings by using the CMake settings editor. 编辑器是手动编辑 CMakeSettings.json 文件的更简单的替代方法,但是如果你希望直接编辑文件,可以单击编辑器右上角的“编辑 JSON”链接 。The editor is intended to be a simpler alternative to manually editing the CMakeSettings.json file, but if you prefer to edit the file directly, you can click the Edit JSON link in the upper right of the editor.

若要添加编辑器,请单击主工具栏的“配置”下拉列表,然后选择“管理配置” 。To open the editor, click on the Configuration drop-down in the main toolbar and choose Manage Configurations.

CMake 配置下拉列表

现在可以看到“设置编辑器”左侧显示了已安装的配置 。Now you see the Settings Editor with the installed configurations on the left.

CMake 设置编辑器

默认情况下,Visual Studio 提供一个 x64-Debug 配置。Visual Studio provides one x64-Debug configuration by default. 可以通过单击绿色加号来添加其他配置。You can add additional configurations by clicking the green plus sign. 在编辑器中看到的设置可能会因所选配置而异。The settings that you see in the editor might vary depending on which configuration is selected.

在编辑器中选择的选项会写入名为 CMakeSettings.json 的文件中 。The options that you choose in the editor are written to a file called CMakeSettings.json. 此文件提供生成项目时传递到 CMake 的命令行参数和环境变量。This file provides command-line arguments and environment variables that are passed to CMake when you build the projects. Visual Studio 绝不会自动修改 CMakeLists.txt;使用 CMakeSettings.json,可通过 Visual Studio 自定义生成,同时使 CMake 项目文件保持不变,以便团队中的其他人可以使用当前工具进行处理 。Visual Studio never modifies CMakeLists.txt automatically; by using CMakeSettings.json you can customize the build through Visual Studio while leaving the CMake project files untouched so that others on your team can consume them with whatever tools they're using.

CMake 常规设置CMake General Settings

“常规”标题下提供了以下设置 :The following settings are available under the General heading:

配置名称Configuration name

对应于“名称”设置 。Corresponds to the name setting. 此名称显示在 C++ 配置下拉列表中。This name appears in the C++ configuration dropdown. 可以使用 ${name} 宏编写其他属性值(如路径)。You can use the ${name} macro to compose other property values such as paths.

配置类型Configuration type

对应于“configurationType”设置 。Corresponds to the configurationType setting. 定义所选生成器的生成配置类型。Defines the build configuration type for the selected generator. 当前支持的值为“Debug”、“MinSizeRel”、“Release”和“RelWithDebInfo”。Currently supported values are "Debug", "MinSizeRel", "Release", and "RelWithDebInfo". 它映射到 CMAKE_BUILD_TYPEIt maps to CMAKE_BUILD_TYPE.

工具集Toolset

对应于“inheritedEnvironments”设置 。Corresponds to the inheritedEnvironments setting. 定义用于生成所选配置的编译器环境。Defines the compiler environment that's used to build the selected configuration. 支持的值取决于配置类型。Supported values depend on the type of configuration. 若要创建自定义环境,请选择“设置编辑器”右上角的“编辑 JSON”链接,然后直接编辑 CMakeSettings.json 文件 。To create a custom environment, choose the Edit JSON link in the upper right corner of the Settings editor, and edit the CMakeSettings.json file directly.

CMake 工具链文件CMake toolchain file

CMake 工具链文件的路径。Path to the CMake toolchain file. 此路径以“-DCMAKE_TOOLCHAIN_FILE = <filepath>”的形式传递给 CMake。This path is passed to CMake as "-DCMAKE_TOOLCHAIN_FILE = <filepath>". 工具链文件指定编译器和工具链实用程序的位置,以及其他目标平台和编译器相关信息。Toolchain files specify locations of compilers and toolchain utilities, and other target platform and compiler related information. 默认情况下,如果未指定此设置,Visual Studio 将使用 vcpkg 工具链文件By default, Visual Studio uses the vcpkg toolchain file if this setting is unspecified.

生成根目录Build root

对应于“buildRoot” 。Corresponds to buildRoot. 映射到 CMAKE_BINARY_DIR,并指定在何处创建 CMake 缓存。Maps to CMAKE_BINARY_DIR, and specifies where to create the CMake cache. 如果指定的文件夹不存在,则创建该文件夹。The specified folder is created if it doesn't exist.

命令参数Command arguments

“命令参数”标题下提供了以下设置 :The following settings are available under the Command arguments heading:

CMake 命令参数CMake command arguments

对应于“cmakeCommandArgs” 。Corresponds to cmakeCommandArgs. 指定传递给 CMake.exe 的任何其他命令行选项Specifies any additional command line options passed to CMake.exe.

生成命令参数Build command arguments

对应于“buildCommandArgs” 。Corresponds to buildCommandArgs. 指定传递给基础生成系统的其他开关。Specifies additional switches to pass to the underlying build system. 例如,在使用 Ninja 生成器时,传递 -v 会强制 Ninja 输出命令行。For example, passing -v when using the Ninja generator forces Ninja to output command lines.

CTest 命令参数CTest command arguments

对应于“ctestCommandArgs” 。Corresponds to ctestCommandArgs. 指定运行测试时传递给 CTest 的其他命令行选项Specifies additional command line options to pass to CTest when running tests.

远程生成的常规设置General settings for remote builds

对于使用远程生成的配置(如 Linux),还提供以下设置:For configurations such as Linux that use remote builds, the following settings are also available:

rsync 命令参数rsync command arguments

传递给 rsync(一种快速通用的文件复制工具)的其他命令行选项。Additional command line options passed to rsync, a fast and versatile file-copying tool.

CMake 变量和缓存CMake variables and cache

通过这些设置,可设置 CMake 变量并将其保存在 CMakeSettings.json 中 。These settings enable you to set CMake variables and save them in CMakeSettings.json. 它们在生成时传递到 CMake,并替代 CMakeLists.txt 文件中的所有值 。They're passed to CMake at build time, and override whatever values are in the CMakeLists.txt file. 你可以按照此部分所述使用 CMakeGUI 来查看可编辑的所有 CMake 变量列表相同。You can use this section in the same way that you might use the CMakeGUI to view a list of all the CMake variables available to edit. 单击“保存并生成缓存”按钮以查看所有可编辑的 CMake 变量列表,包括高级变量(根据 CMakeGUI) 。Click the Save and generate cache button to view a list of all CMake variables available to edit, including advanced variables (per the CMakeGUI). 可以按变量名称筛选列表。You can filter the list by variable name.

对应于“variables” 。Corresponds to variables. 包含以 -D name=value 的形式传递给 CMake 的 CMake 变量名称/值对 。Contains a name-value pair of CMake variables passed as -D name=value to CMake. 如果 CMake 项目生成指令指定将任何变量直接添加到 CMake 缓存文件,那么建议改为在这里添加它们。If your CMake project build instructions specify the addition of any variables directly to the CMake cache file, we recommend you add them here instead.

高级设置Advanced settings

CMake 生成器CMake generator

对应于“generator” 。Corresponds to generator. 映射到 CMake -G 开关并指定要使用的 CMake 生成器Maps to the CMake -G switch, and specifies the CMake generator to use. 编写其他属性时,此属性也可用作宏 ${generator}This property can also be used as a macro, ${generator}, when composing other property values. Visual Studio 当前支持下列 CMake 生成器:Visual Studio currently supports the following CMake generators:

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

由于 Ninja 旨在加快生成速度,而不是提高灵活性和功能,因此它被设为默认生成器。Because Ninja is designed for fast build speeds instead of flexibility and function, it's set as the default. 但是,某些 CMake 项目可能无法使用 Ninja 正确地进行生成。However, some CMake projects may be unable to correctly build using Ninja. 如果发生这种情况,可以指示 CMake 改为生成 Visual Studio 项目。If that occurs, you can instruct CMake to generate a Visual Studio project instead.

IntelliSense 模式IntelliSense mode

IntelliSense 引擎使用的 IntelliSense 模式。The IntelliSense mode used by the IntelliSense engine. 如果未选择任何模式,Visual Studio 将从指定的工具集中继承。If no mode is selected then Visual Studio will inherit from the specified toolset.

安装目录Install directory

CMake 安装目标所在的目录。The directory in which CMake installs targets. 映射到 CMAKE_INSTALL_PREFIXMaps to CMAKE_INSTALL_PREFIX.

CMake 可执行文件CMake executable

CMake 程序可执行文件的完整路径,包括文件名和扩展名。The full path to the CMake program executable, including the file name and extension. 它允许你在 Visual Studio 中使用 CMake 的自定义版本。It allows you to use a custom version of CMake with Visual Studio. 对于远程生成,请在远程计算机上指定 CMake 位置。For remote builds, specify the CMake location on the remote machine.

对于使用远程生成的配置(如 Linux),还提供以下设置:For configurations such as Linux that use remote builds, the following settings are also available:

远程 CMakeLists.txt 根目录Remote CMakeLists.txt root

远程计算机上包含根文件 CMakeLists.txt 的目录 。The directory on the remote machine that contains the root CMakeLists.txt file.

远程安装根目录Remote install root

远程计算机上 CMake 在其中安装目标的目录。The directory on the remote machine in which CMake installs targets. 映射到 CMAKE_INSTALL_PREFIXMaps to CMAKE_INSTALL_PREFIX.

远程复制源Remote copy sources

指定是否将源文件复制到远程计算机,并允许你指定是使用 rsync 还是 sftp。Specifies whether to copy source files to the remote machine, and lets you specify whether to use rsync or sftp.

直接编辑 CMakeSettings.jsonDirectly edit CMakeSettings.json

还可以直接编辑 CMakeSettings.json 以创建自定义配置 。You can also directly edit CMakeSettings.json to create custom configurations. “设置编辑器”的右上角有一个“编辑 JSON”按钮,单击该按钮可打开文件进行编辑 。The Settings Editor has an Edit JSON button in the upper right that opens the file for editing.

下面的示例演示了一个示例配置,可将该配置用作起点:The following example shows a sample configuration, which you can use as a starting point:

    {
      "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 文件 :JSON IntelliSense helps you edit the CMakeSettings.json file:

CMake JSON IntelliSenseCMake JSON IntelliSense

当你选择的设置不兼容时,JSON 编辑器还会进行提示。The JSON editor also informs you when you choose incompatible settings.

有关文件中每个属性的详细信息,请参阅 CMakeSettings.json 架构引用For more information about each of the properties in the file, see CMakeSettings.json schema reference.

Visual Studio 2017 提供多个 CMake 配置,这些配置定义如何调用 CMake.exe 来创建给定项目的 CMake 缓存。Visual Studio 2017 provides several CMake configurations that define how CMake.exe is invoked to create the CMake cache for a given project. 若要添加新的配置,请单击工具栏的下拉列表中的配置,然后选择“管理配置” :To add a new configuration, click the configuration drop-down in the toolbar and choose Manage Configurations:

CMake 管理配置

可从预定义配置列表中进行选择:You can choose from the list of predefined configurations:

CMake 预定义配置

第一次选择配置时,Visual Studio 会在项目的根文件夹中创建一个 CMakeSettings.json 文件 。The first time you select a configuration, Visual Studio creates a CMakeSettings.json file in your project's root folder. 此文件用于重新创建 CMake 缓存文件,例如,在“清除”操作后重新创建 。This file is used to re-create the CMake cache file, for example after a Clean operation.

若要添加其他配置,请右键单击“CMakeSettings.json”,然后选择“添加配置” 。To add an additional configuration, right click CMakeSettings.json and choose Add Configuration.

CMake 添加配置CMake Add configuration

也可使用“CMake 设置编辑器”来编辑文件 。You can also edit the file using the CMake Settings Editor. 右键单击“解决方案资源管理器”中的“CMakeSettings.json”,然后选择“编辑 CMake 设置” 。Right-click on CMakeSettings.json in Solution Explorer and choose Edit CMake Settings. 或者,从顶部的编辑器窗口的配置下拉列表中选择“管理配置” 。Or, select Manage Configurations from the configuration drop-down at the top of the editor window.

还可以直接编辑 CMakeSettings.json 以创建自定义配置 。You can also directly edit CMakeSettings.json to create custom configurations. 下面的示例演示了一个示例配置,可将该配置用作起点:The following example shows a sample configuration, which you can use as a starting point:

    {
      "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 文件 :JSON IntelliSense helps you edit the CMakeSettings.json file:

CMake JSON IntelliSenseCMake JSON IntelliSense

有关文件中每个属性的详细信息,请参阅 CMakeSettings.json 架构引用For more information about each of the properties in the file, see CMakeSettings.json schema reference.

请参阅See also

Visual Studio 中的 CMake 项目CMake Projects in Visual Studio
配置 Linux CMake 项目Configure a Linux CMake project
连接到远程 Linux 计算机Connect to your remote Linux computer
配置 CMake 调试会话Configure CMake debugging sessions
部署、运行和调试 Linux 项目Deploy, run, and debug your Linux project
CMake 预定义配置引用CMake predefined configuration reference