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": 4,
  "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, 2, 3, и 4.

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, даже при наследовании. hidden предварительные настройки предназначены для использования в качестве базы для других предварительных настроек, которые должны наследоваться через поле 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, даже унаследованного. Скрытые наборы параметров предназначены для использования в качестве основы для других наборов параметров, которые могут наследовать их через поле 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. Если нет целевых элементов, определяющих ссылки на пакеты, этот параметр ничего не делает. Допустимые значения:

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

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}

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

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