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": 6,
  "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}
    }
  ],
  "packagePresets": [
    {
      "name": "default",
      "configurePreset": "default",
      "generators": [
        "TGZ"
      ]
    }
  ],
  "workflowPresets": [
    {
      "name": "default",
      "steps": [
        {
          "type": "configure",
          "name": "default"
        },
        {
          "type": "build",
          "name": "default"
        },
        {
          "type": "test",
          "name": "default"
        },
        {
          "type": "package",
          "name": "default"
        }
      ]
    }
  ],
  "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.

6

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

7

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

cmakeMinimumRequired

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

major

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

minor

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

patch

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

include

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

vendor

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

configurePresets

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

buildPresets

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

testPresets

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

packagePresets

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

workflowPresets

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

Включения

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 может включать файлы из любого места.

Начиная с версии 7, поле include поддерживает расширение макросов, но только $penv{} расширение макросов.

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

Каждый элемент массива 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

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

vendor

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

displayName

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

description

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

generator

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

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

architecture, toolset

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

См. опцию cmake -A для возможных значений для architecture и cmake -T для toolset.

Каждое может быть либо строкой, либо объектом со следующими полями:

value

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

strategy

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

"set"

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

"external"

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

Если поле strategy не задано или если поле использует строковый формат вместо объектного, поведение такое же, как у "set".

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 и переменных всех его родителей. Если несколько пресетов в этом объединении определяют одну и ту же переменную, применяются стандартные правила inherits. Установка переменной в значение null приводит к тому, что она не устанавливается, даже если значение было унаследовано от другого пресета.

environment

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

Переменные среды наследуются через поле inherits, и среда пресета будет объединением собственной среды пресета 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

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

deprecated

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

debug

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

output

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

tryCompile

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

find

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

trace

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

mode

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

on

Выводит трассировку всех вызовов и от куда они были сделаны. Эквивалентно передаче --trace в командной строке.

off

Трассировка всех вызовов не будет выводиться.

expand

Выводит трассировку с расширенными переменными всех вызовов и от куда они были сделаны. Эквивалентно передаче --trace-expand в командной строке.

format

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

human

Выводит каждую строку трассировки в удобочитаемом формате. Это формат по умолчанию. Эквивалентно передаче --trace-format=human в командной строке.

json-v1

Выводит каждую строку как отдельный JSON-документ. Эквивалентно передаче --trace-format=json-v1 в командной строке.

source

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

redirect

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

Пресет сборки

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

Примечание

Для проекта CMake, использующего ExternalProject с конфигурационным пресетом, имеющим переменные среды, необходимые в ExternalProject, используйте пресет сборки, который наследует этот конфигурационный пресет, или ExternalProject не будет иметь переменные среды, установленные в конфигурационном пресете. Например, предположим, что по умолчанию используется один компилятор (скажем, Clang), и пользователь хочет использовать другой (скажем, GCC). Установите конфигурационные переменные среды CC и CXX и используйте пресет сборки, который наследует этот конфигурационный пресет. В противном случае ExternalProject может использовать другой компилятор (по умолчанию для системы), чем основной проект CMake.

configurePreset

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

inheritConfigureEnvironment

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

jobs

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

targets

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

configuration

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

cleanFirst

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

resolvePackageReferences

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

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

on

Приводит к разрешению ссылок на пакеты перед попыткой сборки.

off

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

only

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

Примечание

Параметр командной строки --resolve-package-references будет иметь приоритет над этим параметром. Если параметр командной строки не указан и этот параметр не задан, будет оценена переменная кэша, специфичная для среды, чтобы определить, нужно ли выполнять восстановление пакетов.

При использовании генератора Visual Studio ссылки на пакеты определяются с помощью свойства VS_PACKAGE_REFERENCES. Восстановление ссылок на пакеты выполняется с помощью NuGet. Его можно отключить, установив переменную CMAKE_VS_NUGET_PACKAGE_RESTORE в значение OFF. Это также можно сделать из конфигурационного пресета.

verbose

Необязательный bool. Если 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

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

verbosity

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

default

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

verbose

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

extra

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

debug

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

outputOnFailure

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

quiet

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

outputLogFile

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

outputJUnitFile

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

labelSummary

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

subprojectSummary

Необязательный bool. Если 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 в командной строке.

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

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

name

Обязательная строка, представляющая удобочитаемое имя пресета. Этот идентификатор используется в опции cpack --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.

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, переменные среды из связанного конфигурационного пресета наследуются после всех унаследованных сред пресетов пакета, но перед переменными среды, явно указанными в этом пресете пакета.

generators

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

configurations

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

variables

Необязательная карта переменных для передачи CPack, эквивалентная аргументам -D. Каждый ключ — имя переменной, а значение — строка, которая должна быть присвоена этой переменной.

configFile

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

output

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

debug

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

verbose

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

packageName

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

packageVersion

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

packageDirectory

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

vendorName

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

Рабочий пресет

Рабочие пресеты могут использоваться в схеме версии 6 и выше. Каждый элемент массива workflowPresets — это JSON-объект, который может содержать следующие поля:

name

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

vendor

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

displayName

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

description

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

steps

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

type

Обязательная строка. Первый шаг должен быть configure. Последующие шаги должны быть либо build, test, или package.

name

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

Condition

Поле 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 символов) префиксом идентификатора поставщика, за которым следует ., а затем имя макроса. Например, у поставщика "Пример IDE" может быть $vendor{xide.ideInstallDir}.

Схема

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