`CMakeSettings.json` Справочник схем

Статья
04/03/2023

Проекты CMake поддерживаются в Visual Studio версии 2017 и более поздних.

Файл CMakeSettings.json содержит сведения, которые Visual Studio использует для IntelliSense и для формирования аргументов командной строки, передаваемых в программу CMake для указанной конфигурации и среды компилятора. Конфигурация определяет свойства, которые применяются к конкретной платформе и типу сборки, например x86-Debug или Linux-Release. Каждая конфигурация задает среду, которая инкапсулирует сведения о наборе инструментов компилятора, например MSVC, GCC или Clang. CMake использует аргументы командной строки для повторного создания корневого файла CMakeCache.txt и других файлов проекта. Значения в файлах CMakeLists.txt можно переопределять.

Конфигурации можно добавлять или удалять в интегрированной среде разработки, а затем изменять их непосредственно в JSON-файле или с помощью редактора параметров CMake (в Visual Studio 2019 и более поздних версиях). В интегрированной среде разработки можно легко переключаться между конфигурациями для создания различных файлов проекта. Дополнительные сведения см. в статье Настройка параметров сборки CMake в Visual Studio.

Конфигурации

Массив configurations содержит все конфигурации для проекта CMake. Дополнительные сведения о предварительно определенных конфигурациях см. в статье Справочник по предопределенной конфигурации CMake. В файл можно добавить любое количество предварительно определенных или пользовательских конфигураций.

configuration имеет следующие свойства:

addressSanitizerEnabled: если значение — true, компилирует программу используя AddressSanitizer. Для получения наилучших результатов в Linux выполните компиляцию с параметром -fno-omit-frame-pointer и уровнем оптимизации компилятора -Os или -Oo.
addressSanitizerRuntimeFlags: флаги среды выполнения, передаваемые в AddressSanitizer через переменную среды ASAN_OPTIONS. Формат: флаг1=значение:флаг2=значение2.
buildCommandArgs: задает собственные параметры сборки, передаваемые CMake после --build --. Например, передача -v при использовании генератора Ninja приводит к тому, что 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.
cacheRoot: задает путь к кэшу CMake. Этот каталог должен содержать существующий файл CMakeCache.txt.
clangTidyChecks: разделенный запятыми список предупреждений, которые передаются в clang-tidy; могут использоваться подстановочные знаки; для исключения проверок укажите префикс "-".
cmakeCommandArgs: указывает дополнительные параметры командной строки, передаваемые в CMake при создании файлов проекта.
cmakeToolchain: задает файл цепочки инструментов. Передается в CMake с помощью -DCMAKE_TOOLCHAIN_FILE.
codeAnalysisRuleset: указывает набор правил для использования при выполнении анализа кода. Можно использовать полный путь к файлу или имя файла набора правил, установленного Visual Studio.
configurationType; указывает конфигурацию типа сборки для выбранного генератора. Может быть одним из вариантов:
- Debug
- Release
- MinSizeRel
- RelWithDebInfo
ctestCommandArgs: задает дополнительные параметры командной строки, передаваемые CTest при запуске тестов.
description: описание конфигурации, которое отображается в меню.
enableClangTidyCodeAnalysis: использовать Clang-Tidy для анализа кода.
enableMicrosoftCodeAnalysis: использовать средства анализа кода Майкрософт для анализа кода.
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 в Visual Studio 2017, в главном меню откройте редактор параметров, выбрав CMake | Изменить параметры CMake. Удалите слово "Ninja" и введите букву "V". Активирует IntelliSense, позволяя выбрать нужный генератор.

Чтобы указать генератор Visual Studio в Visual Studio 2019, щелкните правой кнопкой мыши CMakeLists.txt файл в Обозреватель решений и выберите CMake Параметры для проекта>Show Advanced Параметры> CMake Generator.

По умолчанию, когда для активной конфигурации выбран генератор Visual Studio, он вызывает MSBuild с аргументами -m -v:minimal. Чтобы настроить сборку, используйте buildCommandArgs свойство внутри CMakeSettings.json файла. Здесь можно указать Аргументы командной строки 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: путь к средству запуска экземпляра подсистемы Windows для Linux.

Параметры для проектов CMake Linux

remoteMachineName: задает имя удаленного компьютера Linux, на котором размещается CMake, сборки и отладчик. Используйте диспетчер подключений для добавления новых компьютеров 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. Формат: "/путь1;/путь2…".
remoteCopyExcludeDirectories: включите каталоги НЕ для копирования с удаленного компьютера. Формат: "/путь1;/путь2…".
remoteCopyUseCompilerDefaults: указывает, следует ли использовать стандартный код компилятора и включать пути для IntelliSense. Значение false следует задавать только в том случае, если используемые компиляторы не поддерживают аргументы в стиле gcc.
rsyncCommandArgs: задает набор параметров командной строки, переданных в rsync.
remoteCopySourcesExclusionList: array задает список путей, исключаемых при копировании исходных файлов: в качестве пути можно указать имя файла или каталога либо путь по отношению к корневому каталогу копии. Можно использовать подстановочные знаки * и ? для сопоставления со стандартной маской.
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 аналогична выполнению командной строки разработчика для VS {version} с аргументами -arch=amd64 -host_arch=amd64 . Вы можете использовать синтаксис env.{<variable_name>} в файле CMakeSettings.json для ссылки на отдельные переменные среды, например с целью формирования путей к папкам. Предоставляются следующие предопределенные среды:

linux_arm: удаленная ориентация на Linux ARM.
linux_x64: удаленная ориентация на Linux x64.
linux_x86: удаленная ориентация на Linux x86.
msvc_arm: ориентация на Windows ARM с компилятором MSVC.
msvc_arm_x64: ориентация на Windows ARM с 64-разрядным компилятором MSVC.
msvc_arm64: ориентация на Windows ARM64 с компилятором MSVC.
msvc_arm64_x64: ориентация на Windows ARM64 с 64-разрядным компилятором MSVC.
msvc_arm64ec: целевой ARM64EC Windows с помощью компилятора MSVC.
msvc_arm64ec_x64: целевая ARM64EC Windows с 64-разрядным компилятором MSVC.
msvc_x64: ориентация на Windows x64 с компилятором MSVC.
msvc_x64_x64: ориентация на Windows x64 с 64-разрядным компилятором MSVC.
msvc_x86: ориентация на Windows x86 с компилятором MSVC.
msvc_x86_x64: ориентация на Windows x86 с 64-разрядным компилятором MSVC.

Доступ к переменным среды из файла `CMakeLists.txt`

Обращение к переменным среды из файла CMakeLists.txt производится с использованием синтаксиса $ENV{variable_name}. Чтобы просмотреть доступные переменные среды, откройте соответствующую командную строку и введите SET. Некоторые сведения в переменных среды также доступны посредством переменных самоанализа системы CMake, но переменные среды, скорее всего, будут удобнее в использовании. Например, с помощью переменных среды можно легко получить версию компилятора MSVC или пакета SDK для Windows.

Пользовательские переменные среды

В 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 определяет свое значение для свойства 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, используемого в этой конфигурации.

Все ссылки на макросы и переменные среды в файле CMakeSettings.json развертываются перед передачей в командную строку CMake.

Аргументы командной строки Ninja

Если целевые объекты не заданы, Ninja создает целевой объект "default".

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`	Указание файла входных данных для сборки (по умолчанию используется `build.ninja`)
`-j N`	Параллельное выполнение `N` заданий (по умолчанию 14, в зависимости от доступных ЦП)
`-k N`	Продолжение выполнения для сбоя `N` заданий (по умолчанию 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`