`CMakeSettings.json` 架构参考

项目
10/13/2023

Visual Studio 2017 及更高版本支持 CMake 项目。

文件包含 Visual Studio 为 IntelliSense 使用的信息，并为指定的配置和编译器环境构造它传递给 CMake 的命令行参数CMakeSettings.json。配置指定适用于特定平台和生成类型的属性，例如 x86-Debug 或 Linux-Release。每个配置都指定一个环境，该环境封装有关编译器工具集的信息，例如 MSVC、GCC 或 Clang。 CMake 使用命令行参数为项目重新生成根文件和其他项目文件CMakeCache.txt。可以在文件中覆盖这些值CMakeLists.txt。

可以在 IDE 中添加或删除配置，然后直接在 JSON 文件中对其进行编辑，或使用“CMake 设置编辑器”（Visual Studio 2019 及更高版本）。可以在 IDE 中轻松切换配置，以生成各种项目文件。有关详细信息，请参阅在 Visual Studio 中自定义 CMake 生成设置。

配置

configurations 数组包含 CMake 项目的所有配置。有关预定义配置的详细信息，请参阅 CMake 预定义配置参考。可以向该文件添加任意数量的预定义或自定义配置。

configuration 具有以下属性：

addressSanitizerEnabled：如果为，则使用 AddressSanitizer 编译程序true。在 Linux 上，使用 -fno-omit-frame-pointer 和编译器优化级别 -Os 或 -Oo 进行编译，以获得最佳结果。
addressSanitizerRuntimeFlags：通过 ASAN_OPTIONS 环境变量传递给 AddressSanitizer 的运行时标志。格式：flag1=value:flag2=value2。
buildCommandArgs：指定在 --build -- 后传递给 CMake 的本机生成开关。例如，在使用 Ninja 生成器时，传递 -v 会强制 Ninja 输出命令行。有关 Ninja 命令的详细信息，请参阅 Ninja 命令行参数。
buildRoot：指定 CMake 要在其中为所选生成器生成生成脚本的目录。映射到 -DCMAKE_BINARY_DIR 开关并指定 CMakeCache.txt 的创建位置。如果此文件夹不存在，则创建一个。支持的宏包括 ${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE}。
cacheGenerationCommand：指定命令行工具和参数，例如，指定来生成缓存gencache.bat debug。当用户显式请求重新生成或者修改了 CMakeLists.txt 或 CMakeSettings.json 文件时，系统会从指定环境中的 shell 运行该命令以实现配置。
cacheRoot：指定 CMake 缓存的路径。此目录应包含现有文件CMakeCache.txt。
clangTidyChecks：要传递给 clang-tidy 的警告的逗号分隔列表；可使用通配符，“-”前缀会删除检查。
cmakeCommandArgs：指定调用以生成项目文件时传递给 CMake 的其他命令行选项。
cmakeToolchain：指定工具链文件。使用 -DCMAKE_TOOLCHAIN_FILE 将其传递给 CMake。
codeAnalysisRuleset：指定运行代码分析时要使用的规则集。可以使用完整路径或由 Visual Studio 安装的规则集文件的文件名。
configurationType：为所选生成器指定生成类型配置。可能是以下其中之一：
- Debug
- Release
- MinSizeRel
- RelWithDebInfo
ctestCommandArgs：指定运行测试时传递给 CTest 的其他命令行选项。
description：菜单中显示的此配置的说明。
enableClangTidyCodeAnalysis：使用 Clang-Tidy 进行代码分析。
enableMicrosoftCodeAnalysis：使用 Microsoft 代码分析工具进行代码分析。
generator：指定在此配置中使用的 CMake 生成器。可能是以下其中之一：

仅限 Visual Studio 2019：
- Visual Studio 16 2019
- Visual Studio 16 2019 Win64
- Visual Studio 16 2019 ARM
Visual Studio 2017 及更高版本：
- 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
- Unix Makefiles
- Ninja

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

若要指定 Visual Studio 2017 中的 Visual Studio 生成器，请选择“CMake”|“更改 CMake 设置”，从主菜单打开设置编辑器。删除“Ninja”并输入“V”。此更改会激活 IntelliSense，从而可选择你所需的生成器。

若要指定 Visual Studio 2019 中的 Visual Studio 生成器，请右键单击“解决方案资源管理器”中的 CMakeLists.txt 文件，并选择“项目的 CMake 设置”>“显示高级设置”>“CMake 生成器”。

默认情况下，当活动配置指定一个 Visual Studio 生成器时，会使用 -m -v:minimal 参数调用 MSBuild。若要自定义生成，请使用 CMakeSettings.json 文件中的 buildCommandArgs 属性。在此，你可以指定要传递到生成系统的 MSBuild 命令行参数：

"buildCommandArgs": "-m:8 -v:minimal -p:PreferredToolArchitecture=x64"

installRoot：指定 CMake 要在其中为所选生成器生成安装目标的目录。支持的宏包括 ${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE}。
inheritEnvironments：指定此配置依赖的一个或多个编译器环境。可以是任何自定义环境或预定义环境之一。有关详细信息，请参阅环境。
intelliSenseMode：指定用于计算 IntelliSense 信息的模式。该值可能是以下某个值：
- windows-msvc-x86
- windows-msvc-x64
- windows-msvc-arm
- windows-msvc-arm64
- android-clang-x86
- android-clang-x64
- android-clang-arm
- android-clang-arm64
- ios-clang-x86
- ios-clang-x64
- ios-clang-arm
- ios-clang-arm64
- windows-clang-x86
- windows-clang-x64
- windows-clang-arm
- windows-clang-arm64
- linux-gcc-x86
- linux-gcc-x64
- linux-gcc-arm
name：为配置命名。有关预定义配置的详细信息，请参阅 CMake 预定义配置参考。
wslPath：适用于 Linux 的 Windows 子系统的实例的启动器路径。

适用于 CMake Linux 项目的设置

remoteMachineName：指定托管 CMake、生成和调试程序的远程 Linux 计算机的名称。使用连接管理器添加新的 Linux 计算机。支持的宏包括 ${defaultRemoteMachineName}。
remoteCopySourcesOutputVerbosity：指定将源复制到远程计算机的操作的详细级别。可能是 Normal、Verbose 或 Diagnostic。
remoteCopySourcesConcurrentCopies：指定将源同步到远程计算机期间使用的并发副本数（仅限 sftp）。
remoteCopySourcesMethod：指定将文件复制到远程计算机的方法。可能是 rsync 或 sftp。
remoteCMakeListsRoot：指定包含 CMake 项目的远程计算机上的目录。支持的宏包括 ${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE}。
remoteBuildRoot：指定 CMake 要在其中为所选生成器生成生成脚本的远程计算机上的目录。支持的宏包括 ${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE}。
remoteInstallRoot：指定 CMake 要在其中为所选生成器生成安装目标的远程计算机上的目录。支持的宏包括 ${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator} 和 ${env.VARIABLE}，其中 VARIABLE 是一项环境变量且已在系统、用户或会话级别进行定义。
remoteCopySources：boolean 指定 Visual Studio 是否应将源文件复制到远程计算机。默认值为 true。如果自行管理文件同步，则设置为 false。
remoteCopyBuildOutput：boolean 指定是否要从远程计算机复制生成输出。
remoteCopyAdditionalIncludeDirectories：要从远程计算机复制以支持 IntelliSense 的附加包含目录。格式为“/path1;/path2...”。
remoteCopyExcludeDirectories：不从远程计算机复制的包含目录。格式为“/path1;/path2...”。
remoteCopyUseCompilerDefaults：指定是否使用编译器的默认定义并包含 IntelliSense 的路径。仅当使用的编译器不支持 gcc 样式的参数时，才应为 false。
rsyncCommandArgs：指定传递给 rsync 的命令行选项集。
remoteCopySourcesExclusionList：指定复制源文件时要排除的路径列表的 array：路径可以是文件/目录的名称，或副本根中的相对路径。可使用通配符 * 和 ? 实现 glob 模式匹配。
cmakeExecutable：指定 CMake 程序可执行文件的完整路径，包括文件名和扩展名。
remotePreGenerateCommand：指定在运行 CMake 以分析文件之前要运行的命令CMakeLists.txt。
remotePrebuildCommand：指定生成前要在远程计算机上运行的命令。
remotePostbuildCommand：指定生成后要在远程计算机上运行的命令。
variables：包含以的形式传递给 CMake 的 CMake 变量名称/值对-D name=value。如果 CMake 项目生成指令指定将任意变量直接添加到文件，那么建议改为在这里添加它们CMakeCache.txt。本示例演示如何指定名称/值对以使用 14.14.26428 MSVC 工具集：

"variables": [
    {
      "name": "CMAKE_CXX_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    },
    {
      "name": "CMAKE_C_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    }
  ]

如果不定义 "type"，则默认为 "STRING"。

remoteCopyOptimizations：Visual Studio 2019 16.5 或更高版本的属性，用于对源到远程目标的复制进行控制。默认情况下启用优化。包括 remoteCopyUseOptimizations、rsyncSingleDirectoryCommandArgs 和 remoteCopySourcesMaxSmallChange。

环境

环境封装了在 Visual Studio 用来调用 CMake 的进程中设置的环境变量。对于 MSVC 项目，它捕获开发人员命令提示中为特定平台设置的变量。例如，msvc_x64_x64 环境与使用 -arch=amd64 -host_arch=amd64 自变量运行适用于 VS {version} 的开发人员命令提示相同。可以使用中的 env.{<variable_name>} 语法来引用各个环境变量，例如用于构造文件夹路径CMakeSettings.json。下面提供了一些预定义环境：

linux_arm：远程将 ARM Linux 设为目标。
linux_x64：远程将 x64 Linux 设为目标。
linux_x86：远程将 x86 Linux 设为目标。
msvc_arm：将具有 MSVC 编译器的 ARM Windows 设为目标。
msvc_arm_x64：将具有 64 位 MSVC 编译器的 ARM Windows 设为目标。
msvc_arm64：将具有 MSVC 编译器的 ARM64 Windows 设为目标。
msvc_arm64_x64：将具有 64 位 MSVC 编译器的 ARM64 Windows 设为目标。
msvc_arm64ec：面向具有 MSVC 编译器的 ARM64EC Windows。
msvc_arm64ec_x64：面向具有 64 位 MSVC 编译器的 ARM64EC Windows。
msvc_x64：将具有 MSVC 编译器的 x64 Windows 设为目标。
msvc_x64_x64：将具有 64 位 MSVC 编译器的 x64 Windows 设为目标。
msvc_x86：将具有 MSVC 编译器的 x86 Windows 设为目标。
msvc_x86_x64：将具有 64 位 MSVC 编译器的 x86 Windows 设为目标。

从访问环境变量`CMakeLists.txt`

在 CMakeLists.txt 文件中，语法 $ENV{variable_name} 可引用所有环境变量。若要查看环境的可用变量，请打开相应的命令提示，然后键入 SET。环境变量中的某些信息也可以通过 CMake 系统自检变量获得，但你可能会发现使用环境变量更方便。例如，你可以通过环境变量轻松检索 MSVC 编译器版本或 Windows SDK 版本。

自定义环境变量

你可在 CMakeSettings.json 的 environments 数组中以全局形式或按配置定义自定义环境变量。自定义环境是对一组属性进行分组的一种简便方法。你可以用它来代替预定义的环境，或者扩展或修改预定义的环境。 environments 数组中的每一项都包含以下内容：

namespace：为环境命令，以便可从窗体 namespace.variable 中的配置中引用其变量。默认环境对象称为 env 并由特定系统环境变量（包括 %USERPROFILE%）填充。
environment：唯一标识此组变量。允许稍后在 inheritEnvironments 输入中继承该组。
groupPriority：评估变量时指定这些变量的优先级的整数。优先评估数字较大的项。
inheritEnvironments：指定由该组继承的一组环境的数组值。使用该功能可以继承默认环境，以及创建在运行时传递给 CMake 的自定义环境变量。

在 Visual Studio 2019 版本 16.4 及更高版本中：调试目标会使用你在中指定的环境自动启动CMakeSettings.json。你可以在 launch.vs.json 和 tasks.vs.json 中按目标或按任务覆盖或添加环境变量。

下面的示例定义一个全局变量 BuildDir，该变量在 x86-Debug 和 x64-Debug 配置中继承。每个配置都使用该变量来指定配置的 buildRoot 属性值。也请注意每个配置如何使用 inheritEnvironments 属性来指定仅应用于该配置的值。

{
  // The "environments" property is an array of key-value pairs of the form
  // { "EnvVar1": "Value1", "EnvVar2": "Value2" }
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x86 compiler.
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.BuildDir}\\${name}"    },
    {
      "name": "x64-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x64 compiler.
      "inheritEnvironments": [ "msvc_x64" ],
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

在下一个示例中，x86-Debug 配置为 BuildDir 属性定义其自己的值。此值替代由全局 BuildDir 属性设置的值，以便 BuildRoot 评估为 D:\custom-builddir\x86-Debug。

{
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",

      // The syntax for this property is the same as the global one above.
      "environments": [
        {
          // Replace the global property entirely.
          "BuildDir": "D:\\custom-builddir"
          // This environment does not specify a namespace, hence by default "env" is assumed.
          // "namespace" : "name" would require that this variable be referenced with "${name.BuildDir}".
        }
      ],

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      // Evaluates to "D:\custom-builddir\x86-Debug"
      "buildRoot": "${env.BuildDir}\\${name}"
    },
    {
      "name": "x64-Debug",

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x64" ],
      // Since this configuration doesn't modify BuildDir, it inherits
      // from the one defined globally.
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

宏

以下宏可在中使用CMakeSettings.json：

${workspaceRoot}：工作区文件夹的完整路径
${workspaceHash}：工作区位置的哈希；可用于创建当前工作区的唯一标识符（例如用于文件路径）
${projectFile} - 根文件的完整路径CMakeLists.txt
${projectDir} - 包含根文件的文件夹完整路径CMakeLists.txt
${projectDirName} - 包含根文件的文件夹名称CMakeLists.txt
${thisFile} – CMakeSettings.json 文件的完整路径
${name}：配置的名称
${generator}：配置中使用的 CMake 生成器的名称

对中宏和环境变量的所有引用在传递给 CMake 命令行之前都已展开CMakeSettings.json。

Ninja 命令行参数

如果未指定目标，Ninja 会生成“默认”目标。

C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -?
ninja: invalid option -- `-?'
usage: ninja [options] [targets...]

选项	说明
`--version`	打印 ninja 版本（“1.7.1”）
`-C DIR`	在执行任何其他操作前更改为 DIR
`-f FILE`	指定输入生成文件 (default=`build.ninja`)
`-j N`	以并行方式运行 `N` 作业（default=14，派生自可用 CPU）
`-k N`	持续操作，直到 `N` 作业失败 (default=1)
`-l N`	如果加载平均值大于 `N`，则不要启动新的作业
`-n`	试运行（不运行命令但像命令行运行成功了一样操作）
`-v`	在生成过程中显示所有命令行
`-d MODE`	启用调试（使用 `-d list` 列出模式）
`-t TOOL`	运行次级工具（使用`-t list` 列出次级工具）。终止顶级选项；有更多标志传递给工具
`-w FLAG`	调整警告（使用 `-w list` 列出警告）

`CMakeSettings.json` 架构参考

配置

适用于 CMake Linux 项目的设置

环境

从访问环境变量`CMakeLists.txt`

自定义环境变量

宏

Ninja 命令行参数

反馈

反馈

其他资源

CMakeSettings.json 架构参考

配置

适用于 CMake Linux 项目的设置

环境

从 访问环境变量CMakeLists.txt

自定义环境变量

宏

Ninja 命令行参数

反馈

反馈

其他资源

`CMakeSettings.json` 架构参考

从访问环境变量`CMakeLists.txt`