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": 10,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 23,
    "patch": 0
  },
  "$comment": "An example CMakePresets.json file",
  "include": [
    "otherThings.json",
    "moreThings.json"
  ],
  "configurePresets": [
    {
      "$comment": [
        "This is a comment row.",
        "This is another comment,",
        "just because we can do it"
      ],
      "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
    }
  }
}

Файлы пресетов, указывающие версию 10 или выше, могут включать комментарии, используя ключ $comment, на любом уровне внутри JSON-объекта для предоставления документации.

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

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

10

Добавлен в версии 3.31.

cmakeMinimumRequired

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

major

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

minor

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

patch

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

include

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

vendor

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

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

toolchainFile

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

graphviz

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

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

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}). $penv{NAME} позволяет добавлять или удалять значения к существующим переменным среды, используя только значения из родительской среды.

Переменные среды наследуются через поле 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}). $penv{NAME} позволяет добавлять или удалять значения к существующим переменным среды, используя только значения из родительской среды.

Переменные среды наследуются через поле 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 в командной строке. Поставщики могут игнорировать свойство целей или скрывать предустановки построения, которые явно указывают цели. Это поле поддерживает расширение макросов.

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}). $penv{NAME} позволяет добавлять или удалять значения к существующим переменным среды, обращаясь только к значениям из родительской среды.

Переменные среды наследуются через поле 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

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

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

enableFailover

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

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

scheduleRandom

Необязательный bool. Если 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}). $penv{NAME} позволяет добавлять или удалять значения к существующим переменным среды, обращаясь только к значениям из родительской среды.

Переменные среды наследуются через поле inherits, и среда пресета будет объединением собственной среды environment и среды environment всех его предков. Если несколько пресетов в этом объединении определяют одну и ту же переменную, применяются стандартные правила inherits. Установка переменной в значение null приводит к тому, что она не будет установлена, даже если значение было унаследовано от другого пресета.

configurePreset

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

inheritConfigureEnvironment

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

generators

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

configurations

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

variables

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

configFile

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

output

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

debug

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

verbose

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

packageName

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

packageVersion

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

packageDirectory

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

vendorName

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

Пресет рабочей области

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

name

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

vendor

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

displayName

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

description

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

steps

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

type

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

name

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

Условие

Поле condition пресета, разрешенное в файлах пресетов, определяющих версию 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.