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

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 中使用 的详细信息，请参阅在 Visual Studio 中使用 CMake 预设进行配置和生成CMakePresets.json

有关如何在 Visual Studio Code 中使用 的详细信息，请参阅在 VS Code 中使用 CMake 预设进行配置和生成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 宏扩展。

已弃用的宏

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

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

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

接受的 shell 语法

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