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
    }
  }
}

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

$schema

Необязательная строка, предоставляющая URI к JSON-схеме, описывающей структуру этого JSON-документа. Это поле используется для проверки и автодополнения в редакторах, поддерживающих JSON-схему. Оно не влияет на поведение самого документа. Если это поле не указано, JSON-документ по-прежнему будет валидным, но инструменты, использующие JSON-схему для проверки и автодополнения, могут работать некорректно. Это разрешено в файлах пресетов, определяющих версию 8 или выше.

version

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

1

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

2

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

3

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

4

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

5

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

6

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

7

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

8

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

9

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

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{} подстановку макросов. Начиная с версии 9, доступны и другие подстановки макросов, за исключением $env{} и пресет-специфических макросов, то есть тех, которые получены из полей внутри определения пресета, таких как presetName.

Предварительная настройка

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

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

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

verbosity

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

default

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

verbose

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

extra

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

debug

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

outputOnFailure

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

quiet

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

outputLogFile

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

outputJUnitFile

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

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

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

Настройки пакета могут использоваться в схеме версии 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 не указан, он должен быть унаследован от пресета inherits (если этот пресет не скрыт). Директория сборки определяется из пресета конфигурации, поэтому упаковка будет выполняться в той же 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 пресета, разрешенное в файлах пресетов, указывающих версию 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.