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": 3,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 21,
    "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"
    },
    {
      "name": "windows-only",
      "inherits": "default",
      "displayName": "Windows-only configuration",
      "description": "This build is only available on Windows",
      "condition": {
        "type": "equals",
        "lhs": "${hostSystemName}",
        "rhs": "Windows"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "default",
      "configurePreset": "default"
    }
  ],
  "testPresets": [
    {
      "name": "default",
      "configurePreset": "default",
      "output": {"outputOnFailure": true},
      "execution": {"noTestsAction": "error", "stopOnFailure": true}
    }
  ],
  "vendor": {
    "example.com/ExampleIDE/1.0": {
      "autoFormat": false
    }
  }
}

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

version

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

cmakeMinimumRequired

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

major

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

minor

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

patch

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

vendor

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

configurePresets

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

buildPresets

Необязательный массив объектов Пресет Сборки. Это разрешено в файлах пресетов, определяющих версию 2 или выше.

testPresets

Необязательный массив объектов Пресет Тестирования. Это разрешено в файлах пресетов, определяющих версию 2 или выше.

Настройка Пресета

Каждый элемент массива configurePresets — это JSON-объект, который может содержать следующие поля:

name

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

hidden

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

inherits

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

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

condition

Необязательный объект Условие. Это разрешено в файлах пресетов, определяющих версию 3 или выше.

vendor

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

displayName

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

description

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

generator

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

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

architecture, toolset

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

value

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

strategy

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

"set"

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

"external"

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

toolchainFile

Необязательная строка, представляющая путь к файлу цепочки инструментов. Это поле поддерживает развертывание макроса. Если указан относительный путь, он вычисляется относительно директории сборки, и если он не найден, относительно исходной директории. Это поле имеет приоритет над любым значением CMAKE_TOOLCHAIN_FILE. Оно разрешено в файлах пресетов, определяющих версию 3 или выше.

binaryDir

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

installDir

Необязательная строка, представляющая путь к директории установки. Это поле поддерживает развертывание макроса. Если указан относительный путь, он вычисляется относительно исходной директории. Разрешено в файлах пресетов, определяющих версию 3 или выше.

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 в командной строке.

Набор параметров сборки

Каждый элемент массива buildPresets — это JSON-объект, который может содержать следующие поля:

name

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

hidden

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

inherits

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

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

condition

Необязательный объект Condition. Разрешено в файлах наборов параметров, использующих версию 3 или выше.

vendor

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

displayName

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

description

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

environment

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

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

configurePreset

Необязательная строка, определяющая имя набора параметров конфигурации, который нужно связать с этим набором параметров сборки. Если configurePreset не указано, оно должно быть унаследовано от набора параметров, который наследуется (если этот набор параметров скрыт). Директория сборки определяется из набора параметров конфигурации, поэтому сборка будет выполняться в той же директории, что и конфигурация.

binaryDir

Необязательный булевый тип, который по умолчанию равен true. Если true, переменные окружения из связанного набора параметров конфигурации наследуются после всех унаследованных сред набора параметров сборки, но перед переменными окружения, явно указанными в этом наборе параметров сборки.

jobs

Необязательное целое число. Эквивалентно передаче --parallel или -j в командной строке.

targets

Необязательная строка или массив строк. Эквивалентно передаче --target или -t в командной строке. Поставщики могут игнорировать свойство targets или скрывать наборы параметров сборки, которые явно указывают targets. Это поле поддерживает макроподстановку.

configuration

Необязательная строка. Эквивалентно передаче --config в командной строке.

cleanFirst

Необязательный булевый тип. Если true, эквивалентно передаче --clean-first в командной строке.

verbose

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

nativeToolOptions

Необязательный массив строк. Эквивалентно передаче опций после -- в командной строке. Значения массива поддерживают макроподстановку.

Набор параметров тестирования

Каждый элемент массива testPresets — это JSON-объект, который может содержать следующие поля:

name

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

hidden

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

inherits

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

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

condition

Необязательный объект Condition. Разрешено в файлах наборов параметров, использующих версию 3 или выше.

vendor

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

displayName

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

description

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

environment

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

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

configurePreset

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

inheritConfigureEnvironment

Необязательный булев параметр, по умолчанию равный true. Если true, переменные окружения из связанного пресета конфигурации наследуются после всех унаследованных тестовых сред пресетов, но перед переменными окружения, явно указанными в этом тестовом пресете.

configuration

Необязательная строка. Эквивалентно передаче --build-config в командной строке.

overwriteConfigurationFile

Необязательный массив параметров конфигурации для перезаписи параметров, указанных в файле конфигурации CTest. Эквивалентно передаче --overwrite для каждого значения в массиве. Значения массива поддерживают макроподстановку.

output

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

shortProgress

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

verbosity

Необязательная строка, задающая уровень детализации. Должно быть одним из следующих:

default

Эквивалентно передаче никаких флагов детализации в командной строке.

verbose

Эквивалентно передаче --verbose в командной строке.

extra

Эквивалентно передаче --extra-verbose в командной строке.

debug

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

outputOnFailure

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

quiet

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

outputLogFile

Необязательная строка, задающая путь к файлу журнала. Эквивалентно передаче --output-log в командной строке. Это поле поддерживает макроподстановку.

labelSummary

Необязательный булев параметр. Если false, эквивалентно передаче --no-label-summary в командной строке.

subprojectSummary

Необязательный булев параметр. Если false, эквивалентно передаче --no-subproject-summary в командной строке.

maxPassedTestOutputSize

Необязательное целое число, задающее максимальный объем вывода для пройденных тестов в байтах. Эквивалентно передаче --test-output-size-passed в командной строке.

maxFailedTestOutputSize

Необязательное целое число, задающее максимальный объем вывода для проваленных тестов в байтах. Эквивалентно передаче --test-output-size-failed в командной строке.

maxTestNameWidth

Необязательное целое число, задающее максимальную ширину имени теста для вывода. Эквивалентно передаче --max-width в командной строке.

filter

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

include

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

name

Необязательная строка, задающая регулярное выражение для имён тестов. Эквивалентно передаче --tests-regex в командной строке. Это поле поддерживает макроподстановку. Синтаксис регулярных выражений CMake описан в string(REGEX).

label

Необязательная строка, задающая регулярное выражение для меток тестов. Эквивалентно передаче --label-regex в командной строке. Это поле поддерживает макроподстановку.

useUnion

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

index

Необязательный объект, определяющий тесты для включения по индексу теста. Объект может содержать следующие поля. Также может быть необязательной строкой, указывающей файл с синтаксисом командной строки для --tests-information. Если задано в виде строки, это поле поддерживает макроподстановку.

start

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

end

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

stride

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

specificTests

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

exclude

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

name

Необязательная строка, задающая регулярное выражение для имён тестов. Эквивалентно передаче --exclude-regex в командной строке. Это поле поддерживает макроподстановку.

label

Необязательная строка, задающая регулярное выражение для меток тестов. Эквивалентно передаче --label-exclude в командной строке. Это поле поддерживает макроподстановку.

fixtures

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

any

Необязательная строка, задающая регулярное выражение для текстовых фикстур, которые исключить из добавления тестов. Эквивалентно --fixture-exclude-any в командной строке. Это поле поддерживает макроподстановку.

setup

Необязательная строка, задающая регулярное выражение для текстовых фикстур, которые исключить из добавления тестовых установок. Эквивалентно --fixture-exclude-setup в командной строке. Это поле поддерживает макроподстановку.

cleanup

Необязательная строка, задающая регулярное выражение для текстовых фикстур, которые исключить из добавления тестовых завершений. Эквивалентно --fixture-exclude-cleanup в командной строке. Это поле поддерживает макроподстановку.

execution

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

stopOnFailure

Необязательный булев параметр. Если true, эквивалентно передаче --stop-on-failure в командной строке.

enableFailover

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

jobs

Необязательное целое число. Эквивалентно передаче --parallel в командной строке.

resourceSpecFile

Необязательная строка. Эквивалентно передаче --resource-spec-file в командной строке. Это поле поддерживает макроподстановку.

testLoad

Необязательное целое число. Эквивалентно передаче --test-load в командной строке.

showOnly

Необязательная строка. Эквивалентно передаче --show-only в командной строке. Строка должна быть одним из следующих значений:

human

json-v1

repeat

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

mode

Обязательная строка. Должна быть одним из следующих значений:

until-fail

until-pass

after-timeout

count

Обязательное целое число.

interactiveDebugging

Необязательный булев параметр. Если true, эквивалентно передаче --interactive-debug-mode 1 в командной строке. Если false, эквивалентно передаче --interactive-debug-mode 0 в командной строке.

scheduleRandom

Необязательный булев параметр. Если true, эквивалентно передаче --schedule-random в командной строке.

timeout

Необязательное целое число. Эквивалентно передаче --timeout в командной строке.

noTestsAction

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

default

Эквивалентно тому, что ничего не передаётся в командную строку.

error

Эквивалентно передаче --no-tests=error в командной строке.

ignore

Эквивалентно передаче --no-tests=ignore в командной строке.

Условие

Поле condition пресета, разрешенное в файлах пресетов, определяющих версию 3 или выше, используется для определения того, включён ли пресет. Например, это можно использовать для отключения пресета на платформах, отличных от Windows. condition может быть булевым значением, null, или объектом. Если это булево значение, оно указывает, включён или отключён пресет. Если это null, пресет включён, но условие null не наследуется никакими пресетами, которые могут наследоваться от пресета. Под-условия (например, в not, anyOf, или allOf условии) не могут быть null. Если это объект, он имеет следующие поля:

type

Обязательная строка с одним из следующих значений:

"const"

Указывает, что условие является постоянным. Это эквивалентно использованию булевого значения вместо объекта. Объект условия будет иметь следующие дополнительные поля:

value

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

"equals"

"notEquals"

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

lhs

Первая строка для сравнения. Это поле поддерживает макроподстановку.

rhs

Вторая строка для сравнения. Это поле поддерживает макроподстановку.

"inList"

"notInList"

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

string

Обязательная строка для поиска. Это поле поддерживает макроподстановку.

list

Обязательный список строк для поиска. Это поле поддерживает макроподстановку и использует короткую цепочку вычислений.

"matches"

"notMatches"

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

string

Обязательная строка для поиска. Это поле поддерживает макроподстановку.

regex

Обязательное регулярное выражение для поиска. Это поле поддерживает макроподстановку.

"anyOf"

"allOf"

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

conditions

Обязательный массив объектов условия. Эти условия используют короткую цепочку вычислений.

"not"

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

condition

Обязательный объект условия.

Макроподстановка

Как упоминалось выше, некоторые поля поддерживают макроподстановку. Макросы распознаются в форме $<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 пресета. Для пресетов сборки и тестирования это значение будет соответствовать генератору, указанному в configurePreset.

${hostSystemName}

Имя хостовой операционной системы. Содержит то же значение, что и CMAKE_HOST_SYSTEM_NAME. Это разрешено в файлах пресетов, указывающих версию 3 или выше.

${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.