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

configurePresets

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

buildPresets

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

testPresets

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

packagePresets

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

workflowPresets

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

Включения

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

Если файл настроек содержит наборы настроек, наследующие от наборов настроек в другом файле, то файл должен включать другой файл либо напрямую, либо косвенно. Циклы включения между файлами недопустимы. Если a.json включает b.json, b.json не может включать a.json. Однако файл может быть включён несколько раз из одного или разных файлов.

Файлы, напрямую или косвенно включенные из CMakePresets.json, должны быть гарантированно предоставлены проектом. CMakeUserPresets.json может включать файлы из любого места.

Начиная с версии 7, поле include поддерживает расширение макросов, но только $penv{} расширение макросов. Начиная с версии 9, доступны и другие расширения макросов, кроме $env{} и макросов, специфичных для набора настроек, т.е. тех, которые получены из полей внутри определения набора настроек, таких как presetName.

Настройки конфигурации

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

name

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

hidden

Необязательный булевый параметр, указывающий, должен ли пресет быть скрытым. Если пресет скрыт, он не может быть использован в аргументе --preset=, не будет отображаться в CMake GUI и не обязан иметь допустимый generator или binaryDir, даже по наследованию. Пресеты hidden предназначены для использования в качестве основы для других пресетов, которые могут наследоваться через поле inherits.

inherits

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

Пресет по умолчанию унаследует все поля от пресетов inherits, за исключением name, hidden, inherits, description, и displayName, но может переопределить их по желанию. Если несколько пресетов inherits предоставляют конфликтующие значения для одного и того же поля, пресет, который стоит раньше в массиве inherits, будет иметь приоритет.

Пресет может унаследовать только от другого пресета, определённого в том же файле или в одном из файлов, который он включает (прямо или косвенно). Пресеты в CMakePresets.json не могут унаследовать от пресетов в CMakeUserPresets.json.

condition

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

vendor

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

displayName

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

description

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

generator

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

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

architecture, toolset

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

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

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

value

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

strategy

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

"set"

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

"external"

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

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

toolchainFile

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

graphviz

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

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

binaryDir

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

installDir

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

cmakeExecutable

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

cacheVariables

Необязательная карта переменных кэша. Ключ — имя переменной (которое не может быть пустой строкой), а значение — либо null, булево значение (что эквивалентно значению "TRUE" или "FALSE" и типу BOOL), строка, представляющая значение переменной (которая поддерживает расширение макросов), или объект со следующими полями:

type

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

value

Обязательная строка или булево значение, представляющее значение переменной. Булево значение эквивалентно "TRUE" или "FALSE". Это поле поддерживает расширение макросов.

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

environment

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

Это поле поддерживает расширение макросов, и переменные среды в этой карте могут ссылаться друг на друга и могут быть перечислены в любом порядке, пока такие ссылки не образуют цикл (например, если ENV_1 равно $env{ENV_2}, ENV_2 не может быть $env{ENV_1}). $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 не указано, оно должно быть унаследовано от пресета inherits (если этот пресет не скрыт). Директория сборки определяется из конфигурационного пресета, поэтому сборка будет выполняться в той же binaryDir, что и конфигурация.

inheritConfigureEnvironment

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

jobs

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

targets

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

configuration

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

cleanFirst

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

resolvePackageReferences

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

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

on

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

off

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

only

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

Примечание

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

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

verbose

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

nativeToolOptions

Необязательный массив строк. Эквивалентно передаче опций после -- в командной строке. Значения массива поддерживают расширение макросов.

Тестовый пресет

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

name

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

hidden

Необязательный булев параметр, определяющий, должен ли пресет быть скрытым. Если пресет скрыт, он не может быть использован в аргументе --preset и не должен иметь действительное значение configurePreset, даже по наследованию. hidden пресеты предназначены для использования в качестве основы для других пресетов, которые могут наследоваться через поле inherits.

inherits

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

Пресет по умолчанию наследует все поля от inherits пресетов (кроме name, hidden, inherits, description, и displayName), но может их переопределить по своему усмотрению. Если несколько inherits пресетов предоставляют конфликтующие значения для одного и того же поля, пресет, расположенный раньше в массиве inherits, будет предпочтительным.

Пресет может наследоваться только от другого пресета, определенного в том же файле или в одном из файлов, которые он включает (прямо или косвенно). Пресеты в CMakePresets.json не могут наследоваться от пресетов в CMakeUserPresets.json.

condition

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

vendor

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

displayName

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

description

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

environment

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

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

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

configurePreset

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

inheritConfigureEnvironment

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

configuration

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

overwriteConfigurationFile

Необязательный массив конфигурационных параметров, которые нужно переопределить, указанные в файле конфигурации CTest. Эквивалентно передаче --overwrite для каждого значения в массиве. Значения массива поддерживают расширение макросов.

output

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

shortProgress

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

verbosity

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

default

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

verbose

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

extra

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

debug

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

outputOnFailure

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

quiet

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

outputLogFile

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

outputJUnitFile

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

labelSummary

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

subprojectSummary

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

maxPassedTestOutputSize

Необязательное целое число, определяющее максимальный размер вывода для пройденных тестов в байтах. Эквивалентно передаче --test-output-size-passed в командной строке.

maxFailedTestOutputSize

Необязательное целое число, определяющее максимальный размер вывода для проваленных тестов в байтах. Эквивалентно передаче --test-output-size-failed в командной строке.

testOutputTruncation

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

maxTestNameWidth

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

filter

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

include

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

name

Дополнительная строка, определяющая регулярное выражение для имён тестов. Эквивалентно передаче --tests-regex в командной строке. Это поле поддерживает расширение макросов. Синтаксис регулярных выражений CMake описан в разделе string(REGEX).

label

Дополнительная строка, определяющая регулярное выражение для меток тестов. Эквивалентно передаче --label-regex в командной строке. Это поле поддерживает расширение макросов.

useUnion

Дополнительный булев параметр. Эквивалентно передаче --union в командной строке.

index

Дополнительный объект, определяющий тесты для включения по индексу. Объект может содержать следующие поля. Также может быть дополнительной строкой, определяющей файл с синтаксисом командной строки для --tests-information. Если указано как строка, это поле поддерживает расширение макросов.

start

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

end

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

stride

Дополнительное целое число, определяющее шаг.

specificTests

Дополнительный массив целых чисел, определяющий конкретные индексы тестов для выполнения.

exclude

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

name

Дополнительная строка, определяющая регулярное выражение для имён тестов. Эквивалентно передаче --exclude-regex в командной строке. Это поле поддерживает расширение макросов.

label

Дополнительная строка, определяющая регулярное выражение для меток тестов. Эквивалентно передаче --label-exclude в командной строке. Это поле поддерживает расширение макросов.

fixtures

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

any

Дополнительная строка, определяющая регулярное выражение для исключения текстовых фикстур из добавления любых тестов. Эквивалентно --fixture-exclude-any в командной строке. Это поле поддерживает расширение макросов.

setup

Дополнительная строка, определяющая регулярное выражение для исключения текстовых фикстур из добавления тестовых установок. Эквивалентно --fixture-exclude-setup в командной строке. Это поле поддерживает расширение макросов.

cleanup

Дополнительная строка, определяющая регулярное выражение для исключения текстовых фикстур из добавления тестовых завершающих операций. Эквивалентно --fixture-exclude-cleanup в командной строке. Это поле поддерживает расширение макросов.

execution

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

stopOnFailure

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

enableFailover

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

jobs

Дополнительное целое число. Эквивалентно передаче --parallel в командной строке.

resourceSpecFile

Дополнительная строка. Эквивалентно передаче --resource-spec-file в командной строке. Это поле поддерживает расширение макросов.

testLoad

Дополнительное целое число. Эквивалентно передаче --test-load в командной строке.

showOnly

Дополнительная строка. Эквивалентно передаче --show-only в командной строке. Строка должна быть одним из следующих значений:

human

json-v1

repeat

Дополнительный объект, определяющий, как повторять тесты. Эквивалентно передаче --repeat в командной строке. Объект должен иметь следующие поля.

mode

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

until-fail

until-pass

after-timeout

count

Необходимое целое число.

interactiveDebugging

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

scheduleRandom

Дополнительный булев параметр. Если true, эквивалентно передаче --schedule-random в командной строке.

timeout

Дополнительное целое число. Эквивалентно передаче --timeout в командной строке.

noTestsAction

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

default

Эквивалентно тому, что не передано никаких значений в командной строке.

error

Эквивалентно передаче --no-tests=error в командной строке.

ignore

Эквивалентно передаче --no-tests=ignore в командной строке.

Пресет пакета

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

name

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

hidden

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

inheritConfigureEnvironment

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

generators

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

configurations

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

variables

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

configFile

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

output

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

debug

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

verbose

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

packageName

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

packageVersion

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

packageDirectory

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

vendorName

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

Пресет рабочей среды

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

name

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

vendor

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

displayName

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

description

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

steps

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

type

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

name

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

Condition

Поле condition пресета, разрешенное в файлах пресетов, определяющих версию 3 или выше, используется для определения того, включен ли пресет. Например, это может использоваться для отключения пресета на платформах, отличных от Windows. condition может быть логическим значением, null, или объектом. Если это логическое значение, то это значение указывает, включен ли пресет или отключен. Если это null, то пресет включен, но условие null не наследуется никакими пресетами, которые могут унаследовать от этого пресета. Под-условия (например, в not, anyOf, или allOf условии) не могут быть null. Если это объект, он имеет следующие поля:

type

Обязательная строка с одним из следующих значений:

"const"

Указывает, что условие является постоянным. Это эквивалентно использованию булевого значения вместо объекта. Объект условия будет иметь следующие дополнительные поля:

value

Обязательный булевый параметр, который предоставляет постоянное значение для оценки условия.

"equals"

"notEquals"

Указывает, что условие сравнивает две строки, чтобы определить, равны ли они (или не равны). Объект условия будет иметь следующие дополнительные поля:

lhs

Первая строка для сравнения. Это поле поддерживает макроподстановку.

rhs

Вторая строка для сравнения. Это поле поддерживает макроподстановку.

"inList"

"notInList"

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

string

Обязательная строка для поиска. Это поле поддерживает макроподстановку.

list

Обязательный массив строк для поиска. Это поле поддерживает макроподстановку и использует краткую оценку.

"matches"

"notMatches"

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

string

Обязательная строка для поиска. Это поле поддерживает макроподстановку.

regex

Обязательное регулярное выражение для поиска. Это поле поддерживает макроподстановку.

"anyOf"

"allOf"

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

conditions

Обязательный массив объектов условий. Эти условия используют краткую оценку.

"not"

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

condition

Обязательный объект условия.

Макроподстановка

Как упоминалось выше, некоторые поля поддерживают макроподстановку. Макросы распознаются в форме $<macro-namespace>{<macro-name>}. Все макросы оцениваются в контексте используемого набора параметров, даже если макрос находится в поле, унаследованном от другого набора параметров. Например, если набор параметров Base устанавливает переменную PRESET_NAME в значение ${presetName}, и набор параметров Derived наследует от Base, то PRESET_NAME будет установлено в Derived.

Ошибка возникает, если закрывающая фигурная скобка не указана в конце имени макроса. Например, ${sourceDir является недопустимым. Знак доллара ($) за которым следует что-либо, кроме открывающей фигурной скобки ({) с возможным именем пространства имён, интерпретируется как буквальный знак доллара.

Распознаваемые макросы:

${sourceDir}

Путь к каталогу исходного кода проекта (то же, что и CMAKE_SOURCE_DIR).

${sourceParentDir}

Путь к родительскому каталогу каталога исходного кода проекта.

${sourceDirName}

Последний компонент имени файла в ${sourceDir}. Например, если ${sourceDir} равно /path/to/source, то это будет source.

${presetName}

Имя, указанное в поле name набора параметров.

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

${generator}

Генератор, указанный в поле generator набора параметров. Для наборов параметров сборки и тестирования это будет соответствовать генератору, указанному в configurePreset.

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

${hostSystemName}

Имя операционной системы хоста. Содержит то же значение, что и CMAKE_HOST_SYSTEM_NAME. Это разрешено в файлах наборов параметров, определяющих версию 3 или выше.

${fileDir}

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

${dollar}

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

${pathListSep}

Символ для разделения списков путей, таких как : или ;.

Например, установив PATH в /path/to/ninja/bin${pathListSep}$env{PATH}, ${pathListSep} будет расширено до символа, используемого основной операционной системой для конкатенации в PATH.

Это разрешено в файлах наборов параметров, определяющих версию 5 или выше.

$env{<variable-name>}

Переменная среды с именем <variable-name>. Имя переменной не может быть пустой строкой. Если переменная определена в поле environment, используется это значение вместо значения из родительской среды. Если переменная среды не определена, это оценивается как пустая строка.

Обратите внимание, что, хотя имена переменных среды в Windows нечувствительны к регистру, имена переменных в наборе параметров по-прежнему чувствительны к регистру. Это может привести к неожиданным результатам при использовании несоответствующего регистра. Для достижения наилучших результатов сохраняйте регистр имен переменных среды согласованным.

$penv{<variable-name>}

Аналогично $env{<variable-name>}, за исключением того, что значение берется только из родительской среды и никогда из поля environment. Это позволяет добавлять или приписывать значения к существующим переменным среды. Например, установка PATH в /path/to/ninja/bin:$penv{PATH} добавит /path/to/ninja/bin к переменной среды PATH. Это необходимо, так как $env{<variable-name>} не позволяет циклических ссылок.

$vendor{<macro-name>}

Точка расширения для поставщиков, чтобы вставлять свои собственные макросы. CMake не сможет использовать наборы параметров, содержащие макрос $vendor{<macro-name>}, и фактически игнорирует такие наборы параметров. Тем не менее, он по-прежнему сможет использовать другие наборы параметров из того же файла.

CMake не пытается интерпретировать макросы $vendor{<macro-name>}. Однако, чтобы избежать конфликтов имён, поставщики IDE должны добавлять префикс <macro-name> с очень коротким (желательно <= 4 символов) префиксом идентификатора поставщика, за которым следует ., за которым следует имя макроса. Например, Example IDE может использовать $vendor{xide.ideInstallDir}.

Схема

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