cmake-presets(7)

• Введение

• Формат

  • Включения
  • Пресет конфигурации
  • Пресет сборки
  • Пресет тестирования
  • Условие
  • Расширение макросов
• Схема

Введение

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

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

CMakePresets.json можно зафиксировать в системе управления версиями, а CMakeUserPresets.json не следует фиксировать. Например, если проект использует Git, CMakePresets.json можно отслеживать, а CMakeUserPresets.json следует добавить в .gitignore.

Формат

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

{
  "version": 5,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 23,
    "patch": 0
  },
  "include": [
    "otherThings.json",
    "moreThings.json"
  ],
  "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

Новое в версии 3.19.

2

Новое в версии 3.20.

3

Новое в версии 3.21.

4

Новое в версии 3.23.

5

Новое в версии 3.24.

cmakeMinimumRequired

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

major

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

minor

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

patch

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

include

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

vendor

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

configurePresets

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

buildPresets

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

testPresets

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

Включения

CMakePresets.json и CMakeUserPresets.json могут включать другие файлы с помощью поля include в версии файла 4 и выше. Файлы, включённые этими файлами, также могут включать другие файлы. Если CMakePresets.json и CMakeUserPresets.json оба присутствуют, CMakeUserPresets.json неявно включает CMakePresets.json, даже без поля include, во всех версиях формата.

Если файл пресета содержит пресеты, которые наследуют от пресетов в другом файле, файл должен включать другой файл прямо или косвенно. Циклы включения между файлами не допускаются. Если a.json включает b.json, b.json не может включать a.json. Однако файл может быть включён несколько раз из одного и того же файла или из разных файлов.

Файлы, включённые прямо или косвенно из CMakePresets.json, должны быть гарантированно предоставлены проектом. CMakeUserPresets.json может включать файлы откуда угодно.

Пресет конфигурации

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

inheritConfigureEnvironment

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

jobs

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

targets

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

configuration

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

cleanFirst

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

resolvePackageReferences

Дополнительная строка, определяющая режим разрешения пакетов. Это разрешено в файлах предустановок, определяющих версию 4 или выше.

Ссылки на пакеты используются для определения зависимостей от пакетов из внешних менеджеров пакетов. В настоящее время поддерживается только NuGet в сочетании с генератором Visual Studio. Если нет targets, определяющих ссылки на пакеты, это свойство ничего не делает. Допустимые значения:

on

Вызывает разрешение ссылок на пакеты перед попыткой построения.

off

Ссылки на пакеты не будут разрешены. Обратите внимание, что это может привести к ошибкам в некоторых средах построения, таких как проекты в стиле .NET SDK.

only

Разрешить только ссылки на пакеты, но не выполнять построение.

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

testOutputTruncation

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

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}

Путь к каталогу исходных кодов проекта (то есть, такой же, как CMAKE_SOURCE_DIR).

${sourceParentDir}

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

${sourceDirName}

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

${presetName}

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

${generator}

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

${hostSystemName}

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

${fileDir}

Путь к каталогу, содержащему файл предопределённого значения, который содержит макрос. Это разрешено в файлах предопределений, указывающих версию 4 или выше.

${dollar}

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

${pathListSep}

Символ по умолчанию для разделения списков путей, таких как : или ;.

Например, установив PATH в значение /path/to/ninja/bin${pathListSep}$env{PATH}, ${pathListSep} будет расширяться до символа подлежащей операционной системы, используемого для конкатенации в PATH.

Это разрешено в файлах предопределений, указывающих версию 5 или выше.

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