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

Основные понятия реестров

  • Статья

Обзор

vcpkg размещает выбор библиотек, упакованных в порты , по https://github.com/Microsoft/vcpkg. Эта коллекция портов называется курируемым реестром. Однако vcpkg не ограничивается курируемым реестром. Пользователи могут расширить выбор портов, создав пользовательские реестры.

Реестр — это коллекция портов и вспомогательных файлов, расположенных в определенной структуре. Следуя структуре реестра, порты, содержащиеся в реестре, можно установить с теми же функциями (управление версиями, двоичном кэшировании), предлагаемым портам в курированном реестре.

В настоящее время существует три типа реестров:

vcpkg можно настроить для учета портов, доступных в пользовательских реестрах, с помощью файла vcpkg-configuration.json. См. статью : Установка зависимости из реестра на основе Git для получения руководства о том, как использовать пользовательские реестры в ваших проектах.

Структура реестра

Для интерфейса vcpkg с реестром он должен соответствовать следующей структуре:

  • Каталог с именем ports содержит коллекцию портов с каждым подкаталогом, содержащим определенный порт, соответствующий имени подкаталога. Например, файлы для портов foo находятся в ports/foo.
  • Каталог с именем versions содержит файлы, составляющие базу данных версий.

Пример: структура реестра

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

База данных версий

Все реестры содержат каталог versions в корне реестра, который содержит базу данных версий.

В базе данных версий есть два компонента:

  • Базовый файл
  • Версионные файлы

Базовый файл — это JSON-файл с именем baseline.json, расположенный в корне каталога versions.

Файлы версий — это JSON-файлы с теми же именами, что и доступные порты. Они должны существовать в versions/<prefix>/<port name>.json, где <prefix> — это первая буква имени порта, за которой следует дефис. Например, файл версий для порта foo должен находиться в versions/f-/foo.json.

Цель файла версий состоит в следующем:

  • Перечислить все доступные версии каждого порта
  • Укажите места хранения каждой версии.

Формат файла версии зависит от типа реестра.

Базовый файл

Все реестры, независимо от их типа, должны содержать файл с именем baseline.json, расположенный в versions/baseline.json.

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

Файл JSON состоит из одного объекта, свойства которого называются базовыми объектами. Свойства каждого базового объекта — это имена портов, значения которых являются записями версий. Справочник по реестрам подробно описывает макет базовых файлов.

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

  • baseline: значением является версия порта, соответствующая соответствующему файлу vcpkg.json.
  • port-version: значением является значение порта port-version, совпадающее с соответствующим файлом vcpkg.json.

Пример базового файла

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

См. справочную документацию по следующим вопросам:

  • Базовая структура файла для реестров Git
  • Базовый макет файла для реестров файловой системы

Файлы версий

Каждый порт в реестре имеет соответствующий файл версий. Файлы версий хранятся в versions/<prefix>/<port name>.json, где <prefix> — это первая буква имени порта, за которой следует дефис. Например, файл версий для порта foo находится в versions/f-/foo.json.

Назначение файла версий заключается в следующем:

  • Перечислите все доступные версии каждого порта
  • Укажите места хранения каждой из этих версий.

Макет файла версий — это объект, содержащий массив "versions", с каждой записью в этом массиве, являющейся объектом версии. Объект версии должен содержать следующие свойства:

  • Свойство версии: ключ и значение должны соответствовать тем, которые используются портом в файле vcpkg.json. Ключ должен быть одним из version, version-semver, version-dateили version-string; значение должно быть версией, как она отображается в файле манифеста порта (vcpkg.json).
  • port-version: это значение представляет собой port-version порта, как указано в файле vcpkg.json для порта.
  • git-tree: (только в реестрах Git) значением является git-tree SHA, соответствующий каталогу порта. Это SHA вычисляется с помощью хэширования содержимого каталога порта; этот SHA дерева Git может использоваться Git для получения содержимого порта, которое соответствует предоставленному дереву Git. Это позволяет vcpkg получать старые версии портов из журнала реестров Git. Ознакомьтесь с разделом реестров Git, чтобы узнать, как получить это значение для любой конкретной версии порта.
  • path: (только в реестрах файловой системы) значением является полный путь к каталогу, содержаму файлы портов для конкретной версии.

Пример файла версии реестра файловой системы

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

См. справочную документацию по следующему:

  • Макет файла версий для реестров Git
  • Макет версий файла для реестров файловой системы

Встроенный реестр

Встроенный реестр — это специальный тип реестра. Это реестр по умолчанию, используемый в классическом режиме . В режиме манифеста , если реестра по умолчанию не указан, vcpkg неявно использует встроенный реестр.

Встроенный реестр относится к локальной копии курированного реестра, созданной при git clone репозитория vcpkg из https://github.com/Microsoft/vcpkg. Некоторые операции ожидают, что переменная среды VCPKG_ROOT указывает на встроенный реестр.

Если vcpkg приобретается с помощью установщика one liner или Visual Studio, встроенный реестр становится эквивалентным реестра Git, указывающим на репозиторий https://github.com/Microsoft/vcpkg.

Реестры Git

Реестр Git — это репозиторий, который следует структуре реестра и использует возможности Git для обеспечения управления версиями портов в реестре. Курированный реестр на https://github.com/Microsoft/vcpkg является реализацией реестра Git.

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

Реестры Git — это рекомендуемый метод реализации пользовательского реестра. Поскольку механизм версионирования такой же, как и в курируемом реестре, реестры Git могут использовать x-add-version для управления файлами базы данных версий.

См. справочник по реестрам для получения подробной информации о реализации реестров Git.

Добавление новой версии в реестр Git

Команду x-add-version можно использовать для добавления нового порта или новой версии в реестр. При добавлении версий, использующих эту команду, следует учитывать следующее:

Важный

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

При внесении изменений в порт необходимо увеличить его версию в файле vcpkg.json. Если изменения включают обновление основной версии пакета, не забудьте задать для port-version значение 0; в противном случае не забудьте увеличить port-version на один.

Команда x-add-version требует, чтобы все изменения портов были зафиксированы в репозитории перед обновлением базы данных версии.

Пример. Добавление новой версии порта в реестр Git

git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json

Варианты перенаправления --x-builtin-ports-root и --x-builtin-registry-versions-dir должны соответственно указывать на каталоги ports и versions вашего реестра.

После успешного выполнения команды x-add-version, измените последний коммит, чтобы включить изменения в файл версий.

git commit --amend -m "Update foo to new version"

Реестры файловой системы

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

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

Дополнительные сведения о реализации реестра файловой системы см. в справочнике по реестрам .

Использование реестров

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

Реестр по умолчанию

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

В качестве удобства для пользователей, которые не взаимодействуют с пользовательскими реестрами, vcpkg неявно добавляет встроенный реестр в качестве реестра по умолчанию. Чтобы изменить это поведение, реестр по умолчанию можно задать для любого реестра или полностью отключить его с помощью свойство default-registry.

Пример: Установите настраиваемый реестр по умолчанию

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

Пример. Отключение реестра по умолчанию

vcpkg-configuration.json

{
  "default-registry": null
}

Массив реестров

Чтобы расширить выбор портов, доступных для установки с помощью vcpkg, можно указать дополнительные реестры с помощью массива registries.

Пример. Добавление пользовательских реестров в конфигурацию

Заметка

В зависимости от типа реестра может потребоваться предоставить различные сведения в массиве registries. Ознакомьтесь со ссылкой vcpkg-configurtion.json, чтобы узнать, какие свойства необходимы для каждого типа реестра.

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://my.privateregistry.git",
      "baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
      "packages": [ "foo" ]
    },
    {
      "kind": "filesystem",
      "path": "C:/path/to/registry",
      "baseline": "baseline1",
      "packages": [ "bar" ]
    }
  ]
}

Не перезаписывай журнал версий

После публикации версии в файлах версий не изменяйте её связанные git-tree в Git-реестре или каталоге файловой системы.

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

Если у существующей версии возникли проблемы, предпочтительно создать новую port-version.

Не удаляйте файлы версий

Заметка

Этот раздел относится только к реестрам Git

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

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

Следующие шаги

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