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

Проекты 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 для проекта>Показать расширенные настройки>Генератор CMake.

По умолчанию, когда для активной конфигурации выбран генератор 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, рекомендуется вместо этого добавить их сюда. В этом примере показано, как указать пары "название-значение" для использования средств сборки MSVC версии 14.14.26428:
"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: удаленная настройка на ARM Linux.
  • 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: Нацельтесь на Windows ARM64EC с помощью компилятора 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 для указания предупреждений)
  • Last updated on