Прочитать на английском

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


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

Общие сведения об использовании манифестов с 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"

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

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

  1. Зависимость порта к порту имеет "default-features": true значение по умолчанию.
  2. Манифест верхнего уровня не имеет зависимости для порта."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 не поддерживается.

Примечание

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

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

  • 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": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
        "repository": "https://github.com/microsoft/vcpkg-docs",
        "reference": "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. Необязательно. Если это не указано, лицензия совпадает с указанным в поле лицензии верхнего уровня.

Примечание

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

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

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

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

  • !<expr>, not <expr> - отрицание
  • <expr>|<expr>, <expr>,<expr> — логический ИЛИ (ключевое слово or зарезервировано, но недопустимо в выражениях платформы)
  • <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"
arm64ec VCPKG_TARGET_ARCHITECTURE == "arm64ec"
wasm32 VCPKG_TARGET_ARCHITECTURE == "wasm32"
mips64 VCPKG_TARGET_ARCHITECTURE == "mips64"
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"
qnx VCPKG_CMAKE_SYSTEM_NAME == "QNX"
vxworks VCPKG_CMAKE_SYSTEM_NAME == "VxWorks"
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)"
}