Справочник по vcpkg.json

Статья
04/04/2024

Общие сведения об использовании манифестов с vcpkg см . в режиме манифеста.

Манифесты — это строгие документы JSON . Они не могут содержать примечания в стиле C++(// или конечные запятые. Однако можно использовать имена полей, начинающиеся с $ записи комментариев в любом объекте с хорошо определенным набором ключей. Эти поля комментариев не допускаются в любых объектах, разрешающих определяемые пользователем ключи (например "features", ).

Последняя схема JSON доступна по адресу https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. Идентификаторы с поддержкой схемы JSON, такие как Visual Studio и Visual Studio Code, могут использовать этот файл для предоставления автозавершения и синтаксиса проверка. Для большинства идентификаторов удостоверяется "$schema"vcpkg.json этот URL-адрес.

Пример

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "boost-system",
    {
      "name": "cpprestsdk",
      "default-features": false
    },
    "libxml2",
    "yajl"
  ]
}

В этом примере демонстрируется манифест для приложения с помощью boost-system, cpprestsdklibxml2и yajl. В этом примере также содержится ссылка, позволяющая улучшить проверку интегрированной $schema среды разработки и автозавершение.

Поля верхнего уровня

имени	Обязательно	Type	Описание
встроенные базовые показатели	Нет	строка	Закрепление версий для использования при создании в качестве верхнего уровня
функции по умолчанию	No	Объект компонента[]	Требовать функции, перечисленные как по умолчанию
dependencies	No	Зависимость[]	Список зависимостей, необходимых для сборки и использования этого проекта
описание	Библиотеки	string или string[]	Описание проекта
документация	Нет	строка	URI в документации проекта вышестоящий
features	No	{string: Компонент}	Дополнительные функции , доступные для пользователей проекта
Домашняя страница	Нет	строка	URI на домашней странице проекта вышестоящий
лицензия	No	строка или null	Выражение лицензии SPDX
Сопровождающих	No	string или string[]	Поддержка файлов пакета
name	Библиотеки	строка	Имя проекта
Переопределения	No	Переопределение[]	Закрепление версий для использования при создании в качестве верхнего уровня
версия порта	No	integer	Редакция файлов портов
Поддерживает	No	Выражение платформы	Поддерживаемые конфигурации платформы и сборки
версия version-semver Дата версии строка версии	Библиотеки	строка	Сведения о версии вышестоящего потока

`"builtin-baseline"`

Ярлык для указания "baseline" разрешения версий в реестре по умолчанию. Строка . Необязательно, только для проектов верхнего уровня.

Это поле указывает фиксацию https://github.com/microsoft/vcpkg , которая предоставляет сведения о глобальной минимальной версии манифеста. Он необходим для файлов манифеста верхнего уровня с использованием управления версиями без указанного значения "default-registry". Он имеет ту же семантику, что и определение реестра по умолчанию:

{
  "default-registry": {
    "kind": "builtin",
    "baseline": "<value>"
  }
}

Дополнительные сведения о семантике см . в разделе "Управление версиями и использование реестров ".

`"default-features"`

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

Функции по умолчанию автоматически выбираются, если одно из них:

Зависимость порта к порту имеет "default-features": true значение по умолчанию.
Манифест верхнего уровня не имеет зависимости для порта."default-features": false

Функции по умолчанию обрабатывают конкретный случай предоставления конфигурации по умолчанию для транзитивных зависимостей, о том, что проект верхнего уровня может не знать о. Порты, используемые другими пользователями, должны почти всегда использовать "default-features": false для их зависимостей.

Функции по умолчанию для конкретной платформы можно определить с помощью объекта компонента:

{
  "name": "my-port",
  "default-features": [
    "png",
    {
      "name": "winssl",
      "platform": "windows"
    }
  ]
}

Дополнительные сведения о функциях см. в статье "features" .

`"description"`

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

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

`"dependencies"`

Список зависимостей, необходимых проекту. Массив объектов зависимостей. Необязательно.

В этом поле перечислены все зависимости, необходимые для сборки и использования библиотеки или приложения.

Примеры зависимостей портов

"dependencies": [
  {
    "name": "arrow",
    "default-features": false,
    "features": [
      "json",
      {
        "name": "mimalloc",
        "platform": "windows"
      }
    ]
  },
  "boost-asio",
  "openssl",
  {
    "name": "picosha2",
    "platform": "!windows"
  }
]

`"documentation"`

Универсальный код ресурса (URI) в документации вышестоящий проекта. Строка . Необязательно.

`"features"`

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

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

`"homepage"`

Универсальный код ресурса (URI) на домашней странице проекта. Строка . Необязательно.

`"license"`

Краткое выражение лицензии SPDX проекта. Строка или null. Необязательно.

"license" Должно быть либо выражение лицензии SPDX 3.19, null либо указывать, что пользователи должны читать развернутый /share/<port>/copyright файл. DocumentRefs не поддерживается.

Примеры строк лицензии

MIT
LGPL-2.1-only AND BSD-2-Clause
GPL-2.0-or-later WITH Bison-exception-2.2

EBNF

vcpkg использует следующий EBNF для синтаксического анализа поля лицензии:

idchar = ? regex /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;

(* note that unrecognized license and license exception IDs will be warned against *)
license-id = idstring ;
license-exception-id = idstring ;
(* note that DocumentRefs are unsupported by this implementation *)
license-ref = "LicenseRef-", idstring ;

with = [ whitespace ], "WITH", [ whitespace ] ;
and = [ whitespace ], "AND", [ whitespace ] ;
or = [ whitespace ], "OR", [ whitespace ] ;

simple-expression = [ whitespace ], (
  | license-id
  | license-id, "+"
  | license-ref
  ), [ whitespace ] ;

(* the following are split up from compound-expression to make precedence obvious *)
parenthesized-expression =
  | simple-expression
  | [ whitespace ], "(", or-expression, ")", [ whitespace ] ;

with-expression =
  | parenthesized-expression
  | simple-expression, with, license-exception-id, [ whitespace ] ;

(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
and-expression = with-expression, { and, with-expression } ;
or-expression = and-expression, { or, and-exression } ;

license-expression = or-expression ;

`"maintainers"`

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

Рекомендуется использовать форму "Адрес электронной почты сименем фамилии<>".

`"name"`

Имя проекта. Строка . Обязательный для библиотек, необязательный для проектов верхнего уровня.

Имя должно быть строчным буквами ASCII, цифрами или дефисами (-). Он не должен начинаться и заканчиваться дефисом. Библиотеки рекомендуется включить имя организации или платформы в качестве префикса, например msft- или boost- помочь пользователям найти и описать связанные библиотеки.

Например, библиотеку с официальным именем Boost.Asio может быть присвоено имя boost-asio.

`"overrides"`

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

"overrides" из транзитивных манифестов (т. е. из зависимостей) игнорируются. Используются только переопределения, определенные проектом верхнего уровня.

имени	Обязательно	Type	Description
name	Да	строка	Имя порта
version	Да	строка	Сведения о версии вышестоящего потока для закрепления.
version-semver Дата версии строка версии	Да	строка	Устаревшие альтернативные варианты `version` именования конкретных схем.
версия порта	No	integer	Исправление файлов портов для закрепления. Не рекомендуется в пользу размещения в самой версии.

"port-version" должен быть указан как #N суффикс в "version". Например, "version": "1.2.3#7" имена версии 1.2.3, порт-версия 7.

Дополнительные сведения о семантике см. в разделе "Управление версиями".

Пример переопределения версий

  "overrides": [
    {
      "name": "arrow", "version": "1.2.3#7"
    },
    {
      "name": "openssl", "version": "1.1.1h#3"
    }
  ]

`"port-version"`

Суффикс версии, отличающий редакции файлов упаковки. Целое число. По умолчанию — 0.

При "port-version" каждом публикации новой версии порта, которая не изменяет версию исходной версии вышестоящий. При изменении исходной версии вышестоящий поле версии должно измениться и "port-version" его следует сбросить 0 (или удалить).

Дополнительные сведения см. в разделе "Управление версиями ".

`"supports"`

Поддерживаемые конфигурации платформы и сборки. Выражение платформы. Необязательно.

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

Например, если библиотека не поддерживает сборку для Linux, вы будете использовать "supports": "!linux".

`"vcpkg-configuration"`

Позволяет внедрять свойства конфигурации vcpkg в vcpkg.json файл. Все, что находится внутри vcpkg-configuration свойства, обрабатывается как если бы оно было определено в vcpkg-configuration.json файле. Дополнительные сведения см. в vcpkg-configuration.json документации.

Наличие определенного vcpkg-configuration в vcpkg.json то время как наличие vcpkg-configuration.json файла не допускается и приведет к прекращению команды vcpkg с сообщением об ошибке.

Пример внедренного кода `vcpkg-configuration`

{
  "name": "test",
  "version": "1.0.0",
  "dependencies": [ "beison", "zlib" ],
  "vcpkg-configuration": {
    "registries": [
      {
        "kind": "git",
        "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
        "repository": "https://github.com/northwindtraders/vcpkg-registry",
        "packages": [ "beicode", "beison" ]
      }
    ],
    "overlay-ports": [ "./my-ports/fmt", 
                       "./team-ports"
    ]
  }

`"version"`, , `"version-semver""version-date""version-string"`

Версия проекта вышестоящий. Строка . Обязательный для библиотек, необязательный для проектов верхнего уровня.

Манифест должен содержать не более одного поля версии. Каждое поле версии соответствует другой схеме управления версиями:

"version" — Расслабленная семантическая версия 2.0.0, что позволяет более или менее 3 первичных чисел. Пример: 1.2.3.4.10-alpha1
"version-semver" — строгая семантическая версия 2.0.0. Пример: 2.0.1-rc5
"version-date" — дата, отформатированная как YYYY-MM-DD с необязательной конечной точкой, отдельной числовой последовательностью. Используется для пакетов, которые не имеют числовых выпусков (например, Live-at-HEAD). Пример: 2022-12-09.314562
"version-string" — произвольная строка. Используется для пакетов, не имеющих упорядоченных версий. Это следует редко использовать, однако все порты, созданные до появления других полей версии, используют эту схему.

Дополнительные сведения см. в разделе "Управление версиями ".

Поля зависимостей

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

имени	Обязательно	Type	Описание
функции по умолчанию	No	bool	Требовать функции, перечисленные как по умолчанию
features	No	Объект компонента[]	Список дополнительных функций, необходимых
host	No	bool	Требовать зависимость для хост-компьютера вместо целевого объекта
name	Да	строка	Имя зависимости
platform	No	Выражение платформы	Квалификатор, для которого платформы используют зависимость
version>=	Нет	строка	Минимальная требуемая версия. Версия порта идентифицируется суффиксом `#N` , например `1.2.3#7` именами портов версии 7.

Строки интерпретируются как объект с именем, определенным для строкового значения.

Зависимость:`"default-features"`

Логическое значение, указывающее, что проект зависит от функций зависимости по умолчанию. По умолчанию — true.

В большинстве случаев это должно быть определено false и все необходимые функции должны быть явно зависят от них.

Зависимость:`"features"`

Список необходимых дополнительных функций. Массив объектов компонента. Необязательно.

Объект компонента — это объект со следующими полями:

name — имя функции. Строка . Обязательный.
platform— Выражение платформы, ограничивающее платформы, в которых требуется функция. Необязательно.

Простая строка также является допустимым Feature Object эквивалентом { "name": "<feature-name>" }.

Например,

{
  "name": "ffmpeg",
  "default-features": false,
  "features": [
    "mp3lame",
    {
      "name": "avisynthplus",
      "platform": "windows"
    }  
  ]
}

Использует библиотеку с поддержкой ffmpeg кодировки mp3. В Windows avisynthplus также включена поддержка.

Зависимость:`"host"`

Логическое значение, указывающее, что зависимость должна быть создана для триплета узла вместо триплета текущего порта. По умолчанию — false.

Любая зависимость, предоставляющая средства или скрипты, которые должны быть "выполнены" во время сборки (например, системы сборки, генераторы кода или вспомогательные средства) должны быть помечены как "host": true. Это позволяет исправить перекрестную компиляцию в случаях, когда целевой объект не является исполняемым, например при компиляции для arm64-android.

Дополнительные сведения см . в зависимостях узлов.

Зависимость:`"name"`

Имя зависимости. Строка . Обязательный.

Это следует тем же ограничениям, что и "name" свойство для проекта.

Зависимость:`"platform"`

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

Если выражение не соответствует текущей конфигурации, зависимость не будет использоваться. Например, если зависимость имеется "platform": "!windows", это необходимо только при выборе систем, отличных от Windows.

Зависимость:`"version>="`

Минимальное ограничение версии для зависимости.

Это поле указывает минимальную версию зависимости, при необходимости используя #N суффикс, чтобы также указать минимальную версию порта при необходимости.

Дополнительные сведения о семантике управления версиями см. в разделе "Управление версиями".

Поля компонентов

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

имени	Обязательно	Type	Описание
описание	Да	строка	Описание функции
dependencies	No	Зависимость[]	Список зависимостей
Поддерживает	No	Выражение платформы	Квалификатор, для которого поддерживаются платформы и конфигурации функции.
лицензия	No	строка или null	Выражение лицензии SPDX

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

Пример порта с функциями

{
  "features": {
    "cbor": {
      "description": "The CBOR backend",
      "dependencies": [
        {
          "$explanation": [
            "This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
          ],
          "name": "libdb",
          "default-features": false,
          "features": [ "json" ]
        }
      ]
    },
    "csv": {
      "description": "The CSV backend",
      "dependencies": [
        "fast-cpp-csv-parser"
      ]
    },
    "json": {
      "description": "The JSON backend",
      "dependencies": [
        "jsoncons"
      ]
    }
  }
}

Функция: `"dependencies"`

Список зависимостей, необходимых компоненту. Массив объектов зависимостей. Необязательно.

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

Функция: `"description"`

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

Это позволяет пользователям обнаруживать функцию как часть search или find команду и узнать, что делает эта функция.

Функция: `"supports"`

Поддерживаемые платформы и конфигурации сборки для функции. Выражение платформы. Необязательно.

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

Функция: `"license"`

Краткое выражение лицензии SPDX функции. Строка или null. Необязательно. Если это не указано, лицензия совпадает с указанным в поле лицензии верхнего уровня.

Выражение платформы

Выражение платформы — это строка JSON, описывающая, когда требуется зависимость или когда ожидается сборка библиотеки или компонента.

Выражения создаются из примитивных идентификаторов, логических операторов и группирования:

!<expr>, not <expr> - отрицание
<expr>|<expr>, — <expr>||<expr><expr>,<expr> логический ИЛИ (ключевое слово or зарезервирован, но недопустим в выражениях платформы)
<expr>&<expr>, — <expr>&&<expr><expr> and <expr> логический И
(<expr>) — группирование и приоритет

Следующие идентификаторы определяются на основе трех параметров и конфигурации сборки :

Идентификатор	Тройное условие
`x64`	`VCPKG_TARGET_ARCHITECTURE` == `"x64"`
`x86`	`VCPKG_TARGET_ARCHITECTURE` == `"x86"`
`arm`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"` Или `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`arm32`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"`
`arm64`	`VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`wasm32`	`VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
`windows`	`VCPKG_CMAKE_SYSTEM_NAME` == `""`или `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"` `VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
`mingw`	`VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
`uwp`	`VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
`xbox`	`VCPKG_CMAKE_SYSTEM_NAME` == `""` и `XBOX_CONSOLE_TARGET` определен.
`linux`	`VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
`osx`	`VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
`ios`	`VCPKG_CMAKE_SYSTEM_NAME` == `"iOS"`
`freebsd`	`VCPKG_CMAKE_SYSTEM_NAME` == `"FreeBSD"`
`openbsd`	`VCPKG_CMAKE_SYSTEM_NAME` == `"OpenBSD"`
`android`	`VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
`emscripten`	`VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
`static`	`VCPKG_LIBRARY_LINKAGE` == `"static"`
`staticcrt`	`VCPKG_CRT_LINKAGE` == `"static"`
`native`	`TARGET_TRIPLET` == `HOST_TRIPLET`

Пример выражения платформы

Требуется picosha2 sha256 в windows, но получить его из ОС в Windows (BCrypt)

{
  "name": "picosha2",
  "platform": "!windows"
}

Требовать zlib в Arm64 Windows и amd64 Linux

{
  "name": "zlib",
  "platform": "(windows & arm64) | (linux & x64)"
}

Поделиться через

Справочник по vcpkg.json

Пример

Поля верхнего уровня

"builtin-baseline"

"default-features"

"description"

"dependencies"

Примеры зависимостей портов

"documentation"

"features"

"homepage"

"license"

Примеры строк лицензии

EBNF

"maintainers"

"name"

"overrides"

Пример переопределения версий

"port-version"

"supports"

"vcpkg-configuration"

Пример внедренного кода vcpkg-configuration

"version", , "version-semver""version-date""version-string"