cmake-presets(7)

• Введение
• Формат
• Схема

Введение

Пользователи CMake часто сталкиваются с проблемой совместного использования настроек проекта с другими пользователями для стандартных способов конфигурации. Это может потребоваться для поддержки CI-сборки или для пользователей, которые часто используют одинаковую сборку. CMake поддерживает два файла, CMakePresets.json и CMakeUserPresets.json, которые позволяют пользователям задавать общие параметры конфигурации и делиться ими с другими.

CMakePresets.json и CMakeUserPresets.json находятся в корневой директории проекта. У них одинаковый формат, и оба являются необязательными (хотя хотя бы один должен быть присутствующим, если указан --preset). CMakePresets.json предназначен для сохранения проектных сборок, в то время как CMakeUserPresets.json предназначен для сохранения локальных сборок разработчиками. CMakePresets.json может быть добавлен в систему управления версиями, а CMakeUserPresets.json не должен добавляться. Например, если проект использует Git, CMakePresets.json может быть отслеживаем, а CMakeUserPresets.json следует добавить в .gitignore.

Формат

Файлы представляют собой JSON-документ с объектом в качестве корня:

{
  "version": 1,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 19,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "default",
      "displayName": "Default Config",
      "description": "Default build using Ninja generator",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/default",
      "cacheVariables": {
        "FIRST_CACHE_VARIABLE": {
          "type": "BOOL",
          "value": "OFF"
        },
        "SECOND_CACHE_VARIABLE": "ON"
      },
      "environment": {
        "MY_ENVIRONMENT_VARIABLE": "Test",
        "PATH": "$env{HOME}/ninja/bin:$penv{PATH}"
      },
      "vendor": {
        "example.com/ExampleIDE/1.0": {
          "autoFormat": true
        }
      }
    },
    {
      "name": "ninja-multi",
      "inherits": "default",
      "displayName": "Ninja Multi-Config",
      "description": "Default build using Ninja Multi-Config generator",
      "generator": "Ninja Multi-Config"
    }
  ],
  "vendor": {
    "example.com/ExampleIDE/1.0": {
      "autoFormat": false
    }
  }
}

Корневой объект распознаёт следующие поля:

version

Обязательное целое число, представляющее версию JSON-схемы. В настоящее время поддерживается только версия 1.

cmakeMinimumRequired

Необязательный объект, представляющий минимальную версию CMake, необходимую для сборки проекта. Этот объект состоит из следующих полей:

major

Необязательное целое число, представляющее основную версию.

minor

Необязательное целое число, представляющее второстепенную версию.

patch

Необязательное целое число, представляющее версию исправления.

vendor

Необязательный массив, содержащий информацию, специфичную для поставщика. CMake не интерпретирует содержимое этого поля, кроме проверки, что оно является массивом, если оно существует. Однако ключи должны быть доменным именем поставщика, за которым следует разделитель / и путь. Например, Example IDE 1.0 может использовать example.com/ExampleIDE/1.0. Значение каждого поля может быть любым, желаемым поставщиком, хотя обычно это будет массив.

configurePresets

Необязательный массив объектов конфигурации. Каждый набор параметров может содержать следующие поля:

name

Обязательная строка, представляющая имя набора параметров, удобное для машины. Этот идентификатор используется в аргументе --preset. В одном каталоге не должно быть двух наборов параметров в объединении CMakePresets.json и CMakeUserPresets.json с одинаковым именем.

hidden

Необязательный булевый параметр, указывающий, нужно ли скрывать набор параметров. Если набор параметров скрыт, он не может быть использован в аргументе --preset=, не будет отображаться в CMake GUI и не должен иметь действительные generator или binaryDir, даже при наследовании. hidden наборы параметров предназначены для использования в качестве основы для других наборов параметров, которые могут наследоваться через поле inherits.

inherits

Необязательный массив строк, представляющий имена наборов параметров, от которых нужно наследоваться. Набор параметров будет наследоваться от всех inherits наборов параметров по умолчанию (кроме name, hidden, inherits, description, и longDescription), но может переопределять их по желанию. Если несколько inherits наборов параметров предоставляют конфликтующие значения для одного и того же поля, то набор параметров, более ранний в списке inherits, будет предпочтительнее. Наборы параметров в CMakePresets.json не могут наследоваться от наборов параметров в CMakeUserPresets.json.

Это поле также может быть строкой, что эквивалентно массиву, содержащему одну строку.

vendor

Необязательный массив, содержащий информацию, специфичную для поставщика. CMake не интерпретирует содержимое этого поля, кроме проверки, что оно является массивом, если оно существует. Однако оно должно соответствовать тем же соглашениям, что и корневое поле vendor.

displayName

Необязательная строка с удобочитаемым именем набора параметров.

description

Необязательная строка с удобочитаемым описанием набора параметров.

generator

Необязательная строка, представляющая генератор для использования в данном наборе параметров. Если generator не указан, он должен быть унаследован от inherits набора параметров (если этот набор параметров не hidden).

Обратите внимание, что для генераторов Visual Studio, в отличие от аргумента командной строки -G, вы не можете включать имя платформы в имя генератора. Используйте поле architecture вместо этого.

architecture toolset

Необязательные поля, представляющие платформу и набор инструментов соответственно для генераторов, которые их поддерживают. Каждое может быть либо строкой, либо объектом со следующими полями:

value

Необязательная строка, представляющая значение.

strategy

Необязательная строка, указывающая CMake, как обработать поле architecture или toolset . Допустимые значения:

"set"

Установить соответствующее значение. Это приведёт к ошибке для генераторов, которые не поддерживают соответствующее поле.

"external"

Не устанавливать значение, даже если генератор его поддерживает. Это полезно, например, если набор параметров использует генератор Ninja, а IDE знает, как настроить среду Visual C++ из полей architecture и toolset. В этом случае CMake проигнорирует поле, но IDE может использовать их для настройки среды до запуска CMake.

binaryDir

Необязательная строка, представляющая путь к каталогу выходного бинарного файла. Это поле поддерживает расширение макросов. Если указан относительный путь, он вычисляется относительно каталога исходных файлов. Если binaryDir не указан, он должен быть унаследован от inherits набора параметров (если этот набор параметров не hidden).

cmakeExecutable

Необязательная строка, представляющая путь к исполняемому файлу CMake для использования в данном наборе параметров. Это зарезервировано для использования IDE и не используется самим CMake. IDE, использующие это поле, должны расширить макросы в нём.

cacheVariables

Необязательный массив переменных кэша. Ключ — имя переменной (которое не может быть пустой строкой), а значение — либо null, булево значение (что эквивалентно "TRUE" или "FALSE" и типу BOOL), строка, представляющая значение переменной (поддерживающая расширение макросов), или объект со следующими полями:

type

Необязательная строка, представляющая тип переменной.

value

Обязательная строка или булево значение, представляющее значение переменной. Булево значение эквивалентно "TRUE" или "FALSE". Это поле поддерживает расширение макросов.

Переменные кэша наследуются через поле inherits, и переменные набора параметров будут объединением его собственных cacheVariables и cacheVariables от всех его родителей. Если несколько наборов параметров в этом объединении определяют одну и ту же переменную, применяются стандартные правила inherits. Установка переменной в null приводит к тому, что она не устанавливается, даже если значение было унаследовано от другого набора параметров.

environment

Необязательный массив переменных окружения. Ключ — имя переменной (которое не может быть пустой строкой), а значение — либо null или строка, представляющая значение переменной. Каждая переменная устанавливается независимо от того, было ли ей присвоено значение окружением процесса. Это поле поддерживает расширение макросов, и переменные окружения в этом массиве могут ссылаться друг на друга, и могут быть перечислены в любом порядке, при условии, что такие ссылки не создают цикл (например, если ENV_1 равно $env{ENV_2}, ENV_2 не может быть $env{ENV_1}).

Переменные окружения наследуются через поле inherits, и окружение набора параметров будет объединением его собственного environment и environment от всех его родителей. Если несколько наборов параметров в этом объединении определяют одну и ту же переменную, применяются стандартные правила inherits. Установка переменной в null приводит к тому, что она не устанавливается, даже если значение было унаследовано от другого набора параметров.

warnings

Необязательный объект, указывающий на включение предупреждений. Объект может содержать следующие поля:

dev

Необязательный булевый параметр. Эквивалентно передаче -Wdev или -Wno-dev в командной строке. Это значение не может быть установлено в false если errors.dev установлено в true.

deprecated

Необязательный булевый параметр. Эквивалентно передаче -Wdeprecated или -Wno-deprecated в командной строке. Это значение не может быть установлено в false если errors.deprecated установлено в true.

uninitialized

Необязательный булевый параметр. Установка этого значения в true эквивалентна передаче --warn-uninitialized в командной строке.

unusedCli

Необязательный булевый параметр. Установка этого значения в false эквивалентна передаче --no-warn-unused-cli в командной строке.

systemVars

Необязательный булевый параметр. Установка этого значения в true эквивалентна передаче --check-system-vars в командной строке.

errors

Необязательный объект, указывающий на включение ошибок. Объект может содержать следующие поля:

dev

Необязательный булевый параметр. Эквивалентно передаче -Werror=dev или -Wno-error=dev в командной строке. Это значение не может быть установлено в true если warnings.dev установлено в false.

deprecated

Необязательный булевый параметр. Эквивалентно передаче -Werror=deprecated или -Wno-error=deprecated в командной строке. Это значение не может быть установлено в true если warnings.deprecated установлено в false.

debug

Необязательный объект, указывающий параметры отладки. Объект может содержать следующие поля:

output

Необязательный булевый параметр. Установка этого значения в true эквивалентна передаче --debug-output в командной строке.

tryCompile

Необязательный булевый параметр. Установка значения в true эквивалентна передаче параметра --debug-trycompile в командной строке.

find

Необязательный булевый параметр. Установка значения в true эквивалентна передаче параметра --debug-find в командной строке.

Как упоминалось выше, некоторые поля поддерживают макроподстановку. Макросы распознаются в формате $<macro-namespace>{<macro-name>}. Все макросы вычисляются в контексте используемого набора предопределённых значений, даже если макрос находится в поле, унаследованном от другого набора. Например, если набор Base устанавливает переменную PRESET_NAME в значение ${presetName}, а набор Derived унаследован от набора Base, то PRESET_NAME будет установлено в значение Derived.

Не допускается отсутствие закрывающей фигурной скобки в конце имени макроса. Например, ${sourceDir является недопустимым. Знак доллара ($) в сочетании с любым символом, кроме открывающей фигурной скобки ({) с возможным пространством имён, интерпретируется как буквальный знак доллара.

Распознаваемые макросы включают:

${sourceDir}

Путь к каталогу исходного кода проекта.

${sourceParentDir}

Путь к родительскому каталогу каталога исходного кода проекта.

${sourceDirName}

Последний компонент имени файла в ${sourceDir}. Например, если ${sourceDir} равно /path/to/source, то это будет source.

${presetName}

Имя, указанное в поле name набора предопределённых значений.

${generator}

Генератор, указанный в поле generator набора предопределённых значений.

${dollar}

Буквальный знак доллара ($).

$env{<variable-name>}

Переменная среды с именем <variable-name>. Имя переменной не может быть пустой строкой. Если переменная определена в поле environment, используется её значение, а не значение из родительской среды. Если переменная среды не определена, это вычисляется как пустая строка.

Обратите внимание, что, хотя имена переменных среды Windows не чувствительны к регистру, имена переменных в наборе предопределённых значений всё ещё чувствительны к регистру. Это может привести к непредсказуемым результатам при несоответствии регистра. Для достижения наилучших результатов сохраняйте согласованность регистра в именах переменных среды.

$penv{<variable-name>}

Аналогично $env{<variable-name>}, за исключением того, что значение берётся только из родительской среды и никогда из поля environment. Это позволяет вам добавлять или удалять значения к существующим переменным среды. Например, установка значения PATH в /path/to/ninja/bin:$penv{PATH} добавит /path/to/ninja/bin в начало переменной среды PATH. Это необходимо, потому что $env{<variable-name>} не допускает циклических ссылок.

$vendor{<macro-name>}

Точка расширения для поставщиков, чтобы вставлять свои собственные макросы. CMake не сможет использовать наборы предопределённых значений, содержащие макрос $vendor{<macro-name>}, и фактически игнорирует такие наборы. Однако он всё ещё сможет использовать другие наборы из того же файла.

CMake не пытается интерпретировать макросы $vendor{<macro-name>}. Однако, чтобы избежать коллизий имён, поставщики IDE должны добавлять префикс <macro-name> к макросу с очень коротким (предпочтительно <= 4 символов) идентификатором поставщика, за которым следует ., а затем имя макроса. Например, Example IDE может иметь $vendor{xide.ideInstallDir}.

Схема

This file предоставляет читаемую машиной JSON-схему для формата CMakePresets.json.