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.

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, а среда разработки знает, как настроить среду Visual C++ из полей architecture и toolset. В этом случае CMake проигнорирует поле, но среда разработки может использовать их для настройки среды перед вызовом CMake.

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

toolchainFile

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

binaryDir

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

installDir

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

cmakeExecutable

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

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

inheritConfigureEnvironment

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

jobs

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

targets

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

configuration

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

cleanFirst

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

Необязательный булевый параметр. Если 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, даже по наследованию. Скрытые пресеты предназначены для использования в качестве базовых для других пресетов, которые будут наследоваться через поле 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 будет добавлено значение /path/to/ninja/bin. Это необходимо, потому что $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.