`CMakePresets.json` 和 `CMakeUserPresets.json` Microsoft 供应商映射

2023-10-12

CMake 支持两个文件（和），用户可以通过它们指定通用配置、生成和测试选项，并与他人共享CMakePresets.jsonCMakeUserPresets.json。

可以使用和在 Visual Studio 中、Visual Studio Code 中、持续集成 (CI) 管道中，以及从命令行驱动 CMakeCMakePresets.jsonCMakeUserPresets.json。

旨在保存项目范围的生成，供开发人员保存其自己的本地生成CMakePresets.jsonCMakeUserPresets.json。这两个文件的架构是相同的。

和支持供应商映射以存储特定于供应商的信息CMakePresets.jsonCMakeUserPresets.json。 Microsoft 维护两个供应商映射，其中包含特定于 Visual Studio 和 Visual Studio Code 的选项。本文介绍两个 Microsoft 供应商映射和供应商宏。有关剩余架构的详细信息，请参阅官方 CMake 文档。它包括有关配置预设、生成预设和测试预设的信息。

有关如何在 Visual Studio 中使用的详细信息，请参阅CMakePresets.json

有关如何在 Visual Studio Code 中使用的详细信息，请参阅CMakePresets.json

Visual Studio 设置供应商映射

每个配置预设允许一个包含供应商 URI microsoft.com/VisualStudioSettings/CMake/<version> 的供应商映射，并且该映射包含特定于 Visual Studio 和 Visual Studio Code 中的 CMake 集成的选项。供应商映射中的所有选项都适用于 Visual Studio。已明确标记适用于 Visual Studio 和 Visual Studio Code 的选项。

Visual Studio 设置供应商映射中的所有设置都是可选的，并且继承自 inherits 键指定的配置预设。仅将已修改的选项写入文件。和都支持 Visual Studio 设置供应商映射CMakePresets.jsonCMakeUserPresets.json。

Visual Studio 设置供应商映射中的选项都不会影响 CMake 或 CTest 命令行的构造。所以可使用同一文件通过 Visual Studio、Visual Studio Code 以及从命令行驱动 CMakeCMakePresets.json。 cacheRoot 和 cmakeGenerateCommand 选项除外。这些选项特定于 Visual Studio 中的打开现有缓存方案，并且不能从命令行复制。

设置	说明
`hostOS`	受支持的操作系统 (OS) 的数组。接受的值为 `Windows`、`Linux` 和 `macOS`。 Visual Studio 和 Visual Studio Code 使用 `hostOS` 的值来隐藏不适用于目标系统 OS 的配置预设，并提供更好的用户体验。如果未指定 `hostOS`，则 Visual Studio 和 Visual Studio Code 将始终显示选择的所有配置预设。此字段也可以是字符串，它等效于包含一个字符串的数组 Visual Studio 和 Visual Studio Code 都支持此选项。
`intelliSenseMode`	指定用于在 Visual Studio 中以 `<target>-<toolset>-<arch>` 格式计算 IntelliSense 信息的模式。接受的值： `android-clang-arm` `android-clang-arm64` `android-clang-x6` `android-clang-x86` `ios-clang-ar` `ios-clang-arm64` `ios-clang-x6` `ios-clang-x86` `linux-gcc-arm` `linux-gcc-x64` `linux-gcc-x86` `windows-clang-arm` `windows-clang-arm64` `windows-clang-x64` `windows-clang-x86` `windows-msvc-arm` `windows-msvc-arm64` `windows-msvc-x64` `windows-msvc-x86` 如果未指定 `intelliSenseMode`，则 Visual Studio 使用与指定的编译器和目标体系结构相匹配的 IntelliSense 模式。 `intelliSenseMode` 通常用于为交叉编译提供改进的 IntelliSense。在 Visual Studio 2019 中，当使用 clang 或 clang-cl 进行生成时，必须显式指定 clang IntelliSense 模式。
`intelliSenseOptions`	其他 IntelliSense 配置选项的映射。 `useCompilerDefaults`：一个 `bool`，用于指定是否使用编译器的默认定义并包含 IntelliSense 的路径。仅当使用的编译器不支持 gcc 样式的参数时，才应为 `false`。默认为 `true`。 `additionalCompilerArgs`：一组用于在 Visual Studio 中控制 IntelliSense 的其他选项。此选项支持宏扩展。
`enableMicrosoftCodeAnalysis`	一个 `bool`，用于在使用 `cl` 或 `clang-cl` 进行生成时，在 Visual Studio 中启用 Microsoft 代码分析。默认为 `false`。
`codeAnalysisRuleset`	指定在 Visual Studio 中运行 Microsoft 代码分析时要使用的规则集。可使用规则集文件的路径，也可以使用随 Visual Studio 一起安装的规则集文件的名称。此选项支持宏扩展。
`disableExternalAnalysis`	一个 `bool`，用于指定是否应在 Visual Studio 中的外部标头上运行代码分析。
`codeAnalysisExternalRuleset`	指定在 Visual Studio 的外部标头上运行 Microsoft 代码分析时要使用的规则集。可使用规则集文件的路径，也可以使用随 Visual Studio 一起安装的规则集文件的名称。此选项支持宏扩展。
`enableClangTidyCodeAnalysis`	一个 bool，用于在使用 `clang-cl` 进行生成时，在 Visual Studio 中启用 clang-tidy 代码分析。默认为 `false`。
`clangTidyChecks`	在 Visual Studio 中运行 clang-tidy 代码分析时，传递给 clang-tidy 的警告列表（以逗号分隔）。可以使用通配符，`-` 前缀将移除检查。
`cacheRoot`	指定 CMake 缓存的路径。此目录应包含现有文件`CMakeCache.txt`。只有 Visual Studio 中的打开现有缓存方案支持此键。此选项支持宏扩展。
`cmakeGenerateCommand`	用于生成 CMake 缓存的命令行工具（指定为命令行程序 + 参数，例如）`gencache.bat debug`。调用 CMake 配置时，此命令使用指定的预设环境在 shell 中运行。只有 Visual Studio 中的打开现有缓存方案支持此键。此选项支持宏扩展。

Visual Studio 远程设置供应商映射

每个配置预设允许一个包含供应商 URI microsoft.com/VisualStudioRemoteSettings/CMake/<version> 的供应商映射，并且该映射包含特定于 Visual Studio 中远程开发的选项。远程开发意味着要对远程 SSH 连接或 WSL 调用 CMake。 Visual Studio 远程设置供应商映射中没有适用于 Visual Studio Code 的选项。

Visual Studio 远程设置供应商映射中的所有设置都是可选的，并且继承自 inherits 键指定的配置预设。仅将已修改的选项写入文件。和都支持 Visual Studio 远程设置供应商映射CMakePresets.jsonCMakeUserPresets.json。

Visual Studio 设置供应商映射中的选项都不会影响 CMake 或 CTest 命令行的构造。所以可使用同一文件通过 Visual Studio、Visual Studio Code 以及从命令行驱动 CMakeCMakePresets.json。

以 WSL1 为目标时，Visual Studio 远程设置供应商映射中的许多选项都将被忽略。这是因为 WSL1 工具集在本地执行所有命令，并依靠安装在 /mnt 文件夹下的 Windows 驱动器从 WSL1 访问本地源文件。不需要源文件复制。已显式标记以 WSL1 为目标时将忽略的选项。

设置	说明
`sourceDir`	远程系统上要将项目复制到的目录的路径。默认为 `$env{HOME}/.vs/$ms{projectDirName}`。此选项支持宏扩展。在远程复制方案中，宏 `${sourceDir}` 的计算结果为远程系统上的项目源目录，而不是 Windows 计算机上的项目源目录。远程复制方案包括以远程 SSH 连接为目标。在这些情况下，远程系统上的项目源目录将由 Visual Studio 远程设置供应商映射中的 `sourceDir` 的值来确定。以 WSL1 为目标时，将忽略此选项。
`copySources`	如果为 `true`，Visual Studio 会将源从 Windows 复制到远程系统。如果自行管理文件同步，则设置为 `false`。默认为 `true`。以 WSL1 为目标时，将忽略此选项。
`copySourcesOptions`	与将源从 Windows 复制到远程系统的操作相关的选项的对象。以 WSL1 为目标时，将忽略此对象。 `copySourcesOptions.exclusionList`：一个列表，其中列出将源文件复制到远程系统时要排除的路径。路径可以是文件或目录的名称，也可以是副本根中的相对路径。默认为 `[ ".vs", ".git", "out" ]`。此选项支持宏扩展。 `copySourcesOptions.method`：用于将源文件复制到远程系统的方法。接受的值为 `rsync` 和 `sftp`。默认为 `rsync`。 `copySourcesOptions.concurrentCopies`：将源同步到远程系统时使用的并发副本数。默认为 `5`。 `copySourcesOptions.outputVerbosity`：将源复制到远程系统的操作的详细级别。接受的级别为 `Normal`、`Verbose` 和 `Diagnostic`。默认为 `Normal`。
`rsyncCommandArgs`	传递给 `rsync` 的命令行参数。默认为 `[ "-t", "--delete", "--delete-excluded" ]`。此选项支持宏扩展，并且在以 WSL1 为目标时将被忽略。
`copyBuildOutput`	指定是否要将生成输出从远程系统复制回到 Windows。默认为 `false`。以 WSL1 为目标时，将忽略此选项。
`copyOptimizations`	与源副本优化相关的选项的对象。以 WSL1 为目标时，将忽略这些选项。 `copyOptimizations.maxSmallChange`：使用 sftp 而不是 rsync 需要复制的最大文件数。默认值为 10。 `copyOptimizations.useOptimizations`：指定正在使用的复制优化。接受的值为“无副本优化”(`None`)、“仅限 rsync 的优化”(`RsyncOnly`) 或“rsync 和 sftp 优化”(`RsyncAndSftp`)。默认为 `RsyncAndSftp`。 `copyOptimizations.rsyncSingleDirectoryCommandArgs`：将单个目录的内容复制到远程系统时传递给 rsync 的命令行参数列表。默认为 `[ "-t", "-d" ]`。此选项支持宏扩展。
`copyAdditionalIncludeDirectoriesList`	一个列表，其中列出要在本地为 Intellisense 复制的远程标头目录的路径。此选项支持宏扩展。
`copyExcludeDirectoriesList`	一个列表，其中列出要在本地为 Intellisense 复制的远程标头目录的路径。此选项支持宏扩展。
`forceWSL1Toolset`	如果为 `true`，则在 Visual Studio 中以 WSL 为目标时，Visual studio 将始终使用 WSL1 工具集。 WSL1 工具集在本地执行所有命令，并依靠安装在 `/mnt` 文件夹下的 Windows 驱动器来从 WSL 访问本地源文件。这些选项可能会因为 WSL2 而变慢。默认为 `false`。在 Visual Studio 2019 版本 16.10 中将始终使用 WSL1 工具集。对 WSL2 的本机支持可用时，此选项才有意义。

远程生成前和生成后事件

采用后，已弃用 remotePrebuildEvent 和 remotePostbuildEvent 选项CMakePresets.json。

在 CMakeLists.txt 中使用 add_custom_command 对预先生成、预链接和后期生成事件进行编码。这会确保通过 Visual Studio 以及从命令行进行生成时具有相同的行为。

如果需要特定于 Visual Studio 的行为，可以在中添加自定义远程任务tasks.vs.json。首先，请在“文件夹视图”的“解决方案资源管理器”中右键单击根，然后选择“配置任务”CMakeLists.txt。然后，你可以将新的远程任务添加到文件tasks.vs.json。

以下远程任务将在远程 Linux 系统上创建一个名为 test 的目录：

{
      "taskLabel": "mkdir",
      "appliesTo": "CMakeLists.txt",
      "type": "remote",
      "command": "mkdir test",
      "remoteMachineName": "localhost"
  }

右键单击任意，然后选择“mkdir”选项来执行此任务CMakeLists.txt。

remoteMachineName 的值必须与“连接管理器”中连接的主机名相匹配。

Microsoft 供应商宏

Visual Studio Settings 和 Visual Studio Remote Settings 这两个 Microsoft 供应商映射都支持 CMake 定义的所有宏。我们的供应商映射支持 CMake 定义的所有宏。有关详细信息，请参阅 cmake-presets 宏扩展。在将所有宏和环境变量传递给 CMake 之前，先对其进行扩展。

Visual Studio 支持具有 ms 前缀的供应商宏。 Microsoft 供应商宏仅可用于 Microsoft 供应商映射。 CMake 不能使用在供应商映射外具有供应商宏的预设。

宏	说明
`$ms{projectDirName}`	计算结果为 Visual Studio 中打开的文件夹的名称。此宏用于在远程复制方案中设置 `sourceDir` 的默认值。 Visual Studio Code 不支持此宏。请改用 `${sourceDirName}`。

环境变量

宏	说明
`$env{<variable-name>}` `$penv{<variable-name>}`	使用 CMake 支持的此语法引用环境变量。有关详细信息，请参阅 cmake-presets 宏扩展。

已弃用的宏

采用 CMakeSettings.json 后，已弃用 CMakePresets.json 支持的一些宏。

使用 CMake 支持的宏来构造文件路径。当你使用这些宏时，它会确保在 Visual Studio 内部以及从命令行运行相同的文件CMakePresets.json。

已弃用的宏	建议
`${projectFile}`	`${sourceDir}/CMakeLists.txt`
`${thisFile}`	`${sourceDir}/CMakePresets.json`

接受的 shell 语法

在 Microsoft 供应商映射中构造 Linux 路径时，请使用 $env{HOME} 语法来引用 $HOME。

通过

CMakePresets.json 和 CMakeUserPresets.json Microsoft 供应商映射