cmake-presets(7)

Введение
Формат
Схема

Введение

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

Пользователи CMake часто сталкиваются с проблемой совместного использования настроек для типовых способов конфигурации проекта с другими людьми. Это может потребоваться для поддержки CI-сборок или для пользователей, часто использующих ту же сборку. CMake поддерживает два основных файла, CMakePresets.json и CMakeUserPresets.json, которые позволяют пользователям указывать общие параметры конфигурации и делиться ими с другими. CMake также поддерживает файлы, включённые с помощью поля include.

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

CMakePresets.json можно добавить в систему управления версиями, а CMakeUserPresets.json не следует добавлять. Например, если проект использует Git, CMakePresets.json можно отслеживать, а CMakeUserPresets.json следует добавить в .gitignore.

Формат

Файлы представляют собой JSON-документ с объектом в качестве корня:

{
  "version": 6,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 23,
    "patch": 0
  },
  "include": [
    "otherThings.json",
    "moreThings.json"
  ],
  "configurePresets": [
    {
      "name": "default",
      "displayName": "Default Config",
      "description": "Default build using Ninja generator",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/default",
      "cacheVariables": {
        "FIRST_CACHE_VARIABLE": {
          "type": "BOOL",
          "value": "OFF"
        },
        "SECOND_CACHE_VARIABLE": "ON"
      },
      "environment": {
        "MY_ENVIRONMENT_VARIABLE": "Test",
        "PATH": "$env{HOME}/ninja/bin:$penv{PATH}"
      },
      "vendor": {
        "example.com/ExampleIDE/1.0": {
          "autoFormat": true
        }
      }
    },
    {
      "name": "ninja-multi",
      "inherits": "default",
      "displayName": "Ninja Multi-Config",
      "description": "Default build using Ninja Multi-Config generator",
      "generator": "Ninja Multi-Config"
    },
    {
      "name": "windows-only",
      "inherits": "default",
      "displayName": "Windows-only configuration",
      "description": "This build is only available on Windows",
      "condition": {
        "type": "equals",
        "lhs": "${hostSystemName}",
        "rhs": "Windows"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "default",
      "configurePreset": "default"
    }
  ],
  "testPresets": [
    {
      "name": "default",
      "configurePreset": "default",
      "output": {"outputOnFailure": true},
      "execution": {"noTestsAction": "error", "stopOnFailure": true}
    }
  ],
  "packagePresets": [
    {
      "name": "default",
      "configurePreset": "default",
      "generators": [
        "TGZ"
      ]
    }
  ],
  "workflowPresets": [
    {
      "name": "default",
      "steps": [
        {
          "type": "configure",
          "name": "default"
        },
        {
          "type": "build",
          "name": "default"
        },
        {
          "type": "test",
          "name": "default"
        },
        {
          "type": "package",
          "name": "default"
        }
      ]
    }
  ],
  "vendor": {
    "example.com/ExampleIDE/1.0": {
      "autoFormat": false
    }
  }
}

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

version

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

1: Новое в версии 3.19.
2: Новое в версии 3.20.
3: Новое в версии 3.21.
4: Новое в версии 3.23.
5: Новое в версии 3.24.
6: Новое в версии 3.25.

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

Пресет конфигурации

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

name

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

hidden

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

inherits

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

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

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

condition

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

vendor

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

displayName

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

description

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

generator

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

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

architecture, toolset

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

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

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

value

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

strategy

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

"set": Установить соответствующее значение. Это приведет к ошибке для генераторов, которые не поддерживают соответствующее поле.
"external": Не устанавливать значение, даже если генератор его поддерживает. Это полезно, если, например, пресет использует генератор Ninja, и интегрированная среда разработки (IDE) знает, как настроить среду Visual C++ из полей architecture и toolset. В этом случае CMake проигнорирует поле, но IDE сможет использовать их для настройки среды перед вызовом CMake.

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

toolchainFile

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

binaryDir

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

installDir

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

cmakeExecutable

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

cacheVariables

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

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

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

environment

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

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

warnings

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

dev: Необязательный булево. Эквивалентно передаче -Wdev или -Wno-dev в командной строке. Не может быть установлено в false если errors.dev установлено в true.
deprecated: Необязательный булево. Эквивалентно передаче -Wdeprecated или -Wno-deprecated в командной строке. Не может быть установлено в false если errors.deprecated установлено в true.
uninitialized: Необязательный булево. Установка этого значения в true эквивалентна передаче --warn-uninitialized в командной строке.
unusedCli: Необязательный булево. Установка этого значения в false эквивалентна передаче --no-warn-unused-cli в командной строке.
systemVars: Необязательный булево. Установка этого значения в true эквивалентна передаче --check-system-vars в командной строке.

errors

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

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

debug

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

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

Настройка сборки

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

name

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

hidden

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

inherits

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

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

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

condition

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

vendor

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

displayName

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

description

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

environment

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

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

Примечание

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

configurePreset

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

inheritConfigureEnvironment

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

jobs

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

targets

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

configuration

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

cleanFirst

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

resolvePackageReferences

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

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

on: Приводит к разрешению ссылок на пакеты перед выполнением сборки.
off: Ссылки на пакеты не будут разрешаться. Обратите внимание, что это может привести к ошибкам в некоторых средах сборки, таких как проекты в стиле .NET SDK.
only: Разрешить только ссылки на пакеты, но не выполнять сборку.

Примечание

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

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

verbose

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

nativeToolOptions

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

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

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

name

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

hidden

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

inherits

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

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

condition

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

vendor

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

displayName

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

description

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

environment

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

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

configurePreset

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

inheritConfigureEnvironment

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

configuration

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

overwriteConfigurationFile

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

output

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

shortProgress

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

verbosity

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

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

debug

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

outputOnFailure

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

quiet

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

outputLogFile

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

outputJUnitFile

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

labelSummary

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

subprojectSummary

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

maxPassedTestOutputSize

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

maxFailedTestOutputSize

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

testOutputTruncation

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

maxTestNameWidth

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

filter

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

include

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

name

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

label

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

useUnion

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

index

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

start: Необязательное целое число, определяющее индекс теста, с которого начать тестирование.
end: Необязательное целое число, определяющее индекс теста, на котором остановить тестирование.
stride: Необязательное целое число, определяющее шаг.
specificTests: Необязательный массив целых чисел, определяющий конкретные индексы тестов для выполнения.

exclude

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

name

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

label

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

fixtures

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

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

execution

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

stopOnFailure

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

enableFailover

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

jobs

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

resourceSpecFile

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

testLoad

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

showOnly

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

human

json-v1

repeat

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

mode

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

until-fail

until-pass

after-timeout

count

Обязательное целое число.

interactiveDebugging

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

scheduleRandom

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

timeout

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

noTestsAction

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

default: Эквивалентно тому, что не передаётся никакого значения в командной строке.
error: Эквивалентно передаче --no-tests=error в командной строке.
ignore: Эквивалентно передаче --no-tests=ignore в командной строке.

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

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

name

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

hidden

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

inherits

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

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

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

condition

Необязательный объект Condition.

vendor

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

displayName

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

description

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

environment

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

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

configurePreset

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

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.

© 2000–2023 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.26/manual/cmake-presets.7.html